Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
doxygenification
[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 #include "xbt/error.h"
15
16 /** \addtogroup GRAS_sock
17  *  \brief Socket handling (Communication facility).
18  */
19
20 /** \name Socket creation functions
21  *  \ingroup GRAS_sock
22  */
23 /*@{*/
24 /** \brief Opaque type describing a socket */
25 typedef struct s_gras_socket *gras_socket_t;
26
27 /** \brief Simply create a client socket (to speak to a remote host) */
28 xbt_error_t gras_socket_client(const char *host,
29                                 unsigned short port,
30                                 /* OUT */ gras_socket_t *dst);
31 /** \brief Simply create a server socket (to ear from remote hosts speaking to you) */
32 xbt_error_t gras_socket_server(unsigned short port,
33                                 /* OUT */ gras_socket_t *dst);
34 /** \brief Close socket */
35 void         gras_socket_close(gras_socket_t sd);
36
37 /** \brief Create a client socket, full interface to all relevant settings */
38 xbt_error_t gras_socket_client_ext(const char *host,
39                                     unsigned short port,
40                                     unsigned long int bufSize,
41                                     int raw, 
42                                     /* OUT */ gras_socket_t *dst);
43 /** \brief Create a server socket, full interface to all relevant settings */
44 xbt_error_t gras_socket_server_ext(unsigned short port,
45                                     unsigned long int bufSize,
46                                     int raw,
47                                     /* OUT */ gras_socket_t *dst);
48 /*@}*/
49 /** \name Retrieving data about sockets and peers 
50  *  \ingroup GRAS_sock
51  * 
52  * Who are you talking to?
53  */
54 /*@{*/
55
56 /** Get the port number on which this socket is connected on my side */
57 int   gras_socket_my_port  (gras_socket_t sock);
58 /** Get the port number on which this socket is connected on remote side */
59 int   gras_socket_peer_port(gras_socket_t sock);
60 /** Get the host name of the remote side */
61 char *gras_socket_peer_name(gras_socket_t sock);
62 /*@}*/
63
64 /** \name Using raw sockets
65  *  \ingroup GRAS_sock
66  * 
67  * You may want to use sockets not to exchange valuable data (in messages), 
68  * but to conduct some experiments such as bandwidth measurement. If so, try those raw sockets.
69  * 
70  * You can only use those functions on sockets openned with the "raw" boolean set to true.
71  * 
72  * \bug Raw sockets are not fully functionnal yet.
73  */
74 /*@{*/
75
76 xbt_error_t gras_socket_raw_send(gras_socket_t peer, 
77                                   unsigned int timeout,
78                                   unsigned long int expSize, 
79                                   unsigned long int msgSize);
80 xbt_error_t gras_socket_raw_recv(gras_socket_t peer, 
81                                   unsigned int timeout,
82                                   unsigned long int expSize, 
83                                   unsigned long int msgSize);
84
85 /*@}*/
86
87 /** \name Using files as sockets
88  *  \ingroup GRAS_sock
89  * 
90  * For debugging purpose, it is possible to deal with files as if they were sockets.
91  * It can even be useful to store stuff in a portable manner, but writing messages to a file
92  * may be strange...
93  * 
94  * \bug Don't use '-' on windows. this file represents stdin or stdout, but I failed to deal with it on windows.
95  */
96 /*@{*/
97 /* debuging functions */
98 xbt_error_t gras_socket_client_from_file(const char*path,
99                                           /* OUT */ gras_socket_t *dst);
100 xbt_error_t gras_socket_server_from_file(const char*path,
101                                           /* OUT */ gras_socket_t *dst);
102                                           
103 /*@}*/
104    
105 #endif /* GRAS_TRANSPORT_H */