String lists

Serialized arrays of NUL-separated strings. More...

Data Structures
struct	pbl_string_list
	Serialized string list. More...

Macros
#define	PBL_STRING_LIST_SIZE(num_values, max_value_size)    (sizeof(struct pbl_string_list) + ((num_values) * (max_value_size)))
	Get the maximum size of a string list.

Functions
char *	pbl_string_list_get_at (struct pbl_string_list *list, size_t index)
	Get a string from a string list.
size_t	pbl_string_list_count (struct pbl_string_list *list)
	Count the strings in a string list.
int	pbl_string_list_add_string (struct pbl_string_list *list, size_t max_list_size, const char *str, size_t max_str_size)
	Append a string to a string list.

Detailed Description

Serialized arrays of NUL-separated strings.

A string list passes a group of strings as a single attribute on the wire, e.g. the canned responses of a notification. The strings are stored back to back, separated by NUL characters; pbl_string_list::serialized_byte_length does not count the final terminator.

uint8_t storage[PBL_STRING_LIST_SIZE(3, 16)] = {0};
struct pbl_string_list *list = (struct pbl_string_list *)storage;
 
pbl_string_list_add_string(list, sizeof(storage), "Yes", 16);
pbl_string_list_add_string(list, sizeof(storage), "No", 16);
const char *second = pbl_string_list_get_at(list, 1); // "No"

---

Data Structure Documentation

pbl_string_list

struct pbl_string_list

Serialized string list.

Data Fields
char	data[]	NUL-separated strings.
uint16_t	serialized_byte_length	Bytes used in data, excluding the final terminator. 0 for an empty list.

Macro Definition Documentation

PBL_STRING_LIST_SIZE

#define PBL_STRING_LIST_SIZE	(		num_values,
			max_value_size
	)		(sizeof(struct pbl_string_list) + ((num_values) * (max_value_size)))

Get the maximum size of a string list.

Parameters

num_values	Number of strings.
max_value_size	Maximum size of each string, including its terminator.

Returns

Size in bytes, including the header.

Function Documentation

pbl_string_list_add_string()

int pbl_string_list_add_string	(	struct pbl_string_list *	list,
		size_t	max_list_size,
		const char *	str,
		size_t	max_str_size
	)

Append a string to a string list.

The string is truncated to fit the remaining space.

Parameters

list	String list, may be NULL.
max_list_size	Size of the storage of list, including the header and the final terminator.
str	String to add.
max_str_size	Maximum number of characters to read from str.

Returns

Number of characters written, excluding the terminator.

pbl_string_list_count()

size_t pbl_string_list_count

(

struct pbl_string_list *

list

)

Count the strings in a string list.

Parameters

list	String list, may be NULL.

Returns

Number of strings, 0 for a NULL or empty list.

pbl_string_list_get_at()

char * pbl_string_list_get_at	(	struct pbl_string_list *	list,
		size_t	index
	)

Get a string from a string list.

Parameters

list	String list, may be NULL.
index	Zero-based index of the string.

Returns

Pointer to the string, or NULL if list is NULL or index is out of bounds.