src/nws_portability/Include/protocol.h

   1 /* $Id$ */
   2
   3
   4 #ifndef PROTOCOL_H
   5 #define PROTOCOL_H
   6
   7
   8 /*
   9  * This module defines functions useful in establishing and maintaining
  10  * connections to other processes on local or remote hosts.  The name is an
  11  * anachronism.
  12  */
  13
  14
  15 #include <sys/types.h>    /* pid_t */
  16 #include "dnsutil.h"      /* IPAddress */
  17
  18 #ifdef __cplusplus
  19 extern "C" {
  20 #endif
  21
  22 /* A definition for socket call-back functions (see NotifyOnDisconnection()). */
  23 typedef void (*SocketFunction)(Socket);
  24
  25
  26 /*
  27  * Attempts to establish a connection to the server listening to #addr#:#port#.
  28  * If successful within #timeOut# seconds, returns 1 and sets #sock# to the
  29  * socket bound to the connection, else returns 0. A #timeOut# of 0 will
  30  * disable timeouts while a negative value will use adaptive timeouts.
  31  */
  32 int
  33 CallAddr(IPAddress addr,
  34          short port,
  35          Socket *sock,
  36          double timeOut);
  37
  38
  39 /*
  40  * Closes connections opened via calls to this module's functions.  Each
  41  * parameter is a boolean value indicated whether that type of connection
  42  * should be included in those closed.
  43  */
  44 void
  45 CloseConnections(int closeEars,
  46                  int closePipes,
  47                  int closeSockets);
  48 #define CloseAllConnections() CloseConnections(1, 1, 1)
  49
  50
  51 /*
  52  * Tests all connections opened via calls to this module's functions and
  53  * closes any that are no longer connected.  Returns the number of connections
  54  * closed.
  55  */
  56 int
  57 CloseDisconnections(void);
  58
  59
  60 /**
  61  * Tears down #sock#.  If #waitForPeer# is non-zero, the function waits this
  62  * many seconds for the host on the other end to close the connection and fails
  63  * if no such close is detected.  If this parameter is zero, the function
  64  * closes #sock# immediately.  Returns 1 and sets #sock# to NO_SOCKET if
  65  * successful, else returns 0.
  66  */
  67 int
  68 CloseSocket(Socket *sock,
  69             int waitForPeer);
  70 #define DROP_SOCKET(sock) CloseSocket(sock, 0)
  71
  72
  73 /**
  74  * Removed all records of #sock# from our FD_SETs
  75  */
  76 void
  77 ClearSocket(Socket sock);
  78
  79 /*
  80 ** Spawns a new process, a duplicate of the running one.  Returns 1 if
  81 ** successful, 0 otherwise.  Returns in #pid# a 0 to the child process and the
  82 ** process id of the child to the parent.  Both processes are given a pair of
  83 ** connections in the Socket parameters that can be used to communicate between
  84 ** the parent and child.  The parent process should send information to the
  85 ** child via #parentToChild# and receive information via #childToParent#; the
  86 ** child reads from the former and writes to the latter.  The parameters may be
  87 ** NULL indicating that communication is unidirectional (one parameter NULL),
  88 ** or that no communication will take place (both NULL).
  89 */
  90 int
  91 CreateLocalChild(pid_t *pid,
  92                  Socket *parentToChild,
  93                  Socket *childToParent);
  94
  95
  96 /*
  97 ** Attempts to bind to any port between #startingPort# and #endingPort#,
  98 ** inclusive.  If successful, returns 1 and sets #ear# to the bound socket and
  99 ** #earPort# to the port to which it is bound, else returns 0.
 100 */
 101 int
 102 EstablishAnEar(unsigned short startingPort,
 103                unsigned short endingPort,
 104                Socket *ear,
 105                unsigned short *earPort);
 106
 107
 108 /**
 109  * Checks all connections established via calls to this module for
 110  * incoming messages.  If one is detected within #timeOut# seconds,
 111  * returns 1, sets #sd# to the socket containing the message, and sets
 112  * #ldap# to the type of message (0 if NWS, 1 if LDAP).  If no message
 113  * detected, returns 0.
 114  *
 115  * NOTE: you have to use SocketIsAvailable to notify IncomingRequest that
 116  * the socket is again available (once the socket is been returned from
 117  * IncomingRequest) */
 118 int
 119 IncomingRequest(double timeOut,
 120                 Socket *sd,
 121                 int *ldap);
 122
 123
 124 /**
 125  * When a socket is returned by IncomingRequest, that socket won't be
 126  * listen till this function is called.
 127  * Return 0 upon failure.
 128  */
 129 int
 130 SocketIsAvailable(Socket sd);
 131
 132 /**
 133  * Tell NWS that a specific socket is still in use and IncomingRequest
 134  * shouldn't listen to it.
 135  */
 136 int
 137 SocketInUse(Socket sd);
 138
 139 /*
 140 ** Returns 1 or 0 depending on whether or not #sd# is connected to another
 141 ** process.
 142 */
 143 int
 144 IsOkay(Socket sd);
 145
 146 /**
 147  * returns 1 or 0 depending on wheter the socket is a pipe or not
 148  */
 149 int
 150 IsPipe(Socket sd);
 151
 152
 153 /*
 154 ** Registers a function that should be called whenever a socket is disconnected,
 155 ** either directly via a call to CloseSocket(), or indirectly because the peer
 156 ** termintes the connection.  The function is passed the closed socket after it
 157 ** has been closed.
 158 */
 159 void
 160 NotifyOnDisconnection(SocketFunction notifyFn);
 161
 162
 163 /*
 164 ** Pass socket #sock# along to child #child# -- call after a successful call
 165 ** to CreateLocalChild().  The parent process will no longer listen for
 166 ** activity on #sock#.  Closing the socket will be put off until after the
 167 ** child dies, just in case the parent and child share descriptors.
 168 */
 169 int
 170 PassSocket(Socket *sock,
 171            pid_t child);
 172
 173
 174 /**
 175  * Receives #byteSize# bytes from connection #sd# and stores them in the
 176  * memory referenced by #bytes#.  The caller must assure that #bytes# is at
 177  * least #byteSize# bytes long.  Returns 1 if successful within #timeOut#
 178  * seconds, else 0.  If #timeOut# is zero, timeout are disabled alltogether.
 179  */
 180 int
 181 RecvBytes(Socket sd,
 182           void *byte,
 183           size_t byteSize,
 184           double timeOut);
 185
 186 /*
 187  * Sends #bytesSize# bytes from the memory pointed to by #bytes# on connection
 188  * #sd#.  Returns 1 if successful within #timeOut# seconds, else 0.
 189  * If #timeOut# is zero, timeout are disabled alltogether..
 190  */
 191 int
 192 SendBytes(Socket sd,
 193           const void *bytes,
 194           size_t byteSize,
 195           double timeOut);
 196
 197
 198 /*
 199 ** A signal handler for dealing with signals (specifically SIGPIPE) that
 200 ** indicate a bad socket.
 201 */
 202 void
 203 SocketFailure(int sig);
 204
 205
 206 #ifdef __cplusplus
 207 }
 208 #endif
 209
 210 #endif