diff libgaim/dnsquery.h @ 14238:f189327b9968

[gaim-migrate @ 16920] Cancelable DNS queries. This eliminates crashes when you cancel a connection attempt while we're waiting for a response from a DNS server. I tested with all three methods, so they SHOULD be ok. Let me know if you have problems. I should be around today, starting in maybe an hour. I feel like it's kinda dumb for us to have three implementations for the same thing. I want to get rid of the child-process method (currently used in Unix and OS-X) and use the thread-based method (currently used in Windows) everywhere. Then we can get rid of the third method, too (currently used when !Unix and !OS-X and !Windows) Any objections? committer: Tailor Script <[e-mail]>

--- a/libgaim/dnsquery.h	Sun Aug 20 22:16:13 2006 +0000
+++ b/libgaim/dnsquery.h	Sun Aug 20 22:24:13 2006 +0000
@@ -32,7 +32,8 @@
 
 /**
  * The "hosts" parameter is a linked list containing pairs of
- * one size_t addrlen and one struct sockaddr *addr.
+ * one size_t addrlen and one struct sockaddr *addr.  It should
+ * be free'd by the callback function.
  */
 typedef void (*GaimDnsQueryConnectFunction)(GSList *hosts, gpointer data, const char *error_message);
 
@@ -49,12 +50,12 @@
 /*@{*/
 
 /**
- * Do an async dns query
+ * Perform an asynchronous DNS query.
  *
- * @param hostname The hostname to resolve
- * @param port A portnumber which is stored in the struct sockaddr
- * @param callback Callback to call after resolving
- * @param data Extra data for the callback function
+ * @param hostname The hostname to resolve.
+ * @param port     A port number which is stored in the struct sockaddr.
+ * @param callback The callback function to call after resolving.
+ * @param data     Extra data to pass to the callback function.
  *
  * @return NULL if there was an error, otherwise return a reference to
  *         a data structure that can be used to cancel the pending
@@ -62,6 +63,24 @@
  */
 GaimDnsQueryData *gaim_dnsquery_a(const char *hostname, int port, GaimDnsQueryConnectFunction callback, gpointer data);
 
+/**
+ * Cancel a DNS query and destroy the associated data structure.
+ *
+ * @param query_data The DNS query to cancel.  This data structure
+ *        is freed by this function.
+ */
+void gaim_dnsquery_destroy(GaimDnsQueryData *query_data);
+
+/**
+ * Initializes the DNS query subsystem.
+ */
+void gaim_dnsquery_init(void);
+
+/**
+ * Uninitializes the DNS query subsystem.
+ */
+void gaim_dnsquery_uninit(void);
+
 /*@}*/
 
 #ifdef __cplusplus