Dynamically created IPC channels
The capability to dynamically create IPC channels allows you to change the topology of interaction between entities on the fly. This is necessary if it is unknown which specific server entity will become the resource provider required by a client entity. For example, you may not know which specific drive you will need to write data to.
In contrast to a statically created IPC channel, a dynamically created IPC channel has the following characteristics:
- It is created between entities that have been started.
- It is created jointly by the client entity and server entity.
- It can be deleted.
- It involves the use of a name server (
kl.core.NameServerentity), which facilitates the transfer of information about available interface implementations from server entities to client entities.
A dynamically created IPC channel uses the following functions:
- Name Server interface
- Connection Manager
The Name Server interface is provided for the user in the following files:
coresrv/ns/ns_api.his a header file of thelibkoslibrary;coresrv/ns/NameServer.idlis an IDL description of the IPC interface of the Name Server.
The Connection Manager is provided for the user in the following files:
coresrv/cm/cm_api.his a header file of thelibkoslibrary;services/cm/CM.idlis an IDL description of the Connection Manager's IPC interface.
An IPC channel is dynamically created according to the following scenario:
- A client entity, server entity and name server are started.
- The server entity connects to the name server by using the
NsCreate()function and publishes the server entity name, interface name, and interface implementation name by using theNsPublishService()function. - The client entity uses the
NsCreate()function to connect to the name server and then uses theNsEnumServices()function to search for the name of the server entity and the name of the interface implementation based on the interface name. - The client entity uses the
KnCmConnect()function to request access to the interface implementation and passes the found server entity name and interface implementation name as arguments to the function. - The server entity calls the
KnCmListen()function to check if the client entity sent a request to access the provided interface implementation. - The server entity accepts the request to access the provided interface implementation by using the
KnCmAccept()function, to which it passes the client entity name and interface implementation name received from theKnCmListen()function as arguments.
To use a name server, the solution security policy must allow the kl.core.NameServer entity to interact with entities for which IPC channels can be dynamically created.
The server entity can use the NsUnPublishService() function to unpublish interface implementations that were previously published on the name server.
The server entity can use the KnCmDrop() function to reject requests to access interface implementations.
ns_api.h (fragment)
/**
* Attempts to connect to name server "name"
* for the specified number of msecs. If the "name" parameter has the value
* RTL_NULL, the function attempts to connect to name server "ns"
* (default name server). Output parameter "ns" contains the handle
* of the connection with the name server.
* If successful, the function returns rcOk, otherwise it returns an error code.
*/
Retcode NsCreate(const char *name, rtl_uint32_t msecs, NsHandle *ns);
/**
* Publishes the interface implementation on the name server.
* The "ns" parameter defines the handle for the connection with the name server.
* The "server" parameter defines the name of the server entity (for example, ata).
* The "type" parameter defines the name of the published interface (for example, IBlkDev).
* The "service" parameter defines the name of the published interface implementation
* (for example, blkdev.blkdev).
* If successful, the function returns rcOk, otherwise it returns an error code.
*/
Retcode NsPublishService(NsHandle ns, const char *type, const char *server,
const char *service);
/**
* Unpublishes the interface implementation on the name server.
* The "ns" parameter defines the handle for the connection with the name server.
* The "server" parameter defines the name of the server entity. The "type" parameter defines the name
* of the published interface. The "service" parameter defines the name of the implementation
* of the published interface.
* If successful, the function returns rcOk, otherwise it returns an error code.
*/
Retcode NsUnPublishService( NsHandle ns, const char *type, const char *server,
const char *service);
/**
* Enumerates the interface implementations published on the
* name server. The "ns" parameter defines the handle for the connection with the name server.
* The "type" parameter defines the name of the required interface. The "index" parameter
* defines the index for enumerating the interface implementations.
* Output parameter "server" contains the name of the server entity providing the
* interface implementation. Output parameter "service" contains the name of the
* interface implementation.
* For example, IBlkDev interface implementations are enumerated
* as follows.
* rc = NsEnumServices(ns, "IBlkDev", 0, outServerName, outServiceName);
* rc = NsEnumServices(ns, "IBlkDev", 1, outServerName, outServiceName);
* ...
* rc = NsEnumServices(ns, "IBlkDev", N, outServerName, outServiceName);
* Function calls with index incrementation continue until
* the function returns rcResourceNotFound.
* If successful, the function returns rcOk, otherwise it returns an error code.
*/
Retcode NsEnumServices(NsHandle ns, const char *type, unsigned index,
char *server, char *service);
cm_api.h (fragment)
/**
* Requests access to the interface implementation named "service"
* provided by server entity "server". The "msecs" parameter defines the
* timeout period (in milliseconds) for the server entity to accept the request. Output
* parameter "endpoint" contains the client IPC handle. Output parameter
* "rsid" contains the identifier of the interface implementation.
* If successful, the function returns rcOk, otherwise it returns an error code.
*/
Retcode KnCmConnect(const char *server, const char *service,
rtl_uint32_t msecs, Handle *endpoint,
rtl_uint32_t *rsid);
/**
* Checks if there is a request to access the interface implementation
* named "filter". If the "filter" parameter has the value RTL_NULL,
* it checks if there is a request to access any
* interface implementation. The "msecs" parameter defines the request timeout period
* in milliseconds. Output parameter "client" contains the name
* of the client entity. Output parameter "service" contains the name of the
* interface implementation.
* If successful, the function returns rcOk, otherwise it returns an error code.
*/
Retcode KnCmListen(const char *filter, rtl_uint32_t msecs, char *client,
char *service);
/**
* Rejects the request to access the interface implementation
* named "service" by client entity "client".
* If successful, the function returns rcOk, otherwise it returns an error code.
*/
Retcode KnCmDrop(const char *client, const char *service);
/**
* Accepts the request to access the interface implementation
* named "service" by client entity "client". The "rsid" parameter defines
/* interface implementation identifier. The "listener" parameter defines
* the listener handle. If the "listener" parameter has the value
* INVALID_HANDLE, a new listener handle is created.
* Output parameter "endpoint" contains the server IPC handle.
* If successful, the function returns rcOk, otherwise it returns an error code.
*/
Retcode KnCmAccept(const char *client, const char *service, rtl_uint32_t rsid,
Handle listener, Handle *endpoint);
The filter parameter of the KnCmListen() function is reserved and does not affect the behavior of the function. The behavior of the function corresponds to the RTL_NULL value of the filter parameter.
The listener handle is a server IPC handle with expanded rights. It is created when the KnCmAccept() function is called with the INVALID_HANDLE argument in the listener parameter. If a listener handle is passed to the KnCmAccept() function when it is called, the created server IPC handle will provide the capability to receive requests over all IPC channels associated with this listener handle. (The first IPC channel associated with the listener handle is created when the KnCmAccept() function is called with the INVALID_HANDLE argument in the listener parameter. The second and subsequent IPC channels associated with the listener handle are created during the second and subsequent calls of the KnCmAccept() function, to which the listener handle obtained during the first call is passed.)
The listener handle is also used when statically creating IPC channels. It is created when the KnHandleConnectEx() function is called with the INVALID_HANDLE argument in the srListener parameter. If a listener handle is passed to the KnHandleConnectEx() function when it is called, the created server IPC handle will provide the capability to receive requests over all IPC channels associated with this listener handle. A listener handle is associated with multiple IPC channels if multiple IPC channels with identical names are created for one server entity.
If the dynamically created IPC channel is no longer required, its client and server handles should be deleted. The IPC channel can be created again if necessary.