From afd9a00a0314997fdce6e901d046fd3632a1fac5 Mon Sep 17 00:00:00 2001 From: nikita Date: Fri, 27 Mar 2026 01:04:25 +0300 Subject: [PATCH] Update README.md --- README.md | 61 ++++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 49 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index e77aaa5..eefb27a 100644 --- a/README.md +++ b/README.md @@ -4,13 +4,13 @@ ## Терминология -- **среда передачи** - то, через что передаются данные. Например, расширение `vk-msg` реализует передачу данные через сообщения ВК. +- **среда передачи** - то, через что передаются данные. Например, расширение `vk-msg` реализует передачу данных через сообщения ВК. Значит, в контексте расширения `vk-msg` "отправить данные через среду передачи" означает "отправить данные, закодировав их в сообщение"; - а "принятие данных из среды передачи" - "принятие сообщения в ВК и его декодировка в двоичный вид". + а "принять данные из среды передачи" - "принять сообщение в ВК и декодировать его в двоичный вид". ## Архитектура -- **`main.c` - входная точка приложения, оркестратор** +- **`main.c` - входная точка приложения** - **`event_loop.c`, `event_loop.h` - реализация событийного цикла**\ Здесь реализована асинхронная обработка событий через `epoll` - **`connection.c`, `connection.h` - реализация соединения**\ @@ -28,9 +28,7 @@ ## Разработка расширений -Расширение в своем заголовочном файле должно реализовывать функцию `void medium__init()`, которая инициализирует всё необходимое для работы расширения. Функция должна вызвать `medium_set_callbacks(...)`, чтобы IPoIM могло взаимодействовать с расширением. Кроме этого расширение должно инициализировать всё, что ему необходимо для работы. - -Также расширение должно реализовывать функцию `void medium__deinit()`, которая освобождает ресурсы и выполняет "правильное" завершение всего, что было инициализировано в ходе работы расширения. +В своем заголовочном файле расширение должно реализовывать только функцию `void medium__setup_callbacks()`, которая настроит колбеки (см. далее). Никаких других "публичных" функций у расширения быть не должно, поскольку всё взаимодействие с расширением производится через колбеки, которое оно настраивает. ### Medium API @@ -66,28 +64,67 @@ IPoIM реализует функции, которые позволяют ра - **Что делает:** - Сообщает IPoIM, какое максимальное количество байтов можно передать `cbmed_on_send_data(...)` - **Когда вызывать:** - - При изменении максимального количества байтов `cbmed_on_send_data(...)` + - При изменении максимального количества байтов, которое может принять `cbmed_on_send_data(...)` - **Заметки:** - - Изначально IPoIM предполагает, что среда передачи может передать 1024 Б за один вызов `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`) + - `events` - битовая маска событий (см. `man epoll_ctl`) - **Возвращаемое значение:** нет - **Заметки**: нет - **`int32_t cbmed_on_send_data(const void *data, int32_t size)`** - - **Когда вызвается:** + - **Когда вызывается:** - IPoIM хочет отправить данные через среду передачи - **Желаемый исход:** - IPoIM ожидает, что после вызова этого колбека, данные отправлены или запланированы к отправке @@ -100,4 +137,4 @@ IPoIM реализует функции, которые позволяют ра - **Заметки**: - Гарантируется `size > 0` - Гарантируется `size <= max_send_size` (см. `medium_set_max_send_size(...)`) - - Гарантируется, что этот колбек не будет вызван, если расширение не сообщило, что оно готово к отправке данных через среду передачи (см. `medium_set_ready_to_send(...)`) \ No newline at end of file + - Гарантируется, что этот колбек не будет вызван, если расширение сообщило, что оно не готово к отправке данных через среду передачи (см. `medium_set_ready_to_send(...)`) \ No newline at end of file