Управление IPC (ipc_api.h)

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

Возможности API:

• Прерывать системные вызовы Call() и Recv(), в ожидании завершения которых заблокирован один или несколько потоков процесса.

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

• Устанавливать обработчики завершения системного вызова Reply().

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

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

Прерывание IPC

API позволяет прерывать системные вызовы в потоках процесса, которые заблокированы после вызова функции CallEx() или RecvEx() из API syscalls.h, если эти функции вызваны с указанием дескриптора объекта синхронизации IPC в параметре syncHandle. От состояния объекта синхронизации IPC зависит, будут ли прерваны блокирующие системные вызовы Call() и Recv(). Чтобы создать объект синхронизации IPC, нужно вызвать функцию KnIpcCreateSyncObject() или KnIpcCreateSyncObjectEx(). Функция KnIpcCreateSyncObject() создает объект синхронизации IPC, состояние которого можно изменять только извне. Функция KnIpcCreateSyncObjectEx() является расширенной версией функции KnIpcCreateSyncObject() и позволяет создать объект синхронизации IPC, который после первого прерывания автоматически переходит в состояние, при котором системные вызовы Call() и Recv() не прерываются. Сразу после создания объект синхронизации IPC находится в состоянии, при котором системные вызовы Call() и Recv() не прерываются.

Дескриптор объекта синхронизации IPC не может быть передан другому процессу, так как в маске прав этого дескриптора не установлен необходимый для этого флаг.

Функция KnIpcSetInterrupt() переводит объект синхронизации IPC в состояние, при котором прерываются системные вызовы Call() и Recv() в тех потоках процесса, которые заблокированы после вызова функции CallEx() или RecvEx() с указанием дескриптора этого объекта синхронизации IPC в параметре syncHandle. Функция KnIpcClearInterrupt() переводит объект синхронизации IPC в обратное состояние.

При прерывании системных вызовов Call() и Recv() вызовы функций CallEx() или RecvEx() завершаются с ошибкой rcIpcInterrupt, а заблокированные потоки возобновляют исполнение. Прерывание системного вызова возможно только на некоторых стадиях его выполнения. Системный вызов Call(), выполняемый функцией CallEx(), может быть прерван только тогда, когда на сервере еще не вызвана функция Recv() или RecvEx() для получения IPC-сообщения, которое было отправлено этому серверу при вызове функции CallEx(). Системный вызов Recv(), выполняемый функцией RecvEx(), может быть прерван только во время ожидания IPC-запроса от клиента.

Объект синхронизации IPC, созданный вызовом функции KnIpcCreateSyncObjectEx() со значением rtl_false в параметре autoclear или вызовом функции KnIpcCreateSyncObject(), имеет следующие особенности:

• Не изменяет свое состояние после прерывания системного вызова Call() или Recv(), поэтому последующие вызовы функций CallEx() и RecvEx() будут завершаться с ошибкой rcIpcInterrupt до тех пор, пока не будет вызвана функция KnIpcClearInterrupt().
• Если при вызове функции KnIpcSetInterrupt() отсутствуют потоки исполнения, заблокированные после вызова функции CallEx() или RecvEx(), то последующие вызовы этих функций будут завершаться с ошибкой rcIpcInterrupt, пока не будет вызвана функция KnIpcClearInterrupt().

Объект синхронизации IPC, созданный вызовом функции KnIpcCreateSyncObjectEx() со значением rtl_true в параметре autoclear, имеет следующие особенности:

• Изменяет свое состояния после прерывания системного вызова Call() или Recv(), поэтому последующие вызовы функций CallEx() и RecvEx() не будут завершаться с ошибкой rcIpcInterrupt до тех пор, пока не будет вызвана функция KnIpcSetInterrupt().
• Если при вызове функции KnIpcSetInterrupt() отсутствуют потоки исполнения, заблокированные после вызова функции CallEx() или RecvEx(), то первый из последующих вызовов этих функций завершится с ошибкой rcIpcInterrupt, после чего объект синхронизации IPC перейдет в состояние, при котором системные вызовы Call() и Recv() не прерываются.

Чтобы удалить объект синхронизации IPC, нужно закрыть его дескриптор.

Установка обработчиков завершения системного вызова Reply()

Чтобы задать для потока исполнения обработчик завершения системного вызова Reply(), нужно вызвать из этого потока функцию KnIpcInstallPostReplyHandler(). Для одного потока исполнения можно задать несколько таких обработчиков, которые запустятся один раз, сразу после выполнения этим потоком системного вызова Reply(). После этого набор обработчиков будет очищен и останется пустым до следующего вызова функции KnIpcInstallPostReplyHandler().

Через параметр callback функции KnIpcInstallPostReplyHandler() нужно задать callback-функцию, которая не возвращает значений и имеет два параметра. Входной параметр replyRc содержит код, с которым завершился системный вызов Reply() (rcOk в случае успеха). Входной параметр context содержит значение, заданное в одноименном параметре функции KnIpcInstallPostReplyHandler().

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

Функции ipc_api.h

Функция	Сведения о функции
KnIpcCreateSyncObject()	Назначение Создает объект синхронизации IPC. Параметры [out] syncHandle – указатель на дескриптор объекта синхронизации IPC. Возвращаемые значения В случае успеха возвращает rcOk, иначе возвращает код ошибки.
KnIpcCreateSyncObjectEx()	Назначение Создает объект синхронизации IPC. Параметры [in] autoclear – булевое значение, которое задает, нужно ли создать объект синхронизации IPC, который автоматически переходит в состояние, при котором системные вызовы Call() и Recv() не прерываются, после первого прерывания этих системных вызовов (rtl_true – да, rtl_false – нет). [out] syncHandle – указатель на дескриптор объекта синхронизации IPC. Возвращаемые значения В случае успеха возвращает rcOk, иначе возвращает код ошибки.
KnIpcSetInterrupt()	Назначение Переводит заданный объект синхронизации IPC в состояние, при котором системные вызовы Call() и Recv() прерываются. Параметры [in] syncHandle – дескриптор объекта синхронизации IPC. Возвращаемые значения В случае успеха возвращает rcOk, иначе возвращает код ошибки.
KnIpcClearInterrupt()	Назначение Переводит заданный объект синхронизации IPC в состояние, при котором системные вызовы Call() и Recv() не прерываются. Параметры [in] syncHandle – дескриптор объекта синхронизации IPC. Возвращаемые значения В случае успеха возвращает rcOk, иначе возвращает код ошибки.
KnIpcInstallPostReplyHandler()	Назначение Задает для вызывающего потока исполнения обработчик завершения системного вызова Reply(). Параметры [in] callback – идентификатор callback-функции, вызываемой сразу после выполнения системного вызова Reply(). [in,optional] context – указатель на данные, которые будут переданы callback-функции, заданной через параметр callback. Можно указать RTL_NULL, если данные передавать не требуется. Callback-функция получит переданные данные через свой параметр context. Возвращаемые значения В случае успеха возвращает rcOk, иначе возвращает код ошибки.

В начало