Использование базового API (dcm_api.h)

API определен в заголовочном файле sysroot-*-kos/include/coresrv/dcm/dcm_api.h из состава KasperskyOS SDK.

Общие сведения об использовании API:

• Серверы публикуют в DCM службы и/или экземпляры компонентов (контейнеры служб).
• Клиенты получают уведомления о публикации отдельных служб и/или экземпляров компонентов.
• Для использования каждой службы сервера создается отдельный IPC-канал, идентифицируемый на стороне клиента callable-дескриптором.
• Если клиенту требуется использовать службу сервера, то этот клиент может выполнить запрос серверу на создание одного IPC-канала для использования этой службы.
• Если клиенту требуется использовать набор служб сервера, предоставляемых экземпляром компонента, то этот клиент может выполнить запрос серверу на создание нескольких IPC-каналов для использования этого набора служб.

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

Динамическое создание IPC-каналов на стороне сервера

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

1. Создать подключение к DCM вызовом функции DcmInit().
2. Опубликовать предоставляемые службы и/или экземпляры компонентов в DCM, используя функцию DcmPublishEndpoint() и/или DcmPublishComponent().

   Функция DcmPublishEndpoint() публикует службу сервера, а функция DcmPublishComponent() публикует экземпляр компонента сервера.

   В параметре serverHandle функций DcmPublishEndpoint() и DcmPublishComponent() нужно указать дескриптор, идентифицирующий сервер. В качестве дескриптора, идентифицирующего сервер, можно использовать дескриптор этого серверного процесса, полученный последовательностью вызовов функций KosTaskGetSelf() и KosTaskGetHandle() из API task.h, или дескриптор, созданный вызовом функции KnHandleCreateUserObject() из API handle_api.h. (При вызове функции KnHandleCreateUserObject() в параметре rights должны быть указаны флаги OCAP_HANDLE_TRANSFER и OCAP_HANDLE_GET_SID.) Клиенты могут получить потомка дескриптора, идентифицирующего серверный процесс, через опциональный параметр outServerHandle функции DcmReadPubQueue(). После публикации службы или экземпляра компонента дескриптор, идентифицирующий сервер, можно закрыть, но только если этот дескриптор не был получен вызовом функции KosTaskGetHandle(). (Дескриптор, полученный вызовом функции KosTaskGetHandle(), закрывать нельзя, так как в случае закрытия он может быть использован для идентификации других ресурсов, что приведет к ошибкам.)

   В результате вызова функции DcmPublishEndpoint() создается DCM-дескриптор, позволяющий получать запросы клиентов на создание IPC-канала для использования заданной службы. В результате вызова функции DcmPublishComponent() создается DCM-дескриптор, позволяющий получать запросы клиентов на создание нескольких IPC-каналов для использования набора служб заданного экземпляра компонента.

   Чтобы отменить публикацию службы или экземпляра компонента, нужно вызовом функции DcmCloseHandle() закрыть DCM-дескриптор, созданный при их публикации. Также публикация всех опубликованных служб и экземпляров компонентов сервера будет отменена, если сервер завершится.

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

   Вызовы функции DcmListen() с одним и тем же DCM-дескриптором в параметре pubHandle позволяют получить только те запросы клиентов, которые направлены на создание IPC-канала (IPC-каналов) для использования той службы или того набора служб экземпляра компонента, которые были заданы при создании этого DCM-дескриптора на шаге 2. (Сервер получает также запросы клиентов, которые были выполнены до публикации службы или экземпляра компонента.)

   Через опциональные параметры outClientHandle и outClientName функции DcmListen() можно получить дескриптор, идентифицирующий клиента, и имя клиента соответственно. (Дескриптор, идентифицирующий клиента, является потомком дескриптора, указанного в параметре clientHandle функции DcmCreateConnection(), вызванной на стороне клиента.) Эти данные можно использовать, чтобы принять решение о принятии или отклонении запроса клиента. При этом дескриптор, идентифицирующий клиента, может быть использован, например, для получения сведений о клиенте от других процессов или для получения SID по этому дескриптору для сравнения с другими имеющимся у сервера дескрипторами, идентифицирующими клиентов. После принятия решения можно закрыть дескриптор, идентифицирующий клиента.

   В результате вызова функции DcmListen() создается DCM-дескриптор, позволяющий принять или отклонить запрос клиента на создание IPC-канала (IPC-каналов).

4. Принять запрос клиента на создание IPC-канала (IPC-каналов) вызовом функции DcmAcceptEndpointConnection() или DcmAcceptComponentConnection().

   Функция DcmAcceptEndpointConnection() принимает запрос клиента на создание IPC-канала для использования службы сервера, а функция DcmAcceptComponentConnection() принимает запрос клиента на создание IPC-каналов для использования набора служб экземпляра компонента сервера.

   В параметре connectionId функций DcmAcceptEndpointConnection() и DcmAcceptComponentConnection() нужно указать DCM-дескриптор, полученный на шаге 3.

   В параметре sessionHandleDesc функции DcmAcceptEndpointConnection() нужно указать транспортный контейнер дескриптора, который содержит callable-дескриптор для использования службы. В параметре sessionHandlesCnt функции DcmAcceptComponentConnection() нужно указать число служб, предоставляемых экземпляром компонента, то есть число служб перечисленных в CDL-файле. Через параметр sessionHandleDescs функции DcmAcceptComponentConnection() нужно задать массив транспортных контейнеров дескрипторов, которые содержат callable-дескрипторы для использования набора служб экземпляра компонента. Порядок элементов в массиве должен соответствовать порядку перечисления служб в CDL-файле. Можно предоставить доступ только к части служб экземпляра компонента. Для служб, которые не будут предоставлены клиенту, вместо callable-дескрипторов нужно указать значение INVALID_HANDLE. Как минимум один элемент массива должен содержать callable-дескриптор.

   Чтобы создать callable-дескриптор, нужно вызвать функцию KnHandleCreateUserObjectEx() из API handle_api.h. При вызове функции KnHandleCreateUserObjectEx() в параметре rights должны быть указаны флаги OCAP_IPC_CALL и OCAP_HANDLE_TRANSFER, а в параметрах ipcChannel и riid требуется указать серверный IPC-дескриптор создаваемого IPC-канала и идентификатор службы (RIID) соответственно. Серверный IPC-дескриптор используется для инициализации IPC-транспорта и управления обработкой IPC-запросов на стороне сервера. Для создания серверного дескриптора можно использовать функцию KnHandleCreateListener() из API handle_api.h. Идентификатор службы является константой в автоматически генерируемом транспортном коде, например, FsDriver_operationsComp_fileOperations_iid. После принятия запроса клиента callable-дескриптор можно закрыть.

   Чтобы поместить callable-дескриптор в транспортный контейнер дескриптора, нужно использовать макрос nk_handle_desc(), который определен в заголовочном файле sysroot-*-kos/include/nk/types.h из состава KasperskyOS SDK. В качестве второго параметра макроса nk_handle_desc() можно указать макрос NK_SAME, определенный в том же заголовочном файле. В этом случае потомок переданного callable-дескриптора будет иметь ту же маску прав, что и переданный callable-дескриптор. Передачу callable-дескриптора клиенту можно ассоциировать с объектом контекста передачи ресурса, указав дескриптор этого объекта в третьем параметре макроса nk_handle_desc(). Это позволит, используя API notice_api.h, отследить, когда будут закрыты или отозваны потомки callable-дескриптора, которые образуют поддерево наследования дескрипторов, корневой узел которого порожден передачей клиенту этого callable-дескриптора. Переданный callable-дескриптор может быть закрыт клиентом, но также закрытие этого дескриптора выполняется в результате завершения клиента. Чтобы создать объект контекста передачи ресурса, нужно вызвать функцию KnHandleCreateBadge() из API handle_api.h.

   Через параметр context функций KnHandleCreateUserObjectEx() и KnHandleCreateBadge() можно задать данные для ассоциации с callable-дескриптором и передачей callable-дескриптора соответственно (аналогично контексту пользовательского ресурса и контексту передачи ресурса). Сервер сможет получить указатель на эти данные при разыменовании callable-дескриптора. (Несмотря на то что callable-дескриптор является IPC-дескриптором, он помещается ядром в поле base_.self фиксированной части IPC-запроса.)

   Чтобы отклонить запрос клиента на создание IPC-канала (IPC-каналов), нужно вызовом функции DcmCloseHandle() закрыть DCM-дескриптор, полученный на шаге 3. (При этом вызов функции DcmConnectToEndpoint() или DcmConnectToComponent() на стороне клиента завершится с ошибкой rcNotConnected.) В случае принятия запроса клиента DCM-дескриптор, полученный на шаге 3, нужно также закрыть, но после вызова функции DcmAcceptEndpointConnection() или DcmAcceptComponentConnection().

Динамическое создание IPC-каналов на стороне клиента

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

1. Создать подключение к DCM вызовом функции DcmInit().

   Если клиенту требуется использовать отдельную службу (не набор служб экземпляра компонента), то вместо выполнения последующих шагов можно вызвать функцию DcmConnectAny() или DcmConnectAnyEx() из вспомогательного API для клиентов connect.h.

2. Создать DCM-дескриптор, позволяющий получать уведомления о публикации и отмене публикации служб с заданным интерфейсом или экземпляров компонента с заданным именем.

   Чтобы выполнить этот шаг, нужно вызвать функцию DcmSubscribeToEndpoints() или DcmSubscribeToComponents(). Функция DcmSubscribeToEndpoints() создает DCM-дескриптор, позволяющий получать уведомления о публикации и отмене публикации служб с заданным интерфейсом, а функция DcmSubscribeToComponents() создает DCM-дескриптор, позволяющий получать уведомления о публикации и отмене публикации экземпляров компонента с заданным именем.

   Опциональные параметры endpointName, componentName serverName и serverHandle функций DcmSubscribeToEndpoints() и DcmSubscribeToComponents() нужно использовать, чтобы включить фильтрацию уведомлений по квалифицированному имени службы, квалифицированному имени экземпляра компонента, имени сервера и дескриптору, идентифицирующему сервер, соответственно. (Дескриптор, идентифицирующий сервер, является потомком дескриптора, указанного в параметре serverHandle функции DcmPublishEndpoint() или DcmPublishComponent(), вызванной на стороне сервера. Клиент может получить этот дескриптор, например, от другого процесса.) Имя сервера, как и дескриптор, однозначно идентифицирует сервер, поэтому, чтобы задать конкретный сервер, можно указать дескриптор, идентифицирующий этот сервер, или имя этого сервера.

   В параметре clientHandle функций DcmSubscribeToEndpoints() и DcmSubscribeToComponents() нужно указать дескриптор, идентифицирующий клиента. В качестве дескриптора, идентифицирующего клиента, можно использовать дескриптор этого клиентского процесса, полученный последовательностью вызовов функций KosTaskGetSelf() и KosTaskGetHandle() из API task.h, или дескриптор, созданный вызовом функции KnHandleCreateUserObject() из API handle_api.h. (При вызове функции KnHandleCreateUserObject() в параметре rights должны быть указаны флаги OCAP_HANDLE_TRANSFER и OCAP_HANDLE_GET_SID.) Дескриптор, идентифицирующий клиента, нельзя закрывать на этом шаге, поскольку он еще потребуется для выполнения шага 4.

   После вызова функции DcmSubscribeToEndpoints() или DcmSubscribeToComponents() начинает формироваться очередь уведомлений, в которую также попадут уведомления о публикации служб или экземпляров компонента, которые были опубликованы до вызова этих функций и соответствуют критериям фильтрации.

   Если больше не требуется получать уведомления о публикации и отмене публикации служб или экземпляров компонента, то DCM-дескриптор, полученный вызовом функции DcmSubscribeToEndpoints() или DcmSubscribeToComponents(), нужно закрыть вызовом функции DcmCloseHandle().

3. Извлечь уведомление о публикации службы или экземпляра компонента из очереди этих уведомлений вызовом функции DcmReadPubQueue().

   В параметре subscrHandle функции DcmReadPubQueue() нужно указать DCM-дескриптор, полученный на шаге 2.

   Через опциональные параметры outServerHandle, outServerName и outNodeName функции DcmReadPubQueue() можно получить дескриптор, идентифицирующий сервер, имя сервера и квалифицированное имя службы или экземпляра компонента соответственно. (Дескриптор, идентифицирующий сервер, является потомком дескриптора, указанного в параметре serverHandle функции DcmPublishEndpoint() или DcmPublishComponent(), вызванной на стороне сервера.) Эти данные можно использовать, чтобы принять решение о выполнении запроса на создание IPC-канала (IPC-каналов) с сервером. При этом дескриптор, идентифицирующий сервер, может быть использован, например, для получения сведений о сервере от других процессов или для получения SID по этому дескриптору для сравнения с другими имеющимися у клиента дескрипторами, идентифицирующими серверы.

   Значение, полученное через параметр outPubStatus функции DcmReadPubQueue(), отражает статус публикации службы или экземпляра компонента. Уведомление об отмене публикации службы или экземпляра компонента появляется в очереди только в том случае, если ранее было извлечено уведомление о публикации этой службы или экземпляра компонента. Публикация службы или экземпляра компонента может быть отменена сервером либо в результате завершения сервера.

4. Создать DCM-дескриптор, позволяющий выполнить запрос на создание IPC-канала (IPC-каналов) с сервером.

   Чтобы выполнить этот шаг, нужно вызвать функцию DcmCreateConnection(). Через параметр nodeType нужно задать имя интерфейса требуемой службы или имя компонента, экземпляр которого предоставляет требуемый набор служб. Через параметр nodeName нужно задать квалифицированное имя требуемой службы или квалифицированное имя экземпляра компонента, предоставляющего требуемый набор служб.

   В параметре serverHandle функции DcmCreateConnection() нужно указать дескриптор, идентифицирующий сервер. Этот дескриптор может быть получен на шаге 3 через параметр outServerHandle функции DcmReadPubQueue() или другим способом (например, от другого процесса).

   В параметре clientHandle функции DcmCreateConnection() нужно указать дескриптор, идентифицирующий клиента. Нужно указать дескриптор, который был указан в параметре clientHandle функции DcmSubscribeToEndpoints() или DcmSubscribeToComponents() на шаге 2. (Серверы могут получить потомков этого дескриптора через опциональный параметр outClientHandle функции DcmListen().) После создания DCM-дескриптора, позволяющего выполнить запрос на создание IPC-канала (IPC-каналов), дескриптор, идентифицирующий клиента, можно закрыть, но только если этот дескриптор не был получен вызовом функции KosTaskGetHandle() из API task.h. (Дескриптор, полученный вызовом функции KosTaskGetHandle(), закрывать нельзя, так как в случае закрытия он может быть использован для идентификации других ресурсов, что приведет к ошибкам.)

5. Выполнить запрос на создание IPC-канала (IPC-каналов) с сервером.

   Чтобы выполнить этот шаг, нужно вызвать функцию DcmConnectToEndpoint() или DcmConnectToComponent(). Функция DcmConnectToEndpoint() выполняет запрос на создание IPC-канала с сервером для использования службы, а функция DcmConnectToComponent() выполняет запрос на создание IPC-каналов с сервером для использования набора служб экземпляра компонента.

   В параметре connectionId функций DcmConnectToEndpoint() и DcmConnectToComponent() нужно указать DCM-дескриптор, полученный на шаге 4. В параметре sessionHandlesCnt функции DcmConnectToComponent() нужно указать число служб, предоставляемых экземпляром компонента, то есть число служб перечисленных в CDL-файле.

   В результате вызова функции DcmConnectToEndpoint() клиент получает через параметр outSessionHandleDesc транспортный контейнер дескриптора, который содержит callable-дескриптор для использования службы. В результате вызова функции DcmConnectToComponent() клиент получает через параметр outSessionHandleDescs массив транспортных контейнеров дескрипторов, которые содержат callable-дескрипторы для использования набора служб экземпляра компонента. Порядок элементов в массиве соответствует порядку перечисления служб в CDL-файле. Сервер может предоставить только часть служб экземпляра компонента. Если сервер принял решение не предоставлять службу, то соответствующий транспортный контейнер дескриптора будет содержать значение INVALID_HANDLE вместо callable-дескриптора.

   Чтобы извлечь callable-дескриптор из транспортного контейнера дескриптора, нужно использовать макрос nk_get_handle(), который определен в заголовочном файле sysroot-*-kos/include/nk/types.h из состава KasperskyOS SDK.

   Клиент использует callable-дескриптор для инициализации IPC-транспорта. При этом в функции инициализации прокси-объекта клиент указывает значение INVALID_RIID в качестве идентификатора службы (RIID).

   После получения callable-дескриптора DCM-дескриптор, полученный на шаге 4, нужно закрыть вызовом функции DcmCloseHandle().

Прерывание блокирующих вызовов функций

Чтобы прервать блокирующий вызов функции DcmConnectToEndpoint(), DcmConnectToComponent(), DcmReadPubQueue() или DcmListen() из другого потока исполнения, нужно вызвать функцию DcmInterruptBlockingCall().

Отслеживание событий

Используя функции DcmSubscribeToEvents*() и DcmUnsubscribeFromEvents() совместно с функциями из API notice_api.h, можно получать уведомления о том, что произошли следующие события:

• публикация или отмена публикации сервером службы или экземпляра компонента (флаг маски событий DCM_PUBLICATION_CHANGED, DCM-дескриптор, полученный вызовом функции DcmSubscribeToEndpoints() или DcmSubscribeToComponents());
• получение сервером запроса от клиента на создание IPC-канала для использования службы или IPC-каналов для использования набора служб экземпляра компонента (флаг маски событий DCM_CLIENT_CONNECTED, DCM-дескриптор, полученный вызовом функции DcmPublishEndpoint() или DcmPublishComponent());
• прерывание блокирующего вызова функции DcmConnectToEndpoint(), DcmConnectToComponent(), DcmReadPubQueue() или DcmListen() (флаг маски событий DCM_BLOCKING_CALL_INTERRUPTED, DCM-дескриптор, полученный вызовом функции DcmCreateConnection(), DcmSubscribeToEndpoints(), DcmSubscribeToComponents(), DcmPublishEndpoint() или DcmPublishComponent());
• прием или отклонение сервером запроса клиента на создание IPC-канала для использования службы или IPC-каналов для использования набора служб экземпляра компонента (флаг маски событий DCM_CLIENT_RELEASED_BY_SERVER, DCM-дескриптор, полученный вызовом функции DcmCreateConnection()).

Функции DcmSubscribeToEvents*() и DcmUnsubscribeFromEvents() позволяют настроить приемник уведомлений, соответственно добавляя и удаляя отслеживаемые объекты, идентифицируемые DCM-дескрипторами. Функция DcmSubscribeToEvents() задает для записей вида "ресурс – маска событий" идентификатор DCM_EVENT_ID, а функция DcmSubscribeToEventsEx() позволяет задать для записей вида "ресурс – маска событий" собственные идентификаторы.

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

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

Удаление подключения к DCM

Если использовать DCM больше не требуется, нужно вызвать функцию DcmFini(), чтобы удалить подключение к DCM и тем самым освободить связанные с этим подключением ресурсы.

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

Функции dcm_api.h