Getting IPC handles and RIIDs to use statically created IPC channels (sl-static.h)

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

The API allows servers to get the listener handles and allows clients to get the client IPC handles and endpoint IDs (RIIDs) for the purpose of using statically created IPC channels. (For information about using client and server IPC handles and endpoint IDs (RIIDs), see Initializing IPC transport for interprocess communication and managing IPC request processing (transport-kos.h, transport-kos-dispatch.h).)

Closing an IPC handle received via the API will cause the IPC channel to become unavailable. After an IPC handle is closed, it is impossible to obtain it again or restore access to the IPC channel.

Information about API functions is provided in the tables below.

Using the API on the server side

To get the listener handle based on the name of a statically created IPC channel connected to a server, call the SLStaticResolveHandle() function.

To get the names and listener handles for all statically created IPC channels connected to a server, call the SLStaticGetServerChannels() or SLStaticAllocateAndGetServerChannels() function. The second function creates a buffer for output data. To flush this buffer, call the SLStaticFreeServerChannels() function.

Using the API on the client side

To get a client IPC handle based on the name of a statically created IPC channel connected to the client, call the SLStaticResolveHandle() function.

To get an endpoint ID (RIID) based on the qualified name of the endpoint provided via the statically created IPC channel connected to the client, call the SLStaticResolveRiid() function. (For information about the qualified name of an endpoint, see Binding methods of security models to security events.)

To get information about the endpoints provided by servers that are connected to a client via statically created IPC channels, call the SLStaticGetEndpoints() or SLStaticAllocateAndGetEndpoints() function. This information includes the names of servers, the names of endpoints (from the EDL descriptions and CDL descriptions, and qualified names) and endpoint IDs (RIIDs). You can define the following criteria for filtering endpoints:

Server name.
Qualified name of the component instance.
For information about the qualified name of a component instance, see Binding methods of security models to security events.

The qualified name of a component instance lets you explicitly identify a component instance implemented on a server. To get information about component instances that are implemented on servers that are connected to a client via statically created IPC channels, call the SLStaticGetComponents() function. This information includes the names of servers and the names of component instances (from the EDL descriptions and CDL descriptions, and qualified names).
Interface name of endpoints according to the IDL description.
Boolean value that defines whether you need to receive information about endpoints provided by embedded instances of components.

The SLStaticAllocateAndGetEndpoints() function creates a buffer for output data. To flush this buffer, call the SLStaticFreeEndpoints() function.

Getting a process name

The API additionally includes the SLStaticSelfUniqId() function, which lets you get the name of the calling process. This function is intended for use by the libkos library.

Information about API functions

sl-static.h functions

Function	Information about the function
`SLStaticResolveHandle()`	Purpose Gets an IPC handle based on the name of a statically created IPC channel connected to a calling client or server. Parameters [in] `channelName` – pointer to the name of the statically created IPC channel. [in] `type` – value that defines which IPC handle should be received: client (on the client side) or listener (on the server side). Returned values If successful, it returns the IPC handle. Otherwise, it returns `INVALID_HANDLE`.
`SLStaticResolveRiid()`	Purpose Gets an endpoint ID (RIID) based on the qualified name of an endpoint provided via a statically created IPC channel connected to a calling client. Parameters [in] `handle` – client IPC handle of the statically created IPC channel. [in] `name` – pointer to the qualified name of the endpoint. Returned values If successful, the function returns the endpoint ID (RIID), otherwise it returns `INVALID_RIID`. The type of returned value is defined in the header file `sysroot-*-kos/include/nk/types.h` from the KasperskyOS SDK.
`SLStaticSelfUniqId()`	Purpose Gets the name of a calling process. Parameters N/A Returned values If successful, the function returns the pointer to the name of the calling process, otherwise it returns `RTL_NULL`.
`SLStaticGetServerChannels()`	Purpose Gets the names and listener handles for all statically created IPC channels connected to a calling server. Parameters [in] `maxChannelsCount` – maximum number of elements in the array defined via the `channels` parameter. [out] `channels` – pointer to the array of structures used to save the names and listener handles for statically created IPC channels. [out] `channelsCount` – pointer to the actual number of statically created IPC channels connected to the calling server. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code. If the value received via the `channelsCount` parameter exceeds the value defined via the `maxChannelsCount` parameter, the function returns `rcBufferTooSmall`.
`SLStaticAllocateAndGetServerChannels()`	Purpose Creates an array and uses this array to store the names and listener handles for all statically created IPC channels connected to a calling server. Parameters [out] `outChannels` – pointer to the address of the array of structures containing the names and listener handles for statically created IPC channels. [out] `channelsCount` – pointer to the number of statically created IPC channels connected to the calling server. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code.
`SLStaticFreeServerChannels()`	Purpose Deletes an array that was created by the `SLStaticAllocateAndGetServerChannels()` function call. Parameters [in] `channels` – pointer to the array that was created by the `SLStaticAllocateAndGetServerChannels()` function call. Returned values N/A
`SLStaticGetComponents()`	Purpose Gets information about component instances that are implemented on servers that are connected to a calling client via statically created IPC channels. Parameters [in] `componentType` – pointer to the component name according to the CDL description. [in] `maxCount` – number of elements in the array defined via the `components` parameter. [out] `components` – pointer to the array of structures used to save the names of servers and the names of component instances (from the EDL descriptions and CDL descriptions, and qualified names). [out] `componentsCount` – pointer to the actual number of component instances that are implemented on servers connected to a calling client via statically created IPC channels. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code. If the value received via the `componentsCount` parameter exceeds the value defined via the `maxCount` parameter, the function returns `rcBufferTooSmall`.
`SLStaticGetEndpoints()`	Purpose Gets information about endpoints provided by servers that are connected to a calling client via statically created IPC channels. Parameters [in,optional] `serverName` – pointer to the server name, or `RTL_NULL` if you do not need to define a server with a specific name. [in,optional] `componentPath` – pointer to the qualified name of the component instance, or `RTL_NULL` if you do not need to define a specific component instance. [in,optional] `endpointType` – pointer to the interface name of endpoints according to the IDL description, or `RTL_NULL` if you do not need to define a specific interface of endpoints. [in] `recursive` – Boolean value that defines whether or not you need to receive information about endpoints provided by embedded instances of components (`rtl_true` – yes, `rtl_false` – no). [in] `maxCount` – number of elements in the array defined via the `endpoints` parameter. [out] `endpoints` – pointer to the array of structures used to save the names of servers, the names of endpoints (from the EDL descriptions and CDL descriptions, and qualified names) and endpoint IDs (RIIDs). [out] `endpointsCount` – pointer to the actual number of endpoints that are provided by servers connected to a calling client via statically created IPC channels and that match the filtering criteria defined via the `serverName`, `componentPath`, `endpointType` and `recursive` parameters. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code. If the value received via the `endpointsCount` parameter exceeds the value defined via the `maxCount` parameter, the function returns `rcBufferTooSmall`.
`SLStaticAllocateAndGetEndpoints()`	Purpose Creates an array and uses this array to store information about endpoints provided by servers that are connected to a calling client via statically created IPC channels. Parameters [in,optional] `serverName` – pointer to the server name, or `RTL_NULL` if you do not need to define a server with a specific name. [in,optional] `componentPath` – pointer to the qualified name of the component instance, or `RTL_NULL` if you do not need to define a specific component instance. [in,optional] `endpointType` – pointer to the interface name of endpoints according to the IDL description, or `RTL_NULL` if you do not need to define a specific interface of endpoints. [in] `recursive` – Boolean value that defines whether or not you need to receive information about endpoints provided by embedded instances of components (`rtl_true` – yes, `rtl_false` – no). [out] `outEndpoints` – pointer to the address of the array of structures containing the names of servers, the names of endpoints (from the EDL descriptions and CDL descriptions, and qualified names) and endpoint IDs (RIIDs). [out] `outEndpointsCount` – pointer to the number of endpoints that are provided by servers connected to a calling client via statically created IPC channels and that match the filtering criteria defined via the `serverName`, `componentPath`, `endpointType` and `recursive` parameters. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code.
`SLStaticFreeEndpoints()`	Purpose Deletes an array that was created by a `SLStaticAllocateAndGetEndpoints()` function call. Parameters [in] `endpoints` – pointer to the array that was created by a `SLStaticAllocateAndGetEndpoints()` function call. Returned values N/A

Page top