Using the additional server API for servers (pub.h)

The API is defined in the header file sysroot-*-kos/include/coresrv/dcm/groups/pub.h from the KasperskyOS SDK.

The API allows servers to publish groups of endpoints. From the server perspective, a group of endpoints is a set of endpoints provided by the server and for which the server may receive client requests to create IPC channels using one DCM handle. A server can publish multiple groups of endpoints. A set of endpoints from different groups published by a server must not overlap.

Information about API functions is provided in the table below.

Publishing a group of endpoints

To publish a group of server-provided endpoints to DCM, call the DcmPublishGroupEndpoints() function. Use the endpoints parameter of the DcmPublishGroupEndpoints() function to define the qualified names and the contexts of grouped endpoints, and the names of endpoint interfaces. (The array of structures whose pointer is defined via the endpoints parameter can be deleted after publication.) An endpoint context is the data that is used by the server to determine which specific endpoint from the published group is required by the client when the DcmListenGroupPub() function is called. You can use a numerical identifier or a pointer to specific data as the endpoint context.

A DcmPublishGroupEndpoints() function call creates a DCM handle that enables receipt of client requests to create IPC channels to use endpoints in the specific group with specific interfaces.

Receives a client request to create an IPC channel.

To receive a client request to create an IPC channel to use an endpoint in the published group, call the DcmListenGroupPub() function. In the pubHandle parameter of the DcmListenGroupPub() function, specify the DCM handle that was obtained by calling the DcmPublishGroupEndpoints() function. The outContext output parameter of the DcmListenGroupPub() function contains the pointer to the endpoint context. (The server also receives client requests that were made before the endpoint group was published.)

The DcmListenGroupPub() function call creates a DCM handle that enables acceptance or rejection of a client request to create an IPC channel to use the specific endpoint in the group that matches the received endpoint context. To accept a client request, call the DcmAcceptEndpointConnection() function from the base API dcm_api.h. To reject a client request, call the DcmCloseHandle() function from the base API dcm_api.h.

Unpublishing a group of endpoints

To unpublish a group of endpoints, call the DcmCloseGroupPubHandle() function to close the DCM handle that was created when the endpoint was published. If a server terminates, all published groups of server endpoints will also be unpublished.

Interrupting blocking function calls

To interrupt a blocking call of the DcmListenGroupPub() function from another thread, call the DcmInterruptGroupPubBlockingCall() function.

Tracking events

You can use the DcmSubscribeToGroupPubEvent() and DcmUnsubscribeFromGroupPubEvent() functions together with functions from the notice_api.h API to receive notifications about the following events:

A server receives a client request to create an IPC channel to use an endpoint from the group (DCM_CLIENT_CONNECTED event mask flag, DCM handle obtained by calling the DcmPublishGroupEndpoints() function).
A blocking call of the DcmListenGroupPub() function is interrupted (DCM_BLOCKING_CALL_INTERRUPTED event mask flag, DCM handle obtained by calling the DcmPublishGroupEndpoints() function).

The DcmSubscribeToGroupPubEvent() and DcmUnsubscribeFromGroupPubEvent() functions let you configure the notification receiver by adding or deleting, respectively, tracked objects identified by DCM handles. The DcmSubscribeToGroupPubEvent() function sets the identifier DCM_EVENT_ID for entries of the "resource–event mask" type. Flags of the event mask and the "resource–event mask" entry ID DCM_EVENT_ID are defined in the header file sysroot-*-kos/include/coresrv/dcm/dcm_api.h from the KasperskyOS SDK.

Information about API functions

pub.h functions

Function	Information about the function
`DcmPublishGroupEndpoints()`	Purpose Publishes a group of endpoints to `DCM`. Parameters [in] `endpoints` – pointer to the array of structures containing information about grouped endpoints, such as the pointers to the qualified names of endpoints, pointers to the names of endpoint interfaces, and the contexts of endpoints. The maximum names size (in bytes), while taking into account the terminating zero, corresponds to the value of the `UCoreStringSize` constant defined in the `sysroot-*-kos/include/kl/core/Types.idl` file from the KasperskyOS SDK. [in] `endpointsCount` – number of grouped endpoints. [in] `serverHandle` – handle that identifies the server. [out] `outPubHandle` – pointer to the DCM handle that enables receipt of client requests to create IPC channels to use endpoints in a specific group with specific interfaces. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code.
`DcmListenGroupPub()`	Purpose Receives a client request to create an IPC channel for use of an endpoint from a published group. Parameters [in] `pubHandle` – DCM handle obtained by calling the `DcmPublishGroupEndpoints()` function. [in] `msec` – timeout (in milliseconds) for the appearance of a client request, or `INFINITE_TIMEOUT` to define an unlimited timeout. The constant `INFINITE_TIMEOUT` is defined in the header file `sysroot--kos/include/rtl/rtc.h` from the KasperskyOS SDK. [out] `outContext` – pointer to the context of an endpoint in the published group. [out] `outConnectionId` – pointer to the DCM handle that enables you to accept or reject a client request to create an IPC channel. [out,optional] `outClientHandle` – pointer to the handle identifying the client, or `RTL_NULL` if this handle is not required. [out,optional] `outClientName` – pointer to the buffer for the client name, or `RTL_NULL` if this name is not required. The maximum name size (in bytes), while taking into account the terminating zero, corresponds to the value of the `UCoreStringSize` constant defined in the `sysroot--kos/include/kl/core/Types.idl` file from the KasperskyOS SDK. [in,optional] `clientNameSize` – size (in bytes) of the buffer for the client name, or `0` if this name is not required. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code. If a blocking call was interrupted by calling the `DcmInterruptGroupPubBlockingCall()` function, `rcAbort` is returned. Additional information Non-blocking call if the `msec` parameter is set to `0`.
`DcmInterruptGroupPubBlockingCall()`	Purpose Interrupts a blocking call of the `DcmListenGroupPub()` function. Parameters [in] `pubHandle` – DCM handle specified when calling the `DcmListenGroupPub()` function. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code.
`DcmCloseGroupPubHandle()`	Purpose Closes the DCM handle that was received by calling the `DcmPublishGroupEndpoints()` function. Parameters [in] `pubHandle` – DCM handle. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code.
`DcmSubscribeToGroupPubEvent()`	Purpose Configures the notification receiver to receive notifications about events related to the object identified by the defined DCM handle. Parameters [in] `notice` – identifier of the notification receiver. The parameter type is defined in the header file `sysroot-*-kos/include/coresrv/handle/notice_api.h` from the KasperskyOS SDK. [in] `pubHandle` – DCM handle obtained by calling the `DcmPublishGroupEndpoints()` function. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code.
`DcmUnsubscribeFromGroupPubEvent()`	Purpose Configures the notification receiver to not receive notifications about events related to the object identified by the defined DCM handle. Parameters [in] `notice` – identifier of the notification receiver. The parameter type is defined in the header file `sysroot-*-kos/include/coresrv/handle/notice_api.h` from the KasperskyOS SDK. [in] `pubHandle` – DCM handle obtained by calling the `DcmPublishGroupEndpoints()` function. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code.

Page top