src/nws_portability/Include/messages.h

   1 /* $Id$ */
   2
   3 #ifndef MESSAGES_H
   4 #define MESSAGES_H
   5
   6 /*
   7  * This package defines NWS functions for sending messages between hosts.
   8  */
   9
  10 #include <sys/types.h>  /* size_t */
  11 #include "formatutil.h" /* DataDescriptor */
  12 #include "protocol.h"   /* Socket */
  13 #ifdef WITH_LDAP
  14 #include <ldap.h>
  15 #endif
  16
  17 #ifdef __cplusplus
  18 extern "C" {
  19 #endif
  20
  21 /**
  22  * This is the four-byte NWS version number.  The first two bytes are
  23  * major and minor release numbers; the meaning of the other two bytes is
  24  * undefined.
  25  */
  26 #define NWS_VERSION 0x02030000
  27
  28
  29 typedef unsigned int MessageType;
  30
  31 /**
  32  * this is the message header: it contains the NWS version (if I don't
  33  * forget to update) so that we can try to be backward compatible, the
  34  * message type and the data size. Upwn recepit of a message this is
  35  * what is passed to the listener along with the open socket.
  36  */
  37 typedef struct {
  38         unsigned int version;
  39         MessageType message;
  40         size_t dataSize;
  41 } MessageHeader;
  42
  43
  44 typedef void (*ListenFunction)(Socket *, MessageHeader);
  45 typedef int (*LdapListenFunction)(Socket *);
  46
  47
  48 /**
  49  * Waits up to #timeOut# seconds to see if a message comes in; if so,
  50  * calls the registered listener for that message (see
  51  * RegisterListener()).
  52  */
  53 void
  54 ListenForMessages(double timeOut);
  55
  56
  57 /**
  58  * Indicates a desire that the function #listener# be called whenever a
  59  * #message# message comes in.  #image# is a printable message name; it's
  60  * used to log the arrival of the message.
  61  */
  62 void
  63 RegisterListener(MessageType message,
  64                  const char *image,
  65                  ListenFunction listener);
  66
  67
  68 #ifdef WITH_LDAP
  69 /*
  70 ** Indicates a desire that the function #listener# be called whenever an
  71 ** LDAP message comes in.  Only one LDAP listener may be active at a time.
  72 */
  73 void
  74 RegisterLdapListener(LdapListenFunction listener);
  75
  76
  77 /*
  78 ** Sends an unsolicited notification of disconnection on *sd, then shut down
  79 ** the socket.  See the LDAP RFC for details on this message.
  80 */
  81 void
  82 SendLdapDisconnect (Socket *sd,
  83                     ber_int_t resultCode);
  84 #endif
  85
  86
  87 /**
  88  * Receives on #sd#, into #data#, the data described by the #howMany#-long
  89  * array of descriptors #description#.  Returns 1 if successful within
  90  * #timeOut# seconds, else 0.
  91  * If #timeOut# is negative adaptive timeouts will be used, if it's 0 no
  92  * timeouts will be used.
  93  */
  94 int
  95 RecvData(Socket sd,
  96          void *data,
  97          const DataDescriptor *description,
  98          size_t howMany,
  99          double timeOut);
 100
 101
 102 /**
 103  * Waits for a #message# message to come in over #sd#.  If successful within
 104  * #timeOut# seconds, returns 1 and copies the size of the accompanying data
 105  * into #dataSize#; otherwise, returns 0.
 106  * If #timeOut# is negative adaptive timeouts will be used, if it's 0 no
 107  * timeouts will be used.
 108  */
 109 int
 110 RecvMessage(Socket sd,
 111             MessageType message,
 112             size_t *dataSize,
 113             double timeOut);
 114
 115
 116 /**
 117  * Waits for a #message# message to come in over #sd#.  If successful within
 118  * #timeOut# seconds, returns 1 and copies the accompanying data into #data1#
 119  * and #data2#, which are described by the #howMany1# and #howMany3#-long
 120  * arrays of descriptors #description1# and #description2#, respectively;
 121  * otherwise, returns 0.
 122  * If #timeOut# is negative adaptive timeouts will be used, if it's 0 no
 123  * timeouts will be used.
 124  */
 125 int
 126 RecvMessageAndDatas(Socket sd,
 127                     MessageType message,
 128                     void *data1,
 129                     const DataDescriptor *description1,
 130                     size_t howMany1,
 131                     void *data2,
 132                     const DataDescriptor *description2,
 133                     size_t howMany2,
 134                     double timeOut);
 135 #define RecvMessageAndData(sd,message,data,description,howMany,timeOut) \
 136   RecvMessageAndDatas(sd,message,data,description,howMany,NULL,NULL,0,timeOut)
 137
 138
 139 /**
 140  * Sends #data#, described by the #howMany#-long array of descriptors
 141  * #description#.  Returns 1 if successful in #timeOut# seconds, else 0.  This
 142  * fuction allows callers to extend the data that accompanies messages beyond
 143  * the two items provided for by SendMessageAndDatas().  Note, however, that
 144  * since the data sent via a call to this function is not packaged with a
 145  * message, the receiver will not be able to determine the data size directly.
 146  * The caller must assure that the data size is known to the recipient, either
 147  * because its length is predetermined, or because its length was enclosed in a
 148  * previously-transmitted message.
 149  * If #timeOut# is negative adaptive timeouts will be used, if it's 0 no
 150  * timeouts will be used.
 151  */
 152 int
 153 SendData(Socket sd,
 154          const void *data,
 155          const DataDescriptor *description,
 156          size_t howMany,
 157          double timeOut);
 158
 159
 160 /**
 161  * Sends a message of type #message# on #sd# followed by #data1# and #data2#,
 162  * which are described, respectively, by the #howMany1#-long and the
 163  * #howMany2#-long arrays of descriptors #description1# and #description2#.
 164  * Each data parameter may be NULL, in which case its description is ignored.
 165  * Returns 1 if successful within #timeOut# seconds, else 0.
 166  * If #timeOut# is negative adaptive timeouts will be used, if it's 0 no
 167  * timeouts will be used.
 168  */
 169 int
 170 SendMessageAndDatas(Socket sd,
 171                     MessageType message,
 172                     const void *data1,
 173                     const DataDescriptor *description1,
 174                     size_t howMany1,
 175                     const void *data2,
 176                     const DataDescriptor *description2,
 177                     size_t howMany2,
 178                     double timeOut);
 179 #define SendMessage(sd,message,timeOut) \
 180    SendMessageAndDatas(sd,message,NULL,NULL,0,NULL,NULL,0,timeOut)
 181 #define SendMessageAndData(sd,message,data,descriptor,howMany,timeOut) \
 182    SendMessageAndDatas(sd,message,data,descriptor,howMany,NULL,NULL,0,timeOut)
 183
 184 /**
 185  * reads the NWS header associated with in incoming message and returns
 186  * the message type #message# as an integer.  returns -1 if the read fails
 187  * If #timeOut# is negative adaptive timeouts will be used, if it's 0 no
 188  * timeouts will be used.
 189  */
 190 int RecvMsgType(Socket sd, double timeout);
 191
 192 #ifdef __cplusplus
 193 }
 194 #endif
 195
 196 #endif /* MESSAGES_H */