Statistics
| Branch: | Revision:

napa-baselibs / ml / include / ml.h @ 5f3adef4

History | View | Annotate | Download (21.2 KB)

1
#ifndef ML_H
2
#define ML_H
3

    
4
/**
5
 * @file ml.h
6
 * @brief NAPA-WINE messaging layer API.
7
 * 
8
 * The messaging layer is a network layer abstraction for p2p systems, that has the primitives:
9
 *       - connect to a peer
10
 *       - send arbitrary size data to a peer
11
 *
12
 *  Furthermore, it provides the functionalites:
13
 *       - PMTU discovery
14
 *       - NAT traversal
15
 *       - data fragmentation and reassembly
16
 *
17
 * The messaging layer (ML) abstracts the access to transport 
18
 * (UDP/TCP) protocols and the corresponding service access points 
19
 * offered by the operating system by extending their capabilities 
20
 * and providing an overlay level addressing, i.e., assigning a 
21
 * unique identifier to each peer. 
22
 * 
23
 * For example, it provides the ability to send a chunk of
24
 * data to another peer, which has to be segmented and then
25
 * reassembled to fit into UDP segments. The messaging layer
26
 * also provides an interface to the monitoring module, which is
27
 * used for passive measurements: whenever a message is sent or
28
 * received an indication will be given to the monitoring module,
29
 * which then can update its statistics.
30
 * Another important feature of the messaging layer is mechanisms
31
 * for the traversal of NAT routers. Network Address Translation 
32
 * allows to attach several hosts to the Internet
33
 * using only one globally unique IP address. Therefore it is
34
 * very popular with private customers, who are also the main
35
 * target audience for P2P TV. However, the presence of a NAT
36
 * device may impede the ability to establish connections to other
37
 * peers, therefore, special NAT traversal functions are needed
38
 * in the messaging layer.
39
 *
40
 * @author Kristian Beckers  <beckers@nw.neclab.eu>
41
 * @author Sebastian Kiesel  <kiesel@nw.neclab.eu>  
42
 *
43
 * @date 7/28/2009
44
 *
45
 */
46

    
47
#include <stdio.h>
48
#include <stdlib.h>
49
#include <unistd.h>
50
#include <stdbool.h>
51
#include <stdint.h>
52
#include <sys/time.h>
53

    
54

    
55
/**
56
 * @brief The size of a socketID
57
 */
58
#define SOCKETID_SIZE 60
59

    
60
/**
61
 * @brief The size of a socketID in string representation
62
 */
63
#define SOCKETID_STRING_SIZE 44
64

    
65
/**
66
 * @brief A struct with direction information of a packet or data that is about to be send. This structure is used to providethe monitoring module with information about where a data/packet will be sent and what the messagetype is.
67
*/
68
struct _socket_ID;
69

    
70
/**
71
 * @brief Typedef that defines a socketID handle a pointer to a socket_ID struct
72
 */
73
typedef struct _socket_ID *socketID_handle;
74

    
75
/**
76
 * @brief Typedef for a callback when a new connection is established
77
 */
78
typedef void (*receive_connection_cb)(int connectionID, void *arg);
79

    
80
/**
81
 * @brief A struct with a couple of buffers and length pairs for the send_all function
82
 */
83
typedef struct {
84

    
85
  char *buffer_1; ///< A buffer pointer
86
  int length_1; ///< The length of the buffer
87
  char *buffer_2; ///< A buffer pointer
88
  int length_2; ///< The length of the buffer
89
  char *buffer_3; ///< A buffer pointer
90
  int length_3; ///< The length of the buffer
91
  char *buffer_4; ///< A buffer pointer
92
  int length_4; ///< The length of the buffer
93
  char *buffer_5; ///< A buffer pointer
94
  int length_5; ///< The length of the buffer
95

    
96
} send_all_data_container;
97

    
98

    
99
/**
100
 * @brief A struct with direction information of a packet or data that is about to be send.
101
 */
102
typedef struct {
103

    
104
  socketID_handle remote_socketID; ///< The remote socketID
105
  char msgtype; ///< The message type
106

    
107
} send_pkt_type_and_dst_inf;
108

    
109
/**
110
  * @brief A structure for parameters that is used in the mlSendData function. This structure contains options of how the sending should occur.
111
  */
112
typedef struct
113
{
114
  bool priority; ///<  A boolean variable that states if the data shall be send with priority.
115
  bool padding; ///<  A boolean that states if missing fragments shall be replaced with '0'
116
  bool confirmation; ///<   A boolean that causes a receive confirmation
117
  bool reliable; ///< A boolean that sends the data over a reliable protocol. Warning: If the messaging layer fails to establish a connection with a reliable protocol it falls back to UDP.
118
  int  keepalive; ///< Send KEEPALIVE messages over this connection at every n. seconds. Set to <= 0 to disable keepalive
119
} send_params;
120

    
121
/**
122
 * @brief A struct that is returned from the messaging layer with metadata about the received data.
123
 */
124
typedef struct {
125
  char msgtype; ///< The message type.
126
  int connectionID; ///< The connectionID.
127
  int nrMissingBytes; ///< The number of bytes that did not arrive.
128
  int recvFragments; ///< The overall number of fragments.
129
  char firstPacketArrived; ///< A boolean that states if the first fragment arrived.
130
  socketID_handle remote_socketID; ///< The remote socketID
131
} recv_params;
132

    
133
/**
134
 * @brief A struct that contains metadata about messaging layer data. It used to transfer metadata about arrived messaging layer data to the monitoring module.
135
 *
136
 */
137
typedef struct {
138

    
139
  socketID_handle remote_socketID; ///< The remote socketID
140
  char *buffer; ///< A pointer to the data that was received
141
  int bufSize; ///< The size of the data that was received
142
  char msgtype; ///< The message type
143
  char monitoringHeaderType; ///<  This value indicates if a monitoring header was added to the data. The header is added when the value is either 1 or 3.
144
  char *monitoringDataHeader; ///<  A pointer to the monitoring header.
145
  int monitoringDataHeaderLen;
146
  struct timeval arrival_time; ///< The arrival time of the data
147
  char firstPacketArrived; ///< A boolean that states if the first fragment arrived.
148
  int nrMissingBytes; ///<  The number of bytes that did not arrive.
149
  int recvFragments; ///< The overall number of fragments arrived
150
  bool priority; ///< A boolean variable that states if the data was send with priority.
151
  bool padding; ///< A boolean that states if missing fragments were replaced with '0'
152
  bool confirmation; ///<  A boolean that states if a receive confirmation was send
153
  bool reliable; ///< A boolean that the data was send  over a reliable protocol.
154

    
155
} mon_data_inf;
156

    
157
/**
158
 * @brief A struct of metadata about messaging layer packets. It is used to inform the monitoring module about arrived packets
159
 */
160
typedef struct {
161

    
162
  socketID_handle remote_socketID; ///< The remote socketID
163
        char *buffer; ///< A pointer to the data that was received
164
  int bufSize; ///< The size of the data that was received
165
  char msgtype; ///<  The message type
166
  int dataID; ///< The data ID field from the messaging layer header.
167
  int offset; ///< The data offset field from the messaging layer header.
168
  int datasize; ///< The datasize field from the messaging layer header.
169
  char *monitoringHeader; ///< A pointer to the monitoring header.
170
  int monitoringHeaderLen;
171
  int ttl; ///< The TTL Field from the IP Header of the packet.
172
  struct timeval arrival_time; ///< The arrival time of the packet.
173

    
174
} mon_pkt_inf;
175

    
176
/**
177
 * Typedef for a callback when a UDP packet is received.
178
 * The callback receives a pointer to a mon_pkt_inf struct as param
179
 * This shall be used by the monitoring module
180
*/
181
typedef void (*get_recv_pkt_inf_cb)(void *arg);
182

    
183
/**
184
 * Typedef for a callback when a packet is send
185
 * The param is a pointer to a mon_pkt_inf struct
186
 */
187
typedef void (*get_send_pkt_inf_cb)(void *arg);
188

    
189
/**
190
 * Typedef for a callback that asks if a monitoring module packet header shall be set
191
 * the first param is a pointer to the monitoring module packet header
192
 * the second param is a pointer to a send_pkt_type_and_dst_inf struct
193
 * return value returns 0 for no header and 1 for header
194
 */
195
typedef int (*set_monitoring_header_pkt_cb)(socketID_handle, uint8_t);
196

    
197
/**
198
 * Typedef for a callback that is envoked when data has been received
199
 * The param is a pointer to a mon_data_inf struct
200
 */
201
typedef void (*get_recv_data_inf_cb)(void *arg);
202

    
203
/**
204
 * Typedef for a callback when data has been send
205
 * The param is a pointer to a mon_data_inf struct
206
 */
207
typedef void (*get_send_data_inf_cb)(void *arg);
208

    
209
/**
210
 * Typedef for a callback that asks if a monitoring module header for data shall be set
211
 * the first param is a pointer to the monitoring module data header
212
 * the second param is a pointer to a send_pkt_type_and_dst_inf struct
213
 * return value returns 0 for no header and 1 for header
214
 */
215
typedef int (*set_monitoring_header_data_cb)(socketID_handle, uint8_t);
216

    
217
/**
218
 * Typedef for a callback when a socketID is ready to be used
219
 * SocketIDhandle is a handle for the local socketID
220
 * Errorstatus is set to -1 if an socket error occurred and the socket is not usable and 1 if the NAT traversal failed and 0 if no error occurred
221
 */
222
typedef void (*receive_localsocketID_cb)(socketID_handle local_socketID,int errorstatus);
223

    
224
/**
225
 * Typedef for a callback when a connection attempt failed
226
 */
227
typedef void (*connection_failed_cb)(int connectionID,void *arg);
228

    
229
/**
230
 * Typedef for a callback when data is received.
231
 * The first param is a pointer to a buffer that has the data
232
 * The second param is an int that holds the length of the data
233
 * The third param is the message type
234
 * The fourth param is a pointer to a recv_params struct
235
 */
236
typedef void (*receive_data_cb)(char *buffer,int buflen,unsigned char msgtype,recv_params *rparams);
237

    
238
#ifdef __cplusplus
239
extern "C" {
240
#endif
241

    
242
/**
243
 * This function is to register a callback that informs the upper layer that the local socketID is ready to use.        
244
 * @param local_socketID_cb  A function pointer to a callback function from the type receive_localsocketID_cb
245
 */
246
void register_recv_localsocketID_cb(receive_localsocketID_cb local_socketID_cb);
247

    
248

    
249
/**
250
 * @brief Initialize the Messaging Layer.
251
 * The init method needs to be called to initialize the messaging layer
252
 * @param recv_data_cb This is a boolean that decides how an upper layer receives data. When the boolean is set to true data is received via callback. When it is set to false the upper layer has to poll with the recv_data function.   
253
* @param timeout_value A timeout value for the data receival   
254
* @param port A port that will be used to create a new UDP socket    
255
* @param ipaddr An ipaddress that will be used to create a new UDP socket. If left NULL the messaging layer binds it to localhost.
256
* @param stun_port The port of the stun server.
257
* @param stun_ipaddr The ip address of the stun server.
258
* @param local_socketID_cb A callback from the type receive_localsocketID_cb that is envoke once the socketID is ready to use.
259
* @param arg A void pointer that is used in this implementation to handover the libevent pointer.
260
* @return The file descriptor used by the ML, or <0 on error
261
 */
262
int mlInit(bool recv_data_cb,struct timeval timeout_value,const int port,const char *ipaddr,const int stun_port,const char *stun_ipaddr,receive_localsocketID_cb local_socketID_cb,void *arg);
263

    
264
/**
265
  * Configure the parameters for output rate control.
266
  * These values may also be set while packets are being transmitted.
267
  * @param bucketsize The size of the bucket in kbytes
268
  * @param drainrate The amount of kbytes draining in a second. If drainrate is <=0, then rateControl is completely disabled (all packets are passed).
269
*/
270
void mlSetThrottle(int bucketsize, int drainrate);
271

    
272
/**
273
 * @brief Register a received packet callback.
274
 * This function is to register a callback that is invoked when a messaging layer packet is received.
275
 * @param recv_pkt_inf_cb A function pointer to a callback function from the type get_recv_pkt_inf_cb
276
 */
277
void mlRegisterGetRecvPktInf(get_recv_pkt_inf_cb  recv_pkt_inf_cb);
278

    
279
/**
280
 * @brief Register a send packet callback.
281
 * This function is to register a callback that is invoked when a messaging layer packet is send.
282
 * @param send_pkt_inf_cb A function pointer to a callback function from the type get_send_pkt_inf_cb
283
 */
284
void mlRegisterGetSendPktInf(get_send_pkt_inf_cb  send_pkt_inf_cb);
285

    
286
/**
287
 * @brief Register a monitoring packet callback.
288
 * This function is to register a callback that allows to add a monitoring module header to a packet.
289
 * @param monitoring_header_pkt_cb A function pointer to a callback function from the type set_monitoring_header_pkt_cb
290
 */
291
void mlRegisterSetMonitoringHeaderPktCb(set_monitoring_header_pkt_cb monitoring_header_pkt_cb);
292

    
293
/**
294
 * @brief Register a receive data callback.
295
 * Register a callback that is called when data is received  
296
 * @param recv_data_inf_cb  A function pointer to a callback function from the type get_recv_data_inf_cb
297
 */
298
void mlRegisterGetRecvDataInf(get_recv_data_inf_cb recv_data_inf_cb);
299

    
300
/**
301
 * @brief Register a send data callback.
302
 * Register a callback that is invoked when data is sent  
303
 * @param send_data_inf_cb  A function pointer to a callback function from the type get_send_data_inf_cb
304
 */
305
void mlRegisterGetSendDataInf(get_send_data_inf_cb  send_data_inf_cb);
306

    
307
/**
308
 * @brief Register a monitoring data callback.
309
 * Register a callback that allows the monitoring module to set a header on data  
310
 * @param monitoring_header_data_cb A function pointer to a callback function from the type set_monitoring_header_data_cb
311
 */
312
void mlRegisterSetMonitoringHeaderDataCb(set_monitoring_header_data_cb monitoring_header_data_cb);
313

    
314
/**
315
 * @brief Register a receive connection callback.
316
 * This function is to register a callback that informs the upper layer that a new connection is established.
317
 * @param recv_conn_cb  A function pointer to a callback function from the type receive_connection_cb
318
 */
319
void mlRegisterRecvConnectionCb(receive_connection_cb recv_conn_cb);
320

    
321
/**
322
 * @brief Register an error connection callback.
323
 * This function is to register a calllback that informs the upper layer that a connection attempt failed. 
324
 * @param conn_failed  A function pointer to a callback function from the type connection_failed_cb
325
 */
326
void mlRegisterErrorConnectionCb(connection_failed_cb conn_failed);
327

    
328
/**
329
 * @brief Register a receive data callback.
330
 * This function is to register callbacks for received messages.
331
 * At maximum 127 callbacks can be registered, one per message type.
332
 * When a message type is set twice with a different function pointer it will simply override the first.
333
 * @param data_cb A function pointer to a callback function from the type receive_data_cb
334
 * @param msgtype The message type: an integer in [0..126]
335
 */
336

    
337
void mlRegisterRecvDataCb(receive_data_cb data_cb,unsigned char msgtype);
338

    
339
/**
340
 * @brief Close a socket.
341
 * This function destroys a messaging layer socket.
342
 * @param socketID The socketID handle to the socket ID that shall be destroyed.
343
 */
344
void mlCloseSocket(socketID_handle socketID);
345

    
346

    
347
/**
348
 * @brief Open a connection.
349
 * This fuction opens a connection between two socketIDs.
350
 * @param external_socketID The remote socketID
351
 * @param *connectionID A pointer to an int. The connectionID will be stored in that int. 
352
 * @param connection_cb  A function pointer to a callback function from the type receive_connect\
353
ion_cb                                                                                           
354
 * @param arg A void pointer that is returned via the callback. 
355
 * @param default_send_params send_params to use if not specified at the send functions
356
 * @return returnValue the connection id and -1 for a failure
357
 */
358
int mlOpenConnection(socketID_handle external_socketID,receive_connection_cb connection_cb,void *arg, const send_params default_send_params);
359

    
360
/**
361
 * @brief Open a connection.
362
 * This function destroys a messaging layer connection.
363
 * @param connectionID 
364
 */
365
void mlCloseConnection(const int connectionID);
366

    
367
/**
368
 * @brief Send data from multiple buffers.
369
 * This function sends data. The data is provided as a list of buffer and length pairs.
370
 * @param connectionID The connection the data should be send to.
371
 * @param container A container for several buffer pointer and length pairs from type send_all_data_container/
372
 * @param nr_entries The number of buffer pointer and length pairs in the container. The maximum nr is 5.
373
 * @param msgtype The message type.
374
 * @param sParams A pointer to a send_params struct. If NULL, the default is used given at mlOpenConnection
375
 * @return 0 if a problem occured, 1 if everything was alright.
376
 */
377
int mlSendAllData(const int connectionID,send_all_data_container *container,int nr_entries,unsigned char msgtype,send_params *sParams);
378

    
379
/**
380
 * @brief Send buffered data.
381
 * This function sends data to a remote messaging layer instance.
382
 * @param connectionID The connection the data should be send to. 
383
 * @param sendbuf A pointer to the send buffer. 
384
 * @param bufsize The buffersize of the send buffer. 
385
 * @param msgtype The message type. 
386
 * @param sParams A pointer to a send_params struct. If NULL, the default is used given at mlOpenConnection
387
 */
388
void mlSendData(const int connectionID,char *sendbuf,int bufsize,unsigned char msgtype,send_params *sParams);
389

    
390
/**
391
 * @brief Receive newly arrived data.
392
 * This function receives data from a remote messaging layer instance.  
393
 * @param connectionID The connection the data came from. 
394
 * @param recvbuf A pointer to a buffer the data will be stored in. 
395
 * @param bufsize A pointer to an int that tells the size of the received data. 
396
 * @param rParams A pointer to a recv_params struct. 
397
 */
398
int mlRecvData(const int connectionID,char *recvbuf,int *bufsize,recv_params *rParams);
399

    
400
/**
401
 * @brief Set the STUN server.
402
 * This function sets the stun server address  
403
 * @param port The port of the stun server. 
404
 * @param ipaddr The ip address of the stun server. 
405
 */
406
void mlSetStunServer(const int port,const char *ipaddr);
407

    
408
/**
409
 * @brief Set a receive timeout.
410
 * This function sets a receive timeout for the data arrival. Should not all fragments of a data buffer arrive within this timeframe the arrival buffer is closed and the fragments that have arrived are returned to the upper layer. 
411
 * @param timeout_value The timeout value for receiving data. 
412
 */
413
void mlSetRecvTimeout(struct timeval timeout_value);
414

    
415
/**
416
 * @brief Get the TTL.
417
 * A function that returns the standard TTL value the operating system places in every IP packet
418
 * @param socketID A local socketID
419
 * @param ttl A pointer to an integer
420
 * @return 0 if everything went well and -1 if an error occured 
421
 */
422
int mlGetStandardTTL(socketID_handle socketID,uint8_t *ttl);
423

    
424
/**
425
 * @brief Get the local socket.
426
 * A function that returns a handle for the local socketID
427
 * @param errorstatus Returns 0 if the socketID is operational and 2 if the NAT traversal failed
428
* @return A socketID handle
429
*/
430
socketID_handle mlGetLocalSocketID(int *errorstatus);
431

    
432
/**
433
 * @brief Get the external IP address.
434
 * A function that returns the external IP from the local socketID
435
 * @param external_addr A pointer to a char buffer that holds the external address
436
 * @return -1 if an error occurred and 0 if it succeeded
437
 */
438
int mlGetExternalIP(char* external_addr);
439

    
440
/**
441
 * @brief Give a string representation of a SocketID.
442
 * A function that returns a string from a socketID handler
443
 * @param socketID
444
 * @param socketID_string
445
 * @param len length of socketID_string buffer
446
 * @return -1 if an error occurred and 0 if it succeded
447
 */
448
int mlSocketIDToString(socketID_handle socketID,char* socketID_string, size_t len);
449

    
450
/**
451
 * @brief Make a SOcketID out of a proper string.
452
 * A function that returns a socketID handler from a string.
453
 * @param socketID A socketID in string format
454
 * @return a pointer to a socketID
455
 */
456
int mlStringToSocketID(const char* socketID_string, socketID_handle socketID);
457

    
458
/**
459
 * @brief Get the connection status.
460
 * A function that returns the whenever a connection is ready to use or not.
461
 * @param connectionID The connectionID of the connection that is queried.                       
462
 * @return 1 if READY 0 if not or -1 if the connectionID does not exist                      
463
 */
464
int mlGetConnectionStatus(int connectionID);
465

    
466
/**
467
 * @brief Check if a connection already exists.
468
 * A function that returns the whenever a connection is ready to use or not.
469
 * @param socketID A remote socketID to which the connection has been established.               
470
 * @param ready if true, returns the connID on READY connections only 
471
 * @return -1 if the connection does not exist and the connection ID if it exists.               
472
 */
473
int mlConnectionExist(socketID_handle socketID, bool ready);
474

    
475
/**
476
 * @brief Try and guess the own IP.
477
 * Convenience function to guess the IP address if not specified in the configuration.
478
 * Not foolproof.
479
 * @return a static structure holding the address or NULL
480
 */
481
const char *mlAutodetectIPAddress();
482

    
483
//Comodity functions added By Robert Birke
484
//int mlPrintSocketID(socketID_handle socketID);
485

    
486
/**
487
 * @brief Give a hash for a SocketID.
488
 * Provide the hash code of the given SocketID argument.
489
 * @param sock A pointer to a socket_ID.
490
 * @return The hash of the argument.
491
 */
492
int mlHashSocketID(socketID_handle sock);
493

    
494
/**
495
 * @brief Compare two SocketIDs.
496
 * Test for equality two given SocketIDs.
497
 * @param sock1 A pointer to a socket_ID.
498
 * @param sock2 A pointer to a socket_ID.
499
 * @return 0 if the arguments are equual ; 1 otherwise.
500
 */
501
int mlCompareSocketIDs(socketID_handle sock1, socketID_handle sock2);
502

    
503
/**
504
 * @brief Compare the port number of two SocketIDs.
505
 * Test for equality the port number associated to two given SocketIDs.
506
 * @param sock1 A pointer to a socket_ID.
507
 * @param sock2 A pointer to a socket_ID.
508
 * @return 0 if the arguments have the same port number ; 1 otherwise.
509
 */
510
int mlCompareSocketIDsByPort(socketID_handle sock1, socketID_handle sock2);
511

    
512
/**
513
 * @brief Get the MTU of a given connection
514
 * Get the MTU associated to a given connection ID.
515
 * @param ConnectionID The ID of an open connection.
516
 * @return The MTU associated to the given connection.
517
 */
518
int mlGetPathMTU(int ConnectionId);
519

    
520
#ifdef __cplusplus
521
}
522
#endif
523

    
524
#endif