pushpull: new module.
[ccan] / 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 */