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_listgetdns_list_create ()
 
getdns_listgetdns_list_create_with_context (const getdns_context *context)
 
getdns_listgetdns_list_create_with_memory_functions (void *(*malloc)(size_t), void *(*realloc)(void *, size_t), void(*free)(void *))
 
getdns_listgetdns_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
listlist of any of the supported data types
answernumber 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
listthe list from which to fetch the data type
indexthe item in the list from which to fetch the data type
*answerassigned 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
listthe list from which to fetch the value
indexthe item in the list from which to fetch the value
**answerassigned 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
listthe list from which to fetch the value
indexthe item in the list from which to fetch the value
**answerassigned 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
listthe list from which to fetch the value
indexthe item in the list from which to fetch the value
**answerassigned 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
listthe list from which to fetch the item
indexthe index of the element in the list to fetch from
*answerassigned 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
contextThe 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
mallocCustom allocator
reallocCustom reallocator
freeCustom 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
userargWill be passed as the first argument to the extended custom malloc, realloc, and free.
mallocCustom allocator
reallocCustom reallocator
freeCustom 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
listlist containing the item to which child_list is to be assigned
indexindex of the item within list to which child_list is to be assigned
*child_dictdict 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
listlist containing the item to which child_list is to be assigned
indexindex of the item within list to which child_list is to be assigned
*child_listlist 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
listlist contiaining the item to which child_list is to be assigned
indexindex of the item within list to which child_list is to be assigned
*child_bindatadata 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_listlist 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
strpointer to the buffer to print to
sizesize of the given buffer. No more than size bytes (including the terminating null byte) will be written to str.
listgetdns_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_listlist to represent as json data
prettywhen 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
strpointer to the buffer to print to
sizesize of the given buffer. No more than size bytes (including the terminating null byte) will be written to str.
listlist to represent as json data
prettywhen 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.