h12_library.md

Интерфейс библиотеки для работы с HTTP 1, 2

Типы данных
Функции
Коллбэки
Вспомогательные методы

Типы данных

`logger`

Контекст логгера

typedef struct logger {
    FILE *file;
    logger_callback callback; 
    logger_log_level level;
    void *attachment;
} logger;

file Указатель на структуру FILE открытого логфайла
callback Указатель на коллбэк (если он ненулевой, то file не используется)
level Уровень логгирования

`logger_log_level`

Уровень логгирования

enum logger_log_level {
    LOG_LEVEL_ERROR = 0,
    LOG_LEVEL_WARN,
    LOG_LEVEL_INFO,
    LOG_LEVEL_DEBUG,
    LOG_LEVEL_TRACE
};

Уровни соответствуют общепринятым.

`http_session`

Контекст HTTP-парсера

struct http_session {
    void *attachment;
    union {
        struct http1_session http1;
        struct http2_session http2;
    }
};

attachment - параметр для использования в коллбэках, переданный при инициализации парсера

`http1_session`

Контекст парсера HTTP/1 содержит контекст единственного потока данных.

struct http1_session {
    http_stream *stream;
};

`http2_session`

Контекст парсера HTTP/2 содержит контекст настройки nghttp2-сессии и карту контекстов для каждого потока.

struct http2_session {
    nghttp2_session session;
    // int -> http_stream *
    hash_t() stream_id_to_stream;
};

`http_stream`

Контекст одного потока HTTP, содержит заголовки текущего запроса или ответа.

struct http_stream {
    void *attachment;
    // PRIVATE FIELDS
    ...
};

attachment - параметр для использования в коллбэках, переданный при инициализации парсера

`http_session_type`

Тип парсера - HTTP-запрос, HTTP-ответ, HTTP/2

enum http_session_type {
    HTTP_REQUEST,
    HTTP_RESPONSE,
    HTTP2
};

Функции

`logger_open`

Открывает лог

logger *logger_open(const char *filename, logger_log_level_t log_level, logger_callback_t callback, void *attachment);

filename - имя лог-файла
log_level - уровень логгирования
callback - коллбэк логгирования
attachment - параметр коллбэка логгирования
возвращаемое значение - контекст логгера

`logger_log`

Записывает сообщение в лог

void logger_log(logger *log, logger_log_level_t log_level, const char *fmt, ...);

log - контекст логгера
log_level - уровень логгирования
fmt - строка формата
... - параметры строки формата

`logger_close`

Закрывает лог

logger_close(logger_t *ctx);

ctx - контекст логгера

`http_session_init`

Инициализирует парсер

int init(logger *log, session_type type, session_callbacks *callbacks, void *attachment, session **p);

log - контекст логгера
type - Тип парсера
callbacks - Коллбэки
attachment - Параметр коллбэков
p - поинтер на переменную поинтера на контекст
return value - код ошибки

`http_session_input`

Передает на обработку полученные данные

int input(http_session *session, const char *buffer, int length);

session - Контекст парсера
buffer - Буфер с данными
length - Размер буфера
return value - код ошибки

`http_session_input_settings`

Передает на обработку значение заголовка HTTP2-Settings при апгрейде с HTTP/1.1

int input_settings(http_session *context, const char *base64_http2_settings, int length);

context - Контекст парсера
base64_http2_settings - Значение заголовка HTTP2-Settings при апгрейде с HTTP/1.1
length - Длина заголовка
return value - код ошибки

`http_session_close`

Освобождает ресурсы парсера

int close(http_session *session);

id - ID соединения
return value - код ошибки

Коллбэки

`h1_headers`

Сигнализирует о получении всех заголовков

void h1_headers(http_stream *stream, struct http_headers headers);

stream - контекст потока (единственного)
headers - заголовки после распаковки

`h1_data_started`

Сигнализирует о начале передачи данных

bool h1_data_started(http_stream *stream);

stream - контекст потока (единственного)
возвращаемое значение - нужно ли применять zlib-декомпрессию данных потока

`h1_data`

Сигнализирует о получении данных

void h1_data(http_stream *stream, const char *data, size_t length);

stream - контекст потока (единственного)
stream_id - идентификатор потока
data - массив байт с данными
length - длина массива байт с данными

`h1_data_finished`

Сигнализирует о завершении получения данных

void h1_data_finished(http_stream *stream, rst_stream_flag rst_stream);

stream - контекст потока (единственного)
rst_stream - сигнал о том, что поток сброшен с помощью фрейма RST_STREAM, а не окончен с флагом END_STREAM

`h2_frame`

Сигнализирует о получении HTTP/2 фрейма

void h2_frame(http_stream *stream, unsigned int stream_id, enum h2_frame_type type,
              struct frame_any frame);

stream - контекст потока
stream_id - идентификатор потока
type - тип фрейма
frame - структура фрейма

`h2_headers`

Сигнализирует о получении всех заголовков в данном потоке

void h2_headers(http_stream *stream, unsigned int stream_id, struct http_headers headers);

stream - контекст потока
stream_id - идентификатор потока
headers - заголовки после распаковки

`h2_data_started`

Сигнализирует о начале передачи данных в данном потоке

bool h2_data_started(http_stream *stream, unsigned int stream_id);

stream - контекст потока
stream_id - идентификатор потока
возвращаемое значение - нужно ли применять zlib-декомпрессию данных потока

`h2_data`

Сигнализирует о получении фрейма с данными в данном потоке

void h2_data(http_stream *stream, unsigned int stream_id, struct frame_data data);

stream - контекст потока
stream_id - идентификатор потока
data - структура фрейма с данными

`h2_data_finished`

Сигнализирует о завершении получения данных в данном потоке

void h2_data_finished(http_stream *stream, unsigned int stream_id, rst_stream_flag rst_stream);

stream - контекст потока
stream_id - идентификатор потока
rst_stream - сигнал о том, что поток сброшен с помощью фрейма RST_STREAM, а не окончен с флагом END_STREAM

Utility methods

Создание, клонирование, модифицирование структур библиотеки.

sfionov/h12_library.md