Update README.md

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_<NAME>_init()`, которая инициализирует всё необходимое для работы расширения. Функция должна вызвать `medium_set_callbacks(...)`, чтобы IPoIM могло взаимодействовать с расширением. Кроме этого расширение должно инициализировать всё, что ему необходимо для работы.
-
-Также расширение должно реализовывать функцию `void medium_<NAME>_deinit()`, которая освобождает ресурсы и выполняет "правильное" завершение всего, что было инициализировано в ходе работы расширения.
+В своем заголовочном файле расширение должно реализовывать только функцию `void medium_<NAME>_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(...)`)
+        - Гарантируется, что этот колбек не будет вызван, если расширение сообщило, что оно не готово к отправке данных через среду передачи (см. `medium_set_ready_to_send(...)`)