Динамическое создание IPC-каналов (cm_api.h, ns

Динамическое создание IPC-каналов (cm_api.h, ns_api.h)

API определены в следующих заголовочных файлах из состава KasperskyOS SDK:

sysroot-*-kos/include/coresrv/cm/cm_api.h;
sysroot-*-kos/include/coresrv/ns/ns_api.h.

API позволяют динамически создавать IPC-каналы.

Сведения о функциях API приведены в таблицах ниже.

Использование API

Чтобы серверы могли сообщать клиентам о предоставляемых службах, нужно включить в решение сервер имен, то есть системную программу NameServer (исполняемый файл sysroot-*-kos/bin/ns из состава KasperskyOS SDK). IPC-каналы от клиентов и серверов к серверу имен можно создать статически (эти IPC-каналы должны иметь имя kl.core.NameServer). Если этого не сделать, то при вызове клиентами и серверами функции NsCreate() будут выполнены попытки динамического создания этих IPC-каналов. Сервер имен не требуется включать в решение, если у клиентов изначально есть сведения об именах серверов и предоставляемых этими серверами служб.

Имена служб и интерфейсов нужно задавать в соответствии с формальными спецификациями компонентов решения. (О квалифицированном имени службы см. "Привязка методов моделей безопасности к событиям безопасности".) Вместо квалифицированного имени службы можно использовать какое-либо условное название этой службы. Имена клиентов и серверов задаются в init-описании. Также имя процесса можно получить вызовом функции KnTaskGetName() из API task_api.h.

Динамическое создание IPC-канала на стороне сервера включает следующие шаги:

Подключиться к серверу имен вызовом функции NsCreate().
Опубликовать предоставляемые службы на сервере имен, используя функцию NsPublishService().
Чтобы отменить публикацию службы, нужно вызвать функцию NsUnPublishService().
Получить запрос клиента на создание IPC-канала вызовом функции KnCmListen().
Функция KnCmListen() позволяет получить первый запрос в очереди, но при этом не удаляет этот запрос, а помещает в конец очереди. Если в очереди всего один запрос, то вызов функции KnCmListen() несколько раз подряд дает один и тот же результат. Запрос удаляется из очереди при вызове функции KnCmAccept() или KnCmDrop().
Принять запрос клиента на создание IPC-канала вызовом функции KnCmAccept().
Чтобы отклонить запрос клиента, нужно вызвать функцию KnCmDrop().

Слушающий дескриптор создается при вызове функции KnCmAccept() со значением INVALID_HANDLE в параметре listener. Если указать слушающий дескриптор, то созданный серверный IPC-дескриптор обеспечит возможность получать IPC-запросы по всем IPC-каналам, ассоциированным с этим слушающим дескриптором. (Первый IPC-канал, ассоциированный со слушающим дескриптором, создается при вызове функции KnCmAccept() со значением INVALID_HANDLE в параметре listener. Второй и последующие IPC-каналы, ассоциированные со слушающим дескриптором, создаются при втором и последующих вызовах функции KnCmAccept() с указанием дескриптора, полученного при первом вызове.) В параметре listener функции KnCmAccept() можно указать слушающий дескриптор, полученный с использованием функций KnHandleConnect(), KnHandleConnectEx() и KnHandleCreateListener() из API handle_api.h, а также функции ServiceLocatorRegister(), объявленной в заголовочном файле sysroot-*-kos/include/coresrv/sl/sl_api.h из состава KasperskyOS SDK. В параметре rsid функции KnCmAccept() нужно указать идентификатор службы (RIID), который является константой в автоматически генерируемом транспортном коде (например, FsDriver_operationsComp_fileOperations_iid).

Динамическое создание IPC-канала на стороне клиента включает следующие шаги:

Подключиться к серверу имен вызовом функции NsCreate().
Найти сервер, предоставляющий требуемую службу, используя функцию NsEnumServices().
Чтобы получить полный список служб с заданным интерфейсом, нужно вызвать функцию несколько раз, инкрементируя индекс, пока не будет получена ошибка rcResourceNotFound.
Выполнить запрос на создание IPC-канала с требуемым сервером вызовом функции KnCmConnect().

К серверу имен можно подключить несколько клиентов и серверов. Каждый клиент и сервер может создать несколько подключений к серверу имен. Сервер может отменить публикацию службы, выполненную другим сервером.

Чтобы удалить подключение к серверу имен, нужно вызвать функцию NsDestroy().

Удаление динамически созданных IPC-каналов

Динамически созданный IPC-канал будет удален при закрытии его клиентского и серверного IPC-дескрипторов.

Сведения о функциях API

Функции ns_api.h

Функция	Сведения о функции
`NsCreate()`	Назначение Создает подключение к серверу имен. Параметры [in,optional] `name` – указатель на имя процесса сервера имен или `RTL_NULL`, чтобы задать имя по умолчанию (соответствует значению макроса `NS_SERVER_NAME`). [in] `msecs` – время ожидания создания подключения к серверу имен в миллисекундах или `INFINITE_TIMEOUT`, чтобы задать неограниченное время ожидания. [out] `ns` – указатель на идентификатор подключения к серверу имен. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки.
`NsDestroy()`	Назначение Удаляет подключение к серверу имен. Параметры [in] `ns` – идентификатор подключения к серверу имен. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки.
`NsPublishService()`	Назначение Публикует службу на сервере имен. Параметры [in] `ns` – идентификатор подключения к серверу имен. [in] `type` – указатель на имя интерфейса службы. [in,optional] `server` – указатель на имя сервера, предоставляющего службу, или `RTL_NULL`, чтобы использовать имя вызывающего процесса. [in] `service` – указатель на квалифицированное имя службы. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки.
`NsUnPublishService()`	Назначение Отменяет публикацию службы на сервере имен. Параметры [in] `ns` – идентификатор подключения к серверу имен. [in] `type` – указатель на имя интерфейса службы. [in,optional] `server` – указатель на имя сервера, предоставляющего службу, или `RTL_NULL`, чтобы использовать имя вызывающего процесса. [in] `service` – указатель на квалифицированное имя службы. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки.
`NsEnumServices()`	Назначение Перечисляет службы, опубликованные на сервере имен. Параметры [in] `ns` – идентификатор подключения к серверу имен. [in] `type` – указатель на имя интерфейса служб. [in] `index` – индекс для перечисления служб. Нумерация начинается с нуля. [out] `server` – указатель на буфер для имени сервера, предоставляющего службу. [in] `serverSize` – размер буфера для имени сервера, предоставляющего службу, в байтах. [out] `service` – указатель на буфер для квалифицированного имени службы. [in] `serviceSize` – размер буфера для квалифицированного имени службы в байтах. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки.

Функции cm_api.h

Функция	Сведения о функции
`KnCmConnect()`	Назначение Выполняет запрос на создание IPC-канала с сервером для использования заданной службы. Параметры [in] `server` – указатель на имя сервера. [in] `service` – указатель на квалифицированное имя службы. [in] `msecs` – время ожидания выполнения запроса в миллисекундах или `INFINITE_TIMEOUT`, чтобы задать неограниченное время ожидания. [out] `handle` – указатель на клиентский IPC-дескриптор. [out] `rsid` – указатель на идентификатор службы (RIID). Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки.
`KnCmListen()`	Назначение Позволяет получить запрос клиента на создание IPC-канала для использования службы. Параметры [in] `filter` – фиктивный параметр, который должен иметь значение `RTL_NULL`. [in] `msecs` – время ожидания появления запроса клиента в миллисекундах или `INFINITE_TIMEOUT`, чтобы задать неограниченное время ожидания. [out] `client` – указатель на имя клиента. [out] `service` – указатель на квалифицированное имя службы. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки.
`KnCmDrop()`	Назначение Отклоняет запрос клиента на создание IPC-канала для использования заданной службы. Параметры [in] `client` – указатель на имя клиента. [in] `service` – указатель на квалифицированное имя службы. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки.
`KnCmAccept()`	Назначение Принимает запрос клиента на создание IPC-канала для использования заданной службы. Параметры [in] `client` – указатель на имя клиента. [in] `service` – указатель на квалифицированное имя службы. [in] `rsid` – идентификатор службы (RIID). [in,optional] `listener` – слушающий дескриптор или `INVALID_HANDLE`, чтобы создать его. [out] `handle` – указатель на серверный IPC-дескриптор. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки.

В начало