/***********************************************************************
 * 
 *  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 _IPCCLIENT_
#define _IPCCLIENT_

//===[ 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
int
IpcClientOpenUnixRemoteEndPoint(
   IN char *pSocketFileName,
   IN int maxRpcRetries,
   INOUT uint32_t *pEndPointHandle);
//
// Arguments In:  port - Server's listening port number.
// 
//                address - The server's IP Address. Use
//                          0x7F000001 if the server is local.
// 
//                maxRpcRetries - Maximum number of Rpc retries that
//                                should be utilized when submitting
//                                a request to the endpoint. A value
//                                of zero requests that the default
//                                setting be utilized.
//
// Arguments Out: pEndPointHandle - Pointer to variable that will receive
//                                  the endpoint handle.
//
// Returns:       0 == Success
//                -1 == Failure
//
// Abstract:      Method to open a UNIX (PF_UNIX) remote endpoint.
// 
// Note:          The service should have been initialized before calling
//                this procedure.
//
//=======================================================================--
typedef
int
(*PFN_IpcClientOpenUnixRemoteEndPoint)(
   IN char *pSocketFileName,
   IN int maxRpcRetries,
   INOUT uint32_t *pEndPointHandle);


//++=======================================================================
extern
int
IpcClientOpenInetRemoteEndPoint(
   IN unsigned short int port,
   IN uint32_t address,
   IN int maxRpcRetries,
   INOUT uint32_t *pEndPointHandle);
//
// Arguments In:  port - Server's listening port number.
// 
//                address - The server's IP Address. Use
//                          0x7F000001 if the server is local.
// 
//                maxRpcRetries - Maximum number of Rpc retries that
//                                should be utilized when submitting
//                                a request to the endpoint. A value
//                                of zero requests that the default
//                                setting be utilized.
//
// Arguments Out: pEndPointHandle - Pointer to variable that will receive
//                                  the endpoint handle.
//
// Returns:       0 == Success
//                -1 == Failure
//
// Abstract:      Method to open a TCP (AF_INET) remote endpoint.
// 
// Note:          The service should have been initialized before calling
//                this procedure.
//
//=======================================================================--

typedef
int
(*PFN_IpcClientOpenInetRemoteEndPoint)(
   IN unsigned short int port,
   IN uint32_t address,
   IN int maxRpcRetries,
   INOUT uint32_t *pEndPointHandle);


//++=======================================================================
extern
int
IpcClientCloseRemoteEndPoint(
   IN uint32_t endPointHandle);
//
// Arguments In:  endpointHandle - Handle of the endpoint being closed.
// 
//
// Arguments Out: None.
//                                  the endpoint handle.
//
// Returns:       0 == Success
//                -1 == Failure
//
// Abstract:      Method to close a remote endpoint.
// 
// Note:          The service should have been initialized before calling
//                this procedure.
//
//=======================================================================--

typedef
int
(*PFN_IpcClientCloseRemoteEndPoint)(
   IN uint32_t endPointHandle);


//++=======================================================================
extern
int
IpcClientSubmitReq(
   IN uint32_t endPointHandle,
   IN char *pClientData,
   IN uint32_t clientDataLen,
   INOUT char **ppServerData,
   INOUT uint32_t *pServerDataLen);
//
// Arguments In:  endPointHandle - Handle of the remote endpoint that will
//                                 be the target of the request.
// 
//                pClientData - Pointer to client data that must be sent to
//                              the server. Buffer is NEVER released by the
//                              procedure.
//
//                clientDataLen - Length of the client data.
//
// Arguments Out: ppServerData - Pointer to variable that will receive a
//                               pointer to the buffer containing the data
//                               received from the server.
//
//                               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.
//
//                pServerDataLen - Pointer to variable that will receive the
//                                 length of the data received from the server.
//
// Returns:       0 == Request completed gracefully
//                -1 == Request did not complete gracefully
//
// Abstract:      Method to submit a request.
//
// Notes:         The routine blocks until the request completes.
// 
//                The buffer returned with the server data must be released
//                by the calling application by calling free().
//
//=======================================================================--

typedef
int
(*PFN_IpcClientSubmitReq)(
   IN uint32_t endPointHandle,
   IN char *pClientData,
   IN uint32_t clientDataLen,
   INOUT char **ppServerData,
   INOUT uint32_t *pServerDataLen);


//++=======================================================================
extern
int
IpcClientInit(
   IN char *pName,
   IN bool multithreaded,
   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.
// 
//                multithreaded - Set to TRUE if the process is
//                                multithreaded.
// 
//                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 appropriate function to
//                set the server address before a request can be submitted.
//
//=======================================================================--

typedef
int
(*PFN_IpcClientInit)(
   IN char *pName,
   IN bool multithreaded,
   IN int debugLevel,
   IN bool useSyslog);


//++=======================================================================
extern
void
IpcClientShutdown(void);
//
// Arguments In:  None.
//
// Arguments Out: None.
//
// Returns:       Nothing.
//
// Abstract:      Method to shutdown the IPC infrastructure for process.
//
//=======================================================================--

typedef
void
(*PFN_IpcClientShutdown)(void);


#endif // _IPCCLIENT_

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