Using the additional API for clients (subscr.h)

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

The API allows clients to receive notifications about the publishing and unpublishing of endpoint groups. From the client perspective, a group of endpoints is a set of endpoints on one server for which clients can use a single DCM handle to receive notifications about the publishing and unpublishing of those endpoints. However, there is a restriction that prevents a server from providing multiple endpoints with one interface. Multiple servers may provide identical groups of endpoints required by a client. A server may provide multiple groups of endpoints required by a client. A set of endpoints from different groups required by a client may overlap.

Information about API functions is provided in the table below.

Creating a DCM handle that enables receipt of notifications about the publication and unpublication of groups of endpoints

To create a DCM handle that enables receipt of notifications about the publishing and unpublishing of endpoints with specific interfaces, call the DcmSetGroupSubscription() function. Use the endpointTypes parameter to define the names of interfaces of grouped endpoints. In the endpointsCount parameter, specify a number of grouped endpoints equal to the number of interfaces defined via the endpointTypes parameter. (Notifications will contain a number of endpoints equal to the number of interfaces because of the restriction dictating that one separate endpoint corresponds to each interface.)

After calling the DcmSetGroupSubscription() function, a notification queue is generated and begins to also receive notifications about the publication of endpoint groups that were published before this function was called and that meet the filter criteria.

Receiving notifications about the publication and unpublication of groups of endpoints

To extract a notification about the publishing or unpublishing of an endpoint group from the notification queue, call the DcmReadGroupPubQueue() function. In the subscrHandle parameter of the DcmReadGroupPubQueue() function, specify the DCM handle that was obtained by calling the DcmSetGroupSubscription() function. In the maxCount parameter of the DcmReadGroupPubQueue() function, specify the number of elements in the array defined via the outEndpoints parameter. The value of this parameter must be greater than or equal to the number of endpoints in the group. The value obtained via the outPubStatus parameter of the DcmReadGroupPubQueue() function indicates that the group of endpoints was published or unpublished. A notification about the publishing of an endpoint group appears in the queue only if the server publishes all endpoints in the group together or one by one. If the server publishes only a portion of the endpoints required by the client, a notification about the publishing of an endpoint group does not appear. A notification regarding the unpublication of an endpoint group appears in the queue only if the notification about the publication of this endpoint group was previously retrieved. An endpoint group can be unpublished by the server or as a result of server termination.

Using the names of interfaces and the qualified names of endpoints resulting from a DcmSetGroupSubscription() function call, you must create DCM handles that allow you to make requests to create IPC channels with the server to use the necessary endpoints. To create these handles, use the DcmCreateConnection() function from the base API dcm_api.h. Then you need to make requests to create IPC channels with the server by using the DcmConnectToEndpoint() function from the base API dcm_api.h.

Closing a DCM handle that enabled receipt of notifications about the publication and unpublication of groups of endpoints

If you no longer need to receive notifications about the publishing and unpublishing of an endpoint group with specific interfaces, the DCM handle that was created by calling the DcmSetGroupSubscription() function must be closed by calling the DcmCloseGroupSubscrHandle() function.

Interrupting blocking function calls

To interrupt a blocking call of the DcmReadGroupPubQueue() function from another thread, call the DcmInterruptGroupSubscrBlockingCall() function.

Tracking events

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

A server publishes or unpublishes an endpoint from a group (DCM_PUBLICATION_CHANGED event mask flag, DCM handle obtained by calling the DcmSetGroupSubscription() function).
A blocking call of the DcmReadGroupPubQueue() function is interrupted (DCM_BLOCKING_CALL_INTERRUPTED event mask flag, DCM handle obtained by calling the DcmSetGroupSubscription() function).

The DcmSubscribeToGroupSubscrEvent() and DcmUnsubscribeFromGroupSubscrEvent() functions let you configure the notification receiver by adding or deleting, respectively, tracked objects identified by DCM handles. The DcmSubscribeToGroupSubscrEvent() 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

subscr.h functions

Function	Information about the function
`DcmSetGroupSubscription()`	Purpose Creates a DCM handle that enables receipt of notifications about the publishing and unpublishing of endpoint groups with specific interfaces. Parameters [in] `endpointTypes` – pointer to the array containing the names of interfaces of the endpoints being grouped. 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. It must match the number of interfaces defined via the `endpointTypes` parameter. [in,optional] `serverName` – pointer to the server name, or `RTL_NULL` to not use notification filtering based on the specific server. 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] `serverHandle` – handle identifying the server, or `INVALID_HANDLE` to not use notification filtering based on a specific server. [in] `clientHandle` – handle that identifies the client. [out] `outSubscrHandle` – pointer to the DCM handle that enables receipt of notifications about the publishing and unpublishing of endpoint groups with specific interfaces. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code.
`DcmReadGroupPubQueue()`	Purpose Extracts a notification about the publishing or unpublishing of an endpoint group from the notification queue. Parameters [in] `subscrHandle` – DCM handle that was obtained by calling the `DcmSetGroupSubscription()` function. [in] `msec` – timeout (in milliseconds) before notifications appearing, or `INFINITE_TIMEOUT` to set an unlimited timeout. The constant `INFINITE_TIMEOUT` is defined in the header file `sysroot--kos/include/rtl/rtc.h` from the KasperskyOS SDK. [in] `maxCount` – number of elements in the array defined via the `outEndpoints` parameter. It must be greater than or equal to the number of endpoints in the group. [out,optional] `outServerHandle` – pointer to the handle identifying the server, or `RTL_NULL` if this handle is not required. [out,optional] `outServerName` – pointer to the buffer for the server 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] `serverNameSize` – size (in bytes) for the server name, or `0` if this name is not required. [out] `outEndpoints` – pointer to the array of structures containing the qualified names of endpoints in the group and the names of interfaces of the group 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. [out] `outEndpointsCount` – pointer to the number of endpoints in the group. [out] `outPubStatus` – pointer to the value indicating that the group of endpoints was published (`DcmEndpointPublished`) or unpublished (`DcmEndpointUnpublished`). The data type for storing this value is defined in the header file `sysroot--kos/include/coresrv/dcm/dcm_api.h`. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code. If a blocking call was interrupted by calling the `DcmInterruptGroupSubscrBlockingCall()` function, `rcAbort` is returned. Additional information Non-blocking call if the `msec` parameter is set to `0`.
`DcmInterruptGroupSubscrBlockingCall()`	Purpose Interrupts a blocking call of the `DcmReadGroupPubQueue()` function. Parameters [in] `subscrHandle` – DCM handle specified when calling the `DcmReadGroupPubQueue()` function. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code.
`DcmCloseGroupSubscrHandle()`	Purpose Closes the DCM handle that was obtained by calling the `DcmSetGroupSubscription()` function. Parameters [in] `subscrHandle` – DCM handle. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code.
`DcmSubscribeToGroupSubscrEvent()`	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] `subscrHandle` – DCM handle that was obtained by calling the `DcmSetGroupSubscription()` function. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code.
`DcmUnsubscribeFromGroupSubscrEvent()`	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] `subscrHandle` – DCM handle that was obtained by calling the `DcmSetGroupSubscription()` function. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code.

Page top