include/gras/transport.h

   1 /* $Id$ */
   2
   3 /* transport - low level communication (send/receive bunches of bytes)      */
   4 /* module's public interface exported to end user.                          */
   5
   6 /* Copyright (c) 2004 Martin Quinson. All rights reserved.                  */
   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 #ifndef GRAS_TRANSPORT_H
  12 #define GRAS_TRANSPORT_H
  13
  14 /** \addtogroup GRAS_sock
  15  *  \brief Socket handling (Communication facility).
  16  *
  17  * <center><table><tr><td><b>Top</b>    <td> [\ref index]::[\ref GRAS_API]
  18  *                <tr><td><b>Prev</b>   <td> [\ref GRAS_dd]
  19  *                <tr><td><b>Next</b>   <td> [\ref GRAS_msg]
  20  *                <tr><td><b>Down</b>   <td> [\ref GRAS_sock_create]          </table></center>
  21  *
  22  * The model of communications in GRAS is very close to the BSD socket one. To get two hosts
  23  * exchanging data, one of them need to open a <i>server</i> socket on which it can listen for incoming messages
  24  * and the other one must connect a <i>client</i> socket onto the server one.
  25  *
  26  * If you need an example of this, check \ref GRAS_ex_ping.
  27  *
  28  */
  29
  30 /** \defgroup GRAS_sock_create Socket creation functions
  31  *  \ingroup GRAS_sock
  32  *
  33  * <center><table><tr><td><b>Top</b>    <td> [\ref index]::[\ref GRAS_API]::[\ref GRAS_sock]
  34  *                <tr><td>Prev          <td>
  35  *                <tr><td><b>Next</b>   <td> [\ref GRAS_sock_info]            </table></center>
  36  */
  37 /* @{*/
  38 /** \brief Opaque type describing a socket */
  39 typedef struct s_gras_socket *gras_socket_t;
  40
  41 /** \brief Simply create a client socket (to speak to a remote host) */
  42 gras_socket_t gras_socket_client(const char *host, unsigned short port);
  43 /** \brief Simply create a server socket (to ear from remote hosts speaking to you) */
  44 gras_socket_t gras_socket_server(unsigned short port);
  45 /** \brief Close socket */
  46 void          gras_socket_close(gras_socket_t sd);
  47
  48 /** \brief Create a client socket, full interface to all relevant settings */
  49 gras_socket_t gras_socket_client_ext(const char *host,
  50                                      unsigned short port,
  51                                      unsigned long int bufSize,
  52                                      int measurement);
  53 /** \brief Create a server socket, full interface to all relevant settings */
  54 gras_socket_t gras_socket_server_ext(unsigned short port,
  55                                      unsigned long int bufSize,
  56                                      int measurement);
  57 /* @}*/
  58 /** \defgroup GRAS_sock_info Retrieving data about sockets and peers
  59  *  \ingroup GRAS_sock
  60  *
  61  * <center><table><tr><td><b>Top</b>    <td> [\ref index]::[\ref GRAS_API]::[\ref GRAS_sock]
  62  *                <tr><td><b>Prev</b>   <td> [\ref GRAS_sock_create]
  63  *                <tr><td><b>Next</b>   <td> [\ref GRAS_sock_meas]         </table></center>
  64  *
  65  * Who are you talking to?
  66  */
  67 /* @{*/
  68
  69 /** Get the port number on which this socket is connected on my side */
  70 int   gras_socket_my_port  (gras_socket_t sock);
  71 /** Get the port number on which this socket is connected on remote side */
  72 int   gras_socket_peer_port(gras_socket_t sock);
  73 /** Get the host name of the remote side */
  74 char *gras_socket_peer_name(gras_socket_t sock);
  75 /* @}*/
  76
  77 /** \defgroup GRAS_sock_meas Using measurement sockets
  78  *  \ingroup GRAS_sock
  79  *
  80  * <center><table><tr><td><b>Top</b>    <td> [\ref index]::[\ref GRAS_API]::[\ref GRAS_sock]
  81  *                <tr><td><b>Prev</b>   <td> [\ref GRAS_sock_info]
  82  *                <tr><td><b>Next</b>   <td> [\ref GRAS_sock_file]         </table></center>
  83  *
  84  * You may want to use sockets not to exchange valuable data (in messages),
  85  * but to conduct some bandwidth measurements and related experiments. If so, try those measurement sockets.
  86  *
  87  * You can only use those functions on sockets openned with the "measurement" boolean set to true.
  88  *
  89  */
  90 /* @{*/
  91
  92
  93
  94 int gras_socket_is_meas(gras_socket_t sock);
  95 void gras_socket_meas_send(gras_socket_t peer,
  96                            unsigned int timeout,
  97                            unsigned long int expSize,
  98                            unsigned long int msgSize);
  99 void gras_socket_meas_recv(gras_socket_t peer,
 100                            unsigned int timeout,
 101                            unsigned long int expSize,
 102                            unsigned long int msgSize);
 103 gras_socket_t gras_socket_meas_accept(gras_socket_t peer);
 104
 105 /* @}*/
 106
 107 /** \defgroup GRAS_sock_file Using files as sockets
 108  *  \ingroup GRAS_sock
 109  *
 110  * <center><table><tr><td><b>Top</b>    <td> [\ref index]::[\ref GRAS_API]::[\ref GRAS_sock]
 111  *                <tr><td><b>Prev</b>   <td> [\ref GRAS_sock_meas]
 112  *                <tr><td>Next          <td>          </table></center>
 113  *
 114  * For debugging purpose, it is possible to deal with files as if they were sockets.
 115  * It can even be useful to store stuff in a portable manner, but writing messages to a file
 116  * may be strange...
 117  *
 118  * \bug Don't use '-' on windows. this file represents stdin or stdout, but I failed to deal with it on windows.
 119  */
 120 /* @{*/
 121 /* debuging functions */
 122 gras_socket_t gras_socket_client_from_file(const char*path);
 123 gras_socket_t gras_socket_server_from_file(const char*path);
 124
 125 /* @} */
 126
 127 #endif /* GRAS_TRANSPORT_H */