home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2007 September / PCWSEP07.iso / Software / Linux / Linux Mint 3.0 Light / LinuxMint-3.0-Light.iso / casper / filesystem.squashfs / usr / include / libpurple / dnsquery.h < prev    next >
Encoding:
C/C++ Source or Header  |  2007-05-04  |  4.5 KB  |  148 lines
  1. /**
  2.  * @file dnsquery.h DNS query API
  3.  * @ingroup core
  4.  *
  5.  * purple
  6.  *
  7.  * Purple is the legal property of its developers, whose names are too numerous
  8.  * to list here.  Please refer to the COPYRIGHT file distributed with this
  9.  * source distribution.
  10.  *
  11.  * This program is free software; you can redistribute it and/or modify
  12.  * it under the terms of the GNU General Public License as published by
  13.  * the Free Software Foundation; either version 2 of the License, or
  14.  * (at your option) any later version.
  15.  *
  16.  * This program is distributed in the hope that it will be useful,
  17.  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19.  * GNU General Public License for more details.
  20.  *
  21.  * You should have received a copy of the GNU General Public License
  22.  * along with this program; if not, write to the Free Software
  23.  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  24.  */
  25. #ifndef _PURPLE_DNSQUERY_H_
  26. #define _PURPLE_DNSQUERY_H_
  27.  
  28. #include <glib.h>
  29. #include "eventloop.h"
  30. #include "account.h"
  31.  
  32. typedef struct _PurpleDnsQueryData PurpleDnsQueryData;
  33.  
  34. /**
  35.  * The "hosts" parameter is a linked list containing pairs of
  36.  * one size_t addrlen and one struct sockaddr *addr.  It should
  37.  * be free'd by the callback function.
  38.  */
  39. typedef void (*PurpleDnsQueryConnectFunction)(GSList *hosts, gpointer data, const char *error_message);
  40.  
  41. /**
  42.  * Callbacks used by the UI if it handles resolving DNS
  43.  */
  44. typedef void  (*PurpleDnsQueryResolvedCallback) (PurpleDnsQueryData *query_data, GSList *hosts);
  45. typedef void  (*PurpleDnsQueryFailedCallback) (PurpleDnsQueryData *query_data, const gchar *error_message);
  46.  
  47. /**
  48.  * DNS Request UI operations
  49.  */
  50. typedef struct
  51. {
  52.     /* If implemented, the UI is responsible for DNS queries */
  53.     gboolean (*resolve_host)(PurpleDnsQueryData *query_data, PurpleDnsQueryResolvedCallback resolved_cb, PurpleDnsQueryFailedCallback failed_cb);
  54.  
  55.     /* After destroy is called, query_data will be feed, so this must
  56.      * cancel any further use of it the UI would do. Unneeded if 
  57.      * resolve_host is not implemented.
  58.      */
  59.     void (*destroy)(PurpleDnsQueryData *query_data);
  60.  
  61.     void (*_purple_reserved1)(void);
  62.     void (*_purple_reserved2)(void);
  63.     void (*_purple_reserved3)(void);
  64.     void (*_purple_reserved4)(void);
  65. } PurpleDnsQueryUiOps;
  66.  
  67. #ifdef __cplusplus
  68. extern "C" {
  69. #endif
  70.  
  71. /**************************************************************************/
  72. /** @name DNS query API                                                   */
  73. /**************************************************************************/
  74. /*@{*/
  75.  
  76. /**
  77.  * Perform an asynchronous DNS query.
  78.  *
  79.  * @param hostname The hostname to resolve.
  80.  * @param port     A port number which is stored in the struct sockaddr.
  81.  * @param callback The callback function to call after resolving.
  82.  * @param data     Extra data to pass to the callback function.
  83.  *
  84.  * @return NULL if there was an error, otherwise return a reference to
  85.  *         a data structure that can be used to cancel the pending
  86.  *         DNS query, if needed.
  87.  */
  88. PurpleDnsQueryData *purple_dnsquery_a(const char *hostname, int port, PurpleDnsQueryConnectFunction callback, gpointer data);
  89.  
  90. /**
  91.  * Cancel a DNS query and destroy the associated data structure.
  92.  *
  93.  * @param query_data The DNS query to cancel.  This data structure
  94.  *        is freed by this function.
  95.  */
  96. void purple_dnsquery_destroy(PurpleDnsQueryData *query_data);
  97.  
  98. /**
  99.  * Sets the UI operations structure to be used when doing a DNS
  100.  * resolve.  The UI operations need only be set if the UI wants to
  101.  * handle the resolve itself; otherwise, leave it as NULL.
  102.  *
  103.  * @param ops The UI operations structure.
  104.  */
  105. void purple_dnsquery_set_ui_ops(PurpleDnsQueryUiOps *ops);
  106.  
  107. /**
  108.  * Returns the UI operations structure to be used when doing a DNS
  109.  * resolve.
  110.  *
  111.  * @return The UI operations structure.
  112.  */
  113. PurpleDnsQueryUiOps *purple_dnsquery_get_ui_ops(void);
  114.  
  115. /**
  116.  * Get the host associated with a PurpleDnsQueryData
  117.  *
  118.  * @param query_data The DNS query
  119.  * @return The host.
  120.  */
  121. char *purple_dnsquery_get_host(PurpleDnsQueryData *query_data);
  122.  
  123. /**
  124.  * Get the port associated with a PurpleDnsQueryData
  125.  *
  126.  * @param query_data The DNS query
  127.  * @return The port.
  128.  */
  129. unsigned short purple_dnsquery_get_port(PurpleDnsQueryData *query_data);
  130.  
  131. /**
  132.  * Initializes the DNS query subsystem.
  133.  */
  134. void purple_dnsquery_init(void);
  135.  
  136. /**
  137.  * Uninitializes the DNS query subsystem.
  138.  */
  139. void purple_dnsquery_uninit(void);
  140.  
  141. /*@}*/
  142.  
  143. #ifdef __cplusplus
  144. }
  145. #endif
  146.  
  147. #endif /* _PURPLE_DNSQUERY_H_ */
  148.