Using the auxiliary API for clients (connect.h)

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

The API allows clients to make requests to create IPC channels to servers to use endpoints with the defined interfaces. To execute a request, it is sufficient to call the DcmConnectAny () or DcmConnectAnyEx () function, while when using the basic API dcm_api.h, this requires a sequence of calls: DcmSubscribeToEndpoints () , DcmReadPubQueue () , DcmCreateConnection () , DcmConnectToEndpoint().

Before calling the DcmConnectAny() or DcmConnectAnyEx() function, you must create a connection to the DCM by calling the DcmInit() function from the base API dcm_api.h.

As a result of calling the DcmConnectAny() or DcmConnectAnyEx() function, the client receives a callable handle for the endpoint in the outSessionHandle parameter.

A call of the DcmConnectAny() function corresponds to a call of the DcmConnectAnyEx() function when the endpointName and serverName parameters are set to RTL_NULL, the serverHandle and clientHandle parameters are set to INVALID_HANDLE, and the findTimeout and connectTimeout parameters are set to INFINITE_TIMEOUT.

Information about API functions is provided in the table below.

connect.h functions

Function	Information about the function
`DcmConnectAny()`	Purpose Makes a request to create an IPC channel with a server to use an endpoint with the specified interface. 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. [out] `outSessionHandle` – pointer to a callable handle for using the endpoint. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code.
`DcmConnectAnyEx()`	Purpose Makes a request to create an IPC channel with a server to use an endpoint with the specified interface. 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,optional] `endpointName` – pointer to the qualified name of the endpoint, or `RTL_NULL` if any endpoint with the defined interface is suitable for use. 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` if it doesn't matter which specific server provides 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] `serverHandle` – handle identifying the server, or `INVALID_HANDLE` if it doesn't matter which specific server provides the endpoint. [in,optional] `clientHandle` – handle that identifies the client, or `INVALID_HANDLE` to use the handle of the calling process to identify the client. [in] `findTimeout` – timeout (in milliseconds) for publishing an endpoint, 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] `connectTimeout` – timeout for a request to create an IPC channel to the server (in milliseconds), 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] `outSessionHandle` – pointer to a callable handle for using the endpoint. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code. If the `connectTimeout` parameter is set to `0` and the server did not handle the request to create an IPC channel, the function returns `rcNotReady`. If the server rejects the request by calling the `DcmCloseHandle()` function from the base API dcm_api.h, the function returns `rcNotConnected`. Additional information Non-blocking call if the `findTimeout` and `connectTimeout` parameters are set to `0`.

Function

Information about the function

DcmConnectAny()

Purpose

Makes a request to create an IPC channel with a server to use an endpoint with the specified interface.

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.
[out] outSessionHandle – pointer to a callable handle for using the endpoint.

Returned values

If successful, the function returns rcOk, otherwise it returns an error code.

DcmConnectAnyEx()

Purpose

Makes a request to create an IPC channel with a server to use an endpoint with the specified interface.

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,optional] endpointName – pointer to the qualified name of the endpoint, or RTL_NULL if any endpoint with the defined interface is suitable for use. 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 if it doesn't matter which specific server provides 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] serverHandle – handle identifying the server, or INVALID_HANDLE if it doesn't matter which specific server provides the endpoint.
[in,optional] clientHandle – handle that identifies the client, or INVALID_HANDLE to use the handle of the calling process to identify the client.
[in] findTimeout – timeout (in milliseconds) for publishing an endpoint, 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] connectTimeout – timeout for a request to create an IPC channel to the server (in milliseconds), 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] outSessionHandle – pointer to a callable handle for using the endpoint.

Returned values

If successful, the function returns rcOk, otherwise it returns an error code.

If the connectTimeout parameter is set to 0 and the server did not handle the request to create an IPC channel, the function returns rcNotReady.

If the server rejects the request by calling the DcmCloseHandle() function from the base API dcm_api.h, the function returns rcNotConnected.

Additional information

Non-blocking call if the findTimeout and connectTimeout parameters are set to 0.

Page top