KasperskyOS Community Edition 1.3

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    В параметре sessionHandle функции DcmAccept() нужно указать 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-дескриптора клиенту можно ассоциировать с объектом контекста передачи ресурса, указав дескриптор этого объекта в параметре badgeHandle функции DcmAccept(). Это позволит, используя API notice_api.h, отследить, когда будут закрыты или отозваны потомки callable-дескриптора, которые образуют поддерево наследования дескрипторов, корневой узел которого порожден передачей клиенту этого callable-дескриптора. (Переданный callable-дескриптор может быть закрыт клиентом, но также закрытие этого дескриптора выполняется в результате завершения клиента.) Чтобы создать объект контекста передачи ресурса, нужно вызвать функцию KnHandleCreateBadge() из API handle_api.h.

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

    Один и тот же callable-дескриптор можно использовать, чтобы принять несколько запросов одного или нескольких клиентов.

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

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

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

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

    Чтобы выполнить этот шаг, нужно вызвать функцию DcmSetSubscription().

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

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

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

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

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

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

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

    Чтобы выполнить этот шаг, нужно вызвать функцию DcmCreateConnection().

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

    В параметре clientHandle функции DcmCreateConnection() нужно указать дескриптор, идентифицирующий клиента. В качестве дескриптора, идентифицирующего клиента, можно использовать дескриптор этого клиентского процесса, полученный последовательностью вызовов функций KosTaskGetSelf() и KosTaskGetHandle() из API task.h, или дескриптор, созданный вызовом функции KnHandleCreateUserObject() из API handle_api.h. (При вызове функции KnHandleCreateUserObject() в параметре rights должны быть указаны флаги OCAP_HANDLE_TRANSFER и OCAP_HANDLE_GET_SID.) Можно создать несколько DCM-дескрипторов, позволяющих выполнить запрос на создание IPC-канала, указывая в параметре clientHandle функции DcmCreateConnection() один и тот же или разные дескрипторы, идентифицирующие клиента. (Серверы могут получить потомков этих дескрипторов через опциональный параметр outClientHandle функции DcmListen().) После создания DCM-дескриптора, позволяющего выполнить запрос на создание IPC-канала, дескриптор, идентифицирующий клиента, можно закрыть.

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

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

    В параметре connectionId нужно указать DCM-дескриптор, полученный на шаге 4.

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

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

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

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

Использование уведомлений

Используя функции DcmSubscribeToEvents() и DcmUnsubscribeFromEvents() совместно с функциями из API notice_api.h, можно получать уведомления о том, что произошли следующие события: публикация или отмена публикации сервером службы в DCM (флаг DCM_PUBLICATION_CHANGED), получение сервером запроса от клиента на создание IPC-канала (флаг DCM_CLIENT_CONNECTED), прерывание блокирующего вызова функции DcmConnect(), DcmReadPubQueue() или DcmListen() (флаг DCM_BLOCKING_CALL_INTERRUPTED), прием или отклонение сервером запроса клиента на создание IPC-канала (флаг DCM_CLIENT_RELEASED_BY_SERVER). (Флаги маски событий и идентификатор записи вида "ресурс – маска событий" DCM_EVENT_ID определены в заголовочном файле sysroot-*-kos/include/dcm/dcm_api.h из состава KasperskyOS SDK.) Функции DcmSubscribeToEvents() и DcmUnsubscribeFromEvents() позволяют настроить приемник уведомлений, соответственно добавляя и удаляя отслеживаемые объекты, идентифицируемые DCM-дескрипторами.

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

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

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

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

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

Функции dcm_api.h

Функция

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

DcmInit()

Назначение

Создает подключение к DCM.

Параметры

Нет.

Возвращаемые значения

В случае успеха возвращает rcOk, иначе возвращает код ошибки.

Если IPC-канал до DCM отсутствует, возвращает rcNoCapability.

Дополнительные сведения

Потокобезопасная функция.

Неблокирующий вызов.

DcmFini()

Назначение

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

Параметры

Нет.

Возвращаемые значения

Нет.

Дополнительные сведения

Потокобезопасная функция.

Неблокирующий вызов.

DcmSubscribeToEvents()

Назначение

Настраивает приемник уведомлений, чтобы он получал уведомления о событиях, связанных с объектом, идентифицируемым заданным DCM-дескриптором.

Параметры

  • [in] notice – идентификатор приемника уведомлений.
  • [in] handle – DCM-дескриптор, полученный вызовом функции DcmSetSubscription(), DcmCreateConnection() или DcmPublishEndpoint().

Возвращаемые значения

В случае успеха возвращает rcOk, иначе возвращает код ошибки.

DcmUnsubscribeFromEvents()

Назначение

Настраивает приемник уведомлений, чтобы он не получал уведомления о событиях, связанных с объектом, идентифицируемым заданным DCM-дескриптором.

Параметры

  • [in] notice – идентификатор приемника уведомлений.
  • [in] handle – DCM-дескриптор, полученный вызовом функции DcmSetSubscription(), DcmCreateConnection() или DcmPublishEndpoint().

Возвращаемые значения

В случае успеха возвращает rcOk, иначе возвращает код ошибки.

DcmCloseHandle()

Назначение

Закрывает DCM-дескриптор, полученный вызовом функции DcmSetSubscription(), DcmCreateConnection(), DcmPublishEndpoint() или DcmListen() из основного API, а также DcmListenGroupPub() из дополнительного API для серверов.

Параметры

  • [in] handle – DCM-дескриптор.

Возвращаемые значения

В случае успеха возвращает rcOk, иначе возвращает код ошибки.

DcmInterruptBlockingCall()

Назначение

Прерывает блокирующий вызов функции DcmConnect(), DcmReadPubQueue() или DcmListen().

Параметры

  • [in] handle – DCM-дескриптор, указанный при вызове функции DcmConnect(), DcmReadPubQueue() или DcmListen().

Возвращаемые значения

В случае успеха возвращает rcOk, иначе возвращает код ошибки.

DcmSetSubscription()

Назначение

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

Параметры

  • [in] endpointType – указатель на имя интерфейса служб.
  • [in,optional] endpointName – указатель на квалифицированное имя службы или RTL_NULL, чтобы не использовать фильтрацию уведомлений по квалифицированному имени службы.
  • [in,optional] serverName – указатель на имя сервера или RTL_NULL, чтобы не использовать фильтрацию уведомлений по имени сервера.
  • [in,optional] serverHandle – дескриптор, идентифицирующий сервер, или INVALID_HANDLE, чтобы не использовать фильтрацию уведомлений по конкретному серверу.
  • [out] outSubscrHandle – указатель на DCM-дескриптор, позволяющий получать уведомления о публикации и отмене публикации служб с заданным интерфейсом.

Возвращаемые значения

В случае успеха возвращает rcOk, иначе возвращает код ошибки.

DcmReadPubQueue()

Назначение

Извлекает уведомление о публикации или отмене публикации службы из очереди этих уведомлений.

Параметры

  • [in] subscrHandle – DCM-дескриптор, созданный вызовом функции DcmSetSubscription().
  • [in] msec – время ожидания появления уведомлений в миллисекундах или INFINITE_TIMEOUT, чтобы задать неограниченное время ожидания.
  • [out,optional] outServerHandle – указатель на дескриптор, идентифицирующий сервер, или RTL_NULL, если этот дескриптор не требуется.
  • [out,optional] outServerName – указатель на буфер для имени сервера или RTL_NULL, если это имя не требуется.
  • [in] serverNameSize – размер буфера для имени сервера в байтах или 0, если это имя не требуется.
  • [out,optional] outEndpointName – указатель на буфер для квалифицированного имени службы или RTL_NULL, если это имя не требуется.
  • [in] endpointNameSize – размер буфера для квалифицированного имени службы в байтах или 0, если это имя не требуется.
  • [out] outPubStatus – указатель на значение, отражающее, что служба опубликована (DcmEndpointPublished), или публикация службы отменена (DcmEndpointUnpublished).

Возвращаемые значения

В случае успеха возвращает rcOk, иначе возвращает код ошибки.

Если блокирующий вызов был прерван вызовом функции DcmInterruptBlockingCall(), возвращает rcAbort.

Дополнительные сведения

Неблокирующий вызов, если в параметре msec указан 0.

DcmCreateConnection()

Назначение

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

Параметры

  • [in] endpointType – указатель на имя интерфейса службы.
  • [in] endpointName – указатель на квалифицированное имя службы.
  • [in] serverHandle – дескриптор, идентифицирующий сервер.
  • [in] clientHandle – дескриптор, идентифицирующий клиента.
  • [out] outConnectionId – указатель на DCM-дескриптор, позволяющий выполнить запрос на создание IPC-канала с сервером для использования заданной службы с заданным интерфейсом.

Возвращаемые значения

В случае успеха возвращает rcOk, иначе возвращает код ошибки.

DcmConnect()

Назначение

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

Параметры

  • [in] connectionId – DCM-дескриптор, созданный вызовом функции DcmCreateConnection().
  • [in] msec – время ожидания выполнения запроса в миллисекундах или INFINITE_TIMEOUT, чтобы задать неограниченное время ожидания.
  • [out] outSessionHandle – указатель на callable-дескриптор.

Возвращаемые значения

В случае успеха возвращает rcOk, иначе возвращает код ошибки.

Если в параметре msec указан 0, и сервер не обработал запрос на создание IPC-канала, возвращает rcNotReady.

Если блокирующий вызов был прерван вызовом функции DcmInterruptBlockingCall(), возвращает rcAbort.

Дополнительные сведения

Неблокирующий вызов, если в параметре msec указан 0.

DcmPublishEndpoint()

Назначение

Публикует службу в DCM.

Параметры

  • [in] endpointType – указатель на имя интерфейса службы.
  • [in] endpointName – указатель на квалифицированное имя службы.
  • [in] serverHandle – дескриптор, идентифицирующий сервер.
  • [out] outPubHandle – указатель на DCM-дескриптор, позволяющий получать запросы клиентов на создание IPC-каналов для использования заданной службы с заданным интерфейсом.

Возвращаемые значения

В случае успеха возвращает rcOk, иначе возвращает код ошибки.

DcmListen()

Назначение

Позволяет получить запрос клиента на создание IPC-канала.

Параметры

  • [in] pubHandle – DCM-дескриптор, созданный вызовом функции DcmPublishEndpoint().
  • [in] msec – время ожидания появления запроса клиента в миллисекундах или INFINITE_TIMEOUT, чтобы задать неограниченное время ожидания.
  • [out] outConnectionId – указатель на DCM-дескриптор, позволяющий принять или отклонить запрос клиента на создание IPC-канала.
  • [out,optional] outClientHandle – указатель на дескриптор, идентифицирующий клиента, или RTL_NULL, если этот дескриптор не требуется.
  • [out,optional] outClientName – указатель на буфер для имени клиента или RTL_NULL, если это имя не требуется.
  • [in] clientNameSize – размер буфера для имени клиента в байтах или 0, если это имя не требуется.

Возвращаемые значения

В случае успеха возвращает rcOk, иначе возвращает код ошибки.

Если блокирующий вызов был прерван вызовом функции DcmInterruptBlockingCall(), возвращает rcAbort.

Дополнительные сведения

Неблокирующий вызов, если в параметре msec указан 0.

DcmAccept()

Назначение

Принимает запрос клиента на создание IPC-канала.

Параметры

  • [in] connectionId – DCM-дескриптор, полученный вызовом функции DcmListen().
  • [in] sessionHandle – callable-дескриптор для клиента.
  • [in,optional] badgeHandle – дескриптор объекта контекста передачи ресурса или INVALID_HANDLE, если не требуется ассоциировать передачу callable-дескриптора с этим объектом.

Возвращаемые значения

В случае успеха возвращает rcOk, иначе возвращает код ошибки.