2 * Declarations and types for CSN1 dissection in wireshark.
3 * By Vincent Helfre, based on original code by Jari Sassi
4 * with the gracious authorization of STE
5 * Copyright (c) 2011 ST-Ericsson
9 * Wireshark - Network traffic analyzer
10 * By Gerald Combs <gerald@wireshark.org>
11 * Copyright 1998 Gerald Combs
13 * This program is free software; you can redistribute it and/or
14 * modify it under the terms of the GNU General Public License
15 * as published by the Free Software Foundation; either version 2
16 * of the License, or (at your option) any later version.
18 * This program is distributed in the hope that it will be useful,
19 * but WITHOUT ANY WARRANTY; without even the implied warranty of
20 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
21 * GNU General Public License for more details.
23 * You should have received a copy of the GNU General Public License
24 * along with this program; if not, write to the Free Software
25 * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
28 #ifndef _PACKET_CSN1_H_
29 #define _PACKET_CSN1_H_
33 #define CSN_ERROR_GENERAL -1
34 #define CSN_ERROR_DATA_NOT_VALID -2
35 #define CSN_ERROR_IN_SCRIPT -3
36 #define CSN_ERROR_INVALID_UNION_INDEX -4
37 #define CSN_ERROR_NEED_MORE_BITS_TO_UNPACK -5
38 #define CSN_ERROR_ILLEGAL_BIT_VALUE -6
39 #define CSN_ERROR_INTERNAL -7
40 #define CSN_ERROR_STREAM_NOT_SUPPORTED -8
41 #define CSN_ERROR_MESSAGE_TOO_LONG -9
42 #define CSN_ERROR_ -10
44 /* CallBack return status */
45 typedef gint16 CSN_CallBackStatus_t;
48 #define CSNCBS_NOT_OK -10
49 #define CSNCBS_NOT_TO_US -11
50 #define CSNCBS_NOT_COMPLETE -12
52 #define CSNCBS_REVISION_LIMIT_STOP -20 /* Stop packing/unpacking - revision limit */
53 #define CSNCBS_NOT_SUPPORTED_IE -21 /* Handling of the unpacked IE is not supported by MS-software */
58 #define ElementsOf(array) (sizeof(array) / sizeof(array[0]))
61 /* Context holding CSN1 parameters */
64 gint remaining_bits_len; /* IN to an csn stream operation */
65 gint bit_offset; /* IN/OUT to an csn stream operation */
68 typedef gint16 (*StreamSerializeFcn_t)(proto_tree *tree, csnStream_t* ar, tvbuff_t *tvb, void* data, int ett_csn1);
81 CSN_BITMAP, /* Bitmap with constant: <bitmap: bit(64)> */
82 CSN_VARIABLE_BITMAP, /* <N: bit (5)> <bitmap: bit(N + offset)> */
83 CSN_VARIABLE_BITMAP_1, /* <bitmap: bit**> i.e. to the end of message (R99) */
84 CSN_LEFT_ALIGNED_VAR_BMP, /* As variable bitmap but the result is left aligned (R99) */
85 CSN_LEFT_ALIGNED_VAR_BMP_1,/* As above only size is to the end of message (R99) */
86 CSN_PADDING_BITS, /* Padding bits fill to the end of the buffer */
87 CSN_VARIABLE_ARRAY, /* Array with length specified in parameter: <N: bit(4)> <list: octet(N + offset)> */
88 CSN_VARIABLE_TARRAY, /* Type Array with length specified in parameter: <N: bit(x)> <Type>*N */
89 CSN_VARIABLE_TARRAY_OFFSET,/* As above but with offset. The offset is stored as third parameter of CSN_DESCR (descr.value) */
90 CSN_RECURSIVE_ARRAY, /* Recursive way to specify an array of uint: <list> ::= {1 <number: bit(4) <list>|0}; */
91 CSN_RECURSIVE_TARRAY, /* Recursive way to specify an array of type: <list> ::= {1 <type>} ** 0 ; */
92 CSN_RECURSIVE_TARRAY_1, /* same as above but first element always exist:<list> ::= <type> {1 <type>} ** 0 ; */
93 CSN_RECURSIVE_TARRAY_2, /* same as above but with reversed separators :<lists> ::= <type> { 0 <type> } ** 1 ; */
101 CSN_UINT_OFFSET, /* unpack will add offset, inverse pack will subtract offset */
102 CSN_UINT_LH, /* Low High extraction of int */
107 /******************************************************************************************
108 * CSN_DESCR structure:
111 * This is the CSN type. All existing types are specified in the section above.
114 * Depending on the contents of the type parameter, the parameter "i" may have following meaning:
115 * - specifies the number of bits for the CSN_UINT or CSN_UINT_OR_NULL types
116 * - the offset for an array size by which the size is incremented
117 * for the CSN_VAR_ARRAY type
118 * - the length of each element of an array for the CSN_REC_ARRAY type
119 * - the number of the elements in an array for the CSN_TYPE_ARRAY type
120 * - the offset to the variable keeping the number of elements of an array for in the CSN_VAR_TARRAY type
121 * - the number of different data types in a union for the CSN_UNION, CSN_UNION_LH, and for the CSN_CHOICE types
122 * - the length in bits of the fixed number defined for the CSN_FIXED type
123 * - the number of lines to skip in the CSN_DESCR type specified for the CSN_NEXT_EXIST, CSN_NEXT_EXIST_LH,
124 * CSN_NEXT_EXIST_OR_NULL, and CSN_NEXT_EXIST_OR_NULL_LH types
125 * - the number of bits in a bitmap for the CSN_BITMAP type
126 * - the value by which the number of bits in a bitmap has to be incremented or decremented for the
127 * CSN_VAR_BITMAP, CSN_LEFT_VAR_BMP, and CSN_LEFT_BMP_1 types
128 * - the offset to param1 for the CSN_CALLBACK type
129 * - ERRORCODE used by the CSN_ERROR type
130 * - the bit-lngth of the LENGTH field in a CSN_SERIALISE type
133 * This parameter has different meaning depending on the value of the type parameter:
134 * - the offset for the CSN_UINT_OFFSET type
135 * - the number of the elements in an array of the CSN_UINT_ARRAY type
136 * - the offset to the parameter where the size of the array has to be stored for the CSN_REC_ARRAY type
137 * - the address of the internal structure, describing the member type (by means of the CSN_DESCR type) in the
138 * CSN_TYPE_ARRAY, CSN_VAR_TARRAY, and CSN_TYPE types
139 * - the address of the variable of type CSN_ChoiceElement_t describing all elements in the CSN_CHOICE type union
140 * - the offset to the variable where the number of bits has to be or is stored for the CSN_VAR_BITMAP,
141 * CSN_LEFT_VAR_BMP, and CSN_LEFT_BMP_1 types
142 * - the function number (case number) for the CSN_CALLBACK and CSN_CALLBACK_NO_ARGS types
143 * - the free text used by the CSN_TRAP_ERROR
146 * This is an offset to the _MEMBER parameter counting from the beginning of struct
147 * where the unpacked or packed value shall be stored or fetched. The meaning of the _MEMBER parameter
148 * varies depending on the type which is specified and so is the meaning of the offset parameter.
149 * Some types (and corresponding macros) do not have the _MEMBER parameter and then the offset parameter
150 * is not used or is different from the offset to the _MEMBER.
151 * - the fixed value for the CSN_FIXED type
152 * - an offset to the variable UnionType for CSN_UNION and CSN_UNION_LH types
153 * - an offset to the variable Exist for CSN_NEXT_EXIST and CSN_NEXT_EXIST_LH types
154 * - an offset to param2 in the CSN_CALLBACK type
157 * TRUE: if dissection may be attempted at an offset beyond the length of existing data bits
161 * - is the name of the parameter within the descr where their unpacked or packed value shall be stored or fetched.
162 * This paramater is pointed out by the offset parameter in the same CSN_DESCR variable as the sz.
163 * - the free text used by the CSN_TRAP_ERROR (the same as parameter "i")
166 * - stores the size of _MEMBER type in case of the M_TYPE_ARRAY and M_VAR_TARRAY,
167 * - the address of the function which is provided by the M_SERIALIZE type.
168 ******************************************************************************************/
181 gboolean may_be_null;
185 StreamSerializeFcn_t fcn;
197 } CSN_ChoiceElement_t;
199 void csnStreamInit(csnStream_t* ar,gint BitOffset,gint BitCount);
201 /******************************************************************************
202 * FUNCTION: csnStreamDissector
204 * UnPacks data from bit stream. According to CSN description.
206 * ar stream will hold the parameters to the pack function
207 * ar->remaining_bits_len [IN] Number of bits to unpack [OUT] number of bits left to unpack.
208 * ar->bit_offset [IN/OUT] is the current bit where to proceed with the next bit to unpack.
210 * pDescr CSN description.
211 * tvb buffer containing the bit stream to unpack.
212 * data unpacked data.
215 * RETURNS: int Number of bits left to be unpacked. Negative Error code if failed to unpack all bits
216 ******************************************************************************/
217 gint16 csnStreamDissector(proto_tree *tree, csnStream_t* ar, const CSN_DESCR* pDescr, tvbuff_t *tvb, void* data, int ett_csn1);
219 /* CSN struct macro's */
220 #define CSN_DESCR_BEGIN(_STRUCT)\
221 CSN_DESCR CSNDESCR_##_STRUCT[] = {
223 #define CSN_DESCR_END(_STRUCT)\
224 {CSN_END, 0, {0}, 0, FALSE, "", {(StreamSerializeFcn_t)0}} };
226 /******************************************************************************
227 * CSN_ERROR(Par1, Par2, Par3)
228 * May be called at any time when an abort of packing or unpacking of a message
230 * Par1: C structure name
231 * Par2: free text which will appear in the error handler
233 *****************************************************************************/
234 #define CSN_ERROR(_STRUCT, _Text, _ERRCODE)\
235 {CSN_TRAP_ERROR, _ERRCODE, {_Text}, 0, FALSE, _Text, {(StreamSerializeFcn_t)0}}
237 /******************************************************************************
238 * M_BIT(Par1, Par2, Par3)
239 * Defines one bit element in the CSN1 syntax.
240 * Par1: C structure name
241 * Par2: C structure element name
242 * Par3: pointer to the header field
243 *****************************************************************************/
244 #define M_BIT(_STRUCT, _MEMBER, _HF_PTR)\
245 {CSN_BIT, 0, {0}, offsetof(_STRUCT, _MEMBER), FALSE, #_MEMBER, {(StreamSerializeFcn_t) _HF_PTR}}
247 /******************************************************************************
248 * M_BIT_OR_NULL(Par1, Par2, Par3)
249 * Similar to the M_BIT except that not only bit 0 or 1 but also the
250 * end of the message may be encountered when looking for the next element in
252 * Covers the case {null | 0 | 1}
253 *****************************************************************************/
254 #define M_BIT_OR_NULL(_STRUCT, _MEMBER, _HF_PTR)\
255 {CSN_BIT, 0, {0}, offsetof(_STRUCT, _MEMBER), TRUE, #_MEMBER, {(StreamSerializeFcn_t) _HF_PTR}}
256 /******************************************************************************
257 * M_NEXT_EXIST(Par1, Par2, Par3)
258 * Indicates whether the next element or a group of elements defined in the
259 * structure is present or not.
260 * Par1: C structure name
261 * Par2: C structure element name
262 * Par3: number of lines to skip in the CSN_DESCR type specified if the
263 * element(s) does not exist
264 *****************************************************************************/
265 #define M_NEXT_EXIST(_STRUCT, _MEMBER, _NoOfExisting)\
266 {CSN_NEXT_EXIST, _NoOfExisting, {0}, offsetof(_STRUCT, _MEMBER), FALSE, #_MEMBER, {(StreamSerializeFcn_t)0}}
268 /******************************************************************************
269 * M_NEXT_EXIST_LH(Par1, Par2, Par3)
270 * similar to the M_NEXT_EXIST except that instead of bit 0/1 which is fetched
271 * from the message in order to find out whether the next element/elements are
272 * present in the message, the logical operation XOR with the background
273 * pattern 0x2B is performed on the read bit before the decision is made.
274 *****************************************************************************/
275 #define M_NEXT_EXIST_LH(_STRUCT, _MEMBER, _NoOfExisting)\
276 {CSN_NEXT_EXIST_LH, _NoOfExisting, {0}, offsetof(_STRUCT, _MEMBER), FALSE, #_MEMBER, {(StreamSerializeFcn_t)0}}
278 /******************************************************************************
279 * M_NEXT_EXIST_OR_NULL(Par1, Par2, Par3)
280 * Similar to the M_NEXT_EXIST except that not only bit 0 or 1 but also the end
281 * of the message may be encountered when looking for the next element in the
283 * Covers the case {null | 0 | 1 < IE >}
284 *****************************************************************************/
285 #define M_NEXT_EXIST_OR_NULL(_STRUCT, _MEMBER, _NoOfExisting)\
286 {CSN_NEXT_EXIST, _NoOfExisting, {0}, offsetof(_STRUCT, _MEMBER), TRUE, #_MEMBER, {(StreamSerializeFcn_t)0}}
288 /******************************************************************************
289 * M_NEXT_EXIST_OR_NULL_LH(Par1, Par2, Par3)
290 * Similar to the M_NEXT_EXIST_LH except that not only bit 0 or 1 but also the
291 * end of the message may be encountered when looking for the next element in
293 * Covers the case {null | L | H < IE >}
294 *****************************************************************************/
295 #define M_NEXT_EXIST_OR_NULL_LH(_STRUCT, _MEMBER, _NoOfExisting)\
296 {CSN_NEXT_EXIST_LH, _NoOfExisting, {(void*)1}, offsetof(_STRUCT, _MEMBER), TRUE, #_MEMBER, {(StreamSerializeFcn_t)0}}
298 /******************************************************************************
299 * M_UINT(Par1, Par2, Par3, Par4)
300 * Defines an integer number.
301 * Par1: C structure name
302 * Par2: C structure element name
303 * Par3: number of bits used to code the element (between 1 and 32)
304 * Par4: pointer to the header field
305 *****************************************************************************/
306 #define M_UINT(_STRUCT, _MEMBER, _BITS, _HF_PTR)\
307 {CSN_UINT, _BITS, {0}, offsetof(_STRUCT, _MEMBER), FALSE, #_MEMBER, {(StreamSerializeFcn_t) _HF_PTR}}
309 /******************************************************************************
310 * M_UINT_OR_NULL(Par1, Par2, Par3, Par4)
311 * Similar to the M_UINT except that not only the request set of bits but also the
312 * end of the message may be encountered when looking for the next element in
314 * Covers the case {null | 0 | 1 < IE >}
315 *****************************************************************************/
316 #define M_UINT_OR_NULL(_STRUCT, _MEMBER, _BITS, _HF_PTR)\
317 {CSN_UINT, _BITS, {0}, offsetof(_STRUCT, _MEMBER), TRUE, #_MEMBER, {(StreamSerializeFcn_t) _HF_PTR}}
319 /******************************************************************************
320 * M_UINT_LH(Par1, Par2, Par3, Par4)
321 * This macro has the same functionality as M_UINT except that in addition the
322 * logical "exclusive or" operation with the background value "0x2B" is
323 * performed before the final value of the integer number is delivered from the
324 * received CSN.1 message
325 *****************************************************************************/
326 #define M_UINT_LH(_STRUCT, _MEMBER, _BITS, _HF_PTR)\
327 {CSN_UINT_LH, _BITS, {0}, offsetof(_STRUCT, _MEMBER), FALSE, #_MEMBER, {(StreamSerializeFcn_t) _HF_PTR}}
329 /******************************************************************************
330 * M_UINT_OFFSET(Par1, Par2, Par3, Par4)
331 * Defines an integer number.
332 * Par1: C structure name
333 * Par2: C structure element name
334 * Par3: number of bits used to code the element (between 1 and 32)
335 * Par4: value added to the returned integer (offset)
336 *****************************************************************************/
337 #define M_UINT_OFFSET(_STRUCT, _MEMBER, _BITS, _OFFSET)\
338 {CSN_UINT_OFFSET, _BITS, {(void*)_OFFSET}, offsetof(_STRUCT, _MEMBER), FALSE, #_MEMBER, {(StreamSerializeFcn_t)0}}
340 /******************************************************************************
341 * M_UINT_ARRAY(Par1, Par2, Par3, Par4)
342 * Defines an array of integer numbers. The size of the array is fixed.
343 * Par1: C structure name
344 * Par2: C structure element name
345 * Par3: number of bits used to code the each integer element (between 1 and 32)
346 * Par4: number of elements in the array (fixed integer value)
347 *****************************************************************************/
348 #define M_UINT_ARRAY(_STRUCT, _MEMBER, _BITS, _ElementCount)\
349 {CSN_UINT_ARRAY, _BITS, {(void*)_ElementCount}, offsetof(_STRUCT, _MEMBER), FALSE, #_MEMBER, {(StreamSerializeFcn_t)0}}
351 /******************************************************************************
352 * M_VAR_UINT_ARRAY(Par1, Par2, Par3, Par4)
353 * Defines an array of integer numbers. The size of the array is variable.
354 * Par1: C structure name
355 * Par2: C structure element name
356 * Par3: number of bits used to code the each integer element (between 1 and 32)
357 * Par4: number of elements in the array supplied by reference to the
358 * structure member holding the length value
359 *****************************************************************************/
360 #define M_VAR_UINT_ARRAY(_STRUCT, _MEMBER, _BITS, _ElementCountField)\
361 {CSN_UINT_ARRAY, _BITS, {(void*)offsetof(_STRUCT, _ElementCountField)}, offsetof(_STRUCT, _MEMBER), FALSE, #_MEMBER, {(StreamSerializeFcn_t)1}}
363 /******************************************************************************
364 * M_VAR_ARRAY(Par1, Par2, Par3, Par4)
365 * Defines an array of 8 bit large integer numbers. The size of the array is variable.
366 * Par1: C structure name
367 * Par2: C structure element name
368 * Par3: name of the structure member holding the size of the array
369 * Par4: offset that is added to the Par3 to get the actual size of the array
370 *****************************************************************************/
371 #define M_VAR_ARRAY(_STRUCT, _MEMBER, _ElementCountField, _OFFSET)\
372 {CSN_VARIABLE_ARRAY, _OFFSET, {(void*)offsetof(_STRUCT, _ElementCountField)}, offsetof(_STRUCT, _MEMBER), FALSE, #_MEMBER, {(StreamSerializeFcn_t)0}}
374 /******************************************************************************
375 * M_VAR_TARRAY(Par1, Par2, Par3, Par4)
376 * Similar to M_TYPE_ARRAY except that the size of the array is variable.
377 * Par1: C structure name
378 * Par2: C structure element name
379 * Par3: the type of each element of the array
380 * Par4: name of the structure member holding the size of the array
381 *****************************************************************************/
382 #define M_VAR_TARRAY(_STRUCT, _MEMBER, _MEMBER_TYPE, _ElementCountField)\
383 {CSN_VARIABLE_TARRAY, offsetof(_STRUCT, _ElementCountField), {(void*)CSNDESCR_##_MEMBER_TYPE}, offsetof(_STRUCT, _MEMBER), FALSE, #_MEMBER, {(StreamSerializeFcn_t)sizeof(_MEMBER_TYPE)}}
385 /******************************************************************************
386 * M_VAR_TARRAY_OFFSET(Par1, Par2, Par3, Par4)
387 * Same as M_VAR_TARRAY with offset
388 *****************************************************************************/
389 #define M_VAR_TARRAY_OFFSET(_STRUCT, _MEMBER, _MEMBER_TYPE, _ElementCountField)\
390 {CSN_VARIABLE_TARRAY_OFFSET, offsetof(_STRUCT, _ElementCountField), {(void*)CSNDESCR_##_MEMBER_TYPE}, offsetof(_STRUCT, _MEMBER), FALSE, #_MEMBER, {(StreamSerializeFcn_t)sizeof(_MEMBER_TYPE)}}
392 /******************************************************************************
393 * M_REC_ARRAY(Par1, Par2, Par3, Par4)
394 * similar to the M_VAR_ARRAY. The difference is that the size of the array is
395 * not known in advance and it has to be calculated during unpacking. Its value
396 * is stored in a variable which belongs to the same structure as the array.
397 * A zero element terminates the array. The CSN.1 syntax describes it
399 * <array> ::={1 <element> <array>| 0}
401 * Par1: C structure name
402 * Par2: C structure element name
403 * Par3: name of the structure member where the calculated the size of the
404 * array will be stored
405 * Par4: length of each element in bits
406 *****************************************************************************/
407 #define M_REC_ARRAY(_STRUCT, _MEMBER, _ElementCountField, _BITS)\
408 {CSN_RECURSIVE_ARRAY, _BITS, {(void*)offsetof(_STRUCT, _ElementCountField)}, offsetof(_STRUCT, _MEMBER), FALSE, #_MEMBER, {(StreamSerializeFcn_t)0}}
410 /******************************************************************************
411 * M_VAR_TYPE_ARRAY(Par1, Par2, Par3, Par4)
412 * Defines an array of structures. The size of the array is variable.
413 * Par1: C structure name
414 * Par2: C structure element name
415 * Par3: name of the structure
416 * Par4: number of elements in the array (fixed integer value)
417 *****************************************************************************/
418 #define M_TYPE_ARRAY(_STRUCT, _MEMBER, _MEMBER_TYPE, _ElementCount)\
419 {CSN_TYPE_ARRAY, _ElementCount, {(void*)CSNDESCR_##_MEMBER_TYPE}, offsetof(_STRUCT, _MEMBER), FALSE, #_MEMBER, {(StreamSerializeFcn_t)sizeof(_MEMBER_TYPE)}}
421 /******************************************************************************
422 * M_REC_TARRAY(Par1, Par2, Par3, Par4)
423 * Defines an recursive array of structures. The size of the array is variable.
424 * <list> ::= {1 <type>} ** 0 ;
425 * Par1: C structure name
426 * Par2: C structure element name
427 * Par3: name of the structure
428 * Par4: will hold the number of element in the array after unpacking
429 *****************************************************************************/
430 #define M_REC_TARRAY(_STRUCT, _MEMBER, _MEMBER_TYPE, _ElementCountField)\
431 {CSN_RECURSIVE_TARRAY, offsetof(_STRUCT, _ElementCountField), {(void*)CSNDESCR_##_MEMBER_TYPE}, offsetof(_STRUCT, _MEMBER), FALSE, #_MEMBER, {(StreamSerializeFcn_t)sizeof(_MEMBER_TYPE)}}
433 /******************************************************************************
434 * M_REC_TARRAY1(Par1, Par2, Par3, Par4)
435 * Same as M_REC_TARRAY but first element always exist:
436 * <list> ::= <type> {1 <type>} ** 0 ;
437 *****************************************************************************/
438 #define M_REC_TARRAY_1(_STRUCT, _MEMBER, _MEMBER_TYPE, _ElementCountField)\
439 {CSN_RECURSIVE_TARRAY_1, offsetof(_STRUCT, _ElementCountField), {(void*)CSNDESCR_##_MEMBER_TYPE}, offsetof(_STRUCT, _MEMBER), FALSE, #_MEMBER, {(StreamSerializeFcn_t)sizeof(_MEMBER_TYPE)}}
441 /******************************************************************************
442 * M_REC_TARRAY2(Par1, Par2, Par3, Par4)
443 * Same as M_REC_TARRAY but with reversed separators :
444 * <lists> ::= <type> { 0 <type> } ** 1 ;
445 *****************************************************************************/
446 #define M_REC_TARRAY_2(_STRUCT, _MEMBER, _MEMBER_TYPE, _ElementCountField)\
447 {CSN_RECURSIVE_TARRAY_2, offsetof(_STRUCT, _ElementCountField), {(void*)CSNDESCR_##_MEMBER_TYPE}, offsetof(_STRUCT, _MEMBER), FALSE, #_MEMBER, {(StreamSerializeFcn_t)sizeof(_MEMBER_TYPE)}}
449 /******************************************************************************
450 * M_TYPE(Par1, Par2, Par3)
451 * Defines a reference to a structure which is described elsewhere
452 * <list> ::= {1 <type>} ** 0 ;
453 * Par1: C structure name
454 * Par2: C structure element name
455 * Par3: type of member
456 *****************************************************************************/
457 #define M_TYPE(_STRUCT, _MEMBER, _MEMBER_TYPE)\
458 {CSN_TYPE, 0, {(void*)CSNDESCR_##_MEMBER_TYPE}, offsetof(_STRUCT, _MEMBER), FALSE, #_MEMBER, {(StreamSerializeFcn_t)0}}
460 /******************************************************************************
461 * M_TYPE_LABEL(Par1, Par2, Par3, Par4)
462 * Same as M_TYPE but allows to define a custom string for the subtree
463 * <list> ::= {1 <type>} ** 0 ;
464 * Par1: C structure name
465 * Par2: C structure element name
466 * Par3: type of member
467 * Par4: C string for the text
468 *****************************************************************************/
469 #define M_TYPE_LABEL(_STRUCT, _MEMBER, _MEMBER_TYPE, _LABEL)\
470 {CSN_TYPE, 0, {(void*)CSNDESCR_##_MEMBER_TYPE}, offsetof(_STRUCT, _MEMBER), FALSE, _LABEL, {(StreamSerializeFcn_t)0}}
472 /******************************************************************************
473 * M_UNION(Par1, Par2)
474 * Informs the CSN.1 library that a union follows and how many possible choices
475 * there are in the union. The actual value of the choice, which points out the
476 * chosen element of the union is stored in the uint8 variable and is usually
477 * called UnionType. The elements of the union have to be listed directly after
478 * the M_UNION statement.
479 * Par1: C structure name
480 * Par2: number of possible choice in the union
481 *****************************************************************************/
482 #define M_UNION(_STRUCT, _COUNT)\
483 {CSN_UNION, _COUNT, {0}, offsetof(_STRUCT, UnionType), FALSE, "UnionType", {(StreamSerializeFcn_t)0}}
485 /******************************************************************************
486 * M_UNION_LH(Par1, Par2)
487 * Same as M_UNION but masked with background value 0x2B
488 *****************************************************************************/
489 #define M_UNION_LH(_STRUCT, _COUNT)\
490 {CSN_UNION_LH, _COUNT, {0}, offsetof(_STRUCT, UnionType), FALSE, "UnionType", {(StreamSerializeFcn_t)0}}
492 /******************************************************************************
493 * M_CHOICE(Par1, Par2, Par3, Par4)
494 * Similar to the M_UNION. In the M_UNION the selected element of all possible
495 * choices in the union is referred as a sequential numbers, i.e., the first
496 * choice is addressed as choice 0 the second as choice 1, the third as choice
497 * 2 and so on, both in the encoded message and in the variable UnionType which
498 * is the part of the message. In the CSN_CHOICE case, this rule does not
499 * apply. There is free but predefined mapping of the element of the union and
500 * the value which addresses this element.
501 * The value of the address is called a selector.
502 * After unpacking, this value is then converted to the sequential number of the
503 * element in the union and stored in the UnionType variable.
504 * Par1: C structure name
505 * Par2: C structure element name
506 * Par3: address of an array of type CSN_ChoiceElement_t where all possible
507 * values of the selector are provided, together with the selector
508 * length expressed in bits and the address of the CSN_DESCR type
509 * where the element is defined. For every element in the union
510 * there is one line in the Choice variable. These lines have to
511 * appear in the _CHOICE in the same order as the elements in the
512 * union. The element of the union selected in the message through
513 * the _CHOICE parameter is after unpacking translated to the
514 * corresponding sequential number of this element and stored in
515 * the variable pointed out by the _MEMBER
516 * Par4: number of possible choices in the union
517 *****************************************************************************/
518 #define M_CHOICE(_STRUCT, _MEMBER, _CHOICE, _ElementCount)\
519 {CSN_CHOICE, _ElementCount, {(void*)_CHOICE}, offsetof(_STRUCT, _MEMBER), FALSE, #_CHOICE, {(StreamSerializeFcn_t)0}}
521 /******************************************************************************
522 * M_CHOICE_IL(Par1, Par2, Par3, Par4)
523 * See M_CHOICE above, but displayed inline (i.e. no specific elements are
524 * displayed to show there was a choice
525 *****************************************************************************/
526 #define M_CHOICE_IL(_STRUCT, _MEMBER, _CHOICE, _ElementCount)\
527 {CSN_CHOICE, _ElementCount, {(void*)_CHOICE}, offsetof(_STRUCT, _MEMBER), FALSE, NULL, {(StreamSerializeFcn_t)0}}
529 /******************************************************************************
530 * M_FIXED(Par1, Par2, Par3)
531 * Defines a fixed value of type integer which should be fetched from or stored
533 * Par1: C structure name
534 * Par2: gives the length of the fixed number in bits.
535 * Par3: the value of the number. If the expected value is not present in
536 * the message the unpacking procedure is aborted
537 *****************************************************************************/
538 #define M_FIXED(_STRUCT, _BITS, _BITVALUE)\
539 {CSN_FIXED, _BITS, {0}, _BITVALUE, FALSE, #_BITVALUE, {(StreamSerializeFcn_t)0}}
541 /******************************************************************************
542 * M_FIXED_LABEL(Par1, Par2, Par3, Par4)
543 * Same as M_FIXED but allows to define a custom string for the subtree
544 * Par1: C structure name
545 * Par2: gives the length of the fixed number in bits.
546 * Par3: the value of the number. If the expected value is not present in
547 * the message the unpacking procedure is aborted
548 * Par4: C string for the text
549 *****************************************************************************/
550 #define M_FIXED_LABEL(_STRUCT, _BITS, _BITVALUE, _LABEL)\
551 {CSN_FIXED, _BITS, {0}, _BITVALUE, FALSE, _LABEL, {(StreamSerializeFcn_t)0}}
553 /******************************************************************************
554 * M_SERIALIZE(Par1, Par2, Par3)
555 * Allows using a complete free format of data being encoded or decoded.
556 * When the M_SERIALIZE is encounted during encoding or decoding of a message
557 * the CSNstream program passes the control over to the specified function
558 * together with all necessary parameters about the current position within
559 * the message being unpacked or packed. When transferring of "serialized"
560 * data to or from the message is finished by the function the CSNstream gets
561 * back control over the data stream and continues to work with the message.
562 *****************************************************************************/
563 #define M_SERIALIZE(_STRUCT, _MEMBER, _LENGTH_LEN, _SERIALIZEFCN)\
564 {CSN_SERIALIZE, _LENGTH_LEN, {0}, offsetof(_STRUCT, _MEMBER), FALSE, #_MEMBER, {_SERIALIZEFCN}}
566 #define M_CALLBACK(_STRUCT, _CSNCALLBACKFCN, _PARAM1, _PARAM2)\
567 {CSN_CALLBACK, offsetof(_STRUCT, _PARAM1), {_CSNCALLBACKFCN}, offsetof(_STRUCT, _PARAM2), FALSE, "CallBack_"#_CSNCALLBACKFCN, {(StreamSerializeFcn_t)0}}
569 /******************************************************************************
570 * M_BITMAP(Par1, Par2, Par3)
571 * Defines a type which consists of a bitmap. The size of the bitmap in bits
572 * is fixed and provided by the parameter Par3
573 * Par1: C structure name
574 * Par2: C structure element name
575 * Par3: length of the bitmap expressed in bits
576 *****************************************************************************/
577 #define M_BITMAP(_STRUCT, _MEMBER, _BITS)\
578 {CSN_BITMAP, _BITS, {0}, offsetof(_STRUCT, _MEMBER), FALSE, #_MEMBER, {(StreamSerializeFcn_t)0}}
580 /* variable length, right aligned bitmap i.e. _ElementCountField = 11 => 00000111 11111111 */
581 #define M_VAR_BITMAP(_STRUCT, _MEMBER, _ElementCountField, _OFFSET)\
582 {CSN_VARIABLE_BITMAP, _OFFSET, {(void*)offsetof(_STRUCT, _ElementCountField)}, offsetof(_STRUCT, _MEMBER), FALSE, #_MEMBER, {(StreamSerializeFcn_t)0}}
584 /* variable length, right aligned bitmap filling the rest of message
585 * - when unpacking the _ElementCountField will be set in runtime
586 * - when packing _ElementCountField contains the size of bitmap
588 #define M_VAR_BITMAP_1(_STRUCT, _MEMBER, _ElementCountField, _OFFSET)\
589 {CSN_VARIABLE_BITMAP_1, _OFFSET, {(void*)offsetof(_STRUCT, _ElementCountField)}, offsetof(_STRUCT, _MEMBER), FALSE, #_MEMBER, {(StreamSerializeFcn_t)0}}
591 /* variable length, left aligned bitmap i.e. _ElementCountField = 11 => 11111111 11100000 */
592 #define M_LEFT_VAR_BMP(_STRUCT, _MEMBER, _ElementCountField, _OFFSET)\
593 {CSN_LEFT_ALIGNED_VAR_BMP, _OFFSET, {(void*)offsetof(_STRUCT, _ElementCountField)}, offsetof(_STRUCT, _MEMBER), FALSE, #_MEMBER, {(StreamSerializeFcn_t)0}}
595 /* variable length, left aligned bitmap filling the rest of message
596 *- when unpacking the _ElementCountField will be set in runtime
597 * - when packing _ElementCountField contains the size of bitmap
599 #define M_LEFT_VAR_BMP_1(_STRUCT, _MEMBER, _ElementCountField, _OFFSET)\
600 {CSN_LEFT_ALIGNED_VAR_BMP_1, _OFFSET, {(void*)offsetof(_STRUCT, _ElementCountField)}, offsetof(_STRUCT, _MEMBER), FALSE, #_MEMBER, {(StreamSerializeFcn_t)0}}
602 /* todo: dissect padding bits looking for unexpected extensions */
603 #define M_PADDING_BITS(_STRUCT)\
604 {CSN_PADDING_BITS, 0, {0}, 0, TRUE, "Padding", {(StreamSerializeFcn_t)0}}
606 #define M_NULL(_STRUCT, _MEMBER)\
607 {CSN_NULL, 0, {0}, offsetof(_STRUCT, _MEMBER), FALSE, #_MEMBER, {(StreamSerializeFcn_t)0}}
609 #define M_THIS_EXIST(_STRUCT)\
610 {CSN_EXIST, 0, {0}, offsetof(_STRUCT, Exist), FALSE, "Exist", {(StreamSerializeFcn_t)0}}
612 #define M_THIS_EXIST_LH(_STRUCT)\
613 {CSN_EXIST_LH, 0, {0}, offsetof(_STRUCT, Exist), FALSE, "Exist", {(StreamSerializeFcn_t)0}}
615 /* return value 0 if ok else discontionue the unpacking */
616 typedef gint16 (*CsnCallBackFcn_t)(void* pv ,...);
618 #define CSNDESCR(_FuncType) CSNDESCR_##_FuncType
620 #endif /*_PACKET_CSN1_H_*/