ipoim/README.md

Internet Protocol over Incidental Medium

IPoIM - это средство для туннелирования SOCKS5 соединения через среду передачи, которая не предназначена для туннелирования таких соединений. IPoIM разрабатывается в расчёте на то, что к нему можно без больших усилий дописывать расширения на языке C.

Терминология

• среда передачи - то, через что передаются данные. Например, расширение vk-msg реализует передачу данных через сообщения ВК. Значит, в контексте расширения vk-msg "отправить данные через среду передачи" означает "отправить данные, закодировав их в сообщение"; а "принять данные из среды передачи" - "принять сообщение в ВК и декодировать его в двоичный вид".

Архитектура

• main.c - входная точка приложения
• event_loop.c, event_loop.h - реализация событийного цикла
  Здесь реализована асинхронная обработка событий через epoll
• connection.c, connection.h - реализация соединения
  Здесь реализован контроль за существующим соединением.
• client.c, client.h - реализация клиента
  Здесь реализовано установление соединения с сервером.
• server.c, server.h - реализация сервера
  Здесь реализован сервер.
• priv_medium.c, priv_medium.h
  Здесь реализованы внутренние функции IPoIM, связанные с Medium API. Эти функции не должны вызываться из кода расширений.
• medium.c, medium.h
  Здесь реализованы функции Medium API, которые вызываются из кода расширения.
• mediums/medium_<NAME>.c, mediums/medium_<NAME>.h
  Реализация расширений. Например, файлы medium_vk_msg.c и medium_vk_msg.h реализуют среду передачи vk-msg.

Разработка расширений

В своем заголовочном файле расширение должно реализовывать только функцию void medium_<NAME>_setup_callbacks(), которая настроит колбеки (см. далее). Никаких других "публичных" функций у расширения быть не должно, поскольку всё взаимодействие с расширением производится через колбеки, которое оно настраивает.

Medium API

IPoIM реализует функции, которые позволяют расширению общаться с остальным приложением:

• void medium_epoll_ctl(int op, int fd, struct epoll_event *ev)
  • Что делает:
    • Вызывает epoll_ctl для дескриптора epoll, который отвечает за событийный цикл
  • Когда вызывать:
    • Когда нужно добавить, модифицировать или удалить описание файлового дескриптора в epoll
  • Заметки:
    • Если был вызван close(...) для файлового дескриптора, то не нужно вызывать эту функцию, чтобы удалить описание дескриптора из epoll. Ядро Linux само удаляет описание из epoll, если дескриптор закрывается
• void medium_set_callbacks(/* колбеки в порядке их перечисления в следующей главе */)
  • Что делает:
    • Сообщает IPoIM, какие функции соответствуют каким колбекам
  • Когда вызывать:
    • Инициализация расширения
  • Заметки: нет
• void medium_on_recv_data(const void *data, int32_t size)
  • Что делает:
    • Сообщает IPoIM, что из среды передачи были получены данные
  • Когда вызывать:
    • При получении данных из среды передачи
  • Заметки:
    • No-op, если data == NULL или size <= 0
• void medium_set_ready_to_send(bool state)
  • Что делает:
    • Сообщает IPoIM, готово ли расширение к вызову cbmed_on_send_data(...)
  • Когда вызывать:
    • При изменении готовности к вызову cbmed_on_send_data(...) и при инициализации
  • Заметки:
    • Изначально IPoIM предполагает, что среда передачи недоступна. Поэтому эта функция должна быть вызвана, как только расширение становится готовым к вызову cbmed_on_send_data(...) после инициализации
• void medium_set_max_send_size(int32_t size)
  • Что делает:
    • Сообщает IPoIM, какое максимальное количество байтов можно передать cbmed_on_send_data(...)
  • Когда вызывать:
    • При изменении максимального количества байтов, которое может принять cbmed_on_send_data(...)
  • Заметки:
    • До первого вызова этой функции IPoIM предполагает, что среда передачи может передать 1024 Б за один вызов cbmed_on_send_data(...)
    • Не допускается size <= 0
• void medium_start_timer(uint32_t id, int32_t ms)
  • Что делает:
    • Ставит таймер #id на ms миллисекунд. Отрицательные значения ms останавливают таймер
  • Когда вызывать:
    • При необходимости выполнить что-либо через какое-либо время по таймеру
  • Заметки:
    • По истечении таймера будет вызван колбек cbmed_on_timer(...), а в качестве аргумента будет передано значение id

Необходимые колбеки

Все колбеки, которые вызывает IPoIM рекомендуется называть с префиксом cbmed_ (callback medium).

Время от времени IPoIM обращается к расширению, чтобы отправить данные. Чтобы IPoIM мог это делать, расширение должно реализовывать следующие колбеки:

• bool cbmed_on_init()
  • Когда вызывается:
    • IPoIM хочет инициализировать расширение
  • Желаемый исход:
    • IPoIM ожидает, что расширение инициализирует всё, что ему нужно для работы, и будет готово к работе
  • Аргументы: нет
  • Возвращаемое значение:
    • true в случае успеха
    • false в случае провала
  • Заметки:
    • эта функция никогда не будет вызвана больше, чем один раз
    • до вызова этой функции работа с расширением не производится
• void cbmed_on_deinit()
  • Когда вызывается:
    • IPoIM завершает работу и освобождает ресурсы
  • Желаемый исход:
    • IPoIM ожидает, что расширение освободит все ресурсы, которые оно выделило
  • Аргументы: нет
  • Возвращаемое значение: нет
  • Заметки:
    • эта функция никогда не будет вызвана больше, чем один раз
    • после вызова этой функции работа с расширением не производится
• void cbmed_on_timer(uint32_t id)
  • Когда вызывается:
    • Истек таймер, который был запущен функцией medium_start_timer(...)
  • Желаемый исход:
    • IPoIM ничего не ожидает от расширения, оно может выполнить здесь любые действия
  • Аргументы:
    • id - идентификатор таймера, который использовался в medium_start_timer(...)
  • Возвращаемое значение: нет
  • Заметки:
    • даже если этот колбек не используется, он всё равно должен существовать, но иметь пустое тело
• void cbmed_on_fd_event(int fd, uint32_t events)
  • Когда вызывается:
    • С файловым дескриптором, добавленным при помощи medium_epoll_ctl(...), что-то случилось
  • Желаемый исход:
    • IPoIM ожидает, что расширение выполнит нужные действия над файловыми дескрипторами, которые оно добавило в epoll
  • Аргументы:
    • fd - файловый дескриптор
    • events - битовая маска событий (см. man epoll_ctl)
  • Возвращаемое значение: нет
  • Заметки: нет
• int32_t cbmed_on_send_data(const void *data, int32_t size)
  • Когда вызывается:
    • IPoIM хочет отправить данные через среду передачи
  • Желаемый исход:
    • IPoIM ожидает, что после вызова этого колбека, данные отправлены или запланированы к отправке
  • Аргументы:
    • data - двоичные данные, которые нужно отправить через среду передачи
    • size - размер двоичный данных в байтах
  • Возвращаемое значение:
    • В случае успеха колбек должен вернуть число байтов, ушедших в среду передачи
    • Если передача провалена, то колбек должен -1
  • Заметки:
    • Гарантируется size > 0
    • Гарантируется size <= max_send_size (см. medium_set_max_send_size(...))
    • Гарантируется, что этот колбек не будет вызван, если расширение сообщило, что оно не готово к отправке данных через среду передачи (см. medium_set_ready_to_send(...))