summaryrefslogtreecommitdiff
path: root/cesar/cl/cl.h
blob: e6b1dc99120fa375ebb6ff4247e1e3f31e741a20 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
#ifndef CL_CL_H_
#define CL_CL_H_

/* Cesar project {{{
 *
 * Copyright (C) 2007 Spidcom
 *
 * <<<Licence>>>
 *
 * }}} */
/**
 * \file    cl/cl.h
 * \brief   Public functions
 * \ingroup cl
 * 
 */

#include "mac/common/mfs.h"
#include "mac/common/store.h"
#include "lib/utils.h"
#include "mac/sar/sar.h"

/** forward declaration. */
typedef struct cl_t cl_t;
typedef struct cl_mme_recv_t cl_mme_recv_t;

/**
 * Callback use to inform the upper layer when a data had been sent over the 
 * PLC.
 * 
 * \param  user  the user data
 * \param  buffer  the buffer use to send the data over the PLC.
 */
typedef void (*cl_data_send_done_cb_t) (void *user, u8 *buffer);

/**
 * Callback to provide a received data to the upper layer comming from the SAR.
 * 
 * \param  user  the user data
 * \param  buffer  the buffer containing the data
 * \param  length  the data length in the buffer.
 */
typedef void (*cl_data_recv_cb_t) (void *user, u8 *buffer, uint length);

/**
 * Provides a MME buffer to the CP.
 *
 * \param  user_data  the layer data.
 * \param  buffer  the buffer to provide.
 */
typedef void (*cl_mme_buffer_add_cb_t) (void *user_data, u8 *buffer);

/**
 * Call back to use when the CL needs to send a MME to the upper layer.
 * 
 * \param  ul_data  the upper layer data provided on the registration.
 * \param  buffer  the buffer containig the MME.
 * \param  length  the length of the MME
 */
typedef void (*cl_mme_ul_send_done_cb_t) (void *ul_data, u8 *buffer, uint length);

/**
 * Call back to use once the CP had used the buffer containing a received MME.
 * 
 * \param  ctx  the CL context
 * \param  mme_recv  user data
 */
typedef void (*cl_mme_recv_done_cb_t) (void *ctx, cl_mme_recv_t *mme_recv);

/**
 * Callback definition used by the CL when the CP had processed the MME
 * in the buffer. This will return the buffer to the upper layer.
 * 
 * \param  user_data  the upper layer user data
 * \param  buffer  the buffer containing the MME.
 */
typedef void (*cl_mme_ul_recv_done_cb_t) (void *user_data, u8 *buffer);

/**
 * Use this callback to provide a received MME to the CP.
 * 
 * \param  user  user daya
 * \param  mfs  the mfs used for the reassembly if MME received from the SAR.
 * \param  buffer  the buffer containing the MME. 
 * \param  length  the MME length
 * \param  mme_recv  private data for the cl_mme.
 * \param  encryption  inform if the MF has been crypted or not when it
 * arrives from the PWL.
 */
typedef void (*cl_mme_recv_cb_t) (void *user, mfs_rx_t *mfs, u8 *buffer,
        uint length, cl_mme_recv_t *mme_recv, bool encryption);

/**
 * Init the Convergence Layer and return a pointer on the CL context.
 * 
 * \param  mac_store  the mac store.
 * \param  sar  the sar context.
 * \param  mac_config  the mac config.
 * \return  the convergence layer context.
 */
cl_t *cl_init (mac_store_t *mac_store, sar_t *sar, mac_config_t *mac_config);

/**
 * Uninit the Convergence layer context.
 * 
 * \param  ctx  the convergence layer context
 */
void cl_uninit (cl_t *ctx);

/**
 * Initialize the CL to call the Upper layer once the CP ends processing the
 * MME.
 * Used each time the CP needs to send an MME to the upper layer.
 * 
 * \param  ctx  the CL context
 * \param  cb  the upper layer callback to use to send an MME.
 * \param  user  the user data to provide with the callback
 */
void cl_mme_ul_init_send_done (cl_t *ctx, cl_mme_ul_recv_done_cb_t cb,
        void *user);

/**
 * Init the function call when an MME is recived from the SAR or the HLE.
 * The CP registers its callback to allow the CL to call it each time a MME
 * is receved from the PLC or the HLE.
 * 
 * \param  ctx  the CL ctx
 * \param  mme_recv_cb
 * \param  user  the user data
 */
void cl_mme_recv_init (cl_t *ctx, cl_mme_recv_cb_t mme_recv_cb, void *user);

/**
 * Initialize the CL to send MMEs to the Upper layer considered as data.
 * Used each time the CP needs to send an MME to the upper layer.
 * 
 * \param  ctx  the CL context
 * \param  cb  the upper layer callback to use to send an MME.
 * \param  user  the user data to provide with the callback
 */
void cl_mme_init_ul_as_data (cl_t *ctx, cl_mme_ul_send_done_cb_t cb, void *user);


/**
 * Initialize the CP call back to get a buffer.
 * 
 * \param  cl  the cl context
 * \param  cb  the call back function
 * \param  user_data  the user data.
 */
void cl_mme_init_buffer_add_cb (cl_t *cl, cl_mme_buffer_add_cb_t cb,
        void *user_data);

/**
 * Send an MME from the CP to the PLC via the SAR MME way.
 * 
 * \param  ctx  the CL context
 * \param  buffer  the buffer containing the MME
 * \param  length  the length of the MME
 * \param  mfs  the MFS use for the SAR if the MME should be send over the PLC
 */
void cl_mme_send_as_mme (cl_t *ctx, u8 *buffer, uint length, mfs_tx_t *mfs);

/**
 * Send an MME as a data packet from the CP to the PLC or to the upper layer.
 * 
 * \param  ctx  the CL context
 * \param  buffer  the buffer containing the MME
 * \param  length  the length of the MME
 */
void cl_mme_send_as_data (cl_t *ctx, u8 *buffer, uint length);

/**
 * Send a MME from the CP to the Upper layer or to the PWL.
 *
 * \param ctx  the cl context.
 * \param  buffer  the buffer containing the data to send.
 * \param  length  the length of the MME.
 * \param  mfs  the mfs to use if necessary.
 */
extern inline void
cl_mme_send (cl_t *ctx, u8 *buffer, uint length, mfs_tx_t *mfs)
{
    dbg_assert (ctx);
    dbg_assert (buffer);

    if (mfs)
        cl_mme_send_as_mme (ctx, buffer, length, mfs);
    else
        cl_mme_send_as_data (ctx, buffer, length);
}

/**
 * Callback called by the sar when a MME as been sent over the PWL.
 * 
 * \param  ctx  the cl context.
 * \param  buffer  the buffer used. 
 */
void cl_mme_sar_send_done (cl_t *ctx, u8 *buffer);

/**
 * Receives an MME from the SAR or the upper layer.
 * This function is called each time the SAR or the HLE has an MME to send to 
 * the CP. It is used by the inline function.
 * When the MFS is NULL the MME received comes from the HLE. Otherwise the MME
 * comes from the SAR. 
 * 
 * \param  ctx  the cl context
 * \param  buffer  the MME buffer
 * \param  length  the MME length
 * \param  mfs  the MFS used in the reassembly process.
 * \param  encryption  if the mac frame comes from the SAR if returns the
 * state of the encryption.
 */
void cl_mme_recv (cl_t *ctx, u8 *buffer, uint length, mfs_rx_t *mfs, bool
                  encryption);

/**
 * Receives an MME from the Upper layer.
 * It will provide this MME to the Control Plane to be processed.
 * 
 * \param  ctx  the cl context
 * \param  buffer  the MME buffer
 * \param  length  the MME length
 */
extern inline void cl_mme_ul_send (cl_t *ctx, u8 *buffer, uint length)
{
    cl_mme_recv (ctx, buffer, length, NULL, false);
}

/**
 * Receives an MME from the SAR.
 * It will provide this MME to the Control Plane to be processed.
 * 
 * \param  ctx  the cl context
 * \param  buffer  the MME buffer
 * \param  length  the MME length
 * \param  mfs  the MFS used by to receive the MME.
 * \param  encryption  boolean informing if the MF was crypted or not.
 */
extern inline void cl_mme_sar_recv (cl_t *ctx, u8 *buffer, uint length,
        mfs_rx_t *mfs, bool encryption)
{
    cl_mme_recv (ctx, buffer, length, mfs, encryption);
}

/**
 * The CP inform the CL that the buffer contaning previously a receved MME can
 * be use again to store another MME if necessary.
 * 
 * \param  ctx  the CL context
 * \param  mme_recv  the data provided on the previous callback.
 */
void cl_mme_recv_done (cl_t *ctx, cl_mme_recv_t *mme_recv);

/**
 * Initialize the callback to inform the upper layer when a data had been sent
 * over the PWL.
 * 
 * \param  cl  the CL context
 * \param  cb  the callback to call once the data had been sent
 * \param  user  the user data to provide with the callback call  
 */
void cl_data_send_done_init (cl_t *cl, cl_data_send_done_cb_t cb, void *user);

/**
 * The SAR inform the CL that the data previously provided had been sent over
 * the PWL.
 * 
 * \param  ctx  the CL context.
 * \param  buffer  the buffer containing the MME
 */
void cl_data_send_done (cl_t *ctx, u8 *buffer);

/**
 * Send a data from the upper layer to the SAR, this data should be sent over
 * the PWL.
 * 
 * \param  cl  the CL context.
 * \param  buffer  the buffer containing the data to send
 * \param  length  the data length
 */
void cl_data_send (cl_t *cl, u8 *buffer, uint length);

/**
 * Initialize the callback to receive the data from the PLC to the upper layer.
 * 
 * \param  cl  the CL context
 * \param  cb  the function callback to call
 * \param  user  the user data to provide on the callback.
 */
void cl_data_recv_init (cl_t *cl, cl_data_recv_cb_t cb, void *user);

/**
 * Called by the SAR each time it has a data to provide to the CL.
 *
 * \param  ctx  the CL context
 * \param  buffer  the buffer containing the data to send to the Upper layer.
 * \param  length  the data length in the buffer
 * \param  mfs  the mfs used to receive the data.
 */
void cl_data_recv (cl_t *ctx, u8 *buffer, uint length, mfs_rx_t *mfs);


/**
 * Provides a buffer to the CP.
 * 
 * \param  cl  the CL context
 * \param  buffer  the buffer to reassembly some datas
 */
void cl_mme_buffer_add (cl_t *cl, u8 *buffer);

/**
 * Provides a buffer to the SAR to reassembly data
 * 
 * \param  cl  the CL context
 * \param  buffer  the buffer to reassembly some datas
 */
void cl_data_buffer_add (cl_t *cl, u8 *buffer);

#endif /* CL_CL_H_ */