ldns/ldns/buffer.h

2  * buffer.h -- generic memory buffer.
9  * The buffer module implements a generic buffer.  The API is based on
30  * number of initial bytes in buffer of
36  * \file buffer.h
45  * to the current end of a buffer, read from the current position, and
58 	/** The amount of data the buffer can contain */
61 	/** The data contained in the buffer */
64 	/** If the buffer is fixed it cannot be resized */
67 	/** The current state of the buffer. If writing to the buffer fails
77 ldns_buffer_invariant(ldns_buffer *ATTR_UNUSED(buffer))
82 ldns_buffer_invariant(ldns_buffer *buffer)
84 	assert(buffer != NULL);
85 	assert(buffer->_position <= buffer->_limit);
86 	assert(buffer->_limit <= buffer->_capacity);
87 	assert(buffer->_data != NULL);
92  * creates a new buffer with the specified capacity.
94  * \param[in] capacity the size (in bytes) to allocate for the buffer
95  * \return the created buffer
100  * creates a buffer with the specified data.  The data IS copied
101  * and MEMORY allocations are done.  The buffer is not fixed and can
104  * \param[in] buffer pointer to the buffer to put the data in
105  * \param[in] data the data to encapsulate in the buffer
108 void ldns_buffer_new_frm_data(ldns_buffer *buffer, void *data, size_t size);
111  * clears the buffer and make it ready for writing.  The buffer's limit
113  * \param[in] buffer the buffer to clear
115 INLINE void ldns_buffer_clear(ldns_buffer *buffer)
117 	ldns_buffer_invariant(buffer);
121 	buffer->_position = 0;
122 	buffer->_limit = buffer->_capacity;
126  * makes the buffer ready for reading the data that has been written to
127  * the buffer.  The buffer's limit is set to the current position and
130  * \param[in] buffer the buffer to flip
133 INLINE void ldns_buffer_flip(ldns_buffer *buffer)
135 	ldns_buffer_invariant(buffer);
137 	buffer->_limit = buffer->_position;
138 	buffer->_position = 0;
142  * make the buffer ready for re-reading the data.  The buffer's
144  * \param[in] buffer the buffer to rewind
146 INLINE void ldns_buffer_rewind(ldns_buffer *buffer)
148 	ldns_buffer_invariant(buffer);
150 	buffer->_position = 0;
154  * returns the current position in the buffer (as a number of bytes)
155  * \param[in] buffer the buffer
159 ldns_buffer_position(ldns_buffer *buffer)
161 	return buffer->_position;
165  * sets the buffer's position to MARK.  The position must be less than
166  * or equal to the buffer's limit.
167  * \param[in] buffer the buffer
171 ldns_buffer_set_position(ldns_buffer *buffer, size_t mark)
173 	assert(mark <= buffer->_limit);
174 	buffer->_position = mark;
178  * changes the buffer's position by COUNT bytes.  The position must not
179  * be moved behind the buffer's limit or before the beginning of the
180  * buffer.
181  * \param[in] buffer the buffer
185 ldns_buffer_skip(ldns_buffer *buffer, ssize_t count)
187 	assert(buffer->_position + count <= buffer->_limit);
188 	buffer->_position += count;
192  * returns the maximum size of the buffer
193  * \param[in] buffer
197 ldns_buffer_limit(ldns_buffer *buffer)
199 	return buffer->_limit;
203  * changes the buffer's limit.  If the buffer's position is greater
205  * \param[in] buffer the buffer
209 ldns_buffer_set_limit(ldns_buffer *buffer, size_t limit)
211 	assert(limit <= buffer->_capacity);
212 	buffer->_limit = limit;
213 	if (buffer->_position > buffer->_limit)
214 		buffer->_position = buffer->_limit;
218  * returns the number of bytes the buffer can hold.
219  * \param[in] buffer the buffer
223 ldns_buffer_capacity(ldns_buffer *buffer)
225 	return buffer->_capacity;
229  * changes the buffer's capacity.  The data is reallocated so any
230  * pointers to the data may become invalid.  The buffer's limit is set
231  * to the buffer's new capacity.
232  * \param[in] buffer the buffer
236 bool ldns_buffer_set_capacity(ldns_buffer *buffer, size_t capacity);
239  * ensures BUFFER can contain at least AMOUNT more bytes.  The buffer's
242  * The buffer's limit is always set to the (possibly increased)
244  * \param[in] buffer the buffer
248 bool ldns_buffer_reserve(ldns_buffer *buffer, size_t amount);
252  * \param[in] buffer the buffer
257 ldns_buffer_at(const ldns_buffer *buffer, size_t at)
259 	assert(at <= buffer->_limit);
260 	return buffer->_data + at;
264  * returns a pointer to the beginning of the buffer (the data at
266  * \param[in] buffer the buffer
270 ldns_buffer_begin(const ldns_buffer *buffer)
272 	return ldns_buffer_at(buffer, 0);
276  * returns a pointer to the end of the buffer (the data at the buffer's
278  * \param[in] buffer the buffer
282 ldns_buffer_end(ldns_buffer *buffer)
284 	return ldns_buffer_at(buffer, buffer->_limit);
288  * returns a pointer to the data at the buffer's current position.
289  * \param[in] buffer the buffer
293 ldns_buffer_current(ldns_buffer *buffer)
295 	return ldns_buffer_at(buffer, buffer->_position);
301  * \param[in] buffer the buffer
306 ldns_buffer_remaining_at(ldns_buffer *buffer, size_t at)
308 	ldns_buffer_invariant(buffer);
309 	assert(at <= buffer->_limit);
310 	return buffer->_limit - at;
314  * returns the number of bytes remaining between the buffer's position and
316  * \param[in] buffer the buffer
320 ldns_buffer_remaining(ldns_buffer *buffer)
322 	return ldns_buffer_remaining_at(buffer, buffer->_position);
326  * checks if the buffer has at least COUNT more bytes available.
329  * \param[in] buffer the buffer
335 ldns_buffer_available_at(ldns_buffer *buffer, size_t at, size_t count)
337 	return count <= ldns_buffer_remaining_at(buffer, at);
341  * checks if the buffer has count bytes available at the current position
342  * \param[in] buffer the buffer
347 ldns_buffer_available(ldns_buffer *buffer, size_t count)
349 	return ldns_buffer_available_at(buffer, buffer->_position, count);
353  * writes the given data to the buffer at the specified position
354  * \param[in] buffer the buffer
356  * \param[in] data pointer to the data to write to the buffer
360 ldns_buffer_write_at(ldns_buffer *buffer, size_t at, const void *data, size_t count)
362 	assert(ldns_buffer_available_at(buffer, at, count));
363 	memcpy(buffer->_data + at, data, count);
367  * writes count bytes of data to the current position of the buffer
368  * \param[in] buffer the buffer
373 ldns_buffer_write(ldns_buffer *buffer, const void *data, size_t count)
375 	ldns_buffer_write_at(buffer, buffer->_position, data, count);
376 	buffer->_position += count;
380  * copies the given (null-delimited) string to the specified position at the buffer
381  * \param[in] buffer the buffer
382  * \param[in] at the position in the buffer
386 ldns_buffer_write_string_at(ldns_buffer *buffer, size_t at, const char *str)
388 	ldns_buffer_write_at(buffer, at, str, strlen(str));
392  * copies the given (null-delimited) string to the current position at the buffer
393  * \param[in] buffer the buffer
397 ldns_buffer_write_string(ldns_buffer *buffer, const char *str)
399 	ldns_buffer_write(buffer, str, strlen(str));
403  * writes the given byte of data at the given position in the buffer
404  * \param[in] buffer the buffer
405  * \param[in] at the position in the buffer
409 ldns_buffer_write_u8_at(ldns_buffer *buffer, size_t at, uint8_t data)
411 	assert(ldns_buffer_available_at(buffer, at, sizeof(data)));
412 	buffer->_data[at] = data;
416  * writes the given byte of data at the current position in the buffer
417  * \param[in] buffer the buffer
421 ldns_buffer_write_u8(ldns_buffer *buffer, uint8_t data)
423 	ldns_buffer_write_u8_at(buffer, buffer->_position, data);
424 	buffer->_position += sizeof(data);
428  * writes the given 2 byte integer at the given position in the buffer
429  * \param[in] buffer the buffer
430  * \param[in] at the position in the buffer
434 ldns_buffer_write_u16_at(ldns_buffer *buffer, size_t at, uint16_t data)
436 	assert(ldns_buffer_available_at(buffer, at, sizeof(data)));
437 	ldns_write_uint16(buffer->_data + at, data);
441  * writes the given 2 byte integer at the current position in the buffer
442  * \param[in] buffer the buffer
446 ldns_buffer_write_u16(ldns_buffer *buffer, uint16_t data)
448 	ldns_buffer_write_u16_at(buffer, buffer->_position, data);
449 	buffer->_position += sizeof(data);
453  * writes the given 4 byte integer at the given position in the buffer
454  * \param[in] buffer the buffer
455  * \param[in] at the position in the buffer
459 ldns_buffer_write_u32_at(ldns_buffer *buffer, size_t at, uint32_t data)
461 	assert(ldns_buffer_available_at(buffer, at, sizeof(data)));
462 	ldns_write_uint32(buffer->_data + at, data);
466  * writes the given 4 byte integer at the current position in the buffer
467  * \param[in] buffer the buffer
471 ldns_buffer_write_u32(ldns_buffer *buffer, uint32_t data)
473 	ldns_buffer_write_u32_at(buffer, buffer->_position, data);
474 	buffer->_position += sizeof(data);
479  * \param[in] buffer the buffer
480  * \param[in] at the position in the buffer to start
481  * \param[out] data buffer to copy to
485 ldns_buffer_read_at(ldns_buffer *buffer, size_t at, void *data, size_t count)
487 	assert(ldns_buffer_available_at(buffer, at, count));
488 	memcpy(data, buffer->_data + at, count);
493  * \param[in] buffer the buffer
494  * \param[out] data buffer to copy to
498 ldns_buffer_read(ldns_buffer *buffer, void *data, size_t count)
500 	ldns_buffer_read_at(buffer, buffer->_position, data, count);
501 	buffer->_position += count;
505  * returns the byte value at the given position in the buffer
506  * \param[in] buffer the buffer
507  * \param[in] at the position in the buffer
511 ldns_buffer_read_u8_at(ldns_buffer *buffer, size_t at)
513 	assert(ldns_buffer_available_at(buffer, at, sizeof(uint8_t)));
514 	return buffer->_data[at];
518  * returns the byte value at the current position in the buffer
519  * \param[in] buffer the buffer
523 ldns_buffer_read_u8(ldns_buffer *buffer)
525 	uint8_t result = ldns_buffer_read_u8_at(buffer, buffer->_position);
526 	buffer->_position += sizeof(uint8_t);
531  * returns the 2-byte integer value at the given position in the buffer
532  * \param[in] buffer the buffer
533  * \param[in] at position in the buffer
537 ldns_buffer_read_u16_at(ldns_buffer *buffer, size_t at)
539 	assert(ldns_buffer_available_at(buffer, at, sizeof(uint16_t)));
540 	return ldns_read_uint16(buffer->_data + at);
544  * returns the 2-byte integer value at the current position in the buffer
545  * \param[in] buffer the buffer
549 ldns_buffer_read_u16(ldns_buffer *buffer)
551 	uint16_t result = ldns_buffer_read_u16_at(buffer, buffer->_position);
552 	buffer->_position += sizeof(uint16_t);
557  * returns the 4-byte integer value at the given position in the buffer
558  * \param[in] buffer the buffer
559  * \param[in] at position in the buffer
563 ldns_buffer_read_u32_at(ldns_buffer *buffer, size_t at)
565 	assert(ldns_buffer_available_at(buffer, at, sizeof(uint32_t)));
566 	return ldns_read_uint32(buffer->_data + at);
570  * returns the 4-byte integer value at the current position in the buffer
571  * \param[in] buffer the buffer
575 ldns_buffer_read_u32(ldns_buffer *buffer)
577 	uint32_t result = ldns_buffer_read_u32_at(buffer, buffer->_position);
578 	buffer->_position += sizeof(uint32_t);
583  * returns the status of the buffer
584  * \param[in] buffer
588 ldns_buffer_status(ldns_buffer *buffer)
590 	return buffer->_status;
594  * returns true if the status of the buffer is LDNS_STATUS_OK, false otherwise
595  * \param[in] buffer the buffer
599 ldns_buffer_status_ok(ldns_buffer *buffer)
601 	if (buffer) {
602 		return ldns_buffer_status(buffer) == LDNS_STATUS_OK;
609  * prints to the buffer, increasing the capacity if required using
610  * buffer_reserve(). The buffer's position is set to the terminating '\\0'
614 int ldns_buffer_printf(ldns_buffer *buffer, const char *format, ...);
618  * frees the buffer.
619  * \param[in] *buffer the buffer to be freed
622 void ldns_buffer_free(ldns_buffer *buffer);
625  * Makes the buffer fixed and returns a pointer to the data.  The
627  * \param[in] *buffer the buffer to be exported
630 void *ldns_buffer_export(ldns_buffer *buffer);
633  * Copy contents of the from buffer to the result buffer and then flips
634  * the result buffer. Data will be silently truncated if the result buffer is
636  * \param[out] *result resulting buffer which is copied to.