This encapsulates a UTF-8 encoded OPC UA string. More...

#include <string.h>

Public Member Functions
static char *	ua_string_strndup (const char *s, size_t n)
	Creates a duplicate of the string `s`. More...

void	ua_string_init (struct ua_string *s)
	Initializes `s` with a null string, so it is safe to clear or perform further operations. More...

void	ua_string_clear (struct ua_string *s)
	Release allocated resources for `s`. More...

void	ua_string_clear_s (struct ua_string *s)
	Securely clears a string. More...

int	ua_string_allocate (struct ua_string *s, size_t size)
	Allocate a string with length `len` bytes. More...

int	ua_string_set (struct ua_string s, const char src)
	Initializes `s` with a copy of `src`. More...

int	ua_string_setn (struct ua_string s, const char src, size_t len)
	Initializes `s` with a copy of `src`. More...

void	ua_string_attach (struct ua_string s, char src)
	Initializes `s` with `src`. More...

void	ua_string_attachn (struct ua_string s, char src, size_t len)
	Initializes `s` with `src`. More...

void	ua_string_attach_const (struct ua_string s, const char src)
	Initializes `s` with string constant `src`. More...

void	ua_string_attachn_const (struct ua_string s, const char src, size_t len)
	Initializes `s` with string constant `src`. More...

int	ua_string_smart_attach_const (struct ua_string s, const char src)
	Simple wrapper for ua_string_attach_const or ua_string_set. More...

int	ua_string_smart_attachn_const (struct ua_string s, const char src, size_t len)
	Simple wrapper for ua_string_attachn_const or ua_string_setn. More...

int	ua_string_compare_lex (const struct ua_string a, const struct ua_string b)
	The compare function returns zero if both strings are equal. More...

int	ua_string_compare (const struct ua_string a, const struct ua_string b)
	The compare function returns zero if both strings are equal. More...

int	ua_string_compare_const (const struct ua_string a, const char b)
	Compares a UA string with a string constant. More...

int	ua_string_comparen_const (const struct ua_string a, const char b, size_t len)
	Compares a UA string with a string constant of known length. More...

int	ua_string_copy (struct ua_string dst, const struct ua_string src)
	Creates a copy of the string `src` including the terminating null byte. More...

int	ua_string_cat (struct ua_string dst, size_t size, const struct ua_string src)
	Appends a copy of `src` to the end of `dst`. More...

int	ua_string_catf (struct ua_string dst, size_t size, const char fmt,...)
	Appends a formatted string to the end of `dst`. More...

int	ua_string_snprintf (struct ua_string s, size_t size, const char fmt,...)
	Replaces the given string `s` with a formatted string. More...

size_t	ua_string_length (const struct ua_string *s)
	Returns the length of the string in bytes excluding the zero terminator. More...

char *	ua_string_data (struct ua_string *s)
	Returns the raw string data of `s`. More...

const char *	ua_string_const_data (const struct ua_string *s)
	Returns the raw string data of `s`. More...

bool	ua_string_is_null (const struct ua_string *s)
	Returns true if the given string is a NULL string. More...

bool	ua_string_is_empty (const struct ua_string *s)
	Returns true if the given string is a valid empty string. More...

const char *	ua_string_printable (const struct ua_string *s)
	Return a printable representation of a ua_string. More...

int	ua_string_index_of (const struct ua_string s, const char substr)
	Searches for the substring `substr` in the given ua string `s`. More...

int	ua_string_replace (struct ua_string s, const char search, const char *replace)
	Replaces the first occurance of `search` in `s` with `replace`. More...

int	ua_string_trim (struct ua_string *s)
	Removes leading and trailing white spaces from string. More...

int	ua_string_from_file (struct ua_string s, const char path)
	Read all bytes from a file and write it into a string. More...

int	ua_string_to_file (struct ua_string s, const char path)
	Write all characters from string into a file. More...

bool	ua_string_is_zeroterminated (const struct ua_string *s)
	Returns true if the string is zero terminated. More...

Data Fields
uint32_t	len: 31
	Length of the string. More...

uint32_t	free: 1
	Bit to indicate if the data pointer must be freed. More...

union {
const char * cdata
	Const pointer to the data. More...

char * data
	Non-const pointer to the data. More...

}	d
	The string data. More...

Related Functions
#define	UA_STRING_INITIALIZER { 0, 0, { NULL } }
	Initializer for null strings.

#define	UA_STRING_FROM_C_STRING(s) { sizeof(s)-1, 0, { s } }
	Initializer for ua_strings from string constants.

Detailed Description

This encapsulates a UTF-8 encoded OPC UA string.

Note, on the wire OPC UA String are not zero terminated, in memory we always add a zero terminator to avoid problems with C functions that expect zero terminated strings.

Member Function Documentation

◆ ua_string_allocate()

int ua_string_allocate	(	struct ua_string *	s,
		size_t	size
	)

Allocate a string with length len bytes.

This creates an empty string, but with an internal buffer of len bytes. Note that one byte is reserved for the null terminator. If you want to store a string with length n you need to allocate n+1 bytes.

Example:

struct ua_string tmp;
ua_string_allocate(tmp, 39);
ua_guid_snprintf(tmp.data, 39, &guid);

◆ ua_string_attach()

void ua_string_attach	(	struct ua_string *	s,
		char *	src
	)

Initializes s with src.

This function takes ownership of src which means the memory of src will be freed when this string gets cleared using ua_string_clear. If src is NULL, s will be initialized as null string.

Parameters

s	The string to initialize.
src	The source string to attach. The string must be zero terminated and the memory must be allocated using ipc_malloc. When clearing the string ua_string using ua_string_clear the memory will be freed.

◆ ua_string_attach_const()

void ua_string_attach_const	(	struct ua_string *	s,
		const char *	src
	)

Initializes s with string constant src.

This way s will refer to an external string src and will not free it when ua_string_clear() is called. This may be useful to initialize a UA string with string constants. If src is NULL, s will be initialized as null string.

Parameters

s	The string to initialize.
src	The source string to attach. The string must be zero terminated.

Example:

struct ua_string tmp;

ua_string_attach_const(&tmp, "Hello World");

◆ ua_string_attachn()

void ua_string_attachn	(	struct ua_string *	s,
		char *	src,
		size_t	len
	)

Initializes s with src.

This function behaves like ua_string_attach, but takes an additional argument len to avoid a strlen() call if the length is already known. Nevertheless the src string must be zero terminated. If not, use ua_string_setn to create a terminated copy. If src is NULL s is initialized as null string.

Parameters

s	The string to initialize.
src	The source string to attach. The string must be zero terminated and the memory must be allocated using ipc_malloc. When clearing the string ua_string using ua_string_clear the memory will be freed.
len	Length of `src` in bytes.

◆ ua_string_attachn_const()

void ua_string_attachn_const	(	struct ua_string *	s,
		const char *	src,
		size_t	len
	)

Initializes s with string constant src.

This function behaves like ua_string_attach_const but takes an additional argument len to avoid a strlen() call. If src is NULL s is initialized as null string.

Parameters

s	The string to initialize.
src	The source string to attach. The string must be zero terminated. If not, use ua_string_setn to create a terminated copy.
len	Length of string in bytes.

◆ ua_string_cat()

int ua_string_cat	(	struct ua_string *	dst,
		size_t	size,
		const struct ua_string *	src
	)

Appends a copy of src to the end of dst.

Parameters

dst	An initialized ua_string. This can be a also a Null string, but it must not be a constant string created with ua_string_attach(n)_const()..
size	Maximum size the concatenated string can reach (including null byte). If size is too small `dst` will be truncated and UA_EBADTRUNCATED is returned.
src	The string to be concatenated to `dst`.

Returns: 0 on success, errorcode on failure.

◆ ua_string_catf()

int ua_string_catf	(	struct ua_string *	dst,
		size_t	size,
		const char *	fmt,
			...
	)

Appends a formatted string to the end of dst.

Parameters

dst	An initialized ua_string. This can be a also a Null string, but it must not be a constant string created with ua_string_attach(n)_const().
size	Maximum size the concatenated string can reach (including null byte). If size is too small `dst` will be truncated and UA_EBADTRUNCATED is returned.
fmt	format string according to the printf-format.

Returns: 0 on success, errorcode on failure.

◆ ua_string_clear()

void ua_string_clear ( struct ua_string * s )

Release allocated resources for s.

It is safe to pass a null string or a string attached from a constant string. So clear every ua_string you don't need any longer!

Parameters

s	string to be cleared, will be a null string afterwards.

◆ ua_string_clear_s()

void ua_string_clear_s ( struct ua_string * s )

Securely clears a string.

This function calls ua_string_clear() internally, but first erases the string contents securely. Use this to clear credentials like e.g. passwords from memory.

Parameters

s	string to be cleared, will be a null string afterwards.

◆ ua_string_compare()

int ua_string_compare	(	const struct ua_string *	a,
		const struct ua_string *	b
	)

The compare function returns zero if both strings are equal.

If not equal an integer value less or greater then zero is returned, so that the return value can be used as a sorting criteria (e.g. qsort).

Strings are compared by their length field first, so shorter strings are considered smaller. Strings with the same length are compared using ua_memcmp.

This function is intended for maximum performance, however if strings are presented to a human ua_string_compare_lex should be considered.

◆ ua_string_compare_const()

int ua_string_compare_const	(	const struct ua_string *	a,
		const char *	b
	)

Compares a UA string with a string constant.

This function is provided for convenience and creates a ua_string from b and then calls ua_string_compare

Returns: Zero if equal.

◆ ua_string_compare_lex()

int ua_string_compare_lex	(	const struct ua_string *	a,
		const struct ua_string *	b
	)

The compare function returns zero if both strings are equal.

If not equal an integer value less or greater then zero is returned, so that the return value can be used as a sorting criteria (e.g. qsort).

Strings are compared byte by byte, so when sorting the result is sorted lexicographical. The comparison is case sensitive and all capital letters are considered smaller than all lowercase letters, similar to the C99 strcmp() function.

For a more performant comparison see ua_string_compare.

◆ ua_string_comparen_const()

int ua_string_comparen_const	(	const struct ua_string *	a,
		const char *	b,
		size_t	len
	)

Compares a UA string with a string constant of known length.

This function is provided for convenience.

It sorts the same way as ua_string_compare.

Parameters

a	ua_string as first string comparison operand
b	const char* string as second comparison operand
len	Length if b in bytes. This function is used if `b` is not zero terminated. Note that the purpose of `len` is only to define the length of b, it is not like the n argument of strncmp. So if `a` is longer than `b`, and `len` bytes of `a` are identical to `b`, this function will return "not equal", because the strings have different lengths. To compare substrings you must reduce the length of `a` and `b`.

Returns: Zero if equal.

◆ ua_string_const_data()

const char * ua_string_const_data ( const struct ua_string * s )

Returns the raw string data of s.

This can be used to pass the string to other C functions which expects a normal C string.

◆ ua_string_copy()

int ua_string_copy	(	struct ua_string *	dst,
		const struct ua_string *	src
	)

Creates a copy of the string src including the terminating null byte.

Parameters

dst	destination string
src	source string

Returns: returns zero on success, or errorcode on failure.

◆ ua_string_data()

char * ua_string_data ( struct ua_string * s )

Returns the raw string data of s.

This pointer can be used to access and modify the characters that compose the string.

◆ ua_string_from_file()

int ua_string_from_file	(	struct ua_string *	s,
		const char *	path
	)

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

The file is opened in text mode. If the file is empty and empty string will be returned.

Parameters

s	String to write to.
path	Path of the file to read.

Returns: Zero on success or errorcode on failure.

◆ ua_string_index_of()

int ua_string_index_of	(	const struct ua_string *	s,
		const char *	substr
	)

Searches for the substring substr in the given ua string s.

Parameters

s	UA String to be searched
substr	Substring to search for. Must be a zero terminated C string.

Returns: Index of substr or -1 of not found.

◆ ua_string_init()

void ua_string_init ( struct ua_string * s )

Initializes s with a null string, so it is safe to clear or perform further operations.

Parameters

s	an uninitialized ua_string.

◆ ua_string_is_empty()

bool ua_string_is_empty ( const struct ua_string * s )

Returns true if the given string is a valid empty string.

This means the string has length of zero, but the data pointer is valid and contains a zero terminator.

◆ ua_string_is_null()

bool ua_string_is_null ( const struct ua_string * s )

Returns true if the given string is a NULL string.

In OPC UA len is set to -1 for NULL strings, however we only check the data pointer. If data is NULL the string is a NULL string and len is ignored.

◆ ua_string_is_zeroterminated()

bool ua_string_is_zeroterminated ( const struct ua_string * s )

Returns true if the string is zero terminated.

This is typically true, as ua_string_set or the decoder always creates zero terminated strings. But it is possible that somebody passes a non-terminated string using ua_string_attachn_const or ua_string_attachn. Using such strings can be dangerous, because most C functions expect zero terminated strings. If any function needs to ensure the string is terminated to work without issues it can use this function to test it. This function checks if the last byte is a zero terminator. If the string was terminated earlier this is ignored. Note that this check would technically be an of-by-one error if the string is not terminated in the allocated memory is exactly len bytes. Because this is not allowed by definition, this is OK. It is the best we can do to stop reading more bytes.

Parameters

s	String to test

Returns: True if terminated, false if not.

◆ ua_string_length()

size_t ua_string_length ( const struct ua_string * s )

Returns the length of the string in bytes excluding the zero terminator.

A value of 0 indicates an empty or null string, or an invalid argument.

◆ ua_string_printable()

const char * ua_string_printable ( const struct ua_string * s )

Return a printable representation of a ua_string.

The returned string is intended for printing/tracing the ua_string, it is purely informative and you cannot rely on the format of the returned value.

This function always returns a zero terminated string, which can be directly used for printing. It is only valid as long as the underlying ua_string is not modified.

◆ ua_string_replace()

int ua_string_replace	(	struct ua_string *	s,
		const char *	search,
		const char *	replace
	)

Replaces the first occurance of search in s with replace.

Parameters

s	UA String to be changed
search	search string to be replaced
replace	replacement string

Returns: Zero on success, a negative error code on failure.

◆ ua_string_set()

int ua_string_set	(	struct ua_string *	s,
		const char *	src
	)

Initializes s with a copy of src.

src must be a zero terminated C string or NULL.

◆ ua_string_setn()

int ua_string_setn	(	struct ua_string *	s,
		const char *	src,
		size_t	len
	)

Initializes s with a copy of src.

Unlike ua_string_set this function takes an additional len argument. This avoids calling strlen() which is faster when the length is already known and it can be used to create substrings of src. s is initialized as null string if src is NULL.

◆ ua_string_smart_attach_const()

int ua_string_smart_attach_const	(	struct ua_string *	s,
		const char *	src
	)

Simple wrapper for ua_string_attach_const or ua_string_set.

When compiled without MEMORY_USE_SHM this simply calls ua_string_attach_const. When compiled with MEMORY_USE_SHM this calls ua_string_set which will create a copy in shared memory, which is necessary to work across memory boundaries. ua_string_attach_const is faster than ua_string_set, so we try to avoid the later one if possible.

◆ ua_string_smart_attachn_const()

int ua_string_smart_attachn_const	(	struct ua_string *	s,
		const char *	src,
		size_t	len
	)

Simple wrapper for ua_string_attachn_const or ua_string_setn.

When compiled without MEMORY_USE_SHM this simply calls ua_string_attachn_const. When compiled with MEMORY_USE_SHM this calls ua_string_setn which will create a copy in shared memory, which is necessary to work across memory boundaries. ua_string_attachn_const is faster than ua_string_setn, so we try to avoid the later one if possible.

◆ ua_string_snprintf()

int ua_string_snprintf	(	struct ua_string *	s,
		size_t	size,
		const char *	fmt,
			...
	)

Replaces the given string s with a formatted string.

Parameters

s	An initialized ua_string. This can be a also a Null string, but it must not be a constant string created with ua_string_attach(n)_const().
size	Maximum size the output string can reach (including null byte). If size is too small `s` will be truncated and depending on the platform either UA_EBAD or UA_EBADTRUNCATED is returned.
fmt	format string according to the printf-format.

Returns: 0 on success, errorcode on failure.

◆ ua_string_strndup()

static char * ua_string_strndup	(	const char *	s,
		size_t	n
	)

Creates a duplicate of the string s.

This function copies at most n-1 characters from s and always adds a zero terminator. So it is safe to call this function from non-terminated string as long as n-1 characters are readable. It also stops copying when it encounters a zero terminator in the sources before reaching n.

Parameters

s	source string
n	size of new string including the zero terminator.

Returns: new zero terminated string on success, NULL if memory allocation fails.

◆ ua_string_to_file()

int ua_string_to_file	(	struct ua_string *	s,
		const char *	path
	)

Write all characters from string into a file.

The file is opened in text mode.

Parameters

s	String 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_string_trim()

int ua_string_trim ( struct ua_string * s )

Removes leading and trailing white spaces from string.

This functions required internal memory allocation and memcpy to removed the leading white spaces.

Parameters

s	The string to trim.

Returns: Zero on success. UA_EBADNOMEM if memory allocation fails.

Field Documentation

◆ cdata

const char* cdata

Const pointer to the data.

◆ d

union { ... } d

The string data.

◆ data

char* data

Non-const pointer to the data.

◆ free

uint32_t free

Bit to indicate if the data pointer must be freed.

◆ len

uint32_t len

Length of the string.

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

/builds/products/embeddedstack/src/uabase/string.h
/builds/products/embeddedstack/src/uabase/string.c

Public Member Functions

Data Fields

Related Functions

Detailed Description

Member Function Documentation

◆ ua_string_allocate()

◆ ua_string_attach()

◆ ua_string_attach_const()

◆ ua_string_attachn()

◆ ua_string_attachn_const()

◆ ua_string_cat()

◆ ua_string_catf()

◆ ua_string_clear()

◆ ua_string_clear_s()

◆ ua_string_compare()

◆ ua_string_compare_const()

◆ ua_string_compare_lex()

◆ ua_string_comparen_const()

◆ ua_string_const_data()

◆ ua_string_copy()

◆ ua_string_data()

◆ ua_string_from_file()

◆ ua_string_index_of()

◆ ua_string_init()

◆ ua_string_is_empty()

◆ ua_string_is_null()

◆ ua_string_is_zeroterminated()

◆ ua_string_length()

◆ ua_string_printable()

◆ ua_string_replace()

◆ ua_string_set()

◆ ua_string_setn()

◆ ua_string_smart_attach_const()

◆ ua_string_smart_attachn_const()

◆ ua_string_snprintf()

◆ ua_string_strndup()

◆ ua_string_to_file()

◆ ua_string_trim()

Field Documentation

◆ cdata

◆ d

◆ data

◆ free

◆ len