Wireshark  4.3.0
The Wireshark network protocol analyzer
packet-csn1.h
1 /* packet-csn1.h
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
6  *
7  * Wireshark - Network traffic analyzer
8  * By Gerald Combs <gerald@wireshark.org>
9  * Copyright 1998 Gerald Combs
10  *
11  * SPDX-License-Identifier: GPL-2.0-or-later
12  */
13 
14 #ifndef _PACKET_CSN1_H_
15 #define _PACKET_CSN1_H_
16 
17 #include <epan/expert.h>
18 
19 /* Error codes */
20 #define CSN_OK 0
21 #define CSN_ERROR_GENERAL -1
22 #define CSN_ERROR_DATA_NOT_VALID -2
23 #define CSN_ERROR_IN_SCRIPT -3
24 #define CSN_ERROR_INVALID_UNION_INDEX -4
25 #define CSN_ERROR_NEED_MORE_BITS_TO_UNPACK -5
26 #define CSN_ERROR_ILLEGAL_BIT_VALUE -6
27 #define CSN_ERROR_INTERNAL -7
28 #define CSN_ERROR_STREAM_NOT_SUPPORTED -8
29 #define CSN_ERROR_MESSAGE_TOO_LONG -9
30 #define CSN_ERROR_ -10
31 
32 /* CallBack return status */
33 typedef gint16 CSN_CallBackStatus_t;
34 
35 #define CSNCBS_OK 0
36 #define CSNCBS_NOT_OK -10
37 #define CSNCBS_NOT_TO_US -11
38 #define CSNCBS_NOT_COMPLETE -12
39 
40 #define CSNCBS_REVISION_LIMIT_STOP -20 /* Stop packing/unpacking - revision limit */
41 #define CSNCBS_NOT_SUPPORTED_IE -21 /* Handling of the unpacked IE is not supported by MS-software */
42 
43 typedef void(*void_fn_t)(void);
44 
45 /* Context holding CSN1 parameters */
46 typedef struct
47 {
48  gint remaining_bits_len; /* IN to an csn stream operation */
49  gint bit_offset; /* IN/OUT to an csn stream operation */
50  packet_info* pinfo;
51 } csnStream_t;
52 
53 typedef gint16 (*StreamSerializeFcn_t)(proto_tree *tree, csnStream_t* ar, tvbuff_t *tvb, void* data, int ett_csn1);
54 typedef CSN_CallBackStatus_t (*DissectorCallbackFcn_t)(proto_tree *tree, tvbuff_t *tvb, void* param1, void* param2, int bit_offset, int ett_csn1, packet_info* pinfo);
55 
56 
57 typedef enum
58 {
59  CSN_END = 0,
60  CSN_BIT,
61  CSN_UINT,
62  CSN_TYPE,
63  CSN_CHOICE,
64  CSN_UNION,
65  CSN_UNION_LH,
66  CSN_UINT_ARRAY,
67  CSN_TYPE_ARRAY,
68  CSN_BITMAP, /* Bitmap with constant: <bitmap: bit(64)> */
69  CSN_VARIABLE_BITMAP, /* <N: bit (5)> <bitmap: bit(N + offset)> */
70  CSN_VARIABLE_BITMAP_1, /* <bitmap: bit**> i.e. to the end of message (R99) */
71  CSN_LEFT_ALIGNED_VAR_BMP, /* As variable bitmap but the result is left aligned (R99) */
72  CSN_LEFT_ALIGNED_VAR_BMP_1,/* As above only size is to the end of message (R99) */
73  CSN_PADDING_BITS, /* Padding bits fill to the end of the buffer */
74  CSN_VARIABLE_ARRAY, /* Array with length specified in parameter: <N: bit(4)> <list: octet(N + offset)> */
75  CSN_VARIABLE_TARRAY, /* Type Array with length specified in parameter: <N: bit(x)> <Type>*N */
76  CSN_VARIABLE_TARRAY_OFFSET,/* As above but with offset. The offset is stored as third parameter of CSN_DESCR (descr.value) */
77  CSN_RECURSIVE_ARRAY, /* Recursive way to specify an array of uint: <list> ::= {1 <number: bit(4) <list>|0}; */
78  CSN_RECURSIVE_TARRAY, /* Recursive way to specify an array of type: <list> ::= {1 <type>} ** 0 ; */
79  CSN_RECURSIVE_TARRAY_1, /* same as above but first element always exist:<list> ::= <type> {1 <type>} ** 0 ; */
80  CSN_RECURSIVE_TARRAY_2, /* same as above but with reversed separators :<lists> ::= <type> { 0 <type> } ** 1 ; */
81  CSN_EXIST,
82  CSN_EXIST_LH,
83  CSN_NEXT_EXIST,
84  CSN_NEXT_EXIST_LH,
85  CSN_NULL,
86  CSN_FIXED,
87  CSN_CALLBACK,
88  CSN_UINT_OFFSET, /* unpack will add offset, inverse pack will subtract offset */
89  CSN_UINT_LH, /* Low High extraction of int */
90  CSN_SERIALIZE,
91  CSN_SPLIT_BITS,
92  CSN_SPLIT_BITS_CRUMB,
93  CSN_TRAP_ERROR
94 } csn_type_t;
95 
96 /******************************************************************************************
97  * CSN_DESCR structure:
98  *
99  * type:
100  * This is the CSN type. All existing types are specified in the section above.
101  *
102  * i:
103  * Depending on the contents of the type parameter, the parameter "i" may have following meaning:
104  * - specifies the number of bits for the CSN_UINT or CSN_UINT_OR_NULL types
105  * - the offset for an array size by which the size is incremented
106  * for the CSN_VAR_ARRAY type
107  * - the length of each element of an array for the CSN_REC_ARRAY type
108  * - the number of the elements in an array for the CSN_TYPE_ARRAY type
109  * - the offset to the variable keeping the number of elements of an array for in the CSN_VAR_TARRAY type
110  * - the number of different data types in a union for the CSN_UNION, CSN_UNION_LH, and for the CSN_CHOICE types
111  * - the length in bits of the fixed number defined for the CSN_FIXED type
112  * - the number of lines to skip in the CSN_DESCR type specified for the CSN_NEXT_EXIST, CSN_NEXT_EXIST_LH,
113  * CSN_NEXT_EXIST_OR_NULL, and CSN_NEXT_EXIST_OR_NULL_LH types
114  * - the number of bits in a bitmap for the CSN_BITMAP type
115  * - the value by which the number of bits in a bitmap has to be incremented or decremented for the
116  * CSN_VAR_BITMAP, CSN_LEFT_VAR_BMP, and CSN_LEFT_BMP_1 types
117  * - the offset to param1 for the CSN_CALLBACK type
118  * - ERRORCODE used by the CSN_ERROR type
119  * - the bit-length of the LENGTH field in a CSN_SERIALISE type
120  *
121  * descr
122  * This parameter has different meaning depending on the value of the type parameter:
123  * - the offset for the CSN_UINT_OFFSET type
124  * - the number of the elements in an array of the CSN_UINT_ARRAY type
125  * - the offset to the parameter where the size of the array has to be stored for the CSN_REC_ARRAY type
126  * - the address of the internal structure, describing the member type (by means of the CSN_DESCR type) in the
127  * CSN_TYPE_ARRAY, CSN_VAR_TARRAY, and CSN_TYPE types
128  * - the address of the variable of type CSN_ChoiceElement_t describing all elements in the CSN_CHOICE type union
129  * - the offset to the variable where the number of bits has to be or is stored for the CSN_VAR_BITMAP,
130  * CSN_LEFT_VAR_BMP, and CSN_LEFT_BMP_1 types
131  * - the function number (case number) for the CSN_CALLBACK and CSN_CALLBACK_NO_ARGS types
132  * - the free text used by the CSN_TRAP_ERROR
133  *
134  * offset
135  * This is an offset to the _MEMBER parameter counting from the beginning of struct
136  * where the unpacked or packed value shall be stored or fetched. The meaning of the _MEMBER parameter
137  * varies depending on the type which is specified and so is the meaning of the offset parameter.
138  * Some types (and corresponding macros) do not have the _MEMBER parameter and then the offset parameter
139  * is not used or is different from the offset to the _MEMBER.
140  * - the fixed value for the CSN_FIXED type
141  * - an offset to the variable UnionType for CSN_UNION and CSN_UNION_LH types
142  * - an offset to the variable Exist for CSN_NEXT_EXIST and CSN_NEXT_EXIST_LH types
143  * - an offset to param2 in the CSN_CALLBACK type
144  *
145  * may_be_null
146  * TRUE: if dissection may be attempted at an offset beyond the length of existing data bits
147  * FALSE: othewise
148  *
149  * sz
150  * - is the name of the parameter within the descr where their unpacked or packed value shall be stored or fetched.
151  * This paramater is pointed out by the offset parameter in the same CSN_DESCR variable as the sz.
152  * - the free text used by the CSN_TRAP_ERROR (the same as parameter "i")
153  *
154  * serialize
155  * - stores the size of _MEMBER type in case of the M_TYPE_ARRAY and M_VAR_TARRAY,
156  * - the address of the function which is provided by the M_SERIALIZE type.
157  ******************************************************************************************/
158 
159 
160 typedef struct
161 {
162  gint16 type;
163  gint16 i;
164  union
165  {
166  const void* ptr;
167  guint32 value;
168  const crumb_spec_t *crumb_spec;
169  } descr;
170  size_t offset;
171  gboolean may_be_null;
172  const char* sz;
173  expert_field* error;
174  guint32 value;
175  int* hf_ptr;
176  /* used in M_REC_ARRAY to distinguish between "field" and "field exists",
177  it's not used on fields that just "exist" */
178  int* hf_exist_ptr;
179  void_fn_t aux_fn;
180 } CSN_DESCR;
181 
182 typedef struct
183 {
184  guint8 bits;
185  guint8 value;
186  gboolean keep_bits;
187  CSN_DESCR descr;
189 
190 void csnStreamInit(csnStream_t* ar, gint BitOffset, gint BitCount, packet_info* pinfo);
191 
192 /******************************************************************************
193 * FUNCTION: csnStreamDissector
194 * DESCRIPTION:
195 * UnPacks data from bit stream. According to CSN description.
196 * ARGS:
197 * ar stream will hold the parameters to the pack function
198 * ar->remaining_bits_len [IN] Number of bits to unpack [OUT] number of bits left to unpack.
199 * ar->bit_offset [IN/OUT] is the current bit where to proceed with the next bit to unpack.
200 
201 * pDescr CSN description.
202 * tvb buffer containing the bit stream to unpack.
203 * data unpacked data.
204 * ett_csn1 tree
205 *
206 * RETURNS: int Number of bits left to be unpacked. Negative Error code if failed to unpack all bits
207 ******************************************************************************/
208 gint16 csnStreamDissector(proto_tree *tree, csnStream_t* ar, const CSN_DESCR* pDescr, tvbuff_t *tvb, void* data, int ett_csn1);
209 
210 /* CSN struct macro's */
211 #define CSN_DESCR_BEGIN(_STRUCT)\
212  CSN_DESCR CSNDESCR_##_STRUCT[] = {
213 
214 #define CSN_DESCR_END(_STRUCT)\
215  {CSN_END, 0, {0}, 0, FALSE, "", NULL, 0, NULL, NULL, NULL} };
216 
217 /******************************************************************************
218  * CSN_ERROR(Par1, Par2, Par3)
219  * May be called at any time when an abort of packing or unpacking of a message
220  * is desired
221  * Par1: C structure name
222  * Par2: free text which will appear in the error handler
223  * Par3: Error code
224  *****************************************************************************/
225 #define CSN_ERROR(_STRUCT, _Text, _ERRCODE, _EI_ERROR)\
226  {CSN_TRAP_ERROR, _ERRCODE, {_Text}, 0, FALSE, _Text, _EI_ERROR, 0, NULL, NULL, NULL}
227 
228 /******************************************************************************
229  * M_BIT(Par1, Par2, Par3)
230  * Defines one bit element in the CSN1 syntax.
231  * Par1: C structure name
232  * Par2: C structure element name
233  * Par3: pointer to the header field
234  *****************************************************************************/
235 #define M_BIT(_STRUCT, _MEMBER, _HF_PTR)\
236  {CSN_BIT, 0, {0}, offsetof(_STRUCT, _MEMBER), FALSE, #_MEMBER, NULL, 0, _HF_PTR, NULL, NULL}
237 
238 /******************************************************************************
239  * M_BIT_OR_NULL(Par1, Par2, Par3)
240  * Similar to the M_BIT except that not only bit 0 or 1 but also the
241  * end of the message may be encountered when looking for the next element in
242  * the message.
243  * Covers the case {null | 0 | 1}
244  *****************************************************************************/
245 #define M_BIT_OR_NULL(_STRUCT, _MEMBER, _HF_PTR)\
246  {CSN_BIT, 0, {0}, offsetof(_STRUCT, _MEMBER), TRUE, #_MEMBER, NULL, 0, _HF_PTR, NULL, NULL}
247 /******************************************************************************
248  * M_NEXT_EXIST(Par1, Par2, Par3)
249  * Indicates whether the next element or a group of elements defined in the
250  * structure is present or not.
251  * Par1: C structure name
252  * Par2: C structure element name
253  * Par3: number of lines to skip in the CSN_DESCR type specified if the
254  * element(s) does not exist
255  *****************************************************************************/
256 #define M_NEXT_EXIST(_STRUCT, _MEMBER, _NoOfExisting, _HF_PTR)\
257  {CSN_NEXT_EXIST, _NoOfExisting, {0}, offsetof(_STRUCT, _MEMBER), FALSE, #_MEMBER, NULL, 0, _HF_PTR, NULL, NULL}
258 
259 /******************************************************************************
260  * M_NEXT_EXIST_LH(Par1, Par2, Par3)
261  * similar to the M_NEXT_EXIST except that instead of bit 0/1 which is fetched
262  * from the message in order to find out whether the next element/elements are
263  * present in the message, the logical operation XOR with the background
264  * pattern 0x2B is performed on the read bit before the decision is made.
265  *****************************************************************************/
266 #define M_NEXT_EXIST_LH(_STRUCT, _MEMBER, _NoOfExisting, _HF_PTR)\
267  {CSN_NEXT_EXIST_LH, _NoOfExisting, {0}, offsetof(_STRUCT, _MEMBER), FALSE, #_MEMBER, NULL, 0, _HF_PTR, NULL, NULL}
268 
269 /******************************************************************************
270  * M_NEXT_EXIST_OR_NULL(Par1, Par2, Par3)
271  * Similar to the M_NEXT_EXIST except that not only bit 0 or 1 but also the end
272  * of the message may be encountered when looking for the next element in the
273  * message.
274  * Covers the case {null | 0 | 1 < IE >}
275  *****************************************************************************/
276 #define M_NEXT_EXIST_OR_NULL(_STRUCT, _MEMBER, _NoOfExisting, _HF_PTR)\
277  {CSN_NEXT_EXIST, _NoOfExisting, {0}, offsetof(_STRUCT, _MEMBER), TRUE, #_MEMBER, NULL, 0, _HF_PTR, NULL, NULL}
278 
279 /******************************************************************************
280  * M_NEXT_EXIST_OR_NULL_LH(Par1, Par2, Par3)
281  * Similar to the M_NEXT_EXIST_LH except that not only bit 0 or 1 but also the
282  * end of the message may be encountered when looking for the next element in
283  * the message.
284  * Covers the case {null | L | H < IE >}
285  *****************************************************************************/
286 #define M_NEXT_EXIST_OR_NULL_LH(_STRUCT, _MEMBER, _NoOfExisting, _HF_PTR)\
287  {CSN_NEXT_EXIST_LH, _NoOfExisting, {(void*)1}, offsetof(_STRUCT, _MEMBER), TRUE, #_MEMBER, NULL, 0, _HF_PTR, NULL, NULL}
288 
289 /******************************************************************************
290  * M_UINT(Par1, Par2, Par3, Par4)
291  * Defines an integer number.
292  * Par1: C structure name
293  * Par2: C structure element name
294  * Par3: number of bits used to code the element (between 1 and 32)
295  * Par4: pointer to the header field
296  *****************************************************************************/
297 #define M_UINT(_STRUCT, _MEMBER, _BITS, _HF_PTR)\
298  {CSN_UINT, _BITS, {0}, offsetof(_STRUCT, _MEMBER), FALSE, #_MEMBER, NULL, 0, _HF_PTR, NULL, NULL}
299 
300 /******************************************************************************
301  * M_UINT_SPLIT(Par1, Par2, Par3, Par4)
302  * Defines an integer number split into segments which may be reordered or have gaps between them.
303  * Par1: C structure name
304  * Par2: C structure element name
305  * Par3: bits_spec_t array
306  * Par4: bit-width of the aggregate field
307  * Par4: pointer to the header field
308  *****************************************************************************/
309 #define M_SPLIT_BITS(_STRUCT, _MEMBER, _SPEC, _BITS, _HF_PTR)\
310  {CSN_SPLIT_BITS, _BITS, {_SPEC}, offsetof(_STRUCT, _MEMBER), FALSE, #_MEMBER, NULL, 0, _HF_PTR, NULL, NULL}
311 
312 /******************************************************************************
313  * M_NULL_SPLIT(Par1, Par2, Par3, Par4)
314  * Defines a subsequent segment of a split integer type.
315  * Par1: C structure name
316  * Par2: C structure element name
317  * Par3: bits_spec_t array
318  * Par4: segment number (0 based)
319  *****************************************************************************/
320 #define M_BITS_CRUMB(_STRUCT, _MEMBER, _SPEC, _SEG, _HF_PTR)\
321  {CSN_SPLIT_BITS_CRUMB, _SEG, {_SPEC}, 0, FALSE, #_MEMBER, NULL, 0, _HF_PTR, NULL, NULL}
322 
323 /******************************************************************************
324  * M_UINT_OR_NULL(Par1, Par2, Par3, Par4)
325  * Similar to the M_UINT except that not only the request set of bits but also the
326  * end of the message may be encountered when looking for the next element in
327  * the message.
328  * Covers the case {null | 0 | 1 < IE >}
329  *****************************************************************************/
330 #define M_UINT_OR_NULL(_STRUCT, _MEMBER, _BITS, _HF_PTR)\
331  {CSN_UINT, _BITS, {0}, offsetof(_STRUCT, _MEMBER), TRUE, #_MEMBER, NULL, 0, _HF_PTR, NULL, NULL}
332 
333 /******************************************************************************
334  * M_UINT_LH(Par1, Par2, Par3, Par4)
335  * This macro has the same functionality as M_UINT except that in addition the
336  * logical "exclusive or" operation with the background value "0x2B" is
337  * performed before the final value of the integer number is delivered from the
338  * received CSN.1 message
339  *****************************************************************************/
340 #define M_UINT_LH(_STRUCT, _MEMBER, _BITS, _HF_PTR)\
341  {CSN_UINT_LH, _BITS, {0}, offsetof(_STRUCT, _MEMBER), FALSE, #_MEMBER, NULL, 0, _HF_PTR, NULL, NULL}
342 
343 /******************************************************************************
344  * M_UINT_OFFSET(Par1, Par2, Par3, Par4)
345  * Defines an integer number.
346  * Par1: C structure name
347  * Par2: C structure element name
348  * Par3: number of bits used to code the element (between 1 and 32)
349  * Par4: value added to the returned integer (offset)
350  *****************************************************************************/
351 #define M_UINT_OFFSET(_STRUCT, _MEMBER, _BITS, _OFFSET, _HF_PTR)\
352  {CSN_UINT_OFFSET, _BITS, {(void*)_OFFSET}, offsetof(_STRUCT, _MEMBER), FALSE, #_MEMBER, NULL, 0, _HF_PTR, NULL, NULL}
353 
354 /******************************************************************************
355  * M_UINT_ARRAY(Par1, Par2, Par3, Par4)
356  * Defines an array of integer numbers. The size of the array is fixed.
357  * Par1: C structure name
358  * Par2: C structure element name
359  * Par3: number of bits used to code the each integer element (between 1 and 32)
360  * Par4: number of elements in the array (fixed integer value)
361  *****************************************************************************/
362 #define M_UINT_ARRAY(_STRUCT, _MEMBER, _BITS, _ElementCount, _HF_PTR)\
363  {CSN_UINT_ARRAY, _BITS, {(void*)_ElementCount}, offsetof(_STRUCT, _MEMBER), FALSE, #_MEMBER, NULL, 0, _HF_PTR, NULL, NULL}
364 
365 /******************************************************************************
366  * M_VAR_UINT_ARRAY(Par1, Par2, Par3, Par4)
367  * Defines an array of integer numbers. The size of the array is variable.
368  * Par1: C structure name
369  * Par2: C structure element name
370  * Par3: number of bits used to code the each integer element (between 1 and 32)
371  * Par4: number of elements in the array supplied by reference to the
372  * structure member holding the length value
373  *****************************************************************************/
374 #define M_VAR_UINT_ARRAY(_STRUCT, _MEMBER, _BITS, _ElementCountField, _HF_PTR)\
375  {CSN_UINT_ARRAY, _BITS, {(void*)offsetof(_STRUCT, _ElementCountField)}, offsetof(_STRUCT, _MEMBER), FALSE, #_MEMBER, NULL, 1, _HF_PTR, NULL, NULL}
376 
377 /******************************************************************************
378  * M_VAR_ARRAY(Par1, Par2, Par3, Par4)
379  * Defines an array of 8 bit large integer numbers. The size of the array is variable.
380  * Par1: C structure name
381  * Par2: C structure element name
382  * Par3: name of the structure member holding the size of the array
383  * Par4: offset that is added to the Par3 to get the actual size of the array
384  *****************************************************************************/
385 #define M_VAR_ARRAY(_STRUCT, _MEMBER, _ElementCountField, _OFFSET, _HF_PTR)\
386  {CSN_VARIABLE_ARRAY, _OFFSET, {(void*)offsetof(_STRUCT, _ElementCountField)}, offsetof(_STRUCT, _MEMBER), FALSE, #_MEMBER, NULL, 0, _HF_PTR, NULL, NULL}
387 
388 /******************************************************************************
389  * M_VAR_TARRAY(Par1, Par2, Par3, Par4)
390  * Similar to M_TYPE_ARRAY except that the size of the array is variable.
391  * Par1: C structure name
392  * Par2: C structure element name
393  * Par3: the type of each element of the array
394  * Par4: name of the structure member holding the size of the array
395  *****************************************************************************/
396 #define M_VAR_TARRAY(_STRUCT, _MEMBER, _MEMBER_TYPE, _ElementCountField)\
397  {CSN_VARIABLE_TARRAY, offsetof(_STRUCT, _ElementCountField), {(const void*)CSNDESCR_##_MEMBER_TYPE}, offsetof(_STRUCT, _MEMBER), FALSE, #_MEMBER, NULL, sizeof(_MEMBER_TYPE), NULL, NULL, NULL}
398 
399 /******************************************************************************
400  * M_VAR_TARRAY_OFFSET(Par1, Par2, Par3, Par4)
401  * Same as M_VAR_TARRAY with offset
402  *****************************************************************************/
403 #define M_VAR_TARRAY_OFFSET(_STRUCT, _MEMBER, _MEMBER_TYPE, _ElementCountField)\
404  {CSN_VARIABLE_TARRAY_OFFSET, offsetof(_STRUCT, _ElementCountField), {(const void*)CSNDESCR_##_MEMBER_TYPE}, offsetof(_STRUCT, _MEMBER), FALSE, #_MEMBER, NULL, sizeof(_MEMBER_TYPE), NULL, NULL, NULL}
405 
406 /******************************************************************************
407  * M_REC_ARRAY(Par1, Par2, Par3, Par4)
408  * similar to the M_VAR_ARRAY. The difference is that the size of the array is
409  * not known in advance and it has to be calculated during unpacking. Its value
410  * is stored in a variable which belongs to the same structure as the array.
411  * A zero element terminates the array. The CSN.1 syntax describes it
412  * recursively as:
413  * <array> ::={1 <element> <array>| 0}
414  *
415  * Par1: C structure name
416  * Par2: C structure element name
417  * Par3: name of the structure member where the calculated the size of the
418  * array will be stored
419  * Par4: length of each element in bits
420  *****************************************************************************/
421 /* XXX - need 2 hf support */
422 #define M_REC_ARRAY(_STRUCT, _MEMBER, _ElementCountField, _BITS, _HF_PTR, _HF_PTR_EXIST)\
423  {CSN_RECURSIVE_ARRAY, _BITS, {(const void*)offsetof(_STRUCT, _ElementCountField)}, offsetof(_STRUCT, _MEMBER), FALSE, #_MEMBER, NULL, 0, _HF_PTR, _HF_PTR_EXIST, NULL}
424 
425 /******************************************************************************
426  * M_VAR_TYPE_ARRAY(Par1, Par2, Par3, Par4)
427  * Defines an array of structures. The size of the array is variable.
428  * Par1: C structure name
429  * Par2: C structure element name
430  * Par3: name of the structure
431  * Par4: number of elements in the array (fixed integer value)
432  *****************************************************************************/
433 #define M_TYPE_ARRAY(_STRUCT, _MEMBER, _MEMBER_TYPE, _ElementCount)\
434  {CSN_TYPE_ARRAY, _ElementCount, {(const void*)CSNDESCR_##_MEMBER_TYPE}, offsetof(_STRUCT, _MEMBER), FALSE, #_MEMBER, NULL, sizeof(_MEMBER_TYPE), NULL, NULL, NULL}
435 
436 /******************************************************************************
437  * M_REC_TARRAY(Par1, Par2, Par3, Par4)
438  * Defines an recursive array of structures. The size of the array is variable.
439  * <list> ::= {1 <type>} ** 0 ;
440  * Par1: C structure name
441  * Par2: C structure element name
442  * Par3: name of the structure
443  * Par4: will hold the number of element in the array after unpacking
444  *****************************************************************************/
445 #define M_REC_TARRAY(_STRUCT, _MEMBER, _MEMBER_TYPE, _ElementCountField, _HF_PTR)\
446  {CSN_RECURSIVE_TARRAY, offsetof(_STRUCT, _ElementCountField), {(const void*)CSNDESCR_##_MEMBER_TYPE}, offsetof(_STRUCT, _MEMBER), FALSE, #_MEMBER, NULL, sizeof(_MEMBER_TYPE), _HF_PTR, NULL, (void_fn_t)array_length(((_STRUCT*)0)->_MEMBER)}
447 
448 /******************************************************************************
449  * M_REC_TARRAY1(Par1, Par2, Par3, Par4)
450  * Same as M_REC_TARRAY but first element always exist:
451  * <list> ::= <type> {1 <type>} ** 0 ;
452  *****************************************************************************/
453 #define M_REC_TARRAY_1(_STRUCT, _MEMBER, _MEMBER_TYPE, _ElementCountField, _HF_PTR)\
454  {CSN_RECURSIVE_TARRAY_1, offsetof(_STRUCT, _ElementCountField), {(const void*)CSNDESCR_##_MEMBER_TYPE}, offsetof(_STRUCT, _MEMBER), FALSE, #_MEMBER, NULL, sizeof(_MEMBER_TYPE), _HF_PTR, NULL, (void_fn_t)array_length(((_STRUCT*)0)->_MEMBER)}
455 
456 /******************************************************************************
457  * M_REC_TARRAY2(Par1, Par2, Par3, Par4)
458  * Same as M_REC_TARRAY but with reversed separators :
459  * <lists> ::= <type> { 0 <type> } ** 1 ;
460  *****************************************************************************/
461 #define M_REC_TARRAY_2(_STRUCT, _MEMBER, _MEMBER_TYPE, _ElementCountField)\
462  {CSN_RECURSIVE_TARRAY_2, offsetof(_STRUCT, _ElementCountField), {(const void*)CSNDESCR_##_MEMBER_TYPE}, offsetof(_STRUCT, _MEMBER), FALSE, #_MEMBER, NULL, sizeof(_MEMBER_TYPE), NULL, NULL, (void_fn_t)array_length(((_STRUCT*)0)->_MEMBER)}
463 
464 /******************************************************************************
465  * M_TYPE(Par1, Par2, Par3)
466  * Defines a reference to a structure which is described elsewhere
467  * <list> ::= {1 <type>} ** 0 ;
468  * Par1: C structure name
469  * Par2: C structure element name
470  * Par3: type of member
471  *****************************************************************************/
472 #define M_TYPE(_STRUCT, _MEMBER, _MEMBER_TYPE)\
473  {CSN_TYPE, 0, {(const void*)CSNDESCR_##_MEMBER_TYPE}, offsetof(_STRUCT, _MEMBER), FALSE, #_MEMBER, NULL, 0, NULL, NULL, NULL}
474 
475 /******************************************************************************
476  * M_TYPE_OR_NULL(Par1, Par2, Par3)
477  * Similar to the M_TYPE except that not only the request set of bits but also the
478  * end of the message may be encountered when looking for the next element in
479  * the message.
480  * Covers the case {null | 0 | 1 < IE >}
481  *****************************************************************************/
482 #define M_TYPE_OR_NULL(_STRUCT, _MEMBER, _MEMBER_TYPE)\
483  {CSN_TYPE, 0, {(const void*)CSNDESCR_##_MEMBER_TYPE}, offsetof(_STRUCT, _MEMBER), TRUE, #_MEMBER, NULL, 0, NULL, NULL, NULL}
484 
485 
486 /******************************************************************************
487  * M_TYPE_LABEL(Par1, Par2, Par3, Par4)
488  * Same as M_TYPE but allows to define a custom string for the subtree
489  * <list> ::= {1 <type>} ** 0 ;
490  * Par1: C structure name
491  * Par2: C structure element name
492  * Par3: type of member
493  * Par4: C string for the text
494  *****************************************************************************/
495 #define M_TYPE_LABEL(_STRUCT, _MEMBER, _MEMBER_TYPE, _LABEL)\
496  {CSN_TYPE, 0, {(const void*)CSNDESCR_##_MEMBER_TYPE}, offsetof(_STRUCT, _MEMBER), FALSE, _LABEL, NULL, 0, NULL, NULL, NULL}
497 
498 /******************************************************************************
499  * M_UNION(Par1, Par2)
500  * Informs the CSN.1 library that a union follows and how many possible choices
501  * there are in the union. The actual value of the choice, which points out the
502  * chosen element of the union is stored in the uint8 variable and is usually
503  * called UnionType. The elements of the union have to be listed directly after
504  * the M_UNION statement.
505  * Par1: C structure name
506  * Par2: number of possible choice in the union
507  *****************************************************************************/
508 #define M_UNION(_STRUCT, _COUNT, _HF_PTR)\
509  {CSN_UNION, _COUNT, {0}, offsetof(_STRUCT, UnionType), FALSE, "UnionType", NULL, 0, _HF_PTR, NULL, NULL}
510 
511 /******************************************************************************
512  * M_UNION_LH(Par1, Par2)
513  * Same as M_UNION but masked with background value 0x2B
514  *****************************************************************************/
515 #define M_UNION_LH(_STRUCT, _COUNT, _HF_PTR)\
516  {CSN_UNION_LH, _COUNT, {0}, offsetof(_STRUCT, UnionType), FALSE, "UnionType", NULL, 0, _HF_PTR, NULL, NULL}
517 
518 /******************************************************************************
519  * M_CHOICE(Par1, Par2, Par3, Par4)
520  * Similar to the M_UNION. In the M_UNION the selected element of all possible
521  * choices in the union is referred as a sequential numbers, i.e., the first
522  * choice is addressed as choice 0 the second as choice 1, the third as choice
523  * 2 and so on, both in the encoded message and in the variable UnionType which
524  * is the part of the message. In the CSN_CHOICE case, this rule does not
525  * apply. There is free but predefined mapping of the element of the union and
526  * the value which addresses this element.
527  * The value of the address is called a selector.
528  * After unpacking, this value is then converted to the sequential number of the
529  * element in the union and stored in the UnionType variable.
530  * Par1: C structure name
531  * Par2: C structure element name
532  * Par3: address of an array of type CSN_ChoiceElement_t where all possible
533  * values of the selector are provided, together with the selector
534  * length expressed in bits and the address of the CSN_DESCR type
535  * where the element is defined. For every element in the union
536  * there is one line in the Choice variable. These lines have to
537  * appear in the _CHOICE in the same order as the elements in the
538  * union. The element of the union selected in the message through
539  * the _CHOICE parameter is after unpacking translated to the
540  * corresponding sequential number of this element and stored in
541  * the variable pointed out by the _MEMBER
542  * Par4: number of possible choices in the union
543  *****************************************************************************/
544 #define M_CHOICE(_STRUCT, _MEMBER, _CHOICE, _ElementCount, _HF_PTR)\
545  {CSN_CHOICE, _ElementCount, {(const void*)_CHOICE}, offsetof(_STRUCT, _MEMBER), FALSE, #_CHOICE, NULL, 0, _HF_PTR, NULL, NULL}
546 
547 /******************************************************************************
548  * M_CHOICE_IL(Par1, Par2, Par3, Par4)
549  * See M_CHOICE above, but displayed inline (i.e. no specific elements are
550  * displayed to show there was a choice
551  *****************************************************************************/
552 #define M_CHOICE_IL(_STRUCT, _MEMBER, _CHOICE, _ElementCount, _HF_PTR)\
553  {CSN_CHOICE, _ElementCount, {(const void*)_CHOICE}, offsetof(_STRUCT, _MEMBER), FALSE, NULL, NULL, 0, _HF_PTR, NULL, NULL}
554 
555 /******************************************************************************
556  * M_FIXED(Par1, Par2, Par3)
557  * Defines a fixed value of type integer which should be fetched from or stored
558  * in the message
559  * Par1: C structure name
560  * Par2: gives the length of the fixed number in bits.
561  * Par3: the value of the number. If the expected value is not present in
562  * the message the unpacking procedure is aborted
563  *****************************************************************************/
564 #define M_FIXED(_STRUCT, _BITS, _BITVALUE, _HF_PTR)\
565  {CSN_FIXED, _BITS, {0}, _BITVALUE, FALSE, #_BITVALUE, NULL, 0, _HF_PTR, NULL, NULL}
566 
567 /******************************************************************************
568  * M_FIXED_LABEL(Par1, Par2, Par3, Par4)
569  * Same as M_FIXED but allows to define a custom string for the subtree
570  * Par1: C structure name
571  * Par2: gives the length of the fixed number in bits.
572  * Par3: the value of the number. If the expected value is not present in
573  * the message the unpacking procedure is aborted
574  * Par4: C string for the text
575  *****************************************************************************/
576 #define M_FIXED_LABEL(_STRUCT, _BITS, _BITVALUE, _LABEL, _HF_PTR)\
577  {CSN_FIXED, _BITS, {0}, _BITVALUE, FALSE, _LABEL, NULL, 0, _HF_PTR, NULL, NULL}
578 
579 /******************************************************************************
580  * M_SERIALIZE(Par1, Par2, Par3)
581  * Allows using a complete free format of data being encoded or decoded.
582  * When the M_SERIALIZE is encounted during encoding or decoding of a message
583  * the CSNstream program passes the control over to the specified function
584  * together with all necessary parameters about the current position within
585  * the message being unpacked or packed. When transferring of "serialized"
586  * data to or from the message is finished by the function the CSNstream gets
587  * back control over the data stream and continues to work with the message.
588  *****************************************************************************/
589 #define M_SERIALIZE(_STRUCT, _MEMBER, _LENGTH_LEN, _HF_PTR, _SERIALIZEFCN)\
590  {CSN_SERIALIZE, _LENGTH_LEN, {0}, offsetof(_STRUCT, _MEMBER), FALSE, #_MEMBER, NULL, 0, _HF_PTR, NULL, (void_fn_t)_SERIALIZEFCN}
591 
592 #define M_CALLBACK(_STRUCT, _CSNCALLBACKFCN, _PARAM1, _PARAM2)\
593  {CSN_CALLBACK, offsetof(_STRUCT, _PARAM1), {0}, offsetof(_STRUCT, _PARAM2), FALSE, "CallBack_"#_CSNCALLBACKFCN, NULL, 0, NULL, NULL, (void_fn_t)_CSNCALLBACKFCN}
594 
595 /******************************************************************************
596  * M_BITMAP(Par1, Par2, Par3)
597  * Defines a type which consists of a bitmap. The size of the bitmap in bits
598  * is fixed and provided by the parameter Par3
599  * Par1: C structure name
600  * Par2: C structure element name
601  * Par3: length of the bitmap expressed in bits
602  *****************************************************************************/
603 #define M_BITMAP(_STRUCT, _MEMBER, _BITS, _HF_PTR)\
604  {CSN_BITMAP, _BITS, {0}, offsetof(_STRUCT, _MEMBER), FALSE, #_MEMBER, NULL, 0, _HF_PTR, NULL, NULL}
605 
606 /* variable length, right aligned bitmap i.e. _ElementCountField = 11 => 00000111 11111111 */
607 #define M_VAR_BITMAP(_STRUCT, _MEMBER, _ElementCountField, _OFFSET, _HF_PTR)\
608  {CSN_VARIABLE_BITMAP, _OFFSET, {(void*)offsetof(_STRUCT, _ElementCountField)}, offsetof(_STRUCT, _MEMBER), FALSE, #_MEMBER, NULL, 0, _HF_PTR, NULL, NULL}
609 
610 /* variable length, right aligned bitmap filling the rest of message
611  * - when unpacking the _ElementCountField will be set in runtime
612  * - when packing _ElementCountField contains the size of bitmap
613  */
614 #define M_VAR_BITMAP_1(_STRUCT, _MEMBER, _ElementCountField, _OFFSET)\
615  {CSN_VARIABLE_BITMAP_1, _OFFSET, {(void*)offsetof(_STRUCT, _ElementCountField)}, offsetof(_STRUCT, _MEMBER), FALSE, #_MEMBER, NULL, 0, NULL, NULL, NULL}
616 
617 /* variable length, left aligned bitmap i.e. _ElementCountField = 11 => 11111111 11100000 */
618 #define M_LEFT_VAR_BMP(_STRUCT, _MEMBER, _ElementCountField, _OFFSET, _HF_PTR)\
619  {CSN_LEFT_ALIGNED_VAR_BMP, _OFFSET, {(void*)offsetof(_STRUCT, _ElementCountField)}, offsetof(_STRUCT, _MEMBER), FALSE, #_MEMBER, NULL, 0, _HF_PTR, NULL, NULL}
620 
621 /* variable length, left aligned bitmap filling the rest of message
622  *- when unpacking the _ElementCountField will be set in runtime
623  * - when packing _ElementCountField contains the size of bitmap
624  */
625 #define M_LEFT_VAR_BMP_1(_STRUCT, _MEMBER, _ElementCountField, _OFFSET, _HF_PTR)\
626  {CSN_LEFT_ALIGNED_VAR_BMP_1, _OFFSET, {(void*)offsetof(_STRUCT, _ElementCountField)}, offsetof(_STRUCT, _MEMBER), FALSE, #_MEMBER, NULL, 0, _HF_PTR, NULL, NULL}
627 
628 /* todo: dissect padding bits looking for unexpected extensions */
629 #define M_PADDING_BITS(_STRUCT, _HF_PTR)\
630  {CSN_PADDING_BITS, 0, {0}, 0, TRUE, "Padding", NULL, 0, _HF_PTR, NULL, NULL}
631 
632 #define M_NULL(_STRUCT, _MEMBER, _SKIP_BITS)\
633  {CSN_NULL, _SKIP_BITS, {0}, offsetof(_STRUCT, _MEMBER), FALSE, #_MEMBER, NULL, 0, NULL, NULL, NULL}
634 
635 #define M_THIS_EXIST(_STRUCT, _HF_PTR)\
636  {CSN_EXIST, 0, {0}, offsetof(_STRUCT, Exist), FALSE, "Exist", NULL, 0, _HF_PTR, NULL, NULL}
637 
638 #define M_THIS_EXIST_LH(_STRUCT, _HF_PTR)\
639  {CSN_EXIST_LH, 0, {0}, offsetof(_STRUCT, Exist), FALSE, "Exist", NULL, 0, _HF_PTR, NULL, NULL}
640 
641 /* return value 0 if ok else discontionue the unpacking */
642 typedef gint16 (*CsnCallBackFcn_t)(void* pv ,...);
643 
644 #define CSNDESCR(_FuncType) CSNDESCR_##_FuncType
645 
646 #endif /*_PACKET_CSN1_H_*/
647 
648 /*
649  * Editor modelines - https://www.wireshark.org/tools/modelines.html
650  *
651  * Local Variables:
652  * c-basic-offset: 2
653  * tab-width: 8
654  * indent-tabs-mode: nil
655  * End:
656  *
657  * vi: set shiftwidth=2 tabstop=8 expandtab:
658  * :indentSize=2:tabSize=8:noTabs=true:
659  */
Definition: packet_info.h:44
Definition: proto.h:904
Definition: packet-csn1.h:183
Definition: packet-csn1.h:161
Definition: proto.h:841
Definition: packet-csn1.h:47
Definition: expert.h:39
Definition: tvbuff-int.h:35