git.ozlabs.org Git - ccan/blob - ccan/pushpull/pull.h

   1 /* CC0 license (public domain) - see LICENSE file for details */
   2 #ifndef CCAN_PUSHPULL_PULL_H
   3 #define CCAN_PUSHPULL_PULL_H
   4 #include "config.h"
   5
   6 #include <stdbool.h>
   7 #include <stdint.h>
   8 #include <stdlib.h>
   9
  10 /**
  11  * pull_bytes - unmarshall bytes from push_bytes.
  12  * @p: pointer to bytes to unmarshal
  13  * @max_len: pointer to number of bytes in unmarshal buffer
  14  * @dst: destination to copy bytes (or NULL to discard)
  15  * @len: length to copy into @dst.
  16  *
  17  * If @max_len isn't long enough, @p is set to NULL, @max_len is set to
  18  * 0 (making chaining safe), and false is returned.  Otherwise, @len
  19  * bytes are copied from *@p into @dst, *@p is incremented by @len,
  20  * @max_len is decremented by @len, and true is returned.
  21  */
  22 bool pull_bytes(const char **p, size_t *max_len, void *dst, size_t len);
  23
  24 /**
  25  * pull_u64 - unmarshall a little-endian 64-bit value.
  26  * @p: pointer to bytes to unmarshal
  27  * @max_len: pointer to number of bytes in unmarshal buffer
  28  * @val: the value (or NULL to discard)
  29  *
  30  * This pulls 8 bytes and converts from little-endian (if necessary for
  31  * this platform).  It returns false and sets @p to NULL on error (ie. not
  32  * enough bytes).
  33  *
  34  * Example:
  35  * struct foo {
  36  *      uint64_t vu64;
  37  *      uint32_t vu32;
  38  *      uint16_t vu16;
  39  *      uint8_t vu8;
  40  * };
  41  *
  42  * static bool pull_foo(const char **p, size_t *len, struct foo *foo)
  43  * {
  44  *      pull_u64(p, len, &foo->vu64);
  45  *      pull_u32(p, len, &foo->vu32);
  46  *      pull_u16(p, len, &foo->vu16);
  47  *      pull_u8(p, len, &foo->vu8);
  48  *
  49  *      // p is set to NULL on error (we could also use return codes)
  50  *      return p != NULL;
  51  * }
  52  */
  53 bool pull_u64(const char **p, size_t *max_len, uint64_t *val);
  54
  55 /**
  56  * pull_u32 - unmarshall a little-endian 32-bit value.
  57  * @p: pointer to bytes to unmarshal
  58  * @max_len: pointer to number of bytes in unmarshal buffer
  59  * @val: the value (or NULL to discard)
  60  *
  61  * This pulls 4 bytes and converts from little-endian (if necessary for
  62  * this platform).
  63  */
  64 bool pull_u32(const char **p, size_t *max_len, uint32_t *val);
  65
  66 /**
  67  * pull_u16 - unmarshall a little-endian 16-bit value.
  68  * @p: pointer to bytes to unmarshal
  69  * @max_len: pointer to number of bytes in unmarshal buffer
  70  * @val: the value (or NULL to discard)
  71  *
  72  * This pulls 2 bytes and converts from little-endian (if necessary for
  73  * this platform).
  74  */
  75 bool pull_u16(const char **p, size_t *max_len, uint16_t *val);
  76
  77 /**
  78  * pull_u8 - unmarshall a single byte value.
  79  * @p: pointer to bytes to unmarshal
  80  * @max_len: pointer to number of bytes in unmarshal buffer
  81  * @val: the value (or NULL to discard)
  82  *
  83  * This pulls one byte.
  84  */
  85 bool pull_u8(const char **p, size_t *max_len, uint8_t *val);
  86 #define pull_uchar pull_u8
  87
  88 /**
  89  * pull_s64 - unmarshall a little-endian 64-bit signed value.
  90  * @p: pointer to bytes to unmarshal
  91  * @max_len: pointer to number of bytes in unmarshal buffer
  92  * @val: the value (or NULL to discard)
  93  *
  94  * This pulls 8 bytes and converts from little-endian (if necessary for
  95  * this platform).
  96  */
  97 bool pull_s64(const char **p, size_t *max_len, int64_t *val);
  98
  99 /**
 100  * pull_s32 - unmarshall a little-endian 32-bit signed value.
 101  * @p: pointer to bytes to unmarshal
 102  * @max_len: pointer to number of bytes in unmarshal buffer
 103  * @val: the value (or NULL to discard)
 104  *
 105  * This pulls 4 bytes and converts from little-endian (if necessary for
 106  * this platform).
 107  */
 108 bool pull_s32(const char **p, size_t *max_len, int32_t *val);
 109
 110 /**
 111  * pull_s16 - unmarshall a little-endian 16-bit signed value.
 112  * @p: pointer to bytes to unmarshal
 113  * @max_len: pointer to number of bytes in unmarshal buffer
 114  * @val: the value (or NULL to discard)
 115  *
 116  * This pulls 2 bytes and converts from little-endian (if necessary for
 117  * this platform).
 118  */
 119 bool pull_s16(const char **p, size_t *max_len, int16_t *val);
 120
 121 /**
 122  * pull_s8 - unmarshall a single byte signed value.
 123  * @p: pointer to bytes to unmarshal
 124  * @max_len: pointer to number of bytes in unmarshal buffer
 125  * @val: the value (or NULL to discard)
 126  *
 127  * This pulls one byte.
 128  */
 129 bool pull_s8(const char **p, size_t *max_len, int8_t *val);
 130
 131 /**
 132  * pull_char - unmarshall a single char value.
 133  * @p: pointer to bytes to unmarshal
 134  * @max_len: pointer to number of bytes in unmarshal buffer
 135  * @val: the value (or NULL to discard)
 136  *
 137  * This pulls one character.
 138  */
 139 bool pull_char(const char **p, size_t *max_len, char *val);
 140 #endif /* CCAN_PUSHPULL_PULL_H */