Diffusion C API  6.3.3
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
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_Tbuf_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_Tbuf_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_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, 2015 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
bufThe 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
bufThe 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
aA pointer to a buffer
bA pointer to a buffer
Return values
0if both buffers have the same length and contents.
-2if the buffers differ in length
-1if the buffers are the same length, but a is lexicographically less than b.
1if 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.
NULLIf 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
bufThe buffer.
bytes_to_removeThe number of bytes to be discarded.
BUF_T* buf_dup ( const BUF_T src)

Creates a deep copy of an existing buffer.

Parameters
srcThe buffer to copy.
Return values
BUF_t *A newly allocated buffer.
NULLIf the new buffer cannot be created.
void buf_free ( BUF_T buf)

Free memory in the buffer, and the buffer itself.

Parameters
bufThe buffer to be freed.
char* buf_read_byte ( const char *  data,
unsigned char *  val 
)

Read a byte from a char array.

Parameters
dataThe source char array.
valThe 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
dataThe source char array.
valThe 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
dataThe source char array.
dst_strA 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.
lenThe length of the string which has been read.
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
dataThe source char array.
valThe 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
dataThe source char array.
valThe location in which to store the int32 value.
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
dataThe source char array.
valThe 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
dataThe source char array.
valThe 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
dstThe buffer to append to.
formatThe 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
bufThe buffer.
offsetThe offset into the buffer.
lengthThe 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
dstThe buffer to append to.
srcThe buffer containing data to append.
void buf_write_byte ( BUF_T buf,
const unsigned char  b 
)

Appends a single byte to the buffer.

Parameters
bufThe buffer to write to.
bThe 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
bufThe buffer to write to.
bytesThe bytes to be appended to the buffer.
lenThe 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
bufThe buffer to write to.
valThe float to be appended to the buffer.
void buf_write_string ( BUF_T buf,
const char *  str 
)

Append a NULL-terminated string to the buffer.

Parameters
bufThe buffer to write to.
strThe 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
bufThe buffer to write to.
strThe 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
bufThe buffer to write to.
strThe string to be appended to the buffer.
lenThe 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
bufThe buffer to write to.
valA 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
bufThe buffer to write to.
valA 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
bufThe buffer to display.