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. */
67     * allocation blob.  argument
75  *   1. blob->current should be equal to blob->end, (if not, too little was  argument
78  *   2. blob->overrun should be false, (otherwise, too much was read).
88  * Init a new, empty blob.
91 blob_init(struct blob *blob);
94  * Init a new, fixed-size blob.
96  * A fixed-size blob has a fixed block of data that will not be freed on
100  * If a fixed-size blob has a NULL data pointer then the data is written but
105 blob_init_fixed(struct blob *blob, void *data, size_t size);
108  * Finish a blob and free its memory.
110  * If \blob was initialized with blob_init_fixed, the data pointer is
114 blob_finish(struct blob *blob)  in blob_finish()  argument
116    if (!blob->fixed_allocation)  in blob_finish()
117       free(blob->data);  in blob_finish()
121 blob_finish_get_buffer(struct blob *blob, void **buffer, size_t *size);
124  * Add some unstructured, fixed-size data to a blob.
129 blob_write_bytes(struct blob *blob, const void *bytes, size_t to_write);
132  * Reserve space in \blob for a number of bytes.
134  * Space will be allocated within the blob for these byes, but the bytes will
138  * \return An offset to space allocated within \blob to which \to_write bytes
142 blob_reserve_bytes(struct blob *blob, size_t to_write);
150 blob_reserve_uint32(struct blob *blob);
158 blob_reserve_intptr(struct blob *blob);
161  * Overwrite some data previously written to the blob.
163  * Writes data to an existing portion of the blob at an offset of \offset.
164  * This data range must have previously been written to the blob by one of the
170  * the current blob's size.
173 blob_overwrite_bytes(struct blob *blob,
179  * Add a uint8_t to a blob.
184 blob_write_uint8(struct blob *blob, uint8_t value);
187  * Overwrite a uint8_t previously written to the blob.
189  * Writes a uint8_t value to an existing portion of the blob at an offset of
190  * \offset.  This data range must have previously been written to the blob by
194  * the current blob's size.
197 blob_overwrite_uint8(struct blob *blob,
202  * Add a uint16_t to a blob.
205  * beginning of the blob's data, so some padding bytes may be added to the
206  * blob if this write follows some unaligned write (such as
212 blob_write_uint16(struct blob *blob, uint16_t value);
215  * Add a uint32_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_uint32(struct blob *blob, uint32_t value);
228  * Overwrite a uint32_t previously written to the blob.
230  * Writes a uint32_t value to an existing portion of the blob at an offset of
231  * \offset.  This data range must have previously been written to the blob by
239  *	offset = blob_reserve_uint32(blob);
240  *	... various blob write calls, writing N items ...
241  *	blob_overwrite_uint32 (blob, offset, N);
244  * the current blob's size.
247 blob_overwrite_uint32(struct blob *blob,
252  * Add a uint64_t to a blob.
255  * beginning of the blob's data, so some padding bytes may be added to the
256  * blob if this write follows some unaligned write (such as
262 blob_write_uint64(struct blob *blob, uint64_t value);
265  * Add an intptr_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_intptr(struct blob *blob, intptr_t value);
278  * Overwrite an intptr_t previously written to the blob.
280  * Writes a intptr_t value to an existing portion of the blob at an offset of
281  * \offset.  This data range must have previously been written to the blob by
287  * the current blob's size.
290 blob_overwrite_intptr(struct blob *blob,
295  * Add a NULL-terminated string to a blob, (including the NULL terminator).
300 blob_write_string(struct blob *blob, const char *str);
303  * Start reading a blob, (initializing the contents of \blob for reading).
314 blob_reader_init(struct blob_reader *blob, const void *data, size_t size);
320  * \note The memory returned belongs to the data underlying the blob reader. The
322  * underlying the blob reader.
327 blob_read_bytes(struct blob_reader *blob, size_t size);
334 blob_copy_bytes(struct blob_reader *blob, void *dest, size_t size);
337  * Skip \size bytes within the blob.
340 blob_skip_bytes(struct blob_reader *blob, size_t size);
349 blob_read_uint8(struct blob_reader *blob);
356  * beginning of the blob's data, so some padding bytes may be skipped.
361 blob_read_uint16(struct blob_reader *blob);
368  * beginning of the blob's data, so some padding bytes may be skipped.
373 blob_read_uint32(struct blob_reader *blob);
380  * beginning of the blob's data, so some padding bytes may be skipped.
385 blob_read_uint64(struct blob_reader *blob);
392  * beginning of the blob's data, so some padding bytes may be skipped.
397 blob_read_intptr(struct blob_reader *blob);
403  * \note The memory returned belongs to the data underlying the blob reader. The
405  * of the data underlying the blob reader.
408  * there is no NULL byte remaining within the blob, this function returns
412 blob_read_string(struct blob_reader *blob);