All of these helper getter functions return GETDNS_RETURN_GOOD if the call is successful.
@@ -583,11 +583,11 @@ getdns_list * getdns_list_create_with_extended_memory_functions(
void *(*realloc)(void *userarg, void *, size_t),
void (*free)(void *userarg, void *)
);
-void getdns_list_destroy(getdns_list *this_list);
-getdns_return_t getdns_list_set_dict(getdns_list *this_list, size_t index, const getdns_dict *child_dict);
-getdns_return_t getdns_list_set_list(getdns_list *this_list, size_t index, const getdns_list *child_list);
-getdns_return_t getdns_list_set_bindata(getdns_list *this_list, size_t index, const getdns_bindata *child_bindata);
-getdns_return_t getdns_list_set_int(getdns_list *this_list, size_t index, uint32_t child_uint32);
+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);
/* Dicts: create, destroy, and set the data at a given name */
getdns_dict * getdns_dict_create();
@@ -605,12 +605,12 @@ getdns_dict * getdns_dict_create_with_extended_memory_functions(
void *(*realloc)(void *userarg, void *, size_t),
void (*free)(void *userarg, void *)
);
-void getdns_dict_destroy(getdns_dict *this_dict);
-getdns_return_t getdns_dict_set_dict(getdns_dict *this_dict, const char *name, const getdns_dict *child_dict);
-getdns_return_t getdns_dict_set_list(getdns_dict *this_dict, const char *name, const getdns_list *child_list);
-getdns_return_t getdns_dict_set_bindata(getdns_dict *this_dict, const char *name, const getdns_bindata *child_bindata);
-getdns_return_t getdns_dict_set_int(getdns_dict *this_dict, const char *name, uint32_t child_uint32);
-getdns_return_t getdns_dict_remove_name(getdns_dict *this_dict, const char *name);
+void getdns_dict_destroy(getdns_dict *dict);
+getdns_return_t getdns_dict_set_dict(getdns_dict *dict, const char *name, const getdns_dict *child_dict);
+getdns_return_t getdns_dict_set_list(getdns_dict *dict, const char *name, const getdns_list *child_list);
+getdns_return_t getdns_dict_set_bindata(getdns_dict *dict, const char *name, const getdns_bindata *child_bindata);
+getdns_return_t getdns_dict_set_int(getdns_dict *dict, const char *name, uint32_t child_uint32);
+getdns_return_t getdns_dict_remove_name(getdns_dict *dict, const char *name);
Lists are extended with the getdns_list_set_ calls with the index set to the
@@ -643,11 +643,11 @@ results that have been validated with DNSSEC, you might use:
/* . . . */ -getdns_dict * this_extensions = getdns_dict_create(); -this_ret = getdns_dict_set_int(this_extensions, "dnssec_return_only_secure", GETDNS_EXTENSION_TRUE); +getdns_dict * extensions = getdns_dict_create(); +ret = getdns_dict_set_int(extensions, "dnssec_return_only_secure", GETDNS_EXTENSION_TRUE); /* . . . Do some processing with the extensions and results . . . */ /* Remember to clean up memory*/ -getdns_dict_destroy(this_extensions); +getdns_dict_destroy(extensions);
The extensions described in this section are are: @@ -2426,7 +2426,7 @@ getdns_pretty_print_dict() for debugging.
There is a tarball that includes the .h files, +
There is a tarball that includes the .h files, the examples, and so on. The examples all make, even though there is no API implementation, based on a pseudo-implementation in the tarball; see make-examples-PLATFORM.sh. Note that this currently builds fine on the Macintosh and Ubuntu; help is definitely appreciated on making the build process diff --git a/src/getdns/getdns.h.in b/src/getdns/getdns.h.in index 2812f0d9..f2cebef2 100644 --- a/src/getdns/getdns.h.in +++ b/src/getdns/getdns.h.in @@ -509,139 +509,139 @@ typedef struct getdns_list getdns_list; /** * get the length of the specified list (returned in *answer) - * @param this_list list of any of the supported data types + * @param list list of any of the supported data types * @param answer number of valid items in the list * @return GETDNS_RETURN_GOOD on success * @return GETDNS_RETURN_NO_SUCH_LIST_ITEM if list is not valid or params are NULL */ -getdns_return_t getdns_list_get_length(const getdns_list *this_list, +getdns_return_t getdns_list_get_length(const getdns_list *list, size_t * answer); /** * get the enumerated data type of the indexed list item - * @param this_list the list from which to fetch the data type + * @param list the list from which to fetch the data type * @param index the item in the list from which to fetch the data type * @param *answer assigned the value of the data type on success * @return GETDNS_RETURN_GOOD on success * @return GETDNS_RETURN_NO_SUCH_LIST_ITEM if the index is out of range or the list is NULL */ -getdns_return_t getdns_list_get_data_type(const getdns_list *this_list, +getdns_return_t getdns_list_get_data_type(const getdns_list *list, size_t index, getdns_data_type * 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. - * @param this_list the list from which to fetch the value + * @param list the list from which to fetch the value * @param index the item in the list from which to fetch the value * @param **answer assigned a pointer to the dict value of the indexed element * @return GETDNS_RETURN_GOOD on success * @return GETDNS_RETURN_NO_SUCH_LIST_ITEM if the index is out of range or the list is NULL * @return GETDNS_RETURN_WRONG_TYPE_REQUESTED if the data type does not match the contents of the indexed item */ -getdns_return_t getdns_list_get_dict(const getdns_list *this_list, size_t index, +getdns_return_t getdns_list_get_dict(const getdns_list *list, size_t index, getdns_dict **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. - * @param this_list the list from which to fetch the value + * @param list the list from which to fetch the value * @param index the item in the list from which to fetch the value * @param **answer assigned a pointer to the list value of the indexed element * @return GETDNS_RETURN_GOOD on success * @return GETDNS_RETURN_NO_SUCH_LIST_ITEM if the index is out of range or the list is NULL * @return GETDNS_RETURN_WRONG_TYPE_REQUESTED if the data type does not match the contents of the indexed item */ -getdns_return_t getdns_list_get_list(const getdns_list *this_list, size_t index, +getdns_return_t getdns_list_get_list(const getdns_list *list, size_t index, getdns_list **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. - * @param this_list the list from which to fetch the value + * @param list the list from which to fetch the value * @param index the item in the list from which to fetch the value * @param **answer assigned a pointer to the list value of the indexed element * @return GETDNS_RETURN_GOOD on success * @return GETDNS_RETURN_NO_SUCH_LIST_ITEM if the index is out of range or the list is NULL * @return GETDNS_RETURN_WRONG_TYPE_REQUESTED if the data type does not match the contents of the indexed item */ -getdns_return_t getdns_list_get_bindata(const getdns_list *this_list, size_t index, +getdns_return_t getdns_list_get_bindata(const getdns_list *list, size_t index, getdns_bindata **answer); /** * retrieve the integer value of the specified list item - * @param this_list the list from which to fetch the item + * @param list the list from which to fetch the item * @param index the index of the element in the list to fetch from * @param *answer assigned the integer value of the indexed element * @return GETDNS_RETURN_GOOD on success * @return GETDNS_RETURN_NO_SUCH_LIST_ITEM if the index is out of range or the list is NULL * @return GETDNS_RETURN_WRONG_TYPE_REQUESTED if the data type does not match the contents of the indexed item */ -getdns_return_t getdns_list_get_int(const getdns_list *this_list, size_t index, +getdns_return_t getdns_list_get_int(const getdns_list *list, size_t index, uint32_t * answer); /** * fetch a list of names from the dictionary, this list must be freed by the caller * via a call to getdns_list_destroy - * @param this_dict dictionary from which to produce the list of names + * @param dict dictionary from which to produce the list of names * @param **answer a pointer to the new list will be assigned to *answer * @return GETDNS_RETURN_GOOD on success * @return GETDNS_RETURN_NO_SUCH_DICT_NAME if dict is invalid or empty */ -getdns_return_t getdns_dict_get_names(const getdns_dict *this_dict, +getdns_return_t getdns_dict_get_names(const getdns_dict *dict, getdns_list **answer); /** * fetch the data type for the data associated with the specified name - * @param this_dict dictionary from which to fetch the data type + * @param dict dictionary from which to fetch the data type * @param name a name/key value to look up in the dictionary * @param *answer data type will be stored at this address * @return GETDNS_RETURN_GOOD on success * @return GETDNS_RETURN_NO_SUCH_DICT_NAME if dict is invalid or name does not exist */ -getdns_return_t getdns_dict_get_data_type(const getdns_dict *this_dict, +getdns_return_t getdns_dict_get_data_type(const getdns_dict *dict, const char *name, getdns_data_type * answer); /** * fetch the dictionary associated with the specified name, the dictionary should * not be free()'d by the caller, it will be freed when the parent dictionary is * free()'d - * @param this_dict dictionary from which to fetch the dictionary + * @param dict dictionary from which to fetch the dictionary * @param name a name/key value to look up in the dictionary * @param **answer a copy of the dictionary will be stored at this address * @return GETDNS_RETURN_GOOD on success * @return GETDNS_RETURN_NO_SUCH_DICT_NAME if dict is invalid or name does not exist */ -getdns_return_t getdns_dict_get_dict(const getdns_dict *this_dict, +getdns_return_t getdns_dict_get_dict(const getdns_dict *dict, const char *name, getdns_dict **answer); /** * fetch the list associated with the specified name * the list should not be free()'d by the caller, when the dictionary is destroyed * the list will also be destroyed - * @param this_dict dictionary from which to fetch the list + * @param dict dictionary from which to fetch the list * @param name a name/key value to look up in the dictionary * @param **answer a copy of the list will be stored at this address * @return GETDNS_RETURN_GOOD on success * @return GETDNS_RETURN_NO_SUCH_DICT_NAME if dict is invalid or name does not exist */ -getdns_return_t getdns_dict_get_list(const getdns_dict *this_dict, +getdns_return_t getdns_dict_get_list(const getdns_dict *dict, const char *name, getdns_list **answer); /** * fetch the bindata associated with the specified name, the bindata should not be * free()'d by the caller - * @param this_dict dictionary from which to fetch the bindata + * @param dict dictionary from which to fetch the bindata * @param name a name/key value to look up in the dictionary * @param **answer a copy of the bindata will be stored at this address * @return GETDNS_RETURN_GOOD on success * @return GETDNS_RETURN_NO_SUCH_DICT_NAME if dict is invalid or name does not exist */ -getdns_return_t getdns_dict_get_bindata(const getdns_dict *this_dict, +getdns_return_t getdns_dict_get_bindata(const getdns_dict *dict, const char *name, getdns_bindata **answer); /** * fetch the integer value associated with the specified name - * @param this_dict dictionary from which to fetch the integer + * @param dict dictionary from which to fetch the integer * @param name a name/key value to look up in the dictionary * @param *answer the integer will be stored at this address * @return GETDNS_RETURN_GOOD on success * @return GETDNS_RETURN_NO_SUCH_DICT_NAME if dict is invalid or name does not exist */ -getdns_return_t getdns_dict_get_int(const getdns_dict *this_dict, +getdns_return_t getdns_dict_get_int(const getdns_dict *dict, const char *name, uint32_t * answer); /** @@ -669,48 +669,48 @@ getdns_list *getdns_list_create_with_extended_memory_functions( * you MUST copy those instances BEFORE you destroy the list else * unpleasant things will happen at run-time */ -void getdns_list_destroy(getdns_list *this_list); +void getdns_list_destroy(getdns_list *list); /** * 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 - * @param this_list list containing the item to which child_list is to be assigned + * @param list list containing the item to which child_list is to be assigned * @param index index of the item within list to which child_list is to be assigned * @param *child_dict dict to assign to the item * @return GETDNS_RETURN_GOOD on success * @return GETDNS_RETURN_NO_SUCH_LIST_ITEM if index is out of range, or list is NULL */ -getdns_return_t getdns_list_set_dict(getdns_list *this_list, size_t index, +getdns_return_t getdns_list_set_dict(getdns_list *list, size_t index, const getdns_dict *child_dict); /** * 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 - * @param this_list list containing the item to which child_list is to be assigned + * @param list list containing the item to which child_list is to be assigned * @param index index of the item within list to which child_list is to be assigned * @param *child_list list to assign to the item * @return GETDNS_RETURN_GOOD on success * @return GETDNS_RETURN_NO_SUCH_LIST_ITEM if index is out of range, or list is NULL */ -getdns_return_t getdns_list_set_list(getdns_list *this_list, size_t index, +getdns_return_t getdns_list_set_list(getdns_list *list, size_t index, const getdns_list *child_list); /** * 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 - * @param this_list list contiaining the item to which child_list is to be assigned + * @param list list contiaining the item to which child_list is to be assigned * @param index index of the item within list to which child_list is to be assigned * @param *child_bindata data to assign to the item * @return GETDNS_RETURN_GOOD on success * @return GETDNS_RETURN_NO_SUCH_LIST_ITEM if index is out of range, or list is NULL */ -getdns_return_t getdns_list_set_bindata(getdns_list *this_list, size_t index, +getdns_return_t getdns_list_set_bindata(getdns_list *list, size_t index, const getdns_bindata *child_bindata); /** * set the integer value of the indexed item (zero based index) * @return GETDNS_RETURN_GOOD on success * @return GETDNS_RETURN_NO_SUCH_LIST_ITEM if index is out of range, or list is NULL */ -getdns_return_t getdns_list_set_int(getdns_list *this_list, size_t index, +getdns_return_t getdns_list_set_int(getdns_list *list, size_t index, uint32_t child_uint32); /** @@ -736,48 +736,48 @@ getdns_dict *getdns_dict_create_with_extended_memory_functions( * be aware that if you have fetched any data from the dictionary it will * no longer be available (you are likely to experience bad things if you try) */ -void getdns_dict_destroy(getdns_dict *this_dict); +void getdns_dict_destroy(getdns_dict *dict); -getdns_return_t getdns_dict_set_dict(getdns_dict *this_dict, +getdns_return_t getdns_dict_set_dict(getdns_dict *dict, const char *name, const getdns_dict *child_dict); /** * create a new entry in the dictionary, or replace the value of an existing entry * this routine makes a copy of the child_list - * @param this_dict dictionary in which to add or change the value + * @param dict dictionary in which to add or change the value * @param name key that identifies which item in the dictionary to add/change * @param child_list value to assign to the node identified by name * @return GETDNS_RETURN_GOOD on success */ -getdns_return_t getdns_dict_set_list(getdns_dict *this_dict, +getdns_return_t getdns_dict_set_list(getdns_dict *dict, const char *name, const getdns_list *child_list); /** * create a new entry in the dictionary, or replace the value of an existing entry * this routine makes a copy of the child_bindata - * @param this_dict dictionary in which to add or change the value + * @param dict dictionary in which to add or change the value * @param name key that identifies which item in the dictionary to add/change * @param child_bindata value to assign to the node identified by name * @return GETDNS_RETURN_GOOD on success */ -getdns_return_t getdns_dict_set_bindata(getdns_dict *this_dict, +getdns_return_t getdns_dict_set_bindata(getdns_dict *dict, const char *name, const getdns_bindata *child_bindata); /** * create a new entry in the dictionary, or replace the value of an existing entry - * @param this_dict dictionary in which to add or change the value + * @param dict dictionary in which to add or change the value * @param name key that identifies which item in the dictionary to add/change * @param child_uint32 value to assign to the node identified by name * @return GETDNS_RETURN_GOOD on success */ -getdns_return_t getdns_dict_set_int(getdns_dict *this_dict, const char *name, +getdns_return_t getdns_dict_set_int(getdns_dict *dict, const char *name, uint32_t child_uint32); /** * remove the value associated with the specified name - * @param this_dict dictionary from which to fetch the integer + * @param dict dictionary from which to fetch the integer * @param name a name/key value to look up in the dictionary * @return GETDNS_RETURN_GOOD on success * @return GETDNS_RETURN_NO_SUCH_DICT_NAME if dict is invalid or name does not exist */ -getdns_return_t getdns_dict_remove_name(getdns_dict *this_dict, const char *name); +getdns_return_t getdns_dict_remove_name(getdns_dict *dict, const char *name); /* Callback arguments */ typedef void (*getdns_callback_t) (getdns_context *context,