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