buf.h File Reference

Defines structures and functions for working with byte arrays of arbitrary length. More...

Data Structures
struct	buf_s
	A buffer for holding arbitrarily terminated byte arrays. More...

Typedefs
typedef struct buf_s	BUF_T
	A buffer for holding arbitrarily terminated byte arrays. More...

Functions
BUF_T *	buf_create (void)
	Allocate memory for a new buffer. More...
void	buf_free (BUF_T *buf)
	Free memory in the buffer, and the buffer itself. More...
void	hexdump_buf (BUF_T *buf)
	A utility function for displaying the contents of a buffer to stdout, in hexadecimal format. More...
BUF_T *	buf_dup (const BUF_T *src)
	Creates a deep copy of an existing buffer. More...
void	buf_write_uint64_enc (BUF_T *buf, const uint64_t val)
	Appends an unsigned 64-bit integer to the buffer in Diffusion's packeder integer format. More...
void	buf_write_uint32_enc (BUF_T *buf, const uint32_t val)
	Appends an unsigned 32-bit integer to the buffer in Diffusion's packed integer format. More...
void	buf_write_float (BUF_T *buf, const float val)
	Appends a float (IEEE-754 encoded) to the buffer. More...
void	buf_write_string (BUF_T *buf, const char *str)
	Append a NULL-terminated string to the buffer. More...
void	buf_write_string_enc (BUF_T *buf, const char *str)
	Append a length-encoded string to the buffer, where the string is NULL- terminated. More...
void	buf_write_string_length_enc (BUF_T *buf, const char *str, const uint64_t len)
	Append a length-encoded string to the buffer. More...
void	buf_write_byte (BUF_T *buf, const unsigned char b)
	Appends a single byte to the buffer. More...
void	buf_write_bytes (BUF_T *buf, const void *bytes, const size_t len)
	Appends an array of bytes to the buffer. More...
void	buf_write_list (BUF_T *buf, const LIST_T *list, void(*serialise_fn)(BUF_T *buf, void *))
	Appends a list to the buffer. More...
void	buf_write_buf (BUF_T *dst, const BUF_T *src)
	Concatenates two buffers. More...
int	buf_sprintf (BUF_T *dst, const char *format,...)
	Safely write sprintf-style to a buffer. More...
char *	buf_read_byte (const char *data, unsigned char *val)
	Read a byte from a char array. More...
char *	buf_read_uint32 (const char *data, uint32_t *val)
	Read an unencoded uint32_t from a char array. More...
char *	buf_read_uint64 (const char *data, uint64_t *val)
	Read an unencoded uint64_t from a char array. More...
char *	buf_read_float (const char *data, float *val)
	Read a float (IEEE754 encoded) from a char array. More...
char *	buf_read_uint32_enc (const char *data, uint32_t *val)
	Reads a int32 encoded in Diffusion's packed integer format from the char array. More...
char *	buf_read_uint64_enc (const char *data, uint64_t *val)
	Reads a int64 encoded in Diffusion's packed integer format from the char array. More...
char *	buf_read_string_length_enc (const char *data, char **dst_str, size_t *len)
	Reads a length-encoded string from the char array. More...
char *	buf_as_string (const BUF_T *buf)
	Returns the contents of the buffer as a NULL terminated string. More...
char *	buf_as_hex (const BUF_T *buf)
	Returns the contents of the buffer as a NULL terminated string of hex digits. More...
char *	buf_substr (const BUF_T *buf, int offset, int length)
	Returns a pointer to the underlying bytes of the BUF_T. More...
int	buf_cmp (const BUF_T *a, const BUF_T *b)
	Compare two buffers for equivalence. More...
void	buf_discard_front (BUF_T *buf, const int bytes_to_remove)
	Discard bytes from the front of a buffer. More...

Detailed Description

Defines structures and functions for working with byte arrays of arbitrary length.

These are mostly used in the serialisation and deserialisation of messages between the client and Diffusion, but are useful in a range of other situations.

Copyright © 2014, 2021 Push Technology Ltd., All Rights Reserved.

Use is subject to license terms.

NOTICE: All information contained herein is, and remains the property of Push Technology. The intellectual and technical concepts contained herein are proprietary to Push Technology and may be covered by U.S. and Foreign Patents, patents in process, and are protected by trade secret or copyright law.

Typedef Documentation

typedef struct buf_s BUF_T

A buffer for holding arbitrarily terminated byte arrays.

Functions are available (see (buf.h)) to manipulate the byte array.

Function Documentation

char* buf_as_hex

(

const BUF_T *

buf

)

Returns the contents of the buffer as a NULL terminated string of hex digits.

It is the caller's responsibility to free() the memory returned by this function.

Parameters

buf	The buffer.

Returns

A pointer to a NULL-terminated string.

char* buf_as_string

(

const BUF_T *

buf

)

Returns the contents of the buffer as a NULL terminated string.

Be aware that if the buffer contains NULL characters, then the returned string will too.

It is the caller's responsibility to free() the memory returned by this function.

Parameters

buf	The buffer.

Returns

A pointer to a NULL-terminated string.

int buf_cmp	(	const BUF_T *	a,
		const BUF_T *	b
	)

Compare two buffers for equivalence.

This function considers a NULL buffer to be equivalent to an empty buffer (size 0).

Parameters

a	A pointer to a buffer
b	A pointer to a buffer

Return values

0	if both buffers have the same length and contents.
-2	if the buffers differ in length
-1	if the buffers are the same length, but a is lexicographically less than b.
1	if the buffers are the same length, but a is lexicographically greater than b.

BUF_T* buf_create

(

void

)

Allocate memory for a new buffer.

Return values

BUF_T *	A pointer to a new buffer.
NULL	If the buffer cannot be created.

void buf_discard_front	(	BUF_T *	buf,
		const int	bytes_to_remove
	)

Discard bytes from the front of a buffer.

Removes bytes_to_remove bytes from the front of a buffer and discards them. The buffer is shrunk and holds the bytes after those which were discarded.

Parameters

buf	The buffer.
bytes_to_remove	The number of bytes to be discarded.

BUF_T* buf_dup

(

const BUF_T *

src

)

Creates a deep copy of an existing buffer.

buf_free should be called on the pointer when no longer needed.

Parameters

src	The buffer to copy.

Return values

BUF_t *	A newly allocated buffer.
NULL	If the new buffer cannot be created.

void buf_free

(

BUF_T *

buf

)

Free memory in the buffer, and the buffer itself.

Parameters

buf	The buffer to be freed.

char* buf_read_byte	(	const char *	data,
		unsigned char *	val
	)

Read a byte from a char array.

Parameters

data	The source char array.
val	The location in which to store the byte value.

Returns

The address in the source char array following the byte which has been read.

char* buf_read_float	(	const char *	data,
		float *	val
	)

Read a float (IEEE754 encoded) from a char array.

Parameters

data	The source char array.
val	The location in which to store the float.

Returns

The address in the source char array following the float which has been read.

char* buf_read_string_length_enc	(	const char *	data,
		char **	dst_str,
		size_t *	len
	)

Reads a length-encoded string from the char array.

Parameters

data	The source char array.
dst_str	A pointer to a location in which to the string is stored once it has been read. This memory is allocated by the API, but the user should free() it once it is no longer required.
len	The length of the string which has been read. Can be NULL.

Returns

The address in the source char array following the string which has been read.

char* buf_read_uint32	(	const char *	data,
		uint32_t *	val
	)

Read an unencoded uint32_t from a char array.

Parameters

data	The source char array.
val	The location in which to store the int32.

Returns

The address in the source char array following the int32 which has been read.

char* buf_read_uint32_enc	(	const char *	data,
		uint32_t *	val
	)

Reads a int32 encoded in Diffusion's packed integer format from the char array.

Parameters

data	The source char array.
val	The location in which to store the int32 value. Is left unset if data is NULL or empty.

Returns

The address in the source char array following the int32 which has been read.

char* buf_read_uint64	(	const char *	data,
		uint64_t *	val
	)

Read an unencoded uint64_t from a char array.

Parameters

data	The source char array.
val	The location in which to store the int64.

Returns

The address in the source char array following the int64 which has been read.

char* buf_read_uint64_enc	(	const char *	data,
		uint64_t *	val
	)

Reads a int64 encoded in Diffusion's packed integer format from the char array.

Parameters

data	The source char array.
val	The location in which to store the int64 value.

Returns

The address in the source char array following the int64 which has been read.

int buf_sprintf	(	BUF_T *	dst,
		const char *	format,
			...
	)

Safely write sprintf-style to a buffer.

Parameters

dst	The buffer to append to.
format	The printf format string.
...	Arguments.

Returns

The number of bytes written, or < 0 on error.

char* buf_substr	(	const BUF_T *	buf,
		int	offset,
		int	length
	)

Returns a pointer to the underlying bytes of the BUF_T.

If the requested range of bytes is outside those contained within the buffer, NULL is returned. No memory is copied in this function; it is incorrect to free() the returned pointer.

Parameters

buf	The buffer.
offset	The offset into the buffer.
length	The length of the requested substr, or -1 for all remaining bytes.

Returns

A pointer to the offset within the underlying bytes, or NULL on error. It is not guaranteed to be a NULL-terminated series of bytes.

void buf_write_buf	(	BUF_T *	dst,
		const BUF_T *	src
	)

Concatenates two buffers.

Parameters

dst	The buffer to append to.
src	The buffer containing data to append.

void buf_write_byte	(	BUF_T *	buf,
		const unsigned char	b
	)

Appends a single byte to the buffer.

Parameters

buf	The buffer to write to.
b	The byte to write.

void buf_write_bytes	(	BUF_T *	buf,
		const void *	bytes,
		const size_t	len
	)

Appends an array of bytes to the buffer.

Parameters

buf	The buffer to write to.
bytes	The bytes to be appended to the buffer.
len	The length of the byte array to be written.

void buf_write_float	(	BUF_T *	buf,
		const float	val
	)

Appends a float (IEEE-754 encoded) to the buffer.

Parameters

buf	The buffer to write to.
val	The float to be appended to the buffer.

void buf_write_list	(	BUF_T *	buf,
		const LIST_T *	list,
		void(*)(BUF_T *buf, void *)	serialise_fn
	)

Appends a list to the buffer.

Parameters

buf	The buffer to write to.
list	The list to be appended to the buffer.
serialise_fn	The serialiser function for the list elements.

void buf_write_string	(	BUF_T *	buf,
		const char *	str
	)

Append a NULL-terminated string to the buffer.

Parameters

buf	The buffer to write to.
str	The NULL-terminated string to be appended to the buffer.

void buf_write_string_enc	(	BUF_T *	buf,
		const char *	str
	)

Append a length-encoded string to the buffer, where the string is NULL- terminated.

Parameters

buf	The buffer to write to.
str	The NULL-terminated string to be appended to the buffer.

void buf_write_string_length_enc	(	BUF_T *	buf,
		const char *	str,
		const uint64_t	len
	)

Append a length-encoded string to the buffer.

Parameters

buf	The buffer to write to.
str	The string to be appended to the buffer.
len	The length of the string to write.

void buf_write_uint32_enc	(	BUF_T *	buf,
		const uint32_t	val
	)

Appends an unsigned 32-bit integer to the buffer in Diffusion's packed integer format.

Parameters

buf	The buffer to write to.
val	A 32-bit unsigned integer.

void buf_write_uint64_enc	(	BUF_T *	buf,
		const uint64_t	val
	)

Appends an unsigned 64-bit integer to the buffer in Diffusion's packeder integer format.

Parameters

buf	The buffer to write to.
val	A 64-bit unsigned integer.

void hexdump_buf

(

BUF_T *

buf

)

A utility function for displaying the contents of a buffer to stdout, in hexadecimal format.

Parameters

buf	The buffer to display.