CASA/CASA-auth-token/non-java/utilities/IpcLibs/README

/***********************************************************************
 * 
 *  Copyright (C) 2006 Novell, Inc. All Rights Reserved.
 *
 *  This library is free software; you can redistribute it and/or
 *  modify it under the terms of the GNU Lesser General Public
 *  License as published by the Free Software Foundation; version 2.1
 *  of the License.
 *
 *  This library is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 *  Library Lesser General Public License for more details.
 *
 *  You should have received a copy of the GNU Lesser General Public
 *  License along with this library; if not, Novell, Inc.
 * 
 *  To contact Novell about this file by physical or electronic mail, 
 *  you may find current contact information at www.novell.com.
 * 
 *  Author: Juan Carlos Luciani <jluciani@novell.com>
 *
 ***********************************************************************/
/***********************************************************************
 *
 *  README for IpcLibs
 *
 ***********************************************************************/

INTRODUCTION

IpcLibs provides an IPC infrastructure that can be linked into client and server
applications.

IpcLibs provides IPC communications over TCP or DOMAIN sockets. It does this in a scalable
and un-serialized manner. The infrastructure can make use of multiple communication channels
between a client and a server and is capabled of concurrently serving multiple requests over
the different channels.

The IpcLib APIs are very simple to utilize and support multi-threaded applications.

SERVER APPLICATION PROGRAMMING NOTES

The IPC API for server applications is defined in casa_s_ipc.h. This API is provided by
libcasa_s_ipc.so.

To utilize the IPC server services, an application must first initialize the infrastructure by
calling IpcServerInit() which is then followed by the desired IpcServerSetXXAddress() call.

After the Ipc server is initialized and the server address is set, then the application calls
IpcServerStart() to start the engine (This causes the engine to start to accept connections and
receive requests from clients).

To start servicing requests, the application executesIpcServerGetRequest(); this calls blocks until
a request is ready to be serviced at which time it returns with an ID which is associated with the
request that needs to be serviced. The returned ID is then used by the application to retrieve the
request data via the IpcServerGetRequestData(), once the application processes the request, it
completes it by executing IpcServerCompleteRequest() with the ID and any data that it may want to
send back to the client.

Note that a server application can call IpcServerGetRequest() from multiple threads to make itself
more scalable.

For an example server application that utilizes the IPC API for servers, see file
linux/server/test/testServer.c.

CLIENT APPLICATION PROGRAMMING NOTES

The IPC API for client applications is defined in casa_c_ipc.h. This API is provided by
libcasa_c_ipc.so.

To utilize the IPC client services, an application must first initialize the infrastructure by
calling IpcClientInit(). Once the IPC client is initialized, then the application needs to open
endpoints for the servers that it wishes to submit requests. Endpoints are opened by calling the
appropriate IpcClientOpenXXRemoteEndPoint() with information about the server listen address.

IpcClientOpenXXRemoteEndpoint() calls return a handles that are associated with the opened
endpoints. This endpoint handles are then utilized by the application to specify the target of
IPC requests.

To submit a request to a particular endpoint, the application executes IpcClientSubmitReq() with
the endpoint handle and the request data. Calls to IpcClientSubmitReq() block until the requests
is processed by the server at which time it returns the reply data.

For an example client application that utilizes the IPC API for clients, see file
linux/client/test/testClient.c.

SECURITY CONSIDERATIONS

IpcLibs does not provide any security features beyond what is provided by the protocol stacks for
tcp/ip and Domain sockets communications.

By leveraging the File System Access Control features, you can scope communications that occur over
Domain sockets to specific or groups of users.