Managing IPC (ipc

Managing IPC (ipc_api.h)

This API is defined in the header file sysroot-*-kos/include/coresrv/ipc/ipc_api.h from the KasperskyOS SDK.

API capabilities:

Interrupt the Call() and Recv() system calls if one or more process threads are locked while waiting for these system calls to complete.
For example, you may need to interrupt these system calls to correctly terminate a process so that threads waiting for the completion of these system calls can resume execution.
Define the Reply() system call termination handlers.
In a Reply() system call termination handler, you can close a handle that was transferred to a client, for example.

Information about API functions is provided in the table below.

IPC interrupt

The API interrupts system calls in process threads that were locked after the CallEx() or RecvEx() function was called from the API syscalls.h if these functions were called while specifying the IPC synchronization object handle in the syncHandle parameter. The state of the IPC synchronization object determines whether the blocking system calls Call() and Recv() will be interrupted. To create an IPC synchronization object, you must call the KnIpcCreateSyncObject() or KnIpcCreateSyncObjectEx() function. The KnIpcCreateSyncObject() function creates an IPC synchronization object whose state can be changed only from the outside. The KnIpcCreateSyncObjectEx() function is an expanded version of the KnIpcCreateSyncObject() function that lets you create an IPC synchronization object, which, after the first interruption, automatically switches to a state in which the Call() and Recv() system calls are not interrupted. Immediately after creation, the IPC synchronization object has a state in which the Call() and Recv() system calls are not interrupted.

The handle of an IPC synchronization object cannot be transferred to another process because the necessary flag for this operation is not set in the permissions mask of this handle.

The KnIpcSetInterrupt() function switches an IPC synchronization object to a state that allows interruption of the Call() and Recv() system calls in those process threads that have been locked after a CallEx() or RecvEx() function call specifying the handle of this IPC synchronization object in the syncHandle parameter. The KnIpcClearInterrupt() function switches the IPC synchronization object back to the reverse state.

When the Call() and Recv() system calls are interrupted, calls of the CallEx() or RecvEx() functions end with the rcIpcInterrupt error and locked threads resume execution. A system call can be interrupted only during certain stages of its execution. The Call() system call that is executed by the CallEx() function can be interrupted only when the server has not yet received a Recv() or RecvEx() function call used to receive an IPC message that was sent to the server when calling the CallEx() function. The CallEx() system call executed by the RecvEx() function can be interrupted only while waiting for an IPC request from a client.

An IPC synchronization object that was created by calling the KnIpcCreateSyncObjectEx() function with the rtl_false value in the autoclear parameter or by calling the KnIpcCreateSyncObject() function has the following characteristics:

It does not change its state after interruption of the Call() or Recv() system calls, and therefore subsequent calls of the CallEx() and RecvEx() functions will end with the rcIpcInterrupt error until the KnIpcClearInterrupt() function is called.
When calling the KnIpcSetInterrupt() function, if there are no threads that were locked after calling the CallEx() or RecvEx() function, subsequent calls of these functions will end with the rcIpcInterrupt error until the KnIpcClearInterrupt() function is called.

An IPC synchronization object that was created by calling the KnIpcCreateSyncObjectEx() function with the rtl_true value in the autoclear parameter has the following characteristics:

It changes its state after interruption of the Call() or Recv() system calls, and therefore subsequent calls of the CallEx() and RecvEx() functions will not end with the rcIpcInterrupt error until the KnIpcSetInterrupt() function is called.
When calling the KnIpcSetInterrupt() function, if there are no threads that were locked after calling the CallEx() or RecvEx() function, the first of subsequent calls of these functions will end with the rcIpcInterrupt error, after which the IPC synchronization object will switch to a state in which the Call() and Recv() system calls are not interrupted.

To delete an IPC synchronization object, you must close its handle.

Installing the Reply() system call termination handlers

To define the Reply() system call termination handler for a thread, call the KnIpcInstallPostReplyHandler() function from this thread. For one thread you can define several such handlers that will be run once immediately after this thread executes the Reply() system call. After that, the set of handlers will be cleared and remain empty until the next call of the KnIpcInstallPostReplyHandler() function.

Use the callback parameter of the KnIpcInstallPostReplyHandler() function to specify a callback function that does not return values and has two parameters. The replyRc input parameter contains the code with which the Reply() system call ended (rcOk if successful). The context input parameter contains the value specified in the identically named parameter of the KnIpcInstallPostReplyHandler() function.

Information about API functions

ipc_api.h functions

Function	Information about the function
`KnIpcCreateSyncObject()`	Purpose Creates an IPC synchronization object. Parameters [out] `syncHandle` – pointer to the handle of the IPC synchronization object. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code.
`KnIpcCreateSyncObjectEx()`	Purpose Creates an IPC synchronization object. Parameters [in] `autoclear` – boolean value that indicates whether or not you need to create an IPC synchronization object that automatically switches to a state in which the `Call()` and `Recv()` system calls are not interrupted after the first interruption of these system calls (`rtl_true` means yes and `rtl_false` means no). [out] `syncHandle` – pointer to the handle of the IPC synchronization object. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code.
`KnIpcSetInterrupt()`	Purpose Switches the defined IPC synchronization object to a state in which the `Call()` and `Recv()` system calls are interrupted. Parameters [in] `syncHandle` – handle of the IPC synchronization object. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code.
`KnIpcClearInterrupt()`	Purpose Switches the defined IPC synchronization object to a state in which the `Call()` and `Recv()` system calls are not interrupted. Parameters [in] `syncHandle` – handle of the IPC synchronization object. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code.
`KnIpcInstallPostReplyHandler()`	Purpose Defines a `Reply()` system call termination handler for the calling thread. Parameters [in] `callback` – identifier of the callback function that is called immediately after the `Reply()` system call is executed. [in,optional] `context` – pointer to the data that will be passed to the callback function that was defined via the `callback` parameter. You can specify `RTL_NULL` if data does not need to be passed. The callback function will receive the passed data through its own `context` parameter. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code.

Page top