Update spec to 0.701

spec/index.html

@@ -522,21 +522,21 @@ name-value pairs in a dict is not important.</li>
 <div class=forh id="datagetters">
 /* Lists: get the length, get the data_type of the value at a given
    position, and get the data at a given position */
-getdns_return_t getdns_list_get_length(const getdns_list *this_list, size_t *answer);
+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 *this_list, size_t index, getdns_data_type *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 *this_list, size_t index, getdns_dict **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 *this_list, size_t index, getdns_list **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 *this_list, size_t index, getdns_bindata **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 *this_list, size_t index, uint32_t *answer);
+getdns_return_t getdns_list_get_int(const getdns_list *list, size_t index, uint32_t *answer);
 
 /* Dicts: get the list of names, get the data_type of the
    value at a given name, and get the data at a given name */
-getdns_return_t getdns_dict_get_names(const getdns_dict *this_dict, getdns_list **answer);
+getdns_return_t getdns_dict_get_names(const getdns_dict *dict, getdns_list **answer);
-getdns_return_t getdns_dict_get_data_type(const getdns_dict *this_dict, const char *name, getdns_data_type *answer);
+getdns_return_t getdns_dict_get_data_type(const getdns_dict *dict, const char *name, getdns_data_type *answer);
-getdns_return_t getdns_dict_get_dict(const getdns_dict *this_dict, const char *name, getdns_dict **answer);
+getdns_return_t getdns_dict_get_dict(const getdns_dict *dict, const char *name, getdns_dict **answer);
-getdns_return_t getdns_dict_get_list(const getdns_dict *this_dict, const char *name, getdns_list **answer);
+getdns_return_t getdns_dict_get_list(const getdns_dict *dict, const char *name, getdns_list **answer);
-getdns_return_t getdns_dict_get_bindata(const getdns_dict *this_dict, const char *name, getdns_bindata **answer);
+getdns_return_t getdns_dict_get_bindata(const getdns_dict *dict, const char *name, getdns_bindata **answer);
-getdns_return_t getdns_dict_get_int(const getdns_dict *this_dict, const char *name, uint32_t *answer);
+getdns_return_t getdns_dict_get_int(const getdns_dict *dict, const char *name, uint32_t *answer);
 </div>
 
 <p>All of these helper getter functions return <code>GETDNS_RETURN_GOOD</code> 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);
+void getdns_list_destroy(getdns_list *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_dict(getdns_list *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_list(getdns_list *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_bindata(getdns_list *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);
+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);
+void getdns_dict_destroy(getdns_dict *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_dict(getdns_dict *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_list(getdns_dict *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_bindata(getdns_dict *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_set_int(getdns_dict *dict, const char *name, uint32_t child_uint32);
-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);
 </div>
 
 <p>Lists are extended with the <code>getdns_list_set_</code> calls with the <code>index</code> set to the
@@ -643,11 +643,11 @@ results that have been validated with DNSSEC, you might use:</p>
 
 <pre>
 /* . . . */
-getdns_dict * this_extensions = getdns_dict_create();
+getdns_dict * extensions = getdns_dict_create();
-this_ret = getdns_dict_set_int(this_extensions, "dnssec_return_only_secure", GETDNS_EXTENSION_TRUE);
+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);
 </pre>
 
 <p>The extensions described in this section are are:
@@ -2426,7 +2426,7 @@ getdns_pretty_print_dict() for debugging.</li>
 
 <h1>9. The Generated Files</h1>
 
-<p>There is <a href="getdns-0.700.tgz">a tarball</a> that includes the .h files,
+<p>There is <a href="getdns-0.701.tgz">a tarball</a> 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

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,