Statistics
| Branch: | Revision:

grapes / include / net_helper.h @ master

History | View | Annotate | Download (6.67 KB)

1 25a27886 Luca Abeni
#ifndef NET_HELPER_H
2
#define NET_HELPER_H
3
4 88cde4b2 Csaba Kiraly
#include <sys/time.h>
5 8f446863 Luca Baldesi
#include <stdint.h>
6
#include <stdlib.h>
7 32469cf7 Luca Abeni
8 8f3dbee6 MarcoBiazzini
/**
9
* @file net_helper.h
10
*
11
* @brief Communication facility interface for SOM.
12
*
13
* A clean interface is provided, through which all the communication procedures needed by SOM functions
14
* are handled. This way the different SOM functionalities are not dependent on any particular
15
* library with respect of the way they may call or be called by other applicative components.
16
*/
17
18
/**
19
* Implementation dependent internal representation of a node ID.
20
*/
21 651ed37d Luca
struct nodeID;
22 480921a6 Luca Abeni
23 8f3dbee6 MarcoBiazzini
/**
24 9e4a282c MarcoBiazzini
* @brief Duplicate a nodeID.
25 59771a03 Luca Abeni
*
26 9e4a282c MarcoBiazzini
* This function provides a duplicate of the given nodeID.
27 8f3dbee6 MarcoBiazzini
* @param[in] s A pointer to the nodeID to be duplicated.
28
* @return A pointer to the duplicate of the argument nodeID.
29
*/
30 fe3ab307 Luca Baldesi
struct nodeID *nodeid_dup(const struct nodeID *s);
31 8f3dbee6 MarcoBiazzini
32
/**
33 9e4a282c MarcoBiazzini
* @brief Test if two nodes are identical.
34 59771a03 Luca Abeni
*
35 8f3dbee6 MarcoBiazzini
* Test if two nodeIDs can be considered identical (where the definition of identity is implementation dependent).
36
* @param[in] s1 The first nodeID to be compared.
37
* @param[in] s2 The second nodeID to be compared.
38
* @return 1 if the two nodeID are identical or 0 if they are not.
39
*/
40 651ed37d Luca
int nodeid_equal(const struct nodeID *s1, const struct nodeID *s2);
41 480921a6 Luca Abeni
42 8f3dbee6 MarcoBiazzini
/**
43 ef4061e4 Csaba Kiraly
* @brief Compare two nodes and give some consistent ordering.
44
* This ordering  should only be used for keeping lists ordered, it has no other meaning.
45
* @param[in] s1 The first nodeID to be compared.
46
* @param[in] s2 The second nodeID to be compared.
47
* @return -1, 0 or 1, depending on the relation between  s1 and s2.
48
*/
49
int nodeid_cmp(const struct nodeID *s1, const struct nodeID *s2);
50
51
/**
52 9e4a282c MarcoBiazzini
* @brief Create a new nodeID.
53 59771a03 Luca Abeni
*
54 8f3dbee6 MarcoBiazzini
* Create a new nodeID from a given IP address and port number.
55
* @param[in] IPaddr The IP address in string form to be associated to the new nodeID.
56
* @param[in] port The port to be associated to the new nodeID.
57
* @return A pointer to the new nodeID.
58
*/
59 b576198c Luca Abeni
struct nodeID *create_node(const char *IPaddr, int port);
60 8f3dbee6 MarcoBiazzini
61
/**
62 9e4a282c MarcoBiazzini
* @brief Delete a nodeID.
63 59771a03 Luca Abeni
*
64 9e4a282c MarcoBiazzini
* Delete a nodeID and free the allocated resources.
65 8f3dbee6 MarcoBiazzini
* @param[in] s A pointer to the nodeID to be deleted.
66
*/
67 678c612d Luca Abeni
void nodeid_free(struct nodeID *s);
68 8f3dbee6 MarcoBiazzini
69
/**
70 9e4a282c MarcoBiazzini
* @brief Initialize all needed internal parameters.
71 59771a03 Luca Abeni
*
72 8f3dbee6 MarcoBiazzini
* Initialize the parameters for the networking facilities and create a nodeID representing the caller.
73
* @param[in] IPaddr The IP in string form to be associated to the caller.
74
* @param[in] port The port to be associated to the caller.
75 c919f1bf Csaba Kiraly
* @param[in] config Additional configuration options.
76 8f3dbee6 MarcoBiazzini
* @return A pointer to a nodeID representing the caller, initialized with all the necessary data.
77
*/
78 c919f1bf Csaba Kiraly
struct nodeID *net_helper_init(const char *IPaddr, int port,const char *config);
79 8f3dbee6 MarcoBiazzini
80
/**
81 59771a03 Luca Abeni
* @brief Prepare to receive messages of the specified type.
82
*
83
* Depending on the networking protocols and technologies used by the net
84
* helper, the application might need to declare the types of messages it's
85
* interested in. This function allows to specify which messages should be
86
* received (messages of different types might be silently discarded).
87
* @param[in] msgtype The MSG_TYPE of the message the caller is interested in.
88 8f3dbee6 MarcoBiazzini
*/
89 59771a03 Luca Abeni
void bind_msg_type(uint8_t msgtype);
90 8f3dbee6 MarcoBiazzini
91
/**
92 9e4a282c MarcoBiazzini
* @brief Send data to a remote peer.
93 59771a03 Luca Abeni
*
94 9e4a282c MarcoBiazzini
* This function provides a transparently handles the sending routines.
95 8f3dbee6 MarcoBiazzini
* @param[in] from A pointer to the nodeID representing the caller.
96
* @param[in] to A pointer to the nodeID representing the remote peer.
97
* @param[in] buffer_ptr A pointer to the buffer containing the data to be sent.
98
* @param[in] buffer_size The length of the data buffer.
99
* @return The number of bytes sent or -1 if some error occurred.
100
*/
101 c5922d21 Luca Abeni
int send_to_peer(const struct nodeID *from, const struct nodeID *to, const uint8_t *buffer_ptr, int buffer_size);
102 8f3dbee6 MarcoBiazzini
103
/**
104 9e4a282c MarcoBiazzini
* @brief Receive data from a remote peer.
105 59771a03 Luca Abeni
*
106 9e4a282c MarcoBiazzini
* This function transparently handles the receiving routines.
107 8f3dbee6 MarcoBiazzini
* @param[in] local A pointer to the nodeID representing the caller.
108
* @param[out] remote The address to a pointer that has to be set to a new nodeID representing the sender peer.
109
* @param[out] buffer_ptr A pointer to the buffer containing the received data.
110
* @param[out] buffer_size The size of the data buffer.
111
* @return The number of received bytes or -1 if some error occurred.
112
*/
113 b576198c Luca Abeni
int recv_from_peer(const struct nodeID *local, struct nodeID **remote, uint8_t *buffer_ptr, int buffer_size);
114 480921a6 Luca Abeni
115 8f3dbee6 MarcoBiazzini
116
/**
117 9e4a282c MarcoBiazzini
* @brief Check for newly arrived data.
118 59771a03 Luca Abeni
*
119 8f3dbee6 MarcoBiazzini
* Check if some data arrived for a given nodeID. It sets a timeout to return at most after a given time.
120
* @param[in] n A pointer to the nodeID representing the caller.
121
* @param[in] tout A pointer to a timer to be used to set the waiting timeout.
122 0cb8677a Luca Abeni
* @param[in] user_fds A "-1 terminated" array of FDs to be monitored.
123 8f3dbee6 MarcoBiazzini
* @return 1 if some data has arrived, 0 otherwise.
124
*/
125 0cb8677a Luca Abeni
int wait4data(const struct nodeID *n, struct timeval *tout, int *user_fds);
126 651ed37d Luca
127 8f3dbee6 MarcoBiazzini
/**
128 9e4a282c MarcoBiazzini
* @brief Give a string representation of a nodeID.
129 59771a03 Luca Abeni
*
130 8f3dbee6 MarcoBiazzini
* Give a string representation of a nodeID.
131
* @param[in] s A pointer to the nodeID to be printed.
132 80d1577c Andrea Zito
* @param[out] addr A pointer to the buffer where to write the address
133
* @param[in] len The length of the addr buffer
134 534e126a Andrea Zito
* @return >= 0 on success, or < 0 on error (buffer too small)
135 8f3dbee6 MarcoBiazzini
*/
136 80d1577c Andrea Zito
int node_addr(const struct nodeID *s, char *addr, int len);
137 8f3dbee6 MarcoBiazzini
138
/**
139 9e4a282c MarcoBiazzini
* @brief Create a nodeID structure from a serialized object.
140 59771a03 Luca Abeni
*
141 8f3dbee6 MarcoBiazzini
* Read from a properly filled byte array (@see #nodeid_dump) and build a new nodeID from its serialized representation in the buffer.
142
* @param[in] b A pointer to the byte array containing the data to be used.
143
* @param[in] len The number of bytes to be read from the buffer to build the new nodeID.
144
* @return A pointer to the new nodeID.
145
*/
146 651ed37d Luca
struct nodeID *nodeid_undump(const uint8_t *b, int *len);
147 8f3dbee6 MarcoBiazzini
148
/**
149 9e4a282c MarcoBiazzini
* @brief Serialize a nodeID in a byte array.
150 59771a03 Luca Abeni
*
151 8f3dbee6 MarcoBiazzini
* Serialize a nodeID in a byte array.
152
* @param[in] b A pointer to the byte array that will contain the nodeID serialization.
153
* @param[in] s A pointer to the nodeID to be serialized.
154 20903c9c Csaba Kiraly
* @param[in] max_write_size A number of bytes available in b
155
* @return The number of bytes written in the buffer, or -1 if error
156 8f3dbee6 MarcoBiazzini
*/
157 20903c9c Csaba Kiraly
int nodeid_dump(uint8_t *b, const struct nodeID *s, size_t max_write_size);
158 8f3dbee6 MarcoBiazzini
159 e55fe1f8 Marco Biazzini
/**
160
* @brief Give a string representation of the public IP belonging to the nodeID.
161 59771a03 Luca Abeni
*
162 e55fe1f8 Marco Biazzini
* Serialize the public IP address of a given node and return it.
163
* @param[in] s A pointer to the nodeID.
164 80d1577c Andrea Zito
* @param[out] ip A  pointer to the buffer where to store the ip address
165
* @param[in] len The length of the ip buffer
166 534e126a Andrea Zito
* @return >= 0 on success, or < 0 on error (buffer too small)
167 e55fe1f8 Marco Biazzini
*/
168 80d1577c Andrea Zito
int node_ip(const struct nodeID *s, char *ip, int len);
169
170
/**
171
* @brief Give the port number associated to the nodeID.
172
*
173
* Return the port number of the nodeID
174
* @param[in] s A pointer to the nodeID.
175
* @return The port number belonging to the nodeID
176
*/
177
int node_port(const struct nodeID *s);
178 e55fe1f8 Marco Biazzini
179 25a27886 Luca Abeni
#endif /* NET_HELPER_H */