Dynamically creating IPC channels (cm_api.h, ns_api.h)

APIs are defined in the header files from the KasperskyOS SDK:

• sysroot-*-kos/include/coresrv/cm/cm_api.h
• sysroot-*-kos/include/coresrv/ns/ns_api.h

The API dynamically creates IPC channels.

Information about API functions is provided in the tables below.

Using the API

To ensure that servers can notify clients about the endpoints that they provide, the solution should include a name server, which is provided by the NameServer system program (executable file sysroot-*-kos/bin/ns from the KasperskyOS SDK). IPC channels from clients and servers to a name server can be statically created (these IPC channels must be named kl.core.NameServer). If this is not done, attempts will be made to dynamically create these IPC channels whenever clients and servers call the NsCreate() function. A name server does not have to be included in a solution if the clients initially already have information about the names of servers and the endpoints provided by these servers.

The names of endpoints and interfaces should be defined according to the formal specifications of solution components. (For information about the qualified name of an endpoint, see "Binding methods of security models to security events") Instead of the qualified name of an endpoint, you can use any conditional name of this endpoint. The names of clients and servers are defined in the init description. You can also get a process name by calling the KnTaskGetName() function from the API task_api.h.

Dynamic creation of an IPC channel on the server side includes the following steps:

1. Connect to the name server by calling the NsCreate() function.
2. Publish the provided endpoints on the name server by using the NsPublishService() function.

   To unpublish an endpoint, call the NsUnPublishService() function.

3. Receive a client request to create an IPC channel by calling the KnCmListen() function.

   The KnCmListen() function gets the first request in the queue without deleting this request but instead putting it at the end of the queue. If there is only one request in the queue, multiple consecutive calls of the KnCmListen() function will provide the same result. A request is deleted from the queue when the KnCmAccept() or KnCmDrop() function is called.

4. You can accept a client request to create an IPC channel by calling the KnCmAccept() function.

   To decline a client request, call the KnCmDrop() function.

   A listener handle is created when the KnCmAccept() function is called with the INVALID_HANDLE value in the listener parameter. If a listener handle is specified, the created server IPC handle will provide the capability to receive IPC requests over all IPC channels associated with this listener handle. (The first IPC channel associated with the listener handle is created when the KnCmAccept() function is called with the INVALID_HANDLE value in the listener parameter. The second and subsequent IPC channels associated with the listener handle are created during the second and subsequent calls of the KnCmAccept() function specifying the handle that was obtained during the first call.) In the listener parameter of the KnCmAccept() function, you can specify the listener handle received using the KnHandleConnect(), KnHandleConnectEx() and KnHandleCreateListener() functions from the API handle_api.h, and the ServiceLocatorRegister() function declared in the header file sysroot-*-kos/include/coresrv/sl/sl_api.h from the KasperskyOS SDK.

Dynamic creation of an IPC channel on the client side includes the following steps:

1. Connect to the name server by calling the NsCreate() function.
2. Find the server providing the required endpoint by using the NsEnumServices() function.

   To get a full list of endpoints with a defined interface, call the function several times while incrementing the index until you receive the rcResourceNotFound error.

3. Fulfill the request to create an IPC channel with the necessary server by calling the KnCmConnect() function.

You can connect multiple clients and servers to the name server. Each client and server can create multiple connections to the name server. A server can unpublish an endpoint that was published by another server.

Deleting dynamically created IPC channels

A dynamically created IPC channel will be deleted when its client IPC handle and server IPC handle are closed.

Information about API functions

ns_api.h functions

Function	Information about the function
NsCreate()	Purpose Creates a connection to a name server. Parameters [in,optional] name – pointer to the name of the name server process, or RTL_NULL to assign the default name (corresponds to the NS_SERVER_NAME macro value). [in] msecs – timeout (in milliseconds) for creating a connection to the name server, or INFINITE_TIMEOUT to define an unlimited timeout. [out] ns – pointer to the ID of the connection to the name server. Returned values If successful, the function returns rcOk, otherwise it returns an error code.
NsPublishService()	Purpose Publishes an endpoint on a name server. Parameters [in] ns – ID of the connection to the name server. [in] type – pointer to the name of the endpoint interface. [in,optional] server – pointer to the name of the server providing the endpoint, or RTL_NULL to use the name of the calling process. [in] service – pointer to the qualified name of the endpoint. Returned values If successful, the function returns rcOk, otherwise it returns an error code.
NsUnPublishService()	Purpose Unpublishes an endpoint on a name server. Parameters [in] ns – ID of the connection to the name server. [in] type – pointer to the name of the endpoint interface. [in,optional] server – pointer to the name of the server providing the endpoint, or RTL_NULL to use the name of the calling process. [in] service – pointer to the qualified name of the endpoint. Returned values If successful, the function returns rcOk, otherwise it returns an error code.
NsEnumServices()	Purpose Enumerates the endpoints published on a name server. Parameters [in] ns – ID of the connection to the name server. [in] type – pointer to the name of the interface of endpoints. [in] index – index for enumerating endpoints. Enumeration starts with zero. [out] server – pointer to the buffer for the name of the server providing the endpoint. [in] serverSize – buffer size (in bytes) for the name of the server providing the endpoint. [out] service – pointer to the buffer for the qualified name of the endpoint. [in] serviceSize – buffer size (in bytes) for the qualified name of the endpoint. Returned values If successful, the function returns rcOk, otherwise it returns an error code.

cm_api.h functions

Function	Information about the function
KnCmConnect()	Purpose Requests to create an IPC channel with a server for use of the defined endpoint. Parameters [in] server – pointer to the server name. [in] service – pointer to the qualified name of the endpoint. [in] msecs – timeout (in milliseconds) for fulfilling a request, or INFINITE_TIMEOUT to define an unlimited timeout. [out] handle – pointer to the client IPC handle. [out] rsid – pointer to the endpoint ID (RIID). Returned values If successful, the function returns rcOk, otherwise it returns an error code.
KnCmListen()	Purpose Receives a client request to create an IPC channel for use of an endpoint. Parameters [in] filter – fictitious parameter that must have the value RTL_NULL. [in] msecs – timeout (in milliseconds) for the appearance of a client request, or INFINITE_TIMEOUT to define an unlimited timeout. [out] client – pointer to the client name. [out] service – pointer to the qualified name of the endpoint. Returned values If successful, the function returns rcOk, otherwise it returns an error code.
KnCmDrop()	Purpose Rejects a client request to create an IPC channel for use of the defined endpoint. Parameters [in] client – pointer to the client name. [in] service – pointer to the qualified name of the endpoint. Returned values If successful, the function returns rcOk, otherwise it returns an error code.
KnCmAccept()	Purpose Accepts a client request to create an IPC channel for use of the defined endpoint. Parameters [in] client – pointer to the client name. [in] service – pointer to the qualified name of the endpoint. [in] rsid – endpoint ID (RIID). [in,optional] listener – listener handle, or INVALID_HANDLE if you need to create it. [out] handle – pointer to the server IPC handle. Returned values If successful, the function returns rcOk, otherwise it returns an error code.

Page top