Динамическое создание 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-канала на стороне сервера включает следующие шаги:

1. Подключиться к серверу имен вызовом функции NsCreate().
2. Опубликовать предоставляемые службы на сервере имен, используя функцию NsPublishService().

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

3. Получить запрос клиента на создание IPC-канала вызовом функции KnCmListen().

   Функция KnCmListen() позволяет получить первый запрос в очереди, но при этом не удаляет этот запрос, а помещает в конец очереди. Если в очереди всего один запрос, то вызов функции KnCmListen() несколько раз подряд дает один и тот же результат. Запрос удаляется из очереди при вызове функции KnCmAccept() или KnCmDrop().

4. Принять запрос клиента на создание 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.

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

1. Подключиться к серверу имен вызовом функции NsCreate().
2. Найти сервер, предоставляющий требуемую службу, используя функцию NsEnumServices().

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

3. Выполнить запрос на создание IPC-канала с требуемым сервером вызовом функции KnCmConnect().

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

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

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

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

Функции ns_api.h

Функция	Сведения о функции
NsCreate()	Назначение Создает подключение к серверу имен. Параметры [in,optional] name – указатель на имя процесса сервера имен или RTL_NULL, чтобы задать имя по умолчанию (соответствует значению макроса NS_SERVER_NAME). [in] msecs – время ожидания создания подключения к серверу имен в миллисекундах или INFINITE_TIMEOUT, чтобы задать неограниченное время ожидания. [out] 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, иначе возвращает код ошибки.

В начало