Using the base API (dcm

Using the base API (dcm_api.h)

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

General information about using the API:

Servers publish endpoints and/or component instances (endpoint containers) to DCM.
Clients receive notifications regarding the publication of individual endpoints and/or component instances.
A separate IPC channel is created to enable use of each endpoint of a server. This IPC channel is identified on the client side by a callable handle.
If a client needs to use a server endpoint, this client can make a request to the server to create one IPC channel to use that endpoint.
If a client needs to use a set of server endpoints provided by a component instance, this client can make a request to the server to create multiple IPC channels to use that set of endpoints.

Information about API functions is provided in the table below.

Dynamically creating IPC channels on the server side

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

Create a connect to DCM by calling the DcmInit() function.
Publish the provided endpoints and/or instances of components to DCM by using the DcmPublishEndpoint() and/or DcmPublishComponent() function.
The DcmPublishEndpoint() function publishes the server endpoint, and the DcmPublishComponent() function publishes the server component instance.

In the serverHandle parameter of the DcmPublishEndpoint() and DcmPublishComponent() functions, you need to specify the handle that identifies the server. The server-identifying handle can be the handle of this server process that was obtained by sequentially calling the KosTaskGetSelf() and KosTaskGetHandle() functions from the task.h API, or the handle that was created by calling the KnHandleCreateUserObject() function from the handle_api.h API. (When calling the KnHandleCreateUserObject() function, the rights parameter must specify the OCAP_HANDLE_TRANSFER and OCAP_HANDLE_GET_SID flags.) Clients can receive the descendant of the handle that identifies the server process via the optional outServerHandle parameter of the DcmReadPubQueue() function. After the endpoint or component instance has been published, the server-identifying handle can be closed but only if this handle was not obtained by calling the KosTaskGetHandle() function. (A handle obtained by calling the KosTaskGetHandle() function cannot be closed because the closed handle could then be used to identify other resources, which will lead to errors.)

A DcmPublishEndpoint() function call creates a DCM handle that enables receipt of client requests to create an IPC channel to use a specific endpoint. A DcmPublishComponent() function call creates a DCM handle that enables receipt of client requests to create multiple IPC channels to use the set of endpoints of the defined component instance.

To unpublish an endpoint or component instance, call the DcmCloseHandle() function to close the DCM handle that was created when they published. If a server terminates, all of its published endpoints and instances of server components will also be unpublished.
Receive a client request to create an IPC channel (or channels) by calling the DcmListen() function.
Calls of the DcmListen() function with the same DCM handle in the pubHandle parameter let you receive only those client requests that are aimed at creating one or more IPC channels to use the endpoint or the set of endpoints of the component instance that were specified when creating this DCM handle at step 2. (The server also receives client requests that were made before the endpoint or component instance was published.)

You can use the optional outClientHandle and outClientName parameters of the DcmListen() function to get the handle identifying the client and the client name, respectively. (The handle identifying the client is the descendant of the handle specified in the clientHandle parameter of the DcmCreateConnection() function called on the client side.) This data can be used to make a decision on whether to accept or reject a client request. For example, the handle identifying the client may be used to get information about the client from other processes or to get the SID for this handle to compare it to other client-identifying handles available to the server. After making a decision, you can close the handle that identifies the client.

A DcmListen() function call creates a DCM handle that enables acceptance or rejection of a client request to create an IPC channel (or channels).
Accept a client request to create one or more IPC channels by calling the DcmAcceptEndpointConnection() or DcmAcceptComponentConnection() function.
The DcmAcceptEndpointConnection() function accepts a client request to create an IPC channel to use a server endpoint, and the DcmAcceptComponentConnection() function accepts a client request to create IPC channels to use the set of endpoints of a server component instance.

In the connectionId parameter of the DcmAcceptEndpointConnection() and DcmAcceptComponentConnection() functions, specify the DCM handle that was obtained at step 3.

In the sessionHandleDesc parameter of the DcmAcceptEndpointConnection() function, you need to specify the handle transport container that contains the callable handle for using the endpoint. In the sessionHandlesCnt parameter of the DcmAcceptComponentConnection() function, you need to specify the number of endpoints provided by the component instance, which is the number of endpoints listed in the CDL file. Use the sessionHandleDescs parameter of the DcmAcceptComponentConnection() function to define an array of handle transport containers that contain callable handles for using the set of endpoints of the component instance. The order of elements in the array must match the order in which the endpoints are listed in the CDL file. You can grant access to only a portion of the endpoints of a component instance. For endpoints that will not be provided to the client, the INVALID_HANDLE value must be specified instead of callable handles. At least one element of the array must contain a callable handle.

To create a callable handle, call the KnHandleCreateUserObjectEx() function from the handle_api.h API. When calling the KnHandleCreateUserObjectEx() function, the rights parameter must specify the OCAP_IPC_CALL and OCAP_HANDLE_TRANSFER flags, and the ipcChannel and riid parameters must specify the server IPC handle of the created IPC channel and the endpoint ID (RIID), respectively. The server IPC handle is used to initialize IPC transport and manage IPC request processing on the server side. You can use the KnHandleCreateListener() function from the handle_api.h API to create a server handle. The endpoint ID (RIID) is a constant in the automatically generated transport code, for example: FsDriver_operationsComp_fileOperations_iid. After the client request is accepted, the callable handle can be closed.

To place a callable handle into the handle transport container, use the nk_handle_desc() macro that is defined in the header file sysroot-*-kos/include/nk/types.h from the KasperskyOS SDK. For the second parameter of the nk_handle_desc() macro, you can specify the NK_SAME macro that is defined in the same header file. In this case, the descendant of the transferred callable handle will have the same permissions mask as the transferred callable handle. The transfer of a callable handle to a client can be associated with a resource transfer context object by specifying the handle of this object in the third parameter of the nk_handle_desc() macro. This will let you use the notice_api.h API to track the closing or revocation of descendants of the callable handle that form the handle inheritance subtree whose root node was generated when this callable handle was transferred to the client. The transferred callable handle can be closed by the client, but this handle is also closed when the client terminates. To create a resource transfer context object, call the KnHandleCreateBadge() function from the handle_api.h API.

You can use the context parameter of the KnHandleCreateUserObjectEx() and KnHandleCreateBadge() functions to define the data to be associated with the callable handle and the transfer of the callable handle, respectively (similar to the user resource context and resource transfer context). The server will be able to receive the pointer to this data when dereferencing the callable handle. (Even though the callable handle is an IPC handle, the kernel puts it into the base_.self field of the constant part of an IPC request.)

To reject a client request to create one or more IPC channels, call the DcmCloseHandle() function to close the DCM handle that was obtained at step 3. (In this case, a DcmConnectToEndpoint() or DcmConnectToComponent() function call on the client side will end with the rcNotConnected error.) If the client request is accepted, the DCM handle obtained at step 3 must also be closed but only after calling the DcmAcceptEndpointConnection() or DcmAcceptComponentConnection() function.

Dynamically creating IPC channels on the client side

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

Create a connect to DCM by calling the DcmInit() function.
If a client needs to use an individual endpoint (not a set of endpoints of a component instance), you can call the DcmConnectAny() or DcmConnectAnyEx() function from the auxiliary API for connect.h clients instead of completing the subsequent steps.
Create a DCM handle that enables receipt of notifications about publication and unpublication of endpoints with the defined interface or instances of the component with the defined name.
To complete this step, call the DcmSubscribeToEndpoints() or DcmSubscribeToComponents() function. The DcmSubscribeToEndpoints() function creates a DCM handle that lets you receive notifications about the publication and unpublication of endpoints with the defined interface, and the DcmSubscribeToComponents() function creates a DCM handle that lets you receive notifications about the publication and unpublication of component instances with the defined name.

Use the optional endpointName, componentName, serverName, and serverHandle parameters of the DcmSubscribeToEndpoints() and DcmSubscribeToComponents() functions to include notification filtering based on the qualified name of the endpoint, qualified name of the component instance, server name, and server-identifying handle, respectively. (The server-identifying handle is the descendant of the handle specified in the serverHandle parameter of the DcmPublishEndpoint() or DcmPublishComponent() function that was called on the server side. The client can receive this handle from another process, for example.) Like the handle, the server name uniquely identifies the server. Therefore, you can define a specific server by specifying the handle that identifies this server or the name of this server.

In the clientHandle parameter of the DcmSubscribeToEndpoints() and DcmSubscribeToComponents() functions, specify the handle that identifies the client. The client-identifying handle can be the handle of this client process that was obtained by sequentially calling the KosTaskGetSelf() and KosTaskGetHandle() functions from the task.h API, or the handle that was created by calling the KnHandleCreateUserObject() function from the handle_api.h API. (When calling the KnHandleCreateUserObject() function, the OCAP_HANDLE_TRANSFER and OCAP_HANDLE_GET_SID flags must be specified in the rights parameter.) The client-identifying handle cannot be closed at this step because it will be needed later to complete step 4.

After calling the DcmSubscribeToEndpoints() or DcmSubscribeToComponents() function, a notification queue is generated and begins to also receive notifications about the publication of endpoints or component instances that were published before these functions were called and that meet the filter criteria.

If you no longer need to receive notifications about the publication and unpublication of endpoints or component instances, the DCM handle that was obtained by calling the DcmSubscribeToEndpoints() or DcmSubscribeToComponents() function must be closed by calling the DcmCloseHandle() function.
You can extract a notification about endpoint or component instance publishing from the queue of these notifications by calling the DcmReadPubQueue() function.
In the subscrHandle parameter of the DcmReadPubQueue() function, specify the DCM handle that was obtained at step 2.

You can use the optional outServerHandle, outServerName, and outNodeName parameters of the DcmReadPubQueue() function to get the server-identifying handle, the server name, and the qualified name of the endpoint or component instance, respectively. (The server-identifying handle is the descendant of the handle that was specified in the serverHandle parameter of the DcmPublishEndpoint() or DcmPublishComponent() function that was called on the server side.) This data can be used to decide whether to make a request to create one or more IPC channels with the server. For example, the handle identifying the server may be used to get information about the server from other processes or to get the SID for this handle to compare it to other server-identifying handles available to the client.

The value received via the outPubStatus parameter of the DcmReadPubQueue() function indicates the publication status of the endpoint or component instance. A notification regarding the unpublication of an endpoint or component instance appears in the queue only if the notification about the publication of that endpoint or component instance was previously retrieved. An endpoint or component instance can be unpublished by the server or as a result of server termination.
Create a DCM handle that enables fulfillment of a request to create an IPC channel (or channels) to the server.
To complete this step, call the DcmCreateConnection() function. Use the nodeType parameter to specify the name of the relevant endpoint interface or the name of the component whose instance provides the necessary set of endpoints. Use the nodeName parameter to define the qualified name of the relevant endpoint or the qualified name of the component instance that provides the necessary set of endpoints.

In the serverHandle parameter of the DcmCreateConnection() function, specify the handle that identifies the server. This handle can be obtained at step 3 via the outServerHandle parameter of the DcmReadPubQueue() function or by other means, such as from another process.

In the clientHandle parameter of the DcmCreateConnection() function, specify the handle that identifies the client. You need to specify the handle that was defined in the clientHandle parameter of the DcmSubscribeToEndpoints() or DcmSubscribeToComponents() function at step 2. (Servers can receive descendants of this handle through the optional outClientHandle parameter of the DcmListen() function.) After creating a DCM handle that enables a request to create one or more IPC channels, the handle that identifies the client can be closed but only if this handle was not obtained by calling the KosTaskGetHandle() function from the task.h API. (A handle obtained by calling the KosTaskGetHandle() function cannot be closed because the closed handle could then be used to identify other resources, which will lead to errors.)
Make a request to create an IPC channel or IPC channels with a server.
To complete this step, call the DcmConnectToEndpoint() or DcmConnectToComponent() function. The DcmConnectToEndpoint() function makes a request to create an IPC channel with the server to use an endpoint, and the DcmConnectToComponent() function makes a request to create IPC channels with the server to use the set of endpoints of a component instance.

In the connectionId parameter of the DcmConnectToEndpoint() and DcmConnectToComponent() functions, specify the DCM handle that was obtained at step 4. In the sessionHandlesCnt parameter of the DcmConnectToComponent() function, you need to specify the number of endpoints provided by the component instance, which is the number of endpoints listed in the CDL file.

As a result of the DcmConnectToEndpoint() function call, the client uses the outSessionHandleDesc parameter to receive a handle transport container that contains a callable handle for using the endpoint. As a result of the DcmConnectToComponent() function call, the client uses the outSessionHandleDescs parameter to receive an array of handle transport containers that contain callable handles for using the set of endpoints of the component instance. The order of elements in the array matches the order in which the endpoints are listed in the CDL file. The server can provide only a portion of the endpoints of a component instance. If the server decided not to provide an endpoint, the corresponding handle transport container will contain the INVALID_HANDLE value instead of the callable handle.

To retrieve the callable handle from the handle transport container, use the nk_get_handle() macro that is defined in the header file sysroot-*-kos/include/nk/types.h from the KasperskyOS SDK.

The client uses a callable handle to initialize IPC transport. In addition, the client specifies the INVALID_RIID value as the Runtime Implementation Identifier (RIID) in the proxy object initialization function.

After receiving a callable handle, the DCM handle obtained at step 4 must be closed by calling the DcmCloseHandle() function.

Interrupting blocking function calls

To interrupt a blocking call of the DcmConnectToEndpoint(), DcmConnectToComponent(), DcmReadPubQueue() or DcmListen() function from another thread, call the DcmInterruptBlockingCall() function.

Tracking events

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

A server publishes or unpublishes an endpoint or component instance (DCM_PUBLICATION_CHANGED event mask flag, DCM handle obtained by calling the DcmSubscribeToEndpoints() or DcmSubscribeToComponents() function).
A server receives a client request to create an IPC channel to use an endpoint or IPC channels to use a set of endpoints of a component instance (DCM_CLIENT_CONNECTED event mask flag, DCM handle obtained by calling the DcmPublishEndpoint() or DcmPublishComponent() function).
A blocking call of the DcmConnectToEndpoint(), DcmConnectToComponent(), DcmReadPubQueue(), or DcmListen() function is interrupted (DCM_BLOCKING_CALL_INTERRUPTED event mask flag, DCM handle obtained by calling the DcmCreateConnection(), DcmSubscribeToEndpoints(), DcmSubscribeToComponents(), DcmPublishEndpoint(), or DcmPublishComponent() function).
A server accepts or rejects a client request to create an IPC channel to use an endpoint or IPC channels to use a set of endpoints of a component instance (DCM_CLIENT_RELEASED_BY_SERVER event mask flag, DCM handle obtained by calling the DcmCreateConnection() function).

The DcmSubscribeToEvents*() and DcmUnsubscribeFromEvents() functions let you configure the notification receiver by adding or deleting, respectively, tracked objects identified by DCM handles. The DcmSubscribeToEvents() function defines the identifier DCM_EVENT_ID for "resource–event mask" entries, and the DcmSubscribeToEventsEx() function lets you define your own identifiers for "resource–event mask" entries.

Deleting dynamically created IPC channels

A dynamically created IPC channel will be deleted when closing the callable handle and server IPC handle of this IPC channel.

Deleting a DCM connection

If you no longer need to use DCM, you need to call the DcmFini() function to delete the connection to DCM and thereby free up the resources linked to this connection.

Information about API functions

dcm_api.h functions

Function	Information about the function
`DcmInit()`	Purpose Creates a connection to `DCM`. Parameters N/A Returned values If successful, the function returns `rcOk`, otherwise it returns an error code. If there is no IPC channel to `DCM`, the function returns `rcNoCapability`. Additional information Thread-safe function. Non-blocking call.
`DcmFini()`	Purpose Deletes a connection to `DCM`. Parameters N/A Returned values N/A Additional information Thread-safe function. Non-blocking call.
`DcmSubscribeToEvents()`	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] `handle` – DCM handle obtained by calling the `DcmSubscribeToEndpoints()`, `DcmSubscribeToComponents()`, `DcmCreateConnection()`, `DcmPublishEndpoint()`, or `DcmPublishComponent()` function. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code.
`DcmSubscribeToEventsEx()`	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] `handle` – DCM handle obtained by calling the `DcmSubscribeToEndpoints()`, `DcmSubscribeToComponents()`, `DcmCreateConnection()`, `DcmPublishEndpoint()`, or `DcmPublishComponent()` function. [in] `eventId` – ID of the "resource–event mask" entry. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code.
`DcmUnsubscribeFromEvents()`	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] `handle` – DCM handle obtained by calling the `DcmSubscribeToEndpoints()`, `DcmSubscribeToComponents()`, `DcmCreateConnection()`, `DcmPublishEndpoint()`, or `DcmPublishComponent()` function. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code.
`DcmCloseHandle()`	Purpose Closes a DCM handle that was obtained by calling the `DcmSubscribeToEndpoints()`, `DcmSubscribeToComponents()`, `DcmCreateConnection()`, `DcmPublishEndpoint()`, `DcmPublishComponent()`, or `DcmListen()` function from the main API, and the `DcmListenGroupPub()` function from the additional API for servers. Parameters [in] `handle` – DCM handle. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code.
`DcmInterruptBlockingCall()`	Purpose Interrupts a blocking call of the `DcmConnectToEndpoint()`, `DcmConnectToComponent()`, `DcmReadPubQueue()`, or `DcmListen()` function. Parameters [in] `handle` – DCM handle specified when calling the `DcmConnectToEndpoint()`, `DcmConnectToComponent()`, `DcmReadPubQueue()` or `DcmListen()` function. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code.
`DcmSubscribeToEndpoints()`	Purpose Creates a DCM handle that enables receipt of a notification about publishing and unpublishing of endpoints with a specific interface. Parameters [in] `endpointType` – pointer to the name of the interface of endpoints. 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] `endpointName` – pointer to the qualified name of the endpoint, or `RTL_NULL` to not use notification filtering based on the qualified name of the endpoint. 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] `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 endpoints with a specific interface. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code.
`DcmSubscribeToComponents()`	Purpose Creates a DCM handle that enables receipt of notifications about the publishing and unpublishing of component instances with specific names. Parameters [in] `componentType` – pointer to the component name. 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] `componentName` – pointer to the qualified name of the component instance, or `RTL_NULL` to not use notification filtering based on the qualified name of the component instance. 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] `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 publishing and unpublishing instances of the component with the defined name. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code.
`DcmReadPubQueue()`	Purpose Extracts a notification about the publishing and unpublishing of an endpoint or component instance from the notification queue. Parameters [in] `subscrHandle` – DCM handle that was created by calling the `DcmSubscribeToEndpoints()` or `DcmSubscribeToComponents()` 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. [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,optional] `serverNameSize` – size (in bytes) for the server name, or `0` if this name is not required. [out,optional] `outNodeName` – pointer to the buffer for the qualified name of the endpoint or the component instance, 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] `nodeNameSize` – size (bytes) of the buffer for the qualified name of the endpoint or component instance, or `0` if this name is not required. [out] `outPubStatus` – pointer to a value that indicates the publication status of the endpoint or component instance: `DcmEndpointPublished` – the endpoint has been published, `DcmEndpointUnpublished` – the endpoint has been unpublished, `DcmComponentPublished` – the component instance has been published, `DcmComponentUnpublished` – the component instance has been unpublished. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code. If a blocking call was interrupted by calling the `DcmInterruptBlockingCall()` function, `rcAbort` is returned. Additional information Non-blocking call if the `msec` parameter is set to `0`.
`DcmCreateConnection()`	Purpose Creates a DCM handle that enables a request to create one or more IPC channels with a server to use a defined endpoint or set of endpoints of a defined component instance. Parameters [in] `nodeType` – pointer to the endpoint interface name or the component name. 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] `nodeName` – pointer to the qualified name of the endpoint or component instance. 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] `serverHandle` – handle that identifies the server. [in] `clientHandle` – handle that identifies the client. [out] `outConnectionId` – pointer to the DCM handle that enables fulfillment of a request to create IPC channels to the server to use a specific endpoint or a set of endpoints with a specific component instance. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code.
`DcmConnectToEndpoint()`	Purpose Makes a request to create an IPC channel with a server to use an endpoint. Parameters [in] `connectionId` – DCM handle obtained by calling the `DcmCreateConnection()` function. [in] `msec` – timeout (in milliseconds) for fulfilling a 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] `outSessionHandleDesc` – pointer to the handle transport container that contains the callable handle for using the endpoint. The type of handle transport container is defined in the header file `sysroot--kos/include/nk/types.h` from the KasperskyOS SDK. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code. If the `msec` parameter is set to `0` and the server did not handle the request to create an IPC channel, the function returns `rcNotReady`. If a blocking call was interrupted by calling the `DcmInterruptBlockingCall()` function, `rcAbort` is returned. If the server rejected the request by calling the `DcmCloseHandle()` function, it returns `rcNotConnected`. Additional information Non-blocking call if the `msec` parameter is set to `0`.
`DcmConnectToComponent()`	Purpose Makes a request to create IPC channels with a server to use a set of endpoints of a component instance. Parameters [in] `connectionId` – DCM handle obtained by calling the `DcmCreateConnection()` function. [in] `msec` – timeout (in milliseconds) for fulfilling a 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. [in] `sessionHandlesCnt` – number of endpoints provided by the component instance. [out] `outSessionHandleDescs` – pointer to an array of handle transport containers that contain callable handles for using the set of endpoints of the component instance. The number of elements in an array cannot exceed the value of the `HandlesLimit` constant defined in the `sysroot--kos/include/kl/core/DCM.idl` file from the KasperskyOS SDK. The type of handle transport container is defined in the header file `sysroot-*-kos/include/nk/types.h` from the KasperskyOS SDK. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code. If the `msec` parameter is set to `0` and the server did not handle the request to create IPC channels, the function returns `rcNotReady`. If a blocking call was interrupted by calling the `DcmInterruptBlockingCall()` function, `rcAbort` is returned. If the server rejected the request by calling the `DcmCloseHandle()` function, it returns `rcNotConnected`. Additional information Non-blocking call if the `msec` parameter is set to `0`.
`DcmPublishEndpoint()`	Purpose Publishes the endpoint to `DCM`. Parameters [in] `endpointType` – pointer to the name of the endpoint interface. 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] `endpointName` – pointer to the qualified name of the endpoint. 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] `serverHandle` – handle that identifies the server. [out] `outPubHandle` – pointer to the DCM handle that enables receipt of client requests to create an IPC channel to use a specific endpoint. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code.
`DcmPublishComponent()`	Purpose Publishes a component instance to `DCM`. Parameters [in] `componentType` – pointer to the component name. 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] `component name` – pointer to the qualified name of the component instance. 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] `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 the set of endpoints of the defined component instance. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code.
`DcmListen()`	Purpose Receives a client request to create an IPC channel (or channels). Parameters [in] `pubHandle` – DCM handle created by calling the `DcmPublishEndpoint()` or `DcmPublishComponent()` 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] `outConnectionId` – pointer to the DCM handle that enables you to accept or reject a client request to create an IPC channel (or channels). [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 `DcmInterruptBlockingCall()` function, `rcAbort` is returned. Additional information Non-blocking call if the `msec` parameter is set to `0`.
`DcmAcceptEndpointConnection()`	Purpose Accepts a client request to create an IPC channel to use an endpoint. Parameters [in] `connectionId` – DCM handle obtained by calling the `DcmListen()` function. [in] `sessionHandleDesc` – handle transport container that contains a callable handle for use of the endpoint. The type of handle transport container is defined in the header file `sysroot-*-kos/include/nk/types.h` from the KasperskyOS SDK. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code.
`DcmAcceptComponentConnection()`	Purpose Accepts a client request to create IPC channels to use a set of endpoints of a component instance. Parameters [in] `connectionId` – DCM handle obtained by calling the `DcmListen()` function. [in] `sessionHandlesCnt` – number of endpoints provided by the component instance. [in] `sessionHandleDescs` – pointer to an array of handle transport containers that contain callable handles for using the set of endpoints of the component instance. The number of elements in an array must not exceed the value of the `HandlesLimit` constant defined in the `sysroot--kos/include/kl/core/DCM.idl` file from the KasperskyOS SDK. The type of handle transport container is defined in the header file `sysroot--kos/include/nk/types.h` from the KasperskyOS SDK. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code.

Page top