Техническая документация Heredes

01. API. Инициализация библиотеки

функция параметры
InitIONLibrary Синтаксис:
void InitIONLibrary (void);
параметры у данной функции отсутствуют. Основная цель данной функции - инициализация использования Winsock DLL в вашем приложении
данную функцию Ваше приложение должно вызвать однократно перед использованием Heredes API

02. API. Получить дескриптор нового подключения

функция параметры
CreateIONHandle Синтаксис:
HANDLE CreateIONHandle (void);
параметры у данной функции отсутствуют. Создает окружение для нового входящего (сервер) или исходящего (клиент) подключения. Возвращает дескриптор подключения
Пример:
HANDLE hDcon = CreateIONHandle();

03. API. закрыть дескриптор подключения

функция параметры
CloseIONHandle Синтаксис:
CloseIONHandle(HANDLE hConn); в качестве параметра принимает дескриптор подключения полученый функцией CreateIONHandle
Функция закрывает дескрипторы созданные функцией CreateIONHandle и освобождает регион памяти занятый окружением подключения
Пример:
HANDLE hDcon = CreateIONHandle();
CloseIONHandle(hDcon);

04. API. Регистрация и клонирование пользователя, исходящее подключение, ожидание входящего подключения

функция параметры
IONConnect Синтаксис:
void IONConnect(HANDLE hConn,
DWORD RemId,
LPDWORD LocValid,
LPDWORD LocId,
CBSTATUS CBStatus,
CBUDATA CBUserData);

hConn - дескриптор подключения полученный функцией CreateIONHandle

RemId - уникальный идентификатор сервера к которому требуется подключиться.
данный параметр должен быть 0 для сервера ожидающего входящие соединения.
Так же данный указатель может быть -1 для клонирования существующего идентификатора
При активном входящем подключении другие пользователи не смогут инициировать подключение к вам. Если Вы хотите реализовать многопоточное взоимодействие на стороне сервера, клонируйте ваш личный идентификатор
Данный параметр не может быть ноль при исходящем подключении так как это вызовет ожидание входящего соединение.
Данный параметр не учитывается при значении переменной на которую ссылается LocId равном нулю

LocValid - указатель на переменную содержащую код подтверждения владельца идентификатора. Значение переменной не учитывается при значении LocId равном нулю

LocId - указатель на переменную содержащую личный идентификатор. Переменная должна быть равна нулю если требуется зарегистрировать новый идентификатор
подробнее об идентификаторах

CBStatus - указатель СallBack функцию StatusProc обработки состояний подключения. Данный параметр может быть равен нулю если вы хотите использовать обработчик по умолчанию.
Прототип функции StatusProc
подробнее о состояниях подключения

CBUserData - указатель СallBack функцию CBUserData обработки пользовательских данных. Данный параметр может быть равен нулю если вы хотите использовать обработчик по умолчанию или Ваше приложение не планирует получать и обрабатывать произвольные данные отправленные другими пользователями.
Прототип функции CBUserData

Данная функция работает асинхронно и не приостанавливает выполнение программы. После вызова IONConnect управление возвращается вашему приложению немедленно.

Для регистрации нового или создания клона существующего пользователя воспользоваться вы можете так же воспользоваться синхронной функцией RegIONId

Для установления ожидания входящего подключения Вы можете использовать так же IONWaitConnection

Об идентификаторах пользователей

Установление соединение между пользователями осуществляется посредством личных уникальных идентификаторов.

Идентификатор пользователя это число от 0х1 до 0хFFFFFFF0 (32 бита)

Когда пользователь запрашивает у STUN сервера параметры исходящего подключения либо уведомляет STUN сервер о готовности принять входящее соединение он передает личный идентификатор и ключ подтверждающий регистрацию

Ключ подтверждения идентификатора это так же число от 0х1 до 0хFFFFFFF0 (32 бита)

STUN сервер сверяет соответствие личного идентификатора с ключем подтверждения

Таким образом осуществляется два уровня безопасности: проверка STUN сервером пользователя на валидность (не считается безопасной) и использование пользователями секретных ключей шифрования которые могут не передаваться по сети в зависимости от реализации вашим программным обеспечением. Кроме того Вы можете при передаче личных данных осуществлять свою систему шифрования, алгоритм которой может быть известен только Вам

Для регистрации нового пользователя и получения личного идентификатора и кода подтверждения следует использовать функции RegIONId или IONConnect

О состояниях подключения

Для определения текущего состояния соединения вы можете использовать Callback функцию, которая получает уведомления о состоянии - статус состояния

статус описание
0 соединение с STUN сервером не установлено
1 соединение с STUN сервером активно
2 получены данные для прямого подключения
3 попытка установить прямое подключение и проверка секретного ключа
4 ошибка секретного ключа шифрования
5 секретный ключ согласован
6 соединение успешно установлено. возможен прямой обмен данными

05.1. API. сбросить соединение

функция параметры
void IONDisconnect Синтаксис:
void IONDisconnect(HANDLE hConn);

hConn - дескриптор подключения полученный функцией CreateIONHandle

Разрывает текущее активное соединение или прекращает попытки установить соединение. Данную функцию следует вызывать так же в случае если соединение было сброшено одной из сторон или было неудачным. Если вы указали в качестве параметра дескриптор полученый для сервера, то сервер перестанет ожидать входящего соединения. Данная функция выполняется синхронно и не вернет управление приложению пока не завершит корректное отключение

Не следует передавать функции дескриптор полученый функцией IONWaitConnection. Для отмены ожидания вызваного IONWaitConnection следует использовать IONTerminate

05.2. API. сбросить соединение

функция параметры
void IONTerminate Синтаксис:
void IONTerminate(HANDLE hConn);

hConn - дескриптор подключения полученный функцией IONWaitConnection

Разрывает текущее активное соединение или прекращает попытки установить соединение. Данную функцию следует вызывать так же в случае если соединение было сброшено одной из сторон или было неудачным. Если вы указали в качестве параметра дескриптор полученый для сервера, то сервер перестанет ожидать входящего соединения. Данная функция выполняется синхронно и не вернет управление приложению пока не завершит корректное отключение

Не следует передавать функции дескриптор полученый функцией CreateIONHandle.

06. API Установить ключ безопасности

функция параметры
SetSecureKey Синтаксис:
void SetSecureKey(HANDLE hConn,
PVOID UserDataAddr);

hConn - дескриптор подключения полученный функцией CreateIONHandle

hUserDataAddr - указатель на 16 байтную строку с произвольным набором значений.
Данная строка будет являться секретным ключем для шифрования пользовательских данных

Рекомендуется обрабатывать уведомления о статусе для установки собственного ключа шифрования и вызывать SetSecureKey в ответ на уведомление о статусе 3

В ответ на уведомление о статусе 4, ваше приложение может вызывать функцию UpdateSecureKey

вы можете не использовать секретный ключ и не вызывать функцию SetSecureKey если усиленное шифрование не требуется. В этом случае шифрование будет производиться небезопасным сессионным ключом

Вам следует решить использовать ли секретные ключи так как клиентское и серверное приложение должны использовать равную политику безопасности. Если для клиентского приложения секретный ключ не установлен а для серверного устанавливается или наоборот то соединение будет прервано.

07. API Обновить ключ безопасности

функция параметры
UpdateSecureKey Синтаксис:
void UpdateSecureKey(HANDLE hConn,
PVOID UserDataAddr);

hConn - дескриптор подключения полученный функцией CreateIONHandle

hUserDataAddr - указатель на 16 байтную строку с произвольным набором значений.
Данная строка будет являться секретным ключем для шифрования пользовательских данных

Рекомендуется обрабатывать уведомления о статусе для установки собственного ключа шифрования и вызывать SetSecureKey в ответ на уведомление о статусе 4

Если на момент соединения клиентское и серверное приложение имеют разные секретные ключи шифрования то их следует синхронизировать, но вызов UpdateSecureKey должна осуществлять только одна из сторон, при этом вторая сторона не должна сбрасывать соединение в ответ на статус 4. В случае если принимающая сторона отклонит запрос на обновление ключа, соединение будет прервано

если тебуется повышеный уровень безопасности то следует использовать другие способы доставки секретных ключей между клиентом и сервером или использовать статичный сохраненный ключ соединения

08. API Передача пользовательских данных неопределенного типа

функция параметры
SendUserData Синтаксис:
int SendUserData(HANDLE hConn,
PVOID UserDataAddr
DWORD LongData);

hConn - дескриптор подключения полученный функцией CreateIONHandle или IONWaitConnection

hUserDataAddr - указатель строку с произвольными пользовательскими данными

LongData - длинна пользовательских данных

фнкция возвращает количество байт поставленных в очередь на отправку и не гарантирует их доставку. Ваше приложение должно организовать при необходимости подтверждение получения данных

следует учитывать что серверное приложение будет отправлять пользовательские данные блоками от 30 до 1006 байт и Ваше приложение должно самостоятельно разбить отправляемые данные на части и маркировать в каком порядке их следует собрать. Так же Ваше приложение должно обеспечить целостность полученных данных, запросив повторную отправку утерянного блока если требуется гарантированная доставка

Ваше приложение может использовать дополнительные произвольные алгоритмы шифрования перед вызовом SendUserData для усиления безопасности

следует принять во внимание что SendUserData может использоваться только для передачи данных при активном коннекте (статус 6)

09. API Передача файлов

функция параметры
IONSendFileToId Синтаксис:
long IONSendFileToId(LPDWORD pValid, LPDWORD pId, CBSELID CBSelUser, LPDWORD pHightDword);

pValid - указатель на переменную типа DWORD содержащую код подтверждения владельца идентификатора

pId - указатель на переменную типа DWORD содержащую идентификатор

CBSelUse - указатель на CALLBACK процедуру для обработки WM_COMMAND. Вы можете использовать данную функцию для предоставления пользователю выбора идентификатора, создания интерфейсов и тд. Может быть NULL если Id получателя пользователь вводит только вручную

pHightDword - указатель на старшие 4 байта размера переданых байт

фнкция возвращает младшие 4 байта размера переданных байт

если старший бит в значении по адресу pHightDword установлен в 1 (значение более 0х80000000) значит произошла ошибка при передаче данных и файл передан не полностью. Ваше приложение должно самостоятельно решать как обрабатывать подобные ошибки

Таким образом теоретическое верхнее ограничение на размер передаваемого файла соответствено 8 388 608 ТБт, тем не менее стоит учитывать что передача ведется поверх UDP и подвержено помехам, таким образом не исключены непредсказуемые сбои в процессе передачи, не все из которых способна обработать данная функция

данная функция использует GUI и не должна применяться в приложениях для которых графический интерфейс не доступен. Вместо этого вы можете реализовать пересылку данных посредством SendUserData