/******************************************************************************
 *
 * PROJECT: Carnegie Mellon Planetary Rover Project
 *          Task Control Architecture 
 * 
 * (c) Copyright 1991 Christopher Fedor and Reid Simmons.  All rights reserved.
 * 
 * MODULE: communications
 *
 * FILE: comModule.c
 *
 * ABSTRACT:
 * 
 * Module Communications
 *
 * $Source: /afs/cs.cmu.edu/project/TCA/Master/ipc/src/comModule.h,v $ 
 * $Revision: 2.7 $
 * $Date: 2009/01/12 15:54:55 $
 * $Author: reids $
 *
 * Copyright (c) 2008, Carnegie Mellon University
 *     This software is distributed under the terms of the 
 *     Simplified BSD License (see ipc/LICENSE.TXT)
 *
 * REVISION HISTORY:
 *
 * $Log: comModule.h,v $
 * Revision 2.7  2009/01/12 15:54:55  reids
 * Added BSD Open Source license info
 *
 * Revision 2.6  2002/01/03 20:52:10  reids
 * Version of IPC now supports multiple threads (Caveat: Currently only
 *   tested for Linux).
 * Also some minor changes to support Java version of IPC.
 *
 * Revision 2.5  2001/01/31 17:54:11  reids
 * Subscribe/unsubscribe to connections/disconnections of modules.
 * Subscribe/unsubscribe to changes in handler registrations for a message.
 *
 * Revision 2.4  2000/07/27 16:59:09  reids
 * Added function IPC_setMsgQueueLength.
 * Made IPC_setMsgQueueLength and IPC_setMsgPriority work with point-to-point
 *   messages (used to work only with centrally-routed messages).
 * Made direct connections a bit more robust.
 *
 * Revision 2.3  2000/07/19 20:55:49  reids
 * Added handling for SIGPIPE; fixed handling of direct messages when pipe
 *   is broken.
 * Also, need to reset handlers (maybe??) since, according to the man page for
 *  "signal", the Linux version resets the handler to its default value each
 *  time the signal is raised.
 *
 * Revision 2.2  2000/07/03 17:03:22  hersh
 * Removed all instances of "tca" in symbols and messages, plus changed
 * the names of all other symbols which conflicted with TCA.  This new
 * version of IPC should be able to interoperate TCA fully.  Client
 * programs can now link to both tca and ipc.
 *
 * Revision 2.1.1.1  1999/11/23 19:07:33  reids
 * Putting IPC Version 2.9.0 under local (CMU) CVS control.
 *
 * Revision 1.1.2.1  1996/10/22 18:49:31  reids
 * Point-to-point broadcast messages.
 *
 * Revision 1.1  1996/05/09 01:01:17  reids
 * Moved all the X_IPC files over to the IPC directory.
 * Fixed problem with sending NULL data.
 * Added function IPC_setCapacity.
 * VxWorks m68k version released.
 *
 * Revision 1.3  1996/04/03 03:11:08  reids
 * The data logging (-ld) option now works, for both IPC and regular X_IPC msgs.
 * Fixed the interaction between signals and listening for messages.
 * IPC version will not exit if connection to central server is not available.
 * IPC version will not print out stats if module exits (x_ipcModError).
 *
 * Revision 1.2  1996/03/12 03:19:33  reids
 * Added "enum" format type.
 * Plugged memory leaks (using Purify).
 *
 * Revision 1.1  1996/03/03 04:31:08  reids
 * First release of IPC files.  X_IPC code (8.5), modified to support NM-DS1 IPC.
 *
 * Revision 1.17  1996/03/05  05:04:21  reids
 * Changes (mainly delineated by NMP_IPC conditionals) to support the
 *   New Millennium IPC.
 *
 * Revision 1.16  1996/03/02  03:21:30  rich
 * Fixed memory leaks found using purify.
 *
 * Revision 1.15  1995/10/25  22:48:03  rich
 * Fixed problems with context switching.  Now the context is a separate
 * data structure accessed from the module data structure, using the
 * currentContext field.  GET_C_GLOBAL is used instead of GET_M_GLOBAL for
 * the context dependent fields.
 *
 * Revision 1.14  1995/05/31  19:35:09  rich
 * Fixed problem with reply data being freed early from replys.
 * Initial work on getting the PC version to work.
 *
 * Revision 1.13  1995/04/21  03:53:15  rich
 * Added central commands to kill the task tree and close a module.
 * Added x_ipcGetContext and x_ipcSetContext to support connections to multiple
 * central servers.  x_ipcConnectModules can be called multiple times.
 * Fixed a bug in the resource limit pending.
 * Created seperate routines to print help and option messages.
 *
 * Revision 1.12  1995/04/08  02:06:21  rich
 * Added x_ipc_waitForReplyFrom to be able to block on replies from only one
 * source.  Useful when querying for the msg info information.  Added a
 * x_ipcQueryCentral that only accepts input from the central server.  Fixed
 * timing problems with direct connections.
 *
 * Revision 1.11  1995/04/07  05:02:58  rich
 * Fixed GNUmakefiles to find the release directory.
 * Cleaned up libc.h file for sgi and vxworks.  Moved all system includes
 * into libc.h
 * Got direct queries to work.
 * Fixed problem in allocating/initializing generic mats.
 * The direct flag (-c) now mostly works.  Connect message has been extended to
 * indicate when direct connections are the default.
 * Problem with failures on sunOS machines.
 * Fixed problem where x_ipcError would not print out its message if logging had
 * not been initialized.
 * Fixed another memory problem in modVar.c.
 * Fixed problems found in by sgi cc compiler.  Many type problems.
 *
 * Revision 1.10  1995/04/04  19:41:54  rich
 * Added sgi support.
 * Split low level com routines out to be used in devUtils.
 * Improved some error messages.
 * Added central switch to default to direct connections.  Does not work yet.
 * Fixed the vectorization code.
 *
 * Revision 1.9  1995/03/30  15:42:36  rich
 * DBMALLOC works.  To use "gmake -k -w DBMALLOC=DBMALLOC install"
 * Added simple list of strings data structure that can be passed via x_ipc
 * messages.
 * Use the string list to maintain a global variable of messages with taps.
 * Tapped messages are not sent via direct connections.
 * Implemented code to vectorize data to be sent so that it does not have
 * to be copied.  Currently, only flat, packed data structures are
 * vectored.  This can now be easily extended.
 * Changed Boolean -> BOOLEAN for consistency and to avoid conflicts with x11.
 * Fixed bug were central would try and free the "***New Module***" and
 * "*** Unkown Host***" strings when a module crashed on startup.
 * Fixed a bug reported by Jay Gowdy where the code to find the size of a
 * variable lenght array would access already freed data when called from
 * x_ipcFreeData.
 *
 * Revision 1.8  1995/01/18  22:39:56  rich
 * X_IPC 7.9: Speed improvements.
 * Use unix sockets for communication on the same machine.
 * Eliminate copying.
 * Optimize loop for arrays, especially simple, primitive arrays.
 * Optimize the buffer size.
 *
 * Revision 1.7  1994/05/17  23:15:24  rich
 * Added global variables and associated routines.
 * Added some error checking.  The central connection is now set to -1
 * rather than zero to prevent x_ipc messages from being send to stdout.
 * Now compiles on the sgi machines.  Still need to have the endian and
 * alignment figured out automatically.
 *
 * Revision 1.6  1994/04/28  16:15:32  reids
 * Changes in X_IPC Version 7.6:
 *  1) New functions: x_ipcIgnoreLogging and x_ipcResumeLogging
 *  2) Code for MacIntosh (MPW) version of X_IPC
 *
 * Revision 1.5  1993/12/01  18:57:47  rich
 * Changed TCP to  IPPROTO_TCP, a system defined constant.
 *
 * Revision 1.4  1993/12/01  18:02:56  rich
 * Fixed a problem with the port number being double converted to network
 * byte order.
 * Some general cleanup.
 *
 * Revision 1.3  1993/11/21  20:17:23  rich
 * Added shared library for sun4c_411 sunos machines.
 * Added install to the makefile.
 * Fixed problems with global variables.
 *
 * Revision 1.2  1993/10/21  16:13:39  rich
 * Fixed compiler warnings.
 *
 * Revision 1.1  1993/08/27  07:14:22  fedor
 * First Pass at V7 and V6+VXWORKS merge
 *
 * Revision 1.3  1993/06/22  13:58:44  rich
 * Added makefile.depend.  Dependencies automatically generated using gcc.
 * Fixed some warnings.
 * Updated the -D<arch> flags to correspond to those generated
 * automatically by the makefile.
 * Changed system includes to the proper format "stdio.h" -> <stdio.h>.
 * This was needed so that the automatic dependency generation can
 * distinguish between "local" and system headers.  The location of the
 * system headers changes from architecture to architecture and should not
 * be included in the dependency list.
 *
 * Revision 1.2  1993/05/27  22:16:27  rich
 * Added automatic logging.
 *
 ****************************************************************/

#ifndef INCcomModule
#define INCcomModule

#define GET_MESSAGE(name) \
(MSG_PTR)x_ipc_hashTableFind(name, GET_C_GLOBAL(messageTable))
#define GET_HANDLER(hndKeyPtr) \
(HND_PTR)x_ipc_hashTableFind((void *)hndKeyPtr, GET_C_GLOBAL(handlerTable))
#define GET_CLASS_FORMAT(classPtr) \
(CLASS_FORM_PTR)x_ipc_hashTableFind((const char *)classPtr, \
			            GET_M_GLOBAL(classFormatTable))
#define GET_FD_HANDLER(fd) \
(FD_HND_PTR)x_ipc_hashTableFind((void *)&fd, GET_M_GLOBAL(externalFdTable))

#define ADD_MESSAGE(name, msg) \
(void)x_ipc_hashTableInsert(name, strlen(name)+1, (const char *)msg, \
		            GET_C_GLOBAL(messageTable))
#define ADD_HANDLER(hndKeyPtr, hnd) \
(void)x_ipc_hashTableInsert((char *)hndKeyPtr, sizeof(HND_KEY_TYPE), \
 		            (char *)hnd, GET_C_GLOBAL(handlerTable))
#define ADD_CLASS_FORMAT(classPtr, classForm) \
(void)x_ipc_hashTableInsert((char *)classPtr, sizeof(X_IPC_MSG_CLASS_TYPE), \
		            (char *)classForm, GET_M_GLOBAL(classFormatTable))

typedef struct {
  X_IPC_VERSION_TYPE version;
  BOOLEAN direct;
} MOD_START_TYPE;

typedef struct {
  X_IPC_REF_PTR ref;
  REPLY_HANDLER_FN handler;
  HND_LANGUAGE_ENUM language;
  void *clientData;
} QUERY_NOTIFICATION_TYPE, *QUERY_NOTIFICATION_PTR;

typedef struct {
  CONNECTION_PTR connection;
  DATA_MSG_PTR   dataMsg;
} QUEUED_MSG_TYPE, *QUEUED_MSG_PTR;

#define MSG_QUEUE_INCR 20

typedef struct {
  QUEUED_MSG_PTR messages;
  int numMessages;
  int queueSize;
} MSG_QUEUE_TYPE, *MSG_QUEUE_PTR;

void initMsgQueue (MSG_QUEUE_PTR msgQueue);
void enqueueMsg (MSG_QUEUE_PTR msgQueue,
		 CONNECTION_PTR connection, DATA_MSG_PTR dataMsg);
QUEUED_MSG_PTR dequeueMsg (MSG_QUEUE_PTR msgQueue);

void x_ipcModuleInitialize(void);

void *x_ipc_decodeDataInLanguage (DATA_MSG_PTR dataMsg, CONST_FORMAT_PTR decodeFormat,
			    HND_LANGUAGE_ENUM language);

X_IPC_RETURN_VALUE_TYPE x_ipc_waitForReplyFrom(X_IPC_REF_PTR ref, void *reply, 
				       BOOLEAN sel, long timeout, int fd);
X_IPC_RETURN_VALUE_TYPE x_ipc_waitForReply(X_IPC_REF_PTR ref, void *reply);
void freeDirectList (MSG_PTR msg);
void x_ipc_establishDirect(MSG_PTR msg);

void x_ipcHandleClosedConnection(int sd, CONNECTION_PTR connection);

#ifdef NMP_IPC
extern MSG_PTR getResponseMsg (DATA_MSG_PTR dataMsg);
#endif

void insertConnect (LIST_PTR *listPtr,
		    char *msgName, X_IPC_HND_FN connectHandler,
		    CONNECT_HANDLE_TYPE handler, void *clientData);
void removeConnect (LIST_PTR list, char *msgName, CONNECT_HANDLE_TYPE handler);

void insertChange (const char *msgName,
		   CHANGE_HANDLE_TYPE handler, void *clientData);
void removeChange (const char *msgName, CHANGE_HANDLE_TYPE handler);

#endif /* INCcomModule */