Statistics
| Branch: | Revision:

grapes / include / net_helper.h @ 534e126a

History | View | Annotate | Download (6.01 KB)

1
#ifndef NET_HELPER_H
2
#define NET_HELPER_H
3

    
4
#include <sys/time.h>
5

    
6
/**
7
* @file net_helper.h
8
*
9
* @brief Communication facility interface for SOM.
10
*
11
* A clean interface is provided, through which all the communication procedures needed by SOM functions
12
* are handled. This way the different SOM functionalities are not dependent on any particular
13
* library with respect of the way they may call or be called by other applicative components.
14
*/
15

    
16
/**
17
* Implementation dependent internal representation of a node ID.
18
*/
19
struct nodeID;
20

    
21
/**
22
* @brief Duplicate a nodeID.
23
*
24
* This function provides a duplicate of the given nodeID.
25
* @param[in] s A pointer to the nodeID to be duplicated.
26
* @return A pointer to the duplicate of the argument nodeID.
27
*/
28
struct nodeID *nodeid_dup(struct nodeID *s);
29

    
30
/**
31
* @brief Test if two nodes are identical.
32
*
33
* Test if two nodeIDs can be considered identical (where the definition of identity is implementation dependent).
34
* @param[in] s1 The first nodeID to be compared.
35
* @param[in] s2 The second nodeID to be compared.
36
* @return 1 if the two nodeID are identical or 0 if they are not.
37
*/
38
int nodeid_equal(const struct nodeID *s1, const struct nodeID *s2);
39

    
40
/**
41
* @brief Create a new nodeID.
42
*
43
* Create a new nodeID from a given IP address and port number.
44
* @param[in] IPaddr The IP address in string form to be associated to the new nodeID.
45
* @param[in] port The port to be associated to the new nodeID.
46
* @return A pointer to the new nodeID.
47
*/
48
struct nodeID *create_node(const char *IPaddr, int port);
49

    
50
/**
51
* @brief Delete a nodeID.
52
*
53
* Delete a nodeID and free the allocated resources.
54
* @param[in] s A pointer to the nodeID to be deleted.
55
*/
56
void nodeid_free(struct nodeID *s);
57

    
58
/**
59
* @brief Initialize all needed internal parameters.
60
*
61
* Initialize the parameters for the networking facilities and create a nodeID representing the caller.
62
* @param[in] IPaddr The IP in string form to be associated to the caller.
63
* @param[in] port The port to be associated to the caller.
64
* @param[in] config Additional configuration options.
65
* @return A pointer to a nodeID representing the caller, initialized with all the necessary data.
66
*/
67
struct nodeID *net_helper_init(const char *IPaddr, int port,const char *config);
68

    
69
/**
70
* @brief Prepare to receive messages of the specified type.
71
*
72
* Depending on the networking protocols and technologies used by the net
73
* helper, the application might need to declare the types of messages it's
74
* interested in. This function allows to specify which messages should be
75
* received (messages of different types might be silently discarded).
76
* @param[in] msgtype The MSG_TYPE of the message the caller is interested in.
77
*/
78
void bind_msg_type(uint8_t msgtype);
79

    
80
/**
81
* @brief Send data to a remote peer.
82
*
83
* This function provides a transparently handles the sending routines.
84
* @param[in] from A pointer to the nodeID representing the caller.
85
* @param[in] to A pointer to the nodeID representing the remote peer.
86
* @param[in] buffer_ptr A pointer to the buffer containing the data to be sent.
87
* @param[in] buffer_size The length of the data buffer.
88
* @return The number of bytes sent or -1 if some error occurred.
89
*/
90
int send_to_peer(const struct nodeID *from, struct nodeID *to, const uint8_t *buffer_ptr, int buffer_size);
91

    
92
/**
93
* @brief Receive data from a remote peer.
94
*
95
* This function transparently handles the receiving routines.
96
* @param[in] local A pointer to the nodeID representing the caller.
97
* @param[out] remote The address to a pointer that has to be set to a new nodeID representing the sender peer.
98
* @param[out] buffer_ptr A pointer to the buffer containing the received data.
99
* @param[out] buffer_size The size of the data buffer.
100
* @return The number of received bytes or -1 if some error occurred.
101
*/
102
int recv_from_peer(const struct nodeID *local, struct nodeID **remote, uint8_t *buffer_ptr, int buffer_size);
103

    
104

    
105
/**
106
* @brief Check for newly arrived data.
107
*
108
* Check if some data arrived for a given nodeID. It sets a timeout to return at most after a given time.
109
* @param[in] n A pointer to the nodeID representing the caller.
110
* @param[in] tout A pointer to a timer to be used to set the waiting timeout.
111
* @param[in] user_fds A "-1 terminated" array of FDs to be monitored.
112
* @return 1 if some data has arrived, 0 otherwise.
113
*/
114
int wait4data(const struct nodeID *n, struct timeval *tout, int *user_fds);
115

    
116
/**
117
* @brief Give a string representation of a nodeID.
118
*
119
* Give a string representation of a nodeID.
120
* @param[in] s A pointer to the nodeID to be printed.
121
* @param[out] addr A pointer to the buffer where to write the address
122
* @param[in] len The length of the addr buffer
123
* @return >= 0 on success, or < 0 on error (buffer too small)
124
*/
125
int node_addr(const struct nodeID *s, char *addr, int len);
126

    
127
/**
128
* @brief Create a nodeID structure from a serialized object.
129
*
130
* Read from a properly filled byte array (@see #nodeid_dump) and build a new nodeID from its serialized representation in the buffer.
131
* @param[in] b A pointer to the byte array containing the data to be used.
132
* @param[in] len The number of bytes to be read from the buffer to build the new nodeID.
133
* @return A pointer to the new nodeID.
134
*/
135
struct nodeID *nodeid_undump(const uint8_t *b, int *len);
136

    
137
/**
138
* @brief Serialize a nodeID in a byte array.
139
*
140
* Serialize a nodeID in a byte array.
141
* @param[in] b A pointer to the byte array that will contain the nodeID serialization.
142
* @param[in] s A pointer to the nodeID to be serialized.
143
* @param[in] max_write_size A number of bytes available in b
144
* @return The number of bytes written in the buffer, or -1 if error
145
*/
146
int nodeid_dump(uint8_t *b, const struct nodeID *s, size_t max_write_size);
147

    
148
/**
149
* @brief Give a string representation of the public IP belonging to the nodeID.
150
*
151
* Serialize the public IP address of a given node and return it.
152
* @param[in] s A pointer to the nodeID.
153
* @param[out] ip A  pointer to the buffer where to store the ip address
154
* @param[in] len The length of the ip buffer
155
* @return >= 0 on success, or < 0 on error (buffer too small)
156
*/
157
int node_ip(const struct nodeID *s, char *ip, int len);
158

    
159
#endif /* NET_HELPER_H */