Statistics
| Branch: | Revision:

ml / include / ml.h @ 6575ae37

History | View | Annotate | Download (21.7 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
 * @brief The size of a socketID
56
 */
57
#define SOCKETID_SIZE 60
58

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

    
64
/**
65
 * @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.
66
*/
67
struct _socket_ID;
68

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

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

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

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

    
95
} send_all_data_container;
96

    
97

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

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

    
106
} send_pkt_type_and_dst_inf;
107

    
108
/**
109
  * @brief A structure for parameters that is used in the mlSendData function. This structure contains options of how the sending should occur.
110
  */
111
typedef struct
112
{
113
  bool priority; ///<  A boolean variable that states if the data shall be send with priority.
114
  bool padding; ///<  A boolean that states if missing fragments shall be replaced with '0'
115
  bool confirmation; ///<   A boolean that causes a receive confirmation
116
  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.
117
  int  keepalive; ///< Send KEEPALIVE messages over this connection at every n. seconds. Set to <= 0 to disable keepalive
118
} send_params;
119

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

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

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

    
154
} mon_data_inf;
155

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

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

    
173
} mon_pkt_inf;
174

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

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

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

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

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

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

    
216
/**
217
 * Typedef for a callback when a socketID is ready to be used
218
 * SocketIDhandle is a handle for the local socketID
219
 * 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
220
 */
221
typedef void (*receive_localsocketID_cb)(socketID_handle local_socketID,int errorstatus);
222

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

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

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

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

    
247

    
248
/**
249
 * @brief Initialize the Messaging Layer.
250
 * The init method needs to be called to initialize the messaging layer
251
 * @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.   
252
* @param timeout_value A timeout value for the data receival   
253
* @param port A port that will be used to create a new UDP socket    
254
* @param ipaddr An ipaddress that will be used to create a new UDP socket. If left NULL the messaging layer binds it to localhost.
255
* @param stun_port The port of the stun server.
256
* @param stun_ipaddr The ip address of the stun server.
257
* @param local_socketID_cb A callback from the type receive_localsocketID_cb that is envoke once the socketID is ready to use.
258
* @param arg A void pointer that is used in this implementation to handover the libevent pointer.
259
* @return The file descriptor used by the ML, or <0 on error
260
 */
261
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);
262

    
263
/**
264
  * Configure the verbosity of messages
265
  * @param log_level [0-4] the lower the less messages are printed out
266
*/
267
void mlSetVerbosity(int log_level);
268

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

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

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

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

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

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

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

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

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

    
334
void mlRegisterRecvDataCb(receive_data_cb data_cb,unsigned char msgtype);
335

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

    
343

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

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

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

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

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

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

    
405
/**
406
 * @brief Set a receive timeout.
407
 * 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. 
408
 * @param timeout_value The timeout value for receiving data. 
409
 */
410
void mlSetRecvTimeout(struct timeval timeout_value);
411

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

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

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

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

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

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

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

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

    
480
//Comodity functions added By Robert Birke
481
//int mlPrintSocketID(socketID_handle socketID);
482

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

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

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

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

    
517

    
518

    
519
/**
520
  * Configure the parameters for output rate control.
521
  * @param bucketsize The size of the bucket in kbytes
522
  * @param drainrate The amount of kbytes draining in a second. If drainrate is <=0, then rateControl is completely disabled (all packets are passed).
523
  * @param maxQueueSize In kbytes. Max data stored while limiting the output rate. If 0 packets limitted by drainrate are dropped.
524
  * @param maxQueueSizeRTX In kbytes. Max data waiting for the retransmission if needed.
525
  * @param maxTimeToHold. Time for which sent packets are stored in RTX queue in seconds.
526
*/
527
void mlSetRateLimiterParams(int bucketsize, int drainrate, int maxQueueSize, int maxQueueSizeRTX, double maxTimeToHold);
528

    
529

    
530
#ifdef __cplusplus
531
}
532
#endif
533

    
534
#endif