Diffusion C API
6.7.9
|
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... | |
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.
A buffer for holding arbitrarily terminated byte arrays.
Functions are available (see (buf.h)) to manipulate the byte array.
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.
buf | The buffer. |
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.
buf | The buffer. |
Compare two buffers for equivalence.
This function considers a NULL buffer to be equivalent to an empty buffer (size 0).
a | A pointer to a buffer |
b | A pointer to a buffer |
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.
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.
buf | The buffer. |
bytes_to_remove | The number of bytes to be discarded. |
Creates a deep copy of an existing buffer.
buf_free
should be called on the pointer when no longer needed.
src | The buffer to copy. |
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.
buf | The buffer to be freed. |
char* buf_read_byte | ( | const char * | data, |
unsigned char * | val | ||
) |
Read a byte from a char array.
data | The source char array. |
val | The location in which to store the byte value. |
char* buf_read_float | ( | const char * | data, |
float * | val | ||
) |
Read a float (IEEE754 encoded) from a char array.
data | The source char array. |
val | The location in which to store the float. |
char* buf_read_string_length_enc | ( | const char * | data, |
char ** | dst_str, | ||
size_t * | len | ||
) |
Reads a length-encoded string from the char array.
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. |
char* buf_read_uint32 | ( | const char * | data, |
uint32_t * | val | ||
) |
Read an unencoded uint32_t from a char array.
data | The source char array. |
val | The location in which to store the int32. |
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.
data | The source char array. |
val | The location in which to store the int32 value. Is left unset if data is NULL or empty. |
char* buf_read_uint64 | ( | const char * | data, |
uint64_t * | val | ||
) |
Read an unencoded uint64_t from a char array.
data | The source char array. |
val | The location in which to store the int64. |
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.
data | The source char array. |
val | The location in which to store the int64 value. |
int buf_sprintf | ( | BUF_T * | dst, |
const char * | format, | ||
... | |||
) |
Safely write sprintf-style to a buffer.
dst | The buffer to append to. |
format | The printf format string. |
... | Arguments. |
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.
buf | The buffer. |
offset | The offset into the buffer. |
length | The length of the requested substr, or -1 for all remaining bytes. |
Concatenates two buffers.
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.
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.
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.
buf | The buffer to write to. |
val | The float to be appended to the buffer. |
Appends a list to the buffer.
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.
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.
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.
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.
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.
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.
buf | The buffer to display. |