Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
Documentation reorganization: no @name anymore since doxygen was buggy on it until...
[simgrid.git] / 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 */