[API 0.367 again] getdns_dict_remove_name() added

Paul added getdns_dict_remove_name() and changed the doc for the adders to be more sane.

spec/example-all-functions.c

@@ -203,6 +203,7 @@ retregular =  getdns_dict_set_dict(dictarg, charstararg, dictarg);
 retregular =  getdns_dict_set_list(dictarg, charstararg, listarg);
 retregular =  getdns_dict_set_bindata(dictarg, charstararg, bindataarg);
 retregular =  getdns_dict_set_int(dictarg, charstararg, uint32arg);
+retregular =  getdns_dict_remove_name(dictarg, charstararg);
 
 retcharstar =  getdns_convert_fqdn_to_dns_name(
   charstararg

spec/example-reverse.c

@@ -0,0 +1,105 @@
+#include <stdio.h>
+#include <stdint.h>
+#include <stdlib.h>
+#include <string.h>
+#include <inttypes.h>
+#include <getdns_libevent.h>
+
+#define UNUSED_PARAM(x) ((void)(x))
+
+/* Set up the callback function, which will also do the processing of the results */
+void this_callbackfn(struct getdns_context *this_context,
+                     uint16_t     this_callback_type,
+                     struct getdns_dict *this_response, 
+                     void *this_userarg,
+                     getdns_transaction_t this_transaction_id)
+{
+	UNUSED_PARAM(this_userarg);  /* Not looking at the userarg for this example */
+	UNUSED_PARAM(this_context);  /* Not looking at the context for this example */
+	getdns_return_t this_ret;  /* Holder for all function returns */
+	if (this_callback_type == GETDNS_CALLBACK_COMPLETE)  /* This is a callback with data */
+	{
+		/* Be sure the search returned something */
+		uint32_t * this_error = NULL;
+		this_ret = getdns_dict_get_int(this_response, "status", this_error);  // Ignore any error
+		if (*this_error != GETDNS_RESPSTATUS_GOOD)  // If the search didn't return "good"
+		{
+			fprintf(stderr, "The search had no results, and a return value of %d. Exiting.", *this_error);
+			return;
+		}
+		struct getdns_list * just_the_addresses_ptr;
+		this_ret = getdns_dict_get_list(this_response, "just_address_answers", &just_the_addresses_ptr);
+		if (this_ret != GETDNS_RETURN_GOOD)  // This check is really not needed, but prevents a compiler error under "pedantic"
+		{
+			fprintf(stderr, "Trying to get the answers failed: %d", this_ret);
+			return;
+		}
+		size_t * num_addresses_ptr = NULL;
+		this_ret = getdns_list_get_length(just_the_addresses_ptr, num_addresses_ptr);  // Ignore any error
+		/* Go through each record */
+		for ( size_t rec_count = 0; rec_count <= *num_addresses_ptr; ++rec_count )
+		{
+			struct getdns_dict * this_address;
+			this_ret = getdns_list_get_dict(just_the_addresses_ptr, rec_count, &this_address);  // Ignore any error
+			/* Just print the address */
+			struct getdns_bindata * this_address_data;
+			this_ret = getdns_dict_get_bindata(this_address, "address_data", &this_address_data); // Ignore any error
+			printf("The address is %s", getdns_display_ip_address(this_address_data));
+		}
+	}
+	else if (this_callback_type == GETDNS_CALLBACK_CANCEL)
+		fprintf(stderr, "The callback with ID %"PRIu64" was cancelled. Exiting.", this_transaction_id);
+	else
+		fprintf(stderr, "The callback got a callback_type of %d. Exiting.", this_callback_type);
+}
+
+int main()
+{
+	/* Create the DNS context for this call */
+	struct getdns_context *this_context = NULL;
+	getdns_return_t context_create_return = getdns_context_create(&this_context, 1);
+	if (context_create_return != GETDNS_RETURN_GOOD)
+	{
+		fprintf(stderr, "Trying to create the context failed: %d", context_create_return);
+		return(GETDNS_RETURN_GENERIC_ERROR);
+	}
+	/* Create an event base and put it in the context using the unknown function name */
+	struct event_base *this_event_base;
+	this_event_base = event_base_new();
+	if (this_event_base == NULL)
+	{
+		fprintf(stderr, "Trying to create the event base failed.");
+		return(GETDNS_RETURN_GENERIC_ERROR);
+	}
+	(void)getdns_extension_set_libevent_base(this_context, this_event_base);
+	/* Set up the getdns call */
+	struct getdns_dict * this_addr_to_look_up = getdns_dict_create();
+	// TODO: check the return value above
+	struct getdns_bindata * this_type = { 4, 0x49507634 };
+	getdns_return_t this_ret = getdns_dict_set_bindata(this_addr_to_look_up, "address_type", this_type);
+	struct getdns_bindata * this_ipv4_addr = { 4, 0x08080808 };
+	this_ret = getdns_dict_set_bindata(this_addr_to_look_up, "address_data", this_ipv4_addr;
+	char* this_userarg = "somestring"; // Could add things here to help identify this call
+	getdns_transaction_t this_transaction_id = 0;
+
+	/* Make the call */
+	getdns_return_t dns_request_return = getdns_hostname(this_context, this_addr_to_look_up,
+		NULL, this_userarg, &this_transaction_id, this_callbackfn);
+	if (dns_request_return == GETDNS_RETURN_BAD_DOMAIN_NAME)
+	{
+		fprintf(stderr, "A bad IP address was used: %s. Exiting.", this_ipv4_addr);
+		return(GETDNS_RETURN_GENERIC_ERROR);
+	}
+	else
+	{
+		/* Call the event loop */
+		int dispatch_return = event_base_dispatch(this_event_base);
+		UNUSED_PARAM(dispatch_return);
+		// TODO: check the return value above
+	}
+	/* Clean up */
+	getdns_dict_destroy(this_addr_to_look_up);
+	getdns_context_destroy(this_context);
+	/* Assuming we get here, leave gracefully */
+	exit(EXIT_SUCCESS);
+}

spec/getdns_core_only.c

@@ -266,6 +266,9 @@ getdns_return_t getdns_dict_set_bindata(struct getdns_dict *this_dict, char *nam
 getdns_return_t getdns_dict_set_int(struct getdns_dict *this_dict, char *name, uint32_t child_uint32)
 { UNUSED_PARAM(this_dict); UNUSED_PARAM(name); UNUSED_PARAM(child_uint32); return GETDNS_RETURN_GOOD; }
 
+getdns_return_t getdns_dict_remove_name(struct getdns_dict *this_dict, char *name)
+{ UNUSED_PARAM(this_dict); UNUSED_PARAM(name); return GETDNS_RETURN_GOOD; }
+
 char *
 getdns_convert_dns_name_to_fqdn(
   char  *name_from_dns_response

spec/getdns_core_only.h

@@ -1,4 +1,4 @@
-/* Created at 2013-12-04-16-47-24*/
+/* Created at 2013-12-06-14-39-56*/
 #ifndef GETDNS_H
 #define GETDNS_H
 
@@ -320,6 +320,7 @@ getdns_return_t getdns_dict_set_dict(struct getdns_dict *this_dict, char *name,
 getdns_return_t getdns_dict_set_list(struct getdns_dict *this_dict, char *name, struct getdns_list *child_list);
 getdns_return_t getdns_dict_set_bindata(struct getdns_dict *this_dict, char *name, struct getdns_bindata *child_bindata);
 getdns_return_t getdns_dict_set_int(struct getdns_dict *this_dict, char *name, uint32_t child_uint32);
+getdns_return_t getdns_dict_remove_name(struct getdns_dict *this_dict, char *name);
 
 /* Callback arguments */
 typedef void (*getdns_callback_t)(

spec/index.html

@@ -97,7 +97,7 @@ tr.code { font-family: monospace }
 
 <p class=title>Description of the <code>getdns</code> API</p>
 <p class=title2>Paul Hoffman, Editor</p>
-<p class=title2>Document version: "getdns November 2013"</p>
+<p class=title2>Document version: "getdns December 2013"</p>
 
 <p>This document describes a modern asynchronous DNS API. This new API is intended to be useful to
 application developers and operating system distributors as a way of making
@@ -602,13 +602,20 @@ getdns_return_t getdns_dict_set_dict(struct getdns_dict *this_dict, char *name,
 getdns_return_t getdns_dict_set_list(struct getdns_dict *this_dict, char *name, struct getdns_list *child_list);
 getdns_return_t getdns_dict_set_bindata(struct getdns_dict *this_dict, char *name, struct getdns_bindata *child_bindata);
 getdns_return_t getdns_dict_set_int(struct getdns_dict *this_dict, char *name, uint32_t child_uint32);
+getdns_return_t getdns_dict_remove_name(struct getdns_dict *this_dict, char *name);
 </div>
 
+<p>Lists are extended with the <code>getdns_list_set_</code> calls with the <code>index</code> set to the
+size of the list (such as 0 for an empty list). Dicts are extended with the <code>getdns_dict_set_</code> calls
+with the <code>name</code> set to a name that does not yet exist. Name-value pairs are removed with
+<code>getdns_dict_remove_name()</code>.</p>
+
 <p>These helper setter functions return <code>GETDNS_RETURN_GOOD</code> if the call is successful.
-The list functions will return <code>GETDNS_RETURN_NO_SUCH_LIST_ITEM</code> if the index argument is
+The functions return <code>GETDNS_RETURN_WRONG_TYPE_REQUESTED</code> if the requested data type
-out of range; the dict functions will return <code>GETDNS_RETURN_NO_SUCH_DICT_NAME</code> if the name
+doesn't match the contents of the indexed argument or name. The list functions will return
-argument doesn't exist in the dict. The functions also return <code>GETDNS_RETURN_WRONG_TYPE_REQUESTED</code>
+<code>GETDNS_RETURN_NO_SUCH_LIST_ITEM</code> if the index argument is higher than the length of the
-if the requested data type doesn't match the contents of the indexed argument or name.</p>
+list. <code>getdns_dict_remove_name()</code> will return
+<code>GETDNS_RETURN_NO_SUCH_DICT_NAME</code> if the name argument doesn't exist in the dict. </p>
 
 <h1>3. <a id="Extensions">Extensions</a></h1>
 
@@ -2089,7 +2096,7 @@ getdns_context_set_edns_do_bit(
 <p class=cont>The value is between 0 and 1; the default
 is <span class=default>0</span>.</p>
 
-<h2>8.9 Context use of custom memory management functions</h2>
+<h2>8.9 Context Use of Custom Memory Management Functions</h2>
 
 <div class=forh>
 getdns_return_t
@@ -2101,7 +2108,7 @@ getdns_context_set_memory_functions(
 );</div>
 <p class=cont>The given memory management functions will be used for creating the response dicts.
 The response dicts inherit the custom memory management functions from the context and will deallocate themselves (and their members) with the custom deallocator.
-By default the system <span class=default>malloc</span>, <span class=default>realloc</span> and <span>free</span> are used.</p>
+By default, the system <span class=default>malloc</span>, <span class=default>realloc</span>, and <span>free</span> are used.</p>
 
 <div class=forh>
 getdns_return_t
@@ -2112,8 +2119,8 @@ getdns_context_set_extended_memory_functions(
   void                  *(*realloc)(void *userarg, void *ptr, size_t sz),
   void                  (*free)(void *userarg, void *ptr)
 );</div>
-<p class=cont><p class=cont>The given extended memory management functions will be used for creating the response dicts.
+<p class=cont>The given extended memory management functions will be used for creating the response dicts.
-The value of <code>userarg</code> argument will be passed to the custom <code>malloc<code>, <code>realloc</code> and <code>free</code>.
+The value of <code>userarg</code> argument will be passed to the custom <code>malloc<code>, <code>realloc</code>, and <code>free</code>.
 The response dicts inherit the custom memory management functions and the value for <code>userarg</code> from the context and will deallocate themselves (and their members) with the custom deallocator.</p>
 
 <h2>8.10 <a id="ContextCodes">Context Codes</a></h2>