interesting
/
getdns
mirror of https://github.com/getdnsapi/getdns.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Update spec to 0.701

This commit is contained in:
Willem Toorop 2015-10-22 15:12:15 +02:00
parent 973fcbddcc
commit c613743644
2 changed files with 69 additions and 69 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

54
spec/index.html
View File

@ -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_data_type(const getdns_list *this_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_list(const getdns_list *this_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_int(const getdns_list *this_list, size_t index, uint32_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 *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);
/* 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_data_type(const getdns_dict *this_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_list(const getdns_dict *this_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_int(const getdns_dict *this_dict, const char *name, uint32_t *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 *dict, const char *name, getdns_data_type *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 *dict, const char *name, getdns_list **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 *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);
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);
</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();
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);
</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

84
src/getdns/getdns.h.in
View File

@ -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,