src/lwes_marshall_functions.h

   1 /*======================================================================*
   2  * Copyright (C) 2008 Light Weight Event System                         *
   3  * All rights reserved.                                                 *
   4  *                                                                      *
   5  * This program is free software; you can redistribute it and/or modify *
   6  * it under the terms of the GNU General Public License as published by *
   7  * the Free Software Foundation; either version 2 of the License, or    *
   8  * (at your option) any later version.                                  *
   9  *                                                                      *
  10  * This program is distributed in the hope that it will be useful,      *
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of       *
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the        *
  13  * GNU General Public License for more details.                         *
  14  *                                                                      *
  15  * You should have received a copy of the GNU General Public License    *
  16  * along with this program; if not, write to the Free Software          *
  17  * Foundation, Inc., 51 Franklin Street, Fifth Floor,                   *
  18  * Boston, MA 02110-1301 USA.                                           *
  19  *======================================================================*/
  20 #ifndef __LWES_MARSHAL_FUNCTIONS_H
  21 #define __LWES_MARSHAL_FUNCTIONS_H
  22
  23 #include <ctype.h>
  24 #include <stdio.h>
  25
  26 #include "lwes_types.h"
  27
  28 #ifdef __cplusplus
  29 extern "C" {
  30 #endif
  31
  32 /*! \file lwes_marshall_functions.h
  33  *  \brief Functions for marshalling LWES data types to/from byte arrays
  34  */
  35
  36 /*! \brief Marshall a byte into a byte array
  37  *
  38  * Attempt to marshall aByte into the given byte array at the given
  39  * offset if there is enough total space.  The length should be the total
  40  * length of the array.
  41  *
  42  * The offset will be modified by the number of bytes set, and that value
  43  * will be returned.  Thus a value of 0 is an error, meaning not enough
  44  * space to write this.
  45  *
  46  *  \param[in] aByte the byte to write into the array
  47  *  \param[in] bytes the byte array to write into
  48  *  \param[in] length total length of the array
  49  *  \param[in,out] offset the offset into the array, then the new offset
  50  *
  51  *  \return 0 on error, the number of bytes written on success.
  52  */
  53 int
  54 marshall_BYTE
  55   (LWES_BYTE         aByte,
  56    LWES_BYTE_P       bytes,
  57    size_t            length,
  58    size_t            *offset);
  59
  60 /*! \brief Marshall a 16 bit unsigned int into a byte array
  61  *
  62  * Attempt to marshall anInt into the given byte array at the given
  63  * offset if there is enough total space.  The length should be the total
  64  * length of the array.
  65  *
  66  * The offset will be modified by the number of bytes set, and that value
  67  * will be returned.  Thus a value of 0 is an error, meaning not enough
  68  * space to write this.
  69  *
  70  *  \param[in] anInt the LWES_U_INT_16 to write into the array
  71  *  \param[in] bytes the byte array to write into
  72  *  \param[in] length total length of the array
  73  *  \param[in,out] offset the offset into the array, then the new offset
  74  *
  75  *  \return 0 on error, the number of bytes written on success.
  76  */
  77 int
  78 marshall_U_INT_16
  79   (LWES_U_INT_16     anInt,
  80    LWES_BYTE_P       bytes,
  81    size_t            length,
  82    size_t            *offset);
  83
  84 /*! \brief Marshall a 16 bit int into a byte array
  85  *
  86  * Attempt to marshall anInt into the given byte array at the given
  87  * offset if there is enough total space.  The length should be the total
  88  * length of the array.
  89  *
  90  * The offset will be modified by the number of bytes set, and that value
  91  * will be returned.  Thus a value of 0 is an error, meaning not enough
  92  * space to write this.
  93  *
  94  *  \param[in] anInt the LWES_INT_16 to write into the array
  95  *  \param[in] bytes the byte array to write into
  96  *  \param[in] length total length of the array
  97  *  \param[in,out] offset the offset into the array, then the new offset
  98  *
  99  *  \return 0 on error, the number of bytes written on success.
 100  */
 101 int
 102 marshall_INT_16
 103   (LWES_INT_16       anInt,
 104    LWES_BYTE_P       bytes,
 105    size_t            length,
 106    size_t            *offset);
 107
 108 /*! \brief Marshall a 32 bit unsigned int into a byte array
 109  *
 110  * Attempt to marshall anInt into the given byte array at the given
 111  * offset if there is enough total space.  The length should be the total
 112  * length of the array.
 113  *
 114  * The offset will be modified by the number of bytes set, and that value
 115  * will be returned.  Thus a value of 0 is an error, meaning not enough
 116  * space to write this.
 117  *
 118  *  \param[in] anInt the LWES_U_INT_32 to write into the array
 119  *  \param[in] bytes the byte array to write into
 120  *  \param[in] length total length of the array
 121  *  \param[in,out] offset the offset into the array, then the new offset
 122  *
 123  *  \return 0 on error, the number of bytes written on success.
 124  */
 125 int
 126 marshall_U_INT_32
 127   (LWES_U_INT_32     anInt,
 128    LWES_BYTE_P       bytes,
 129    size_t            length,
 130    size_t            *offset);
 131
 132 /*! \brief Marshall a 32 bit int into a byte array
 133  *
 134  * Attempt to marshall anInt into the given byte array at the given
 135  * offset if there is enough total space.  The length should be the total
 136  * length of the array.
 137  *
 138  * The offset will be modified by the number of bytes set, and that value
 139  * will be returned.  Thus a value of 0 is an error, meaning not enough
 140  * space to write this.
 141  *
 142  *  \param[in] anInt the LWES_INT_32 to write into the array
 143  *  \param[in] bytes the byte array to write into
 144  *  \param[in] length total length of the array
 145  *  \param[in,out] offset the offset into the array, then the new offset
 146  *
 147  *  \return 0 on error, the number of bytes written on success.
 148  */
 149 int
 150 marshall_INT_32
 151   (LWES_INT_32       anInt,
 152    LWES_BYTE_P       bytes,
 153    size_t            length,
 154    size_t            *offset);
 155
 156 /*! \brief Marshall a 64 bit unsigned int into a byte array
 157  *
 158  * Attempt to marshall anInt into the given byte array at the given
 159  * offset if there is enough total space.  The length should be the total
 160  * length of the array.
 161  *
 162  * The offset will be modified by the number of bytes set, and that value
 163  * will be returned.  Thus a value of 0 is an error, meaning not enough
 164  * space to write this.
 165  *
 166  *  \param[in] anInt the LWES_U_INT_64 to write into the array
 167  *  \param[in] bytes the byte array to write into
 168  *  \param[in] length total length of the array
 169  *  \param[in,out] offset the offset into the array, then the new offset
 170  *
 171  *  \return 0 on error, the number of bytes written on success.
 172  */
 173 int
 174 marshall_U_INT_64
 175   (LWES_U_INT_64     anInt,
 176    LWES_BYTE_P       bytes,
 177    size_t            length,
 178    size_t            *offset);
 179
 180 /*! \brief Marshall a 64 bit int into a byte array
 181  *
 182  * Attempt to marshall anInt into the given byte array at the given
 183  * offset if there is enough total space.  The length should be the total
 184  * length of the array.
 185  *
 186  * The offset will be modified by the number of bytes set, and that value
 187  * will be returned.  Thus a value of 0 is an error, meaning not enough
 188  * space to write this.
 189  *
 190  *  \param[in] anInt the LWES_INT_64 to write into the array
 191  *  \param[in] bytes the byte array to write into
 192  *  \param[in] length total length of the array
 193  *  \param[in,out] offset the offset into the array, then the new offset
 194  *
 195  *  \return 0 on error, the number of bytes written on success.
 196  */
 197 int
 198 marshall_INT_64
 199   (LWES_INT_64       anInt,
 200    LWES_BYTE_P       bytes,
 201    size_t            length,
 202    size_t            *offset);
 203
 204 /*! \brief Marshall a boolean into a byte array
 205  *
 206  * Attempt to marshall aBoolean into the given byte array at the given
 207  * offset if there is enough total space.  The length should be the total
 208  * length of the array.
 209  *
 210  * The offset will be modified by the number of bytes set, and that value
 211  * will be returned.  Thus a value of 0 is an error, meaning not enough
 212  * space to write this.
 213  *
 214  *  \param[in] aBoolean the LWES_BOOLEAN to write into the array
 215  *  \param[in] bytes the byte array to write into
 216  *  \param[in] length total length of the array
 217  *  \param[in,out] offset the offset into the array, then the new offset
 218  *
 219  *  \return 0 on error, the number of bytes written on success.
 220  */
 221 int
 222 marshall_BOOLEAN
 223   (LWES_BOOLEAN      aBoolean,
 224    LWES_BYTE_P       bytes,
 225    size_t            length,
 226    size_t            *offset);
 227
 228 /*! \brief Marshall an ip4v address into a byte array
 229  *
 230  * Attempt to marshall ipAddress into the given byte array at the given
 231  * offset if there is enough total space.  The length should be the total
 232  * length of the array.
 233  *
 234  * The offset will be modified by the number of bytes set, and that value
 235  * will be returned.  Thus a value of 0 is an error, meaning not enough
 236  * space to write this.
 237  *
 238  *  \param[in] ipAddress the LWES_IP_ADDR to write into the array
 239  *  \param[in] bytes the byte array to write into
 240  *  \param[in] length total length of the array
 241  *  \param[in,out] offset the offset into the array, then the new offset
 242  *
 243  *  \return 0 on error, the number of bytes written on success.
 244  */
 245 int
 246 marshall_IP_ADDR
 247   (LWES_IP_ADDR      ipAddress,
 248    LWES_BYTE_P       bytes,
 249    size_t            length,
 250    size_t            *offset);
 251
 252 /*! \brief Marshall a short string into a byte array
 253  *
 254  * Attempt to marshall aString into the given byte array at the given
 255  * offset if there is enough total space.  The length should be the total
 256  * length of the array.
 257  *
 258  * The offset will be modified by the number of bytes set, and that value
 259  * will be returned.  Thus a value of 0 is an error, meaning not enough
 260  * space to write this.
 261  *
 262  *  \param[in] aString the LWES_SHORT_STRING to write into the array
 263  *  \param[in] bytes the byte array to write into
 264  *  \param[in] length total length of the array
 265  *  \param[in,out] offset the offset into the array, then the new offset
 266  *
 267  *  \return 0 on error, the number of bytes written on success.
 268  */
 269 int
 270 marshall_SHORT_STRING
 271   (LWES_SHORT_STRING aString,
 272    LWES_BYTE_P       bytes,
 273    size_t            length,
 274    size_t            *offset);
 275
 276 /*! \brief Marshall a long string into a byte array
 277  *
 278  * Attempt to marshall aString into the given byte array at the given
 279  * offset if there is enough total space.  The length should be the total
 280  * length of the array.
 281  *
 282  * The offset will be modified by the number of bytes set, and that value
 283  * will be returned.  Thus a value of 0 is an error, meaning not enough
 284  * space to write this.
 285  *
 286  *  \param[in] aString the LWES_LONG_STRING to write into the array
 287  *  \param[in] bytes the byte array to write into
 288  *  \param[in] length total length of the array
 289  *  \param[in,out] offset the offset into the array, then the new offset
 290  *
 291  *  \return 0 on error, the number of bytes written on success.
 292  */
 293 int
 294 marshall_LONG_STRING
 295   (LWES_LONG_STRING  aString,
 296    LWES_BYTE_P       bytes,
 297    size_t            length,
 298    size_t            *offset);
 299
 300 /*! \brief Unmarshall a byte from a byte array
 301  *
 302  * Attempt to unmarshall aByte from the given byte array at the
 303  * given offset, without overflowing the bound.  If the bound would be
 304  * overflown, an error is returned.
 305  *
 306  * The length should be the total length of the array.
 307  *
 308  * The offset will be modified by the number of bytes consumed, and that value
 309  * will be returned.  Thus a value of 0 is an error, meaning not enough
 310  * bytes to fill out the given type.
 311  *
 312  *  \param[out] aByte the byte to read from the array and write into
 313  *  \param[in] bytes the byte array to read from
 314  *  \param[in] length total length of the byte array
 315  *  \param[in,out] offset the offset into the array, then the new offset
 316  *
 317  *  \return 0 on error, the number of bytes consumed on success.
 318  */
 319 int
 320 unmarshall_BYTE
 321   (LWES_BYTE *       aByte,
 322    LWES_BYTE_P       bytes,
 323    size_t            length,
 324    size_t *          offset);
 325
 326 /*! \brief Unmarshall a 16 bit unsigned int from a byte array
 327  *
 328  * Attempt to unmarshall anInt from the given byte array at the
 329  * given offset, without overflowing the bound.  If the bound would be
 330  * overflown, an error is returned.
 331  *
 332  * The length should be the total length of the array.
 333  *
 334  * The offset will be modified by the number of bytes consumed, and that value
 335  * will be returned.  Thus a value of 0 is an error, meaning not enough
 336  * bytes to fill out the given type.
 337  *
 338  *  \param[out] anInt the LWES_U_INT_16 to read from the array and write into
 339  *  \param[in] bytes the byte array to read from
 340  *  \param[in] length total length of the byte array
 341  *  \param[in,out] offset the offset into the array, then the new offset
 342  *
 343  *  \return 0 on error, the number of bytes consumed on success.
 344  */
 345 int
 346 unmarshall_U_INT_16
 347   (LWES_U_INT_16 *   anInt,
 348    LWES_BYTE_P       bytes,
 349    size_t            length,
 350    size_t *          offset);
 351
 352 /*! \brief Unmarshall a 16 bit int from a byte array
 353  *
 354  * Attempt to unmarshall anInt from the given byte array at the
 355  * given offset, without overflowing the bound.  If the bound would be
 356  * overflown, an error is returned.
 357  *
 358  * The length should be the total length of the array.
 359  *
 360  * The offset will be modified by the number of bytes consumed, and that value
 361  * will be returned.  Thus a value of 0 is an error, meaning not enough
 362  * bytes to fill out the given type.
 363  *
 364  *  \param[out] anInt the LWES_INT_16 to read from the array and write into
 365  *  \param[in] bytes the byte array to read from
 366  *  \param[in] length total length of the byte array
 367  *  \param[in,out] offset the offset into the array, then the new offset
 368  *
 369  *  \return 0 on error, the number of bytes consumed on success.
 370  */
 371 int
 372 unmarshall_INT_16
 373   (LWES_INT_16 *     anInt,
 374    LWES_BYTE_P       bytes,
 375    size_t            length,
 376    size_t *          offset);
 377
 378 /*! \brief Unmarshall a 32 bit unsigned int from a byte array
 379  *
 380  * Attempt to unmarshall anInt from the given byte array at the
 381  * given offset, without overflowing the bound.  If the bound would be
 382  * overflown, an error is returned.
 383  *
 384  * The length should be the total length of the array.
 385  *
 386  * The offset will be modified by the number of bytes consumed, and that value
 387  * will be returned.  Thus a value of 0 is an error, meaning not enough
 388  * bytes to fill out the given type.
 389  *
 390  *  \param[out] anInt the LWES_U_INT_32 to read from the array and write into
 391  *  \param[in] bytes the byte array to read from
 392  *  \param[in] length total length of the byte array
 393  *  \param[in,out] offset the offset into the array, then the new offset
 394  *
 395  *  \return 0 on error, the number of bytes consumed on success.
 396  */
 397 int
 398 unmarshall_U_INT_32
 399   (LWES_U_INT_32 *   anInt,
 400    LWES_BYTE_P       bytes,
 401    size_t            length,
 402    size_t *          offset);
 403
 404 /*! \brief Unmarshall a 32 bit int from a byte array
 405  *
 406  * Attempt to unmarshall anInt from the given byte array at the
 407  * given offset, without overflowing the bound.  If the bound would be
 408  * overflown, an error is returned.
 409  *
 410  * The length should be the total length of the array.
 411  *
 412  * The offset will be modified by the number of bytes consumed, and that value
 413  * will be returned.  Thus a value of 0 is an error, meaning not enough
 414  * bytes to fill out the given type.
 415  *
 416  *  \param[out] anInt the LWES_INT_32 to read from the array and write into
 417  *  \param[in] bytes the byte array to read from
 418  *  \param[in] length total length of the byte array
 419  *  \param[in,out] offset the offset into the array, then the new offset
 420  *
 421  *  \return 0 on error, the number of bytes consumed on success.
 422  */
 423 int
 424 unmarshall_INT_32
 425   (LWES_INT_32 *     anInt,
 426    LWES_BYTE_P       bytes,
 427    size_t            length,
 428    size_t *          offset);
 429
 430 /*! \brief Unmarshall a 64 bit unsigned int from a byte array
 431  *
 432  * Attempt to unmarshall anInt from the given byte array at the
 433  * given offset, without overflowing the bound.  If the bound would be
 434  * overflown, an error is returned.
 435  *
 436  * The length should be the total length of the array.
 437  *
 438  * The offset will be modified by the number of bytes consumed, and that value
 439  * will be returned.  Thus a value of 0 is an error, meaning not enough
 440  * bytes to fill out the given type.
 441  *
 442  *  \param[out] anInt the LWES_U_INT_64 to read from the array and write into
 443  *  \param[in] bytes the byte array to read from
 444  *  \param[in] length total length of the byte array
 445  *  \param[in,out] offset the offset into the array, then the new offset
 446  *
 447  *  \return 0 on error, the number of bytes consumed on success.
 448  */
 449 int
 450 unmarshall_U_INT_64
 451   (LWES_U_INT_64 *   anInt,
 452    LWES_BYTE_P       bytes,
 453    size_t            length,
 454    size_t *          offset);
 455
 456 /*! \brief Unmarshall a 64 bit int from a byte array
 457  *
 458  * Attempt to unmarshall anInt from the given byte array at the
 459  * given offset, without overflowing the bound.  If the bound would be
 460  * overflown, an error is returned.
 461  *
 462  * The length should be the total length of the array.
 463  *
 464  * The offset will be modified by the number of bytes consumed, and that value
 465  * will be returned.  Thus a value of 0 is an error, meaning not enough
 466  * bytes to fill out the given type.
 467  *
 468  *  \param[out] anInt the LWES_INT_64 to read from the array and write into
 469  *  \param[in] bytes the byte array to read from
 470  *  \param[in] length total length of the byte array
 471  *  \param[in,out] offset the offset into the array, then the new offset
 472  *
 473  *  \return 0 on error, the number of bytes consumed on success.
 474  */
 475 int
 476 unmarshall_INT_64
 477   (LWES_INT_64 *     anInt,
 478    LWES_BYTE_P       bytes,
 479    size_t            length,
 480    size_t *          offset);
 481
 482 /*! \brief Unmarshall a boolean from a byte array
 483  *
 484  * Attempt to unmarshall aBoolean from the given byte array at the
 485  * given offset, without overflowing the bound.  If the bound would be
 486  * overflown, an error is returned.
 487  *
 488  * The length should be the total length of the array.
 489  *
 490  * The offset will be modified by the number of bytes consumed, and that value
 491  * will be returned.  Thus a value of 0 is an error, meaning not enough
 492  * bytes to fill out the given type.
 493  *
 494  *  \param[out] aBoolean the LWES_BOOLEAN to read from the array and write into
 495  *  \param[in] bytes the byte array to read from
 496  *  \param[in] length total length of the byte array
 497  *  \param[in,out] offset the offset into the array, then the new offset
 498  *
 499  *  \return 0 on error, the number of bytes consumed on success.
 500  */
 501 int
 502 unmarshall_BOOLEAN
 503   (LWES_BOOLEAN *    aBoolean,
 504    LWES_BYTE_P       bytes,
 505    size_t            length,
 506    size_t *          offset);
 507
 508 /*! \brief Unmarshall an ipv4 address from a byte array
 509  *
 510  * Attempt to unmarshall ipAddress from the given byte array at the
 511  * given offset, without overflowing the bound.  If the bound would be
 512  * overflown, an error is returned.
 513  *
 514  * The length should be the total length of the array.
 515  *
 516  * The offset will be modified by the number of bytes consumed, and that value
 517  * will be returned.  Thus a value of 0 is an error, meaning not enough
 518  * bytes to fill out the given type.
 519  *
 520  *  \param[out] ipAddress the LWES_IP_ADDR to read from the array and write into
 521  *  \param[in] bytes the byte array to read from
 522  *  \param[in] length total length of the byte array
 523  *  \param[in,out] offset the offset into the array, then the new offset
 524  *
 525  *  \return 0 on error, the number of bytes consumed on success.
 526  */
 527 int
 528 unmarshall_IP_ADDR
 529   (LWES_IP_ADDR *    ipAddress,
 530    LWES_BYTE_P       bytes,
 531    size_t            length,
 532    size_t *          offset);
 533
 534 /*! \brief Unmarshall a short string from a byte array
 535  *
 536  * Attempt to unmarshall aString from the given byte array at the
 537  * given offset, without overflowing the bound.  If the bound would be
 538  * overflown, an error is returned.
 539  *
 540  * The max_string_length is the maximum length of the passed in string.
 541  *
 542  * The length should be the total length of the array.
 543  *
 544  * The offset will be modified by the number of bytes consumed, and that value
 545  * will be returned.  Thus a value of 0 is an error, meaning not enough
 546  * bytes to fill out the given type.
 547  *
 548  *  \param[out] aString the LWES_SHORT_STRING to read from the array
 549  *                      and write into
 550  *  \param[in] max_string_length the total length of aString, this will not
 551  *                               be overflowed
 552  *  \param[in] bytes the byte array to read from
 553  *  \param[in] length total length of the byte array
 554  *  \param[in,out] offset the offset into the array, then the new offset
 555  *
 556  *  \return 0 on error, the number of bytes consumed on success.
 557  */
 558 int
 559 unmarshall_SHORT_STRING
 560   (LWES_SHORT_STRING aString,
 561    size_t            max_string_length,
 562    LWES_BYTE_P       bytes,
 563    size_t            length,
 564    size_t *          offset);
 565
 566 /*! \brief Unmarshall a long string from a byte array
 567  *
 568  * Attempt to unmarshall aString from the given byte array at the
 569  * given offset, without overflowing the bound.  If the bound would be
 570  * overflown, an error is returned.
 571  *
 572  * The max_string_length is the maximum length of the passed in string.
 573  *
 574  * The length should be the total length of the array.
 575  *
 576  * The offset will be modified by the number of bytes consumed, and that value
 577  * will be returned.  Thus a value of 0 is an error, meaning not enough
 578  * bytes to fill out the given type.
 579  *
 580  *  \param[out] aString the LWES_LONG_STRING to read from the array
 581  *                      and write into
 582  *  \param[in] max_string_length the total length of aString, this will not
 583  *                               be overflowed
 584  *  \param[in] bytes the byte array to read from
 585  *  \param[in] length total length of the byte array
 586  *  \param[in,out] offset the offset into the array, then the new offset
 587  *
 588  *  \return 0 on error, the number of bytes consumed on success.
 589  */
 590 int
 591 unmarshall_LONG_STRING
 592   (LWES_LONG_STRING aString,
 593    size_t           max_string_length,
 594    LWES_BYTE_P      bytes,
 595    size_t           length,
 596    size_t *         offset);
 597
 598 #ifdef __cplusplus
 599 }
 600 #endif
 601
 602 #endif /* __LWES_MARSHALL_FUNCTIONS_H */