36 /* The blob functions implement a simple, low-level API for serializing and
39  * All objects written to a blob will be serialized directly, (without any
42  * by knowing exactly what data is expected, or by writing to the blob
45  * A blob is efficient in that it dynamically grows by doubling in size, so
49 struct blob {  struct
50    /* The data actually written to the blob. Never read or write this directly
70     * allocation blob.  argument
78  *   1. blob->current should be equal to blob->end, (if not, too little was  argument
81  *   2. blob->overrun should be false, (otherwise, too much was read).
91  * Init a new, empty blob.
94 blob_init(struct blob *blob);
97  * Init a new, fixed-size blob.
99  * A fixed-size blob has a fixed block of data that will not be freed on
103  * If a fixed-size blob has a NULL data pointer then the data is written but
108 blob_init_fixed(struct blob *blob, void *data, size_t size);
111  * Finish a blob and free its memory.
113  * If \blob was initialized with blob_init_fixed, the data pointer is
117 blob_finish(struct blob *blob)  in blob_finish()  argument
119    if (!blob->fixed_allocation)  in blob_finish()
120       free(blob->data);  in blob_finish()
124 blob_finish_get_buffer(struct blob *blob, void **buffer, size_t *size);
127  * Aligns the blob to the given alignment.
134 blob_align(struct blob *blob, size_t alignment);
137  * Add some unstructured, fixed-size data to a blob.
142 blob_write_bytes(struct blob *blob, const void *bytes, size_t to_write);
145  * Reserve space in \blob for a number of bytes.
147  * Space will be allocated within the blob for these byes, but the bytes will
151  * \return An offset to space allocated within \blob to which \to_write bytes
155 blob_reserve_bytes(struct blob *blob, size_t to_write);
163 blob_reserve_uint32(struct blob *blob);
171 blob_reserve_intptr(struct blob *blob);
174  * Overwrite some data previously written to the blob.
176  * Writes data to an existing portion of the blob at an offset of \offset.
177  * This data range must have previously been written to the blob by one of the
183  * the current blob's size.
186 blob_overwrite_bytes(struct blob *blob,
192  * Add a uint8_t to a blob.
197 blob_write_uint8(struct blob *blob, uint8_t value);
200  * Overwrite a uint8_t previously written to the blob.
202  * Writes a uint8_t value to an existing portion of the blob at an offset of
203  * \offset.  This data range must have previously been written to the blob by
207  * the current blob's size.
210 blob_overwrite_uint8(struct blob *blob,
215  * Add a uint16_t to a blob.
218  * beginning of the blob's data, so some padding bytes may be added to the
219  * blob if this write follows some unaligned write (such as
225 blob_write_uint16(struct blob *blob, uint16_t value);
228  * Add a uint32_t to a blob.
231  * beginning of the blob's data, so some padding bytes may be added to the
232  * blob if this write follows some unaligned write (such as
238 blob_write_uint32(struct blob *blob, uint32_t value);
241  * Overwrite a uint32_t previously written to the blob.
243  * Writes a uint32_t value to an existing portion of the blob at an offset of
244  * \offset.  This data range must have previously been written to the blob by
252  *	offset = blob_reserve_uint32(blob);
253  *	... various blob write calls, writing N items ...
254  *	blob_overwrite_uint32 (blob, offset, N);
257  * the current blob's size.
260 blob_overwrite_uint32(struct blob *blob,
265  * Add a uint64_t to a blob.
268  * beginning of the blob's data, so some padding bytes may be added to the
269  * blob if this write follows some unaligned write (such as
275 blob_write_uint64(struct blob *blob, uint64_t value);
278  * Add an intptr_t to a blob.
281  * beginning of the blob's data, so some padding bytes may be added to the
282  * blob if this write follows some unaligned write (such as
288 blob_write_intptr(struct blob *blob, intptr_t value);
291  * Overwrite an intptr_t previously written to the blob.
293  * Writes a intptr_t value to an existing portion of the blob at an offset of
294  * \offset.  This data range must have previously been written to the blob by
300  * the current blob's size.
303 blob_overwrite_intptr(struct blob *blob,
308  * Add a NULL-terminated string to a blob, (including the NULL terminator).
313 blob_write_string(struct blob *blob, const char *str);
316  * Start reading a blob, (initializing the contents of \blob for reading).
327 blob_reader_init(struct blob_reader *blob, const void *data, size_t size);
330  * Align the current offset of the blob reader to the given alignment.
333  * particular alignment.  Note that this only aligns relative to blob->data
334  * and the alignment of the resulting pointer is only guaranteed if blob->data
338 blob_reader_align(struct blob_reader *blob, size_t alignment);
344  * \note The memory returned belongs to the data underlying the blob reader. The
346  * underlying the blob reader.
351 blob_read_bytes(struct blob_reader *blob, size_t size);
358 blob_copy_bytes(struct blob_reader *blob, void *dest, size_t size);
361  * Skip \size bytes within the blob.
364 blob_skip_bytes(struct blob_reader *blob, size_t size);
373 blob_read_uint8(struct blob_reader *blob);
380  * beginning of the blob's data, so some padding bytes may be skipped.
385 blob_read_uint16(struct blob_reader *blob);
392  * beginning of the blob's data, so some padding bytes may be skipped.
397 blob_read_uint32(struct blob_reader *blob);
404  * beginning of the blob's data, so some padding bytes may be skipped.
409 blob_read_uint64(struct blob_reader *blob);
416  * beginning of the blob's data, so some padding bytes may be skipped.
421 blob_read_intptr(struct blob_reader *blob);
427  * \note The memory returned belongs to the data underlying the blob reader. The
429  * of the data underlying the blob reader.
432  * there is no NULL byte remaining within the blob, this function returns
436 blob_read_string(struct blob_reader *blob);