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