ua_bytestring Struct Reference

This Built-in DataType defines a value that is a sequence of Byte values. More...

#include <bytestring.h>

Public Member Functions
void	ua_bytestring_init (struct ua_bytestring *bs)
	Initialize an ua_bytestring as empty bytestring.
int	ua_bytestring_create (struct ua_bytestring *bs, size_t size)
	Creates a new bytestring of given size. More...
void	ua_bytestring_clear (struct ua_bytestring *bs)
	Clear an ua_bytestring and set to empty bytestring.
void	ua_bytestring_clear_data (struct ua_bytestring *bs)
	Clears the contained data by setting all bytes to zero.
size_t	ua_bytestring_length (const struct ua_bytestring *bs)
	Returns the length of the bytestring in bytes. More...
char *	ua_bytestring_data (struct ua_bytestring *bs)
	Returns the raw data of bs. More...
const char *	ua_bytestring_const_data (const struct ua_bytestring *bs)
	Returns the raw string data of bs. More...
const unsigned char *	ua_bytestring_unsigned_const_data (const struct ua_bytestring *bs)
	Returns the raw string data of bs as unsigned byte array. More...
bool	ua_bytestring_is_null (const struct ua_bytestring *bs)
	Returns true if the given bytestring is a NULL bytestring.
int	ua_bytestring_compare (const struct ua_bytestring *a, const struct ua_bytestring *b)
	Compare to ua_bytestrings. More...
int	ua_bytestring_compare_data (const struct ua_bytestring *a, const void *data, int32_t len)
	Compares the given bytestring with a C byte array. More...
int	ua_bytestring_copy (struct ua_bytestring *dst, const struct ua_bytestring *src)
	Copy ua_bytestring src to dst. More...
int	ua_bytestring_set (struct ua_bytestring *bs, const char *src, int32_t len)
	Initializes the bytestring bs with the given data. More...
void	ua_bytestring_set_null (struct ua_bytestring *bs)
	Initializes the bytestring bs as null bytestring. More...
void	ua_bytestring_attach (struct ua_bytestring *bs, char *src, int32_t len)
	Initializes the bytestring bs with the given data. More...
int	ua_bytestring_resize (struct ua_bytestring *bs, int32_t len)
	Resize bytestring to given size. More...
int	ua_bytestring_copy_data (struct ua_bytestring *bs, const unsigned char *data, uint32_t len, uint32_t offset)
	Copy the given data into the bytestring bs. More...
int	ua_bytestring_append (struct ua_bytestring *dst, const struct ua_bytestring *src)
	Appends the bytestring src to the bytestring dst. More...
int	ua_bytestring_from_file (struct ua_bytestring *bs, const char *path)
	Read all bytes from a file and write it into a bytestring. More...
int	ua_bytestring_to_file (const struct ua_bytestring *bs, const char *path)
	Write all bytes from bytestring into a file. More...
int	ua_bytestring_to_hex (const struct ua_bytestring *bs, struct ua_string *hex, enum ua_string_format fmt)
	Converts the given bytestring into a hex string. More...
int	ua_bytestring_to_string (const struct ua_bytestring *bs, struct ua_string *dst)
	Creates a ua_string dst with base64 encoded content from a ua_bytestring bs. More...
int	ua_bytestring_snprintf (char *dst, size_t size, const struct ua_bytestring *bs)
	Converts the given bytestring into a base64 string. More...
int	ua_bytestring_from_string (struct ua_bytestring *bs, const struct ua_string *src)
	Creates a ua_bytestring bs from a given base46 string src. More...
int	ua_bytestring_sha1sum (const struct ua_bytestring *bs, struct ua_bytestring *sha1sum)
	Computes the SHA1 hash of the given bytestring bs. More...

Data Fields
int32_t	len
	Number of bytes, or -1 for a ‘null’ bytestring. More...
char *	data
	Pointer to actual array with bytes.

Related Functions
#define	UA_BYTESTRING_INITIALIZER   { 0, NULL }
	Initializer for empty ua_bytestrings.

Detailed Description

This Built-in DataType defines a value that is a sequence of Byte values.

Member Function Documentation

ua_bytestring_append()

int ua_bytestring_append	(	struct ua_bytestring *	dst,
		const struct ua_bytestring *	src
	)

Appends the bytestring src to the bytestring dst.

Returns

Zero on succes or errorcode on failure

ua_bytestring_attach()

void ua_bytestring_attach	(	struct ua_bytestring *	bs,
		char *	src,
		int32_t	len
	)

Initializes the bytestring bs with the given data.

This function takes ownership of src and will free it when calling ua_bytestring_clear().

ua_bytestring_compare()

int ua_bytestring_compare	(	const struct ua_bytestring *	a,
		const struct ua_bytestring *	b
	)

Compare to ua_bytestrings.

Returns

Zero if both are the same.

ua_bytestring_compare_data()

int ua_bytestring_compare_data	(	const struct ua_bytestring *	a,
		const void *	data,
		int32_t	len
	)

Compares the given bytestring with a C byte array.

Parameters

a	Bytestring to compare.
data	Data to compare with.
len	Length of data in bytes.

Returns

Zero if both are the same.

ua_bytestring_const_data()

const char * ua_bytestring_const_data

(

const struct ua_bytestring *

bs

)

Returns the raw string data of bs.

This version of the function returns a const pointer.

ua_bytestring_copy()

int ua_bytestring_copy	(	struct ua_bytestring *	dst,
		const struct ua_bytestring *	src
	)

Copy ua_bytestring src to dst.

Returns

Zero on success or errorcode on failure.

ua_bytestring_copy_data()

int ua_bytestring_copy_data	(	struct ua_bytestring *	bs,
		const unsigned char *	data,
		uint32_t	len,
		uint32_t	offset
	)

Copy the given data into the bytestring bs.

This operation checks the internal length to avoid memory corruption. It will only succeed if enough memory is available. It will only write all or nothing, so there is no truncation. Use ua_bytestring_resize to allocate enough memory.

Parameters

bs	Bytestring with enough memory to receive len bytes at offset.
data	Data to copy.
len	Length of bytes to copy.
offset	Byte offset to copy the data to in bytestring.

Returns

Zero on success or errorcode on failure:

• UA_EBADINVALIDARGUMENT if len is invalid

ua_bytestring_create()

int ua_bytestring_create	(	struct ua_bytestring *	bs,
		size_t	size
	)

Creates a new bytestring of given size.

This must be freed using ua_bytestring_clear(). To create a null bytestring use ua_bytestring_set_null, to create an empty bytestring use ua_bytestring_init.

Parameters

bs	Bytestring to initialize.
size	Number of bytes to allocated internally. This is limited to INT32_MAX.

ua_bytestring_data()

char * ua_bytestring_data

(

struct ua_bytestring *

bs

)

Returns the raw data of bs.

This pointer can be used to access and modify the data that compose the bytestring.

ua_bytestring_from_file()

int ua_bytestring_from_file	(	struct ua_bytestring *	bs,
		const char *	path
	)

Read all bytes from a file and write it into a bytestring.

The file is opened in binary mode. If the file is empty a NULL bytestring is returned.

Parameters

bs	Bytestring to write to.
path	Path of the file to read.

Returns

Zero on success or errorcode on failure.

ua_bytestring_from_string()

int ua_bytestring_from_string	(	struct ua_bytestring *	bs,
		const struct ua_string *	src
	)

Creates a ua_bytestring bs from a given base46 string src.

Parameters

bs	Destination for the base64 decoded bytestring. It is save to pass an uninitialized ua_bytestring.
src	ua_string with base64 encoded content to be decoded.

Returns

Returns 0 on success.

ua_bytestring_length()

size_t ua_bytestring_length

(

const struct ua_bytestring *

bs

)

Returns the length of the bytestring in bytes.

A value of 0 indicates an invalid argument or empty or null bytestring. To check for the latter use ua_bytestring_is_null.

ua_bytestring_resize()

int ua_bytestring_resize	(	struct ua_bytestring *	bs,
		int32_t	len
	)

Resize bytestring to given size.

When the size is increased the new data is uninitialized. Setting the size to 0 will actually free the memory.

Parameters

bs	Bytestring to resize.
len	New size in bytes. When len==0 the internal memory will be freed. Negative values are not allowed.

Returns

Zero on success or errorcode on failure:

• UA_EBADINVALIDARGUMENT if len is negative
• UA_EBADNOMEM if memory allocation fails

ua_bytestring_set()

int ua_bytestring_set	(	struct ua_bytestring *	bs,
		const char *	src,
		int32_t	len
	)

Initializes the bytestring bs with the given data.

This function creates a copy of src.

ua_bytestring_set_null()

void ua_bytestring_set_null

(

struct ua_bytestring *

bs

)

Initializes the bytestring bs as null bytestring.

Sometimes a distinction between empty and null bytestring is required, this function can set a null bytestring.

ua_bytestring_sha1sum()

int ua_bytestring_sha1sum	(	const struct ua_bytestring *	bs,
		struct ua_bytestring *	sha1sum
	)

Computes the SHA1 hash of the given bytestring bs.

Parameters

bs	Data to hash.
sha1sum	Returns the resulting hash. The caller must pass an initialized bytestring here. The internal memory will be (re-)allocated if required. The return value must be cleared using ua_bytestring_clear() by the caller if the operation succeeds.

Returns

Zero on success or errorcode on failure.

ua_bytestring_snprintf()

int ua_bytestring_snprintf	(	char *	dst,
		size_t	size,
		const struct ua_bytestring *	bs
	)

Converts the given bytestring into a base64 string.

Parameters

dst	Destination string where the base64 string will be written to.
size	Size in bytes of dst.
bs	The bytestring to be converted.

Returns

Upon successful return, these functions return the number of characters printed (excluding the null byte used to end output to strings). This function does not write more than size bytes (including the terminating null byte). If the output was truncated due to this limit then the return value is the number of characters (excluding the terminating null byte) which would have been written to the final string if enough space had been available. Thus, a return value of size or more means that the output was truncated.

ua_bytestring_to_file()

int ua_bytestring_to_file	(	const struct ua_bytestring *	bs,
		const char *	path
	)

Write all bytes from bytestring into a file.

The file is opened in binary mode.

Parameters

bs	Bytestring to be written, must be at least one byte.
path	Path of the file to create.

Returns

Zero on success or errorcode on failure.

ua_bytestring_to_hex()

int ua_bytestring_to_hex	(	const struct ua_bytestring *	bs,
		struct ua_string *	hex,
		enum ua_string_format	fmt
	)

Converts the given bytestring into a hex string.

Parameters

bs	Bytestring to convert.
hex	Returns the hex string. The resulting string must be freed using ua_string_clear if the operation succeeds.
fmt	Defines the resulting format of the hex string. Allowed values are only UA_STRING_UPPERCASE and UA_STRING_LOWERCASE, other values will result in a UA_EBADINVALIDARGUMENT error.

Returns

Zero on success, or a negative error code.

ua_bytestring_to_string()

int ua_bytestring_to_string	(	const struct ua_bytestring *	bs,
		struct ua_string *	dst
	)

Creates a ua_string dst with base64 encoded content from a ua_bytestring bs.

Parameters

bs	ua_bytestring to be converted to a base64 ua_string.
dst	ua_string to write the encoded data to. It is save to pass an uninitialized ua_string.

Returns

Returns 0 on success

ua_bytestring_unsigned_const_data()

const unsigned char * ua_bytestring_unsigned_const_data

(

const struct ua_bytestring *

bs

)

Returns the raw string data of bs as unsigned byte array.

This is an alternative for ua_bytestring_const_data, because some APIs expect unsigned byte arrays and this way ugly casts can be avoided when passing the bytestring data to such APIs.

Field Documentation

len

int32_t len

Number of bytes, or -1 for a ‘null’ bytestring.

---

The documentation for this struct was generated from the following files:

• /builds/products/embeddedstack/src/uabase/bytestring.h
• /builds/products/embeddedstack/src/uabase/bytestring.c