Creating, destroying, reading from and manipulating getdns_lists

Functions
getdns_return_t	getdns_list_get_length (const getdns_list *list, size_t *answer)
getdns_return_t	getdns_list_get_data_type (const getdns_list *list, size_t index, getdns_data_type *answer)
getdns_return_t	getdns_list_get_dict (const getdns_list *list, size_t index, getdns_dict **answer)
getdns_return_t	getdns_list_get_list (const getdns_list *list, size_t index, getdns_list **answer)
getdns_return_t	getdns_list_get_bindata (const getdns_list *list, size_t index, getdns_bindata **answer)
getdns_return_t	getdns_list_get_int (const getdns_list *list, size_t index, uint32_t *answer)
getdns_list *	getdns_list_create ()
getdns_list *	getdns_list_create_with_context (const getdns_context *context)
getdns_list *	getdns_list_create_with_memory_functions (void *(*malloc)(size_t), void *(*realloc)(void *, size_t), void(*free)(void *))
getdns_list *	getdns_list_create_with_extended_memory_functions (void *userarg, void *(*malloc)(void *userarg, size_t), void *(*realloc)(void *userarg, void *, size_t), void(*free)(void *userarg, void *))
void	getdns_list_destroy (getdns_list *list)
getdns_return_t	getdns_list_set_dict (getdns_list *list, size_t index, const getdns_dict *child_dict)
getdns_return_t	getdns_list_set_list (getdns_list *list, size_t index, const getdns_list *child_list)
getdns_return_t	getdns_list_set_bindata (getdns_list *list, size_t index, const getdns_bindata *child_bindata)
getdns_return_t	getdns_list_set_int (getdns_list *list, size_t index, uint32_t child_uint32)
char *	getdns_pretty_print_list (const getdns_list *some_list)
int	getdns_pretty_snprint_list (char *str, size_t size, const getdns_list *list)
char *	getdns_print_json_list (const getdns_list *some_list, int pretty)
int	getdns_snprint_json_list (char *str, size_t size, const getdns_list *list, int pretty)

Detailed Description

Function Documentation

getdns_list_get_length()

getdns_return_t getdns_list_get_length	(	const getdns_list *	list,
		size_t *	answer
	)

get the length of the specified list (returned in *answer)

Parameters

list	list of any of the supported data types
answer	number of valid items in the list

Returns

GETDNS_RETURN_GOOD on success

GETDNS_RETURN_NO_SUCH_LIST_ITEM if list is not valid or params are NULL

getdns_list_get_data_type()

getdns_return_t getdns_list_get_data_type	(	const getdns_list *	list,
		size_t	index,
		getdns_data_type *	answer
	)

get the enumerated data type of the indexed list item

Parameters

list	the list from which to fetch the data type
index	the item in the list from which to fetch the data type
*answer	assigned the value of the data type on success

Returns

GETDNS_RETURN_GOOD on success

GETDNS_RETURN_NO_SUCH_LIST_ITEM if the index is out of range or the list is NULL

getdns_list_get_dict()

getdns_return_t getdns_list_get_dict	(	const getdns_list *	list,
		size_t	index,
		getdns_dict **	answer
	)

retrieve the dictionary value of the specified list item, the caller must not free storage associated with the return value. When the list is destroyed this dict data is also free()'d - keep this in mind when using this function.

Parameters

list	the list from which to fetch the value
index	the item in the list from which to fetch the value
**answer	assigned a pointer to the dict value of the indexed element

Returns

GETDNS_RETURN_GOOD on success

GETDNS_RETURN_NO_SUCH_LIST_ITEM if the index is out of range or the list is NULL

GETDNS_RETURN_WRONG_TYPE_REQUESTED if the data type does not match the contents of the indexed item

getdns_list_get_list()

getdns_return_t getdns_list_get_list	(	const getdns_list *	list,
		size_t	index,
		getdns_list **	answer
	)

retrieve the list value of the specified list item, the caller must not free storage associated with the return value. When the list is destroyed any list data is also free()'d - keep this in mind when using this function.

Parameters

list	the list from which to fetch the value
index	the item in the list from which to fetch the value
**answer	assigned a pointer to the list value of the indexed element

Returns

GETDNS_RETURN_GOOD on success

GETDNS_RETURN_NO_SUCH_LIST_ITEM if the index is out of range or the list is NULL

GETDNS_RETURN_WRONG_TYPE_REQUESTED if the data type does not match the contents of the indexed item

getdns_list_get_bindata()

getdns_return_t getdns_list_get_bindata	(	const getdns_list *	list,
		size_t	index,
		getdns_bindata **	answer
	)

retrieve the binary data value of the specified list item, the caller must not free storage associated with the return value. When the list is destroyed any bindata data is also free()'d - keep this in mind when using this function.

Parameters

list	the list from which to fetch the value
index	the item in the list from which to fetch the value
**answer	assigned a pointer to the list value of the indexed element

Returns

GETDNS_RETURN_GOOD on success

GETDNS_RETURN_NO_SUCH_LIST_ITEM if the index is out of range or the list is NULL

GETDNS_RETURN_WRONG_TYPE_REQUESTED if the data type does not match the contents of the indexed item

getdns_list_get_int()

getdns_return_t getdns_list_get_int	(	const getdns_list *	list,
		size_t	index,
		uint32_t *	answer
	)

retrieve the integer value of the specified list item

Parameters

list	the list from which to fetch the item
index	the index of the element in the list to fetch from
*answer	assigned the integer value of the indexed element

Returns

GETDNS_RETURN_GOOD on success

GETDNS_RETURN_NO_SUCH_LIST_ITEM if the index is out of range or the list is NULL

GETDNS_RETURN_WRONG_TYPE_REQUESTED if the data type does not match the contents of the indexed item

getdns_list_create()

getdns_list* getdns_list_create

(

)

create a new list with no items

Returns

pointer to an allocated list, NULL if insufficient memory

getdns_list_create_with_context()

getdns_list* getdns_list_create_with_context

(

const getdns_context *

context

)

create a new list with no items, creating and initializing it with the custom memory function from context. These memory functions will be used for creating, and inherited by the list members when populating the list. The custom deallocator will be used for destroying the list.

Parameters

context

The context from which the custom memory functions will be used to create and initialize the list.

Returns

pointer to an allocated list, NULL if insufficient memory

getdns_list_create_with_memory_functions()

getdns_list* getdns_list_create_with_memory_functions	(	void *(*)(size_t)	malloc,
		void *(*)(void *, size_t)	realloc,
		void(*)(void *)	free
	)

create a new list with no items, creating and initializing it with the provided custom memory function. These memory functions will be used for creating, and inherited by the list members when populating the list. The custom deallocator will be used for destroying the list.

Parameters

malloc	Custom allocator
realloc	Custom reallocator
free	Custom deallocator

Returns

pointer to an allocated list, NULL if insufficient memory

getdns_list_create_with_extended_memory_functions()

getdns_list* getdns_list_create_with_extended_memory_functions	(	void *	userarg,
		void *(*)(void *userarg, size_t)	malloc,
		void *(*)(void *userarg, void *, size_t)	realloc,
		void(*)(void *userarg, void *)	free
	)

create a new list with no items, creating and initializing it with the provided extended custom memory function. These memory functions will be used for creating, and inherited by the list members when populating the list. The custom deallocator will be used for destroying the list.

Parameters

userarg	Will be passed as the first argument to the extended custom malloc, realloc, and free.
malloc	Custom allocator
realloc	Custom reallocator
free	Custom deallocator

Returns

pointer to an allocated list, NULL if insufficient memory

getdns_list_destroy()

void getdns_list_destroy

(

getdns_list *

list

)

free memory allocated to the list (also frees all children of the list) note that lists and bindata retrieved from the list via the getdns_list_get_* helper functions will be destroyed as well - if you fetched them previously you MUST copy those instances BEFORE you destroy the list else unpleasant things will happen at run-time

getdns_list_set_dict()

getdns_return_t getdns_list_set_dict	(	getdns_list *	list,
		size_t	index,
		const getdns_dict *	child_dict
	)

assign the child_dict to an item in a parent list, the parent list copies the child dict and will free the copy when the list is destroyed

Parameters

list	list containing the item to which child_list is to be assigned
index	index of the item within list to which child_list is to be assigned
*child_dict	dict to assign to the item

Returns

GETDNS_RETURN_GOOD on success

GETDNS_RETURN_NO_SUCH_LIST_ITEM if index is out of range, or list is NULL

getdns_list_set_list()

getdns_return_t getdns_list_set_list	(	getdns_list *	list,
		size_t	index,
		const getdns_list *	child_list
	)

assign the child_list to an item in a parent list, the parent list copies the child list and will free the copy when the list is destroyed

Parameters

list	list containing the item to which child_list is to be assigned
index	index of the item within list to which child_list is to be assigned
*child_list	list to assign to the item

Returns

GETDNS_RETURN_GOOD on success

GETDNS_RETURN_NO_SUCH_LIST_ITEM if index is out of range, or list is NULL

getdns_list_set_bindata()

getdns_return_t getdns_list_set_bindata	(	getdns_list *	list,
		size_t	index,
		const getdns_bindata *	child_bindata
	)

assign the child_bindata to an item in a parent list, the parent list copies the child data and will free the copy when the list is destroyed

Parameters

list	list contiaining the item to which child_list is to be assigned
index	index of the item within list to which child_list is to be assigned
*child_bindata	data to assign to the item

Returns

GETDNS_RETURN_GOOD on success

GETDNS_RETURN_NO_SUCH_LIST_ITEM if index is out of range, or list is NULL

getdns_list_set_int()

getdns_return_t getdns_list_set_int	(	getdns_list *	list,
		size_t	index,
		uint32_t	child_uint32
	)

set the integer value of the indexed item (zero based index)

Returns

GETDNS_RETURN_GOOD on success

GETDNS_RETURN_NO_SUCH_LIST_ITEM if index is out of range, or list is NULL

getdns_pretty_print_list()

char* getdns_pretty_print_list

(

const getdns_list *

some_list

)

creates a string that describes the list in a human readable form.

Parameters

some_list

list to pretty print

Returns

character array (caller must free this) containing pretty string

getdns_pretty_snprint_list()

int getdns_pretty_snprint_list	(	char *	str,
		size_t	size,
		const getdns_list *	list
	)

Pretty print the getdns_list in a given buffer snprintf style.

Parameters

str	pointer to the buffer to print to
size	size of the given buffer. No more than size bytes (including the terminating null byte) will be written to str.
list	getdns_list to print

Returns

The number of characters written excluding the terminating null byte or the number of characters which would have been written if enough space had been available.

getdns_print_json_list()

char* getdns_print_json_list	(	const getdns_list *	some_list,
		int	pretty
	)

creates a string containing a json representation of some_list. bindatas are converted to strings when possible, including bindatas for addresses, dnames and other printable data. All other bindatas are converted to lists of byte values.

Parameters

some_list	list to represent as json data
pretty	when non-zero returns formatted json

Returns

character array (caller must free this) containing pretty string

getdns_snprint_json_list()

int getdns_snprint_json_list	(	char *	str,
		size_t	size,
		const getdns_list *	list,
		int	pretty
	)

Prints a json representation of list in a given buffer snprintf style. bindatas are converted to strings when possible, including bindatas for addresses, dnames and other printable data. All other bindatas are converted to lists of byte values.

Parameters

str	pointer to the buffer to print to
size	size of the given buffer. No more than size bytes (including the terminating null byte) will be written to str.
list	list to represent as json data
pretty	when non-zero returns formatted json

Returns

The number of characters written excluding the terminating null byte or the number of characters which would have been written if enough space had been available.