Statistics
| Branch: | Revision:

ml / ml.h @ abbdb922

History | View | Annotate | Download (8.13 KB)

1
/*
2
 *             Policy Management
3
 *
4
 *          NEC Europe Ltd. PROPRIETARY INFORMATION
5
 *
6
 * This software is supplied under the terms of a license agreement
7
 * or nondisclosure agreement with NEC Europe Ltd. and may not be
8
 * copied or disclosed except in accordance with the terms of that
9
 * agreement.
10
 *
11
 *      Copyright (c) 2009 NEC Europe Ltd. All Rights Reserved.
12
 *
13
 * Authors: Kristian Beckers  <beckers@nw.neclab.eu>
14
 *    Sebastian Kiesel  <kiesel@nw.neclab.eu>
15
 *          
16
 *
17
 * NEC Europe Ltd. DISCLAIMS ALL WARRANTIES, EITHER EXPRESS OR IMPLIED,
18
 * INCLUDING BUT NOT LIMITED TO IMPLIED WARRANTIES OF MERCHANTABILITY
19
 * AND FITNESS FOR A PARTICULAR PURPOSE AND THE WARRANTY AGAINST LATENT
20
 * DEFECTS, WITH RESPECT TO THE PROGRAM AND THE ACCOMPANYING
21
 * DOCUMENTATION.
22
 *
23
 * No Liability For Consequential Damages IN NO EVENT SHALL NEC Europe
24
 * Ltd., NEC Corporation OR ANY OF ITS SUBSIDIARIES BE LIABLE FOR ANY
25
 * DAMAGES WHATSOEVER (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS
26
 * OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF INFORMATION, OR
27
 * OTHER PECUNIARY LOSS AND INDIRECT, CONSEQUENTIAL, INCIDENTAL,
28
 * ECONOMIC OR PUNITIVE DAMAGES) ARISING OUT OF THE USE OF OR INABILITY
29
 * TO USE THIS PROGRAM, EVEN IF NEC Europe Ltd. HAS BEEN ADVISED OF THE
30
 * POSSIBILITY OF SUCH DAMAGES.
31
 *
32
 *     THIS HEADER MAY NOT BE EXTRACTED OR MODIFIED IN ANY WAY.
33
 */
34

    
35
/**
36
 * @file ml.h
37
 * @brief This is the file that contains the API to the NAPA-WINE messaging layer
38
 * 
39
 * The messaging layer is a network layer abstraction for p2p systems, that has the primitives:
40
 *       - connect to a peer
41
 *       - send arbitrary size data to a peer
42
 *
43
 *  Furthermore, it provides the functionalites:
44
 *       - pmtu discovery
45
 *       - NAT traversal
46
 *       - data fragmentation and reassembly
47
 *
48
 *
49
 * @author Kristian Beckers  <beckers@nw.neclab.eu>
50
 * @author Sebastian Kiesel  <kiesel@nw.neclab.eu>  
51
 *
52
 * @date 7/28/2009
53
 *
54
 */
55

    
56
#ifndef ML_H
57
#define ML_H
58

    
59
#include <stdio.h>
60
#include <stdlib.h>
61
#include <unistd.h>
62
//#include <event2/event.h>
63
#include "transmissionHandler.h"
64

    
65
/**
66
 * The size of a socketID  
67
 */
68
#define SOCKETID_SIZE 68
69

    
70
/** 
71
 * The init method needs to be called to initialise the messaging layer
72
 * @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. 
73
 * @param timeout_value A timeout value for the data receival. 
74
 * @param stun_port The port of the stun server.
75
 * @param stun_ipaddr The ip address of the stun server. 
76
 */
77
void init_messaging_layer(boolean recv_data_cb,struct timeval timeout_value,const int stun_port,const char *stun_ipaddr);
78

    
79
/** 
80
 * This function is to register a callback that is envoked when a messaging layer packet is received.  
81
 * @param recv_pkt_inf_cb A function pointer to a callback function from the type get_recv_pkt_inf_cb
82
 */
83
void register_Get_recv_pkt_inf(get_recv_pkt_inf_cb  recv_pkt_inf_cb);
84

    
85
/** 
86
 *  This function is to register a callback that allows to add a monitoring module header to a packet. 
87
 * @param monitoring_header_pkt_cb A function pointer to a callback function from the type set_monitoring_header_pkt_cb
88
 */
89
void register_Set_monitoring_header_pkt_cb(set_monitoring_header_pkt_cb monitoring_header_pkt_cb);
90

    
91
/** 
92
 * Register a callback that is called when data is received  
93
 * @param recv_data_inf_cb  A function pointer to a callback function from the type get_recv_data_inf_cb
94
 */
95
void register_Get_recv_data_inf(get_recv_data_inf_cb recv_data_inf_cb);
96

    
97
/** 
98
 * Register a callback that is invoked when data is sent  
99
 * @param send_data_inf_cb  A function pointer to a callback function from the type get_send_data_inf_cb
100
 */
101
void register_Get_send_data_inf(get_send_data_inf_cb  send_data_inf_cb);
102

    
103
/** 
104
 * Register a callback that allows the monitoring module to set a header on data  
105
 * @param monitoring_header_data_cb A function pointer to a callback function from the type set_monitoring_header_data_cb
106
 */
107
void register_Set_monitoring_header_data_cb(set_monitoring_header_data_cb monitoring_header_data_cb);
108

    
109
/**
110
 * This function is to register a callback that informs the upper layer that a new connection is established.
111
 * @param recv_conn_cb  A function pointer to a callback function from the type receive_connection_cb
112
 */
113
void register_Recv_connection_cb(receive_connection_cb recv_conn_cb);
114

    
115
/** 
116
 * This function is to register a calllback that informs the upper layer that a connection attempt failed. 
117
 * @param conn_failed  A function pointer to a callback function from the type connection_failed_cb
118
 */
119
void register_Error_connection_cb(connection_failed_cb conn_failed);
120

    
121
/** 
122
 * This function is to register callbacks for received messages
123
 * at maximum 127 callbacks can be registered, one per message type,
124
 * each registered callback returns a value between 0 and 126
125
 * this value must be set as message type while sending data. 
126
 * When a message type is set twice with a different function pointer it will simply override the first. 
127
 * @param data_cb A function pointer to a callback function from the type receive_data_cb 
128
 * @param msgtype The message type
129
 */
130
void register_Recv_data_cb(receive_data_cb data_cb,unsigned char msgtype);
131

    
132
/**   
133
/* create a socket: returns a socketID handle  
134
 * A socketID handle is a pointer to the opague data structre
135
 * @param port A port that will be used to create a new UDP socket
136
 * @param ipaddr An ipaddress that will be used to create a new UDP socket. If left NULL the messaging layer binds it to localhost. 
137
*/
138
socketID_handle create_Socket(const int port,const char *ipaddr);
139

    
140
/** 
141
 * This function destroys a messaging layer socket.
142
 * @param socketID The socketID handle to the socket ID that shall be destroyed.
143
*/
144
void close_Socket(socketID_handle socketID);
145

    
146

    
147
/** 
148
 * This fuction opens a connection between two socketIDs.
149
 * @param local_socketID The local socketID
150
 * @param external_socketID The remote socketID
151
 * @param *connectionID A pointer to an int. The connectionID will be stored in that int. 
152
 * @return returnValue A value that indicates if the messaging layer could try to establish the connection. It returns 1 for success and 0 for a failure.
153
 */
154
int open_Connection(socketID_handle local_socketID,socketID_handle external_socketID,int *connectionID)
155
;
156

    
157
/** 
158
 * This function destroys a messaging layer connection.
159
 * @param connectionID 
160
 */
161
void close_Connection(const int connectionID);
162

    
163
/** 
164
 * This function sends data to a remote messaging layer instance.
165
 * @param connectionID The connection the data should be send to. 
166
 * @param sendbuf A pointer to the send buffer. 
167
 * @param bufsize The buffersize of the send buffer. 
168
 * @param msgtype The message type. 
169
 * @param sParams A pointer to a send_params struct. 
170
 */
171
void send_Data(const int connectionID,char *sendbuf,int bufsize,unsigned char msgtype,send_params *sParams);
172

    
173
/** 
174
 * This function receives data from a remote messaging layer instance.  
175
 * @param connectionID The connection the data came from. 
176
 * @param recvbuf A pointer to a buffer the data will be stored in. 
177
 * @param bufsize A pointer to an int that tells the size of the received data. 
178
 * @param rParams A pointer to a recv_params struct. 
179
 */
180
int recv_Data(const int connectionID,char *recvbuf,int *bufsize,recv_params *rParams);
181

    
182
/** 
183
 * This function sets the stun server address  
184
 * @param port The port of the stun server. 
185
 * @param ipaddr The ip address of the stun server. 
186
 */
187
void set_Stun_Server(const int port,const char *ipaddr);
188

    
189
/** 
190
 * 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. 
191
 * @param timeout_value The timeout value for receiving data. 
192
 */
193
void set_Recv_Timeout(struct timeval timeout_value);
194

    
195
/** 
196
 * A function that returns the standard TTL value the operating system places in every IP packet
197
 * @param socketID A local socketID
198
 * @param ttl A pointer to an integer
199
 * @return 0 if everything went well and -1 if an error occured 
200
 */
201
int get_standard_ttl(socketID_handle socketID,int *ttl);
202

    
203
#endif