/***********************************************************************
 * 
 *  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>
 *
 ***********************************************************************/

#ifndef _IPCSERVER_
#define _IPCSERVER_

//===[ Header files specific to this module ]==============================

//===[ Manifest constants                   ]==============================

#ifndef IN
#define  IN
#endif
#ifndef OUT
#define  OUT
#endif
#ifndef INOUT
#define  INOUT
#endif

//===[ Structure Definitions                ]==============================

//===[ Function Prototypes                  ]==============================


//++=======================================================================
extern
uint32_t
IpcServerGetRequest(void);
//
// Arguments In:  None.
//
// Arguments Out: None.
//
// Returns:       The id of the pending request.
//                0 == Not able to wait for request.
//
// Abstract:      A server thread invokes this method to be informed when
//                a request is received that needs to be acted upon.
//
// Notes:         The routine blocks until a request becomes available or
//                until the IpcServer is shutdown.
// 
//                An application can execute this method from multiple
//                threads to allow requests to be process concurrently.
//
//=======================================================================--


//++=======================================================================
extern
int32_t
IpcServerGetRequestData(
   IN uint32_t requestId,
   INOUT char **ppReqData);
//
// Arguments In:  requestId - The id of the request being processed.
//
// Arguments Out: ppReqData - Pointer to variable that will receive a
//                            pointer to the buffer containing the request
//                            data the client.
//
// Returns:       The length of the request data returned.
//
// Abstract:      Method to obtain the data associated with a particular
//                request.
//
// Notes:         The returned buffer SHOULD NOT be released by the calling
//                application.
// 
//                The returned buffer always contains a NULL after the
//                data indicated. You may be able to leverage this to
//                treat the data as a NULL terminated string in cases
//                where the request consists of ASCII characters.
//
//=======================================================================--


//++=======================================================================
extern
void
IpcServerCompleteRequest(
   IN uint32_t requestId,
   IN char *pReplyData);
//
// Arguments In:  requestId - The id of the request being completed.
// 
//                pReplyData - Pointer to reply data that must be sent to
//                             the client for this request.
//
// Arguments Out: None.
//
// Returns:       Nothing.
//
// Abstract:      Method to complete a request being processed.
//
// Notes:         The returned buffer will not NOT be released by the method.
//
//=======================================================================--


//++=======================================================================
extern
void
IpcServerAbortRequest(
   IN uint32_t requestId);
//
// Arguments In:  requestId - The id of the request being aborted.
// 
// Arguments Out: None.
//
// Returns:       Nothing.
//
// Abstract:      Method to abort a request being processed.
//
// Notes:
//
//=======================================================================--


//++=======================================================================
extern
int
IpcServerStart(void);
//
// Arguments In:  None.
//
// Arguments Out: None.
//
// Returns:       0 == Success
//                -1 == Failure
//
// Abstract:      Method to enable the reception of server requests.
//
// Note:          The service needs to be initialized and the listen address
//                needs to be set before calling this procedure.
//
//=======================================================================--


//++=======================================================================
extern
int
IpcServerSetUnAddress(
   IN char *pSocketFileName);
//
// Arguments In:  pSocketFileName - Pointer to string containing the name
//                                  of the socket file to listen on.
//
// Arguments Out: None.
//
// Returns:       0 == Success
//                -1 == Failure
//
// Abstract:      Method to set the socket file name to utilize for
//                communicating with the server via DOMAIN sockets.
//
// Note:          The service needs to be initialized before calling this procedure.
//
//=======================================================================--


//++=======================================================================
extern
int
IpcServerSetInAddress(
   IN unsigned short int listenPort);
//
// Arguments In:  serverPort - Server's listening port number.
//
// Arguments Out: None.
//
// Returns:       0 == Success
//                -1 == Failure
//
// Abstract:      Method to set the address to utilize for communicating
//                with the server via TCP sockets.
//
// Note:          The service needs to be initialized before calling this procedure.
//
//=======================================================================--


//++=======================================================================
extern
int
IpcServerInit(
   IN char *pName,
   IN int debugLevel,
   IN bool useSyslog);
//
// Arguments In:  pName - Pointer to string containing the name that the
//                        calling application wants associated with the
//                        debug logs emitted by the library.
// 
//                debugLevel - The level that the library should use for
//                             determining what information should be logged
//                             for debugging purposes. 0 being the lowest
//                             level.
// 
//                useSyslog - Set to TRUE to log debug statements using Syslog,
//                            else debugs are log to stderr.
//
// Arguments Out: None.
//
// Returns:       0 == Success
//                -1 == Failure
//
// Abstract:      Method to initialize the IPC infrastructure for process.
// 
// Note:          It is necessary to call the start procedure to start
//                servicing requests.
//
//=======================================================================--


//++=======================================================================
extern
void
IpcServerShutdown(void);
//
// Arguments In:  None.
//
// Arguments Out: None.
//
// Returns:       Nothing.
//
// Abstract:      Method to shutdown the IPC service.
//
// Note:
//
//=======================================================================--


#endif // _IPCSERVER_

//=========================================================================
//=========================================================================