include/socket.h

   1 /* $Id$ */
   2
   3 /* gras/socket.h - handling sockets in GRAS                                 */
   4
   5 /* Authors: Martin Quinson                                                  */
   6 /* Copyright (C) 2003 the OURAGAN project.                                  */
   7
   8 /* This program is free software; you can redistribute it and/or modify it
   9    under the terms of the license (GNU LGPL) which comes with this package. */
  10
  11
  12 #ifndef GRAS_SOCK_H
  13 #define GRAS_SOCK_H
  14
  15 #include <stddef.h>    /* offsetof() */
  16 #include <sys/types.h>  /* size_t */
  17 #include <stdarg.h>
  18
  19
  20 /*! C++ users need love */
  21 #ifndef BEGIN_DECL
  22 # ifdef __cplusplus
  23 #  define BEGIN_DECL extern "C" {
  24 # else
  25 #  define BEGIN_DECL
  26 # endif
  27 #endif
  28
  29 /*! C++ users need love */
  30 #ifndef END_DECL
  31 # ifdef __cplusplus
  32 #  define END_DECL }
  33 # else
  34 #  define END_DECL
  35 # endif
  36 #endif
  37 /* End of cruft for C++ */
  38
  39 BEGIN_DECL
  40
  41 /****************************************************************************/
  42 /* Openning/Maintaining/Closing connexions                                  */
  43 /****************************************************************************/
  44 /** Number of channel opened at most on a given host within SimGrid */
  45 #define MAX_CHANNEL 10
  46
  47 /*! Type of a communication socket */
  48 typedef struct gras_sock_s gras_sock_t;
  49
  50 /**
  51  * gras_sock_client_open:
  52  * @host: name of the host we want to connect to
  53  * @Param2: port on which we want to connect on this host
  54  * @sock: Newly created socket
  55  * @Returns: an errcode
  56  *
  57  * Attempts to establish a connection to the server listening to host:port
  58  */
  59 gras_error_t
  60 gras_sock_client_open(const char *host, short port,
  61                       /* OUT */ gras_sock_t **sock);
  62
  63 /**
  64  * gras_sock_server_open:
  65  * @Param1: starting port
  66  * @Param2: ending port
  67  * @sock: Newly create socket
  68  * @Returns: an errcode
  69  *
  70  * Attempts to bind to any port between #startingPort# and #endingPort#,
  71  * inclusive.
  72  *
  73  * You can get the port on which you connected using grasSockGetPort().
  74  */
  75 gras_error_t
  76 gras_sock_server_open(unsigned short startingPort,
  77                       unsigned short endingPort,
  78                       /* OUT */ gras_sock_t **sock);
  79
  80 /**
  81  * gras_sock_close:
  82  * @sock: The socket to close.
  83  * @Returns: an errcode
  84  *
  85  * Tears down a socket.
  86  */
  87 gras_error_t gras_sock_close(gras_sock_t *sock);
  88
  89
  90 /****************************************************************************/
  91 /* Converting DNS name <-> IP                                               */
  92 /****************************************************************************/
  93 /**
  94  * gras_sock_get_peer_name:
  95  * @sd:
  96  * @Returns: the DNS name of the host connected to #sd#, or descriptive text if
  97  * #sd# is not an inter-host connection: returns NULL in case of error
  98  *
  99  * The value returned should not be freed.
 100  */
 101 char *
 102 gras_sock_get_peer_name(gras_sock_t *sd);
 103
 104 /**
 105  * gras_sock_get_peer_port:
 106  * @sd:
 107  * @Returns: the port number on the other side of socket sd. -1 is returned
 108  * if pipes or unknown
 109  */
 110 unsigned short
 111 gras_sock_get_peer_port(gras_sock_t *sd);
 112
 113 /**
 114  * gras_sock_get_peer_addr:
 115  * @sd:
 116  * @Returns: the IP address of the other side of this socket.
 117  *
 118  * can return NULL (out of memory condition).
 119  * Do not free the result.
 120  */
 121 char *
 122 gras_sock_get_peer_addr(gras_sock_t *sd);
 123
 124 /**
 125  * gras_sock_get_my_port:
 126  * @sd:
 127  * @Returns: the port number on the this side of socket sd. -1 is returned
 128  * if pipes or unknown
 129  */
 130 unsigned short
 131 gras_sock_get_my_port(gras_sock_t *sd);
 132
 133 /* **************************************************************************
 134  * Raw sockets and BW experiments (should be placed in another file)
 135  * **************************************************************************/
 136 typedef struct gras_rawsock_s gras_rawsock_t;
 137
 138 /**
 139  * gras_rawsock_client_open:
 140  *
 141  * Establishes a connection to @machine : @port on which the buffer sizes have
 142  * been set to @bufSize bytes.
 143  *
 144  * Those sockets are meant to send raw data without any conversion, for example
 145  * for bandwidth tests.
 146  */
 147 gras_error_t
 148 gras_rawsock_client_open(const char *host, short port, unsigned int bufSize,
 149                          /* OUT */ gras_rawsock_t **sock);
 150
 151 /**
 152  * gras_rawsock_server_open:
 153  *
 154  * Open a connexion waiting for external input, on which the buffer sizes have
 155  * been set to @bufSize bytes.
 156  *
 157  * Those sockets are meant to send raw data without any conversion, for example
 158  * for bandwidth tests.
 159  */
 160 gras_error_t
 161 gras_rawsock_server_open(unsigned short startingPort, unsigned short endingPort,
 162                          unsigned int bufSize, /* OUT */ gras_rawsock_t **sock);
 163
 164 /**
 165  * gras_rawsock_close:
 166  *
 167  * Close a raw socket.
 168  *
 169  * Those sockets are meant to send raw data without any conversion, for example
 170  * for bandwidth tests.
 171  */
 172 gras_error_t
 173 gras_rawsock_close(gras_rawsock_t *sock);
 174
 175 /**
 176  * gras_rawsocket_get_my_port:
 177  * @sd:
 178  * @Returns: the port number on the this side of socket sd. -1 is returned
 179  * if pipes or unknown
 180  */
 181 unsigned short
 182 gras_rawsocket_get_my_port(gras_rawsock_t *sd);
 183
 184 /**
 185  * gras_rawsocket_get_peer_port:
 186  * @sd:
 187  * @Returns: the port number on the other side of socket sd. -1 is returned
 188  * if pipes or unknown
 189  */
 190 unsigned short
 191 gras_rawsock_get_peer_port(gras_rawsock_t *sd);
 192
 193 /**
 194  * gras_rawsock_send:
 195  * @sock: on which raw socket to send the data
 196  * @expSize: total size of data sent
 197  * @msgSize: size of each message sent one after the other
 198  *
 199  * Send a raw bunch of data, for example for a bandwith test.
 200  */
 201
 202 gras_error_t
 203 gras_rawsock_send(gras_rawsock_t *sd, unsigned int expSize, unsigned int msgSize);
 204
 205 /**
 206  * gras_rawsock_recv:
 207  * @sock: on which raw socket to read the data
 208  * @expSize: total size of data received
 209  * @msgSize: size of each message received one after the other
 210  * @timeout: time to wait for that data
 211  *
 212  * Receive a raw bunch of data, for example for a bandwith test.
 213  */
 214
 215 gras_error_t
 216 gras_rawsock_recv(gras_rawsock_t *sd, unsigned int expSize, unsigned int msgSize,
 217                   unsigned int timeout);
 218
 219
 220 END_DECL
 221
 222 #endif /* GRAS_SOCK_H */
 223