Mercurialadium-1.4 / file revision
summary | shortlog | changelog | graph | tags | branches | files | changeset | file | latest | revisions | annotate | diff | raw | help
Frameworks/libpurple.framework/Versions/0.6.2/Headers/dnsquery.h
author Zachary West <zacw@adium.im>
Fri Aug 21 13:25:11 2009 -0700 (2009-08-21)
changeset 2592 e8d15275025e
parent 1739 Frameworks/libpurple.framework/Versions/0.6.0/Headers/dnsquery.h@8b0daad9656c
permissions -rw-r--r--
im.pidgin.adium.1-4 at 267c6165e02e34318a1823960bd04c0639952f73 
     1 /**
     2  * @file dnsquery.h DNS query API
     3  * @ingroup core
     4  */
     5 
     6 /* purple
     7  *
     8  * Purple is the legal property of its developers, whose names are too numerous
     9  * to list here.  Please refer to the COPYRIGHT file distributed with this
    10  * source distribution.
    11  *
    12  * This program is free software; you can redistribute it and/or modify
    13  * it under the terms of the GNU General Public License as published by
    14  * the Free Software Foundation; either version 2 of the License, or
    15  * (at your option) any later version.
    16  *
    17  * This program is distributed in the hope that it will be useful,
    18  * but WITHOUT ANY WARRANTY; without even the implied warranty of
    19  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    20  * GNU General Public License for more details.
    21  *
    22  * You should have received a copy of the GNU General Public License
    23  * along with this program; if not, write to the Free Software
    24  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
    25  */
    26 #ifndef _PURPLE_DNSQUERY_H_
    27 #define _PURPLE_DNSQUERY_H_
    28 
    29 #include <glib.h>
    30 #include "eventloop.h"
    31 #include "account.h"
    32 
    33 typedef struct _PurpleDnsQueryData PurpleDnsQueryData;
    34 
    35 /**
    36  * The "hosts" parameter is a linked list containing pairs of
    37  * one size_t addrlen and one struct sockaddr *addr.  It should
    38  * be free'd by the callback function.
    39  */
    40 typedef void (*PurpleDnsQueryConnectFunction)(GSList *hosts, gpointer data, const char *error_message);
    41 
    42 /**
    43  * Callbacks used by the UI if it handles resolving DNS
    44  */
    45 typedef void  (*PurpleDnsQueryResolvedCallback) (PurpleDnsQueryData *query_data, GSList *hosts);
    46 typedef void  (*PurpleDnsQueryFailedCallback) (PurpleDnsQueryData *query_data, const gchar *error_message);
    47 
    48 /**
    49  * DNS Request UI operations;  UIs should implement this if they want to do DNS
    50  * lookups themselves, rather than relying on the core.
    51  *
    52  * @see @ref ui-ops
    53  */
    54 typedef struct
    55 {
    56 	/** If implemented, the UI is responsible for DNS queries */
    57 	gboolean (*resolve_host)(PurpleDnsQueryData *query_data,
    58 	                         PurpleDnsQueryResolvedCallback resolved_cb,
    59 	                         PurpleDnsQueryFailedCallback failed_cb);
    60 
    61 	/** Called just before @a query_data is freed; this should cancel any
    62 	 *  further use of @a query_data the UI would make. Unneeded if
    63 	 *  #resolve_host is not implemented.
    64 	 */
    65 	void (*destroy)(PurpleDnsQueryData *query_data);
    66 
    67 	void (*_purple_reserved1)(void);
    68 	void (*_purple_reserved2)(void);
    69 	void (*_purple_reserved3)(void);
    70 	void (*_purple_reserved4)(void);
    71 } PurpleDnsQueryUiOps;
    72 
    73 #ifdef __cplusplus
    74 extern "C" {
    75 #endif
    76 
    77 /**************************************************************************/
    78 /** @name DNS query API                                                   */
    79 /**************************************************************************/
    80 /*@{*/
    81 
    82 /**
    83  * Perform an asynchronous DNS query.
    84  *
    85  * @param hostname The hostname to resolve.
    86  * @param port     A port number which is stored in the struct sockaddr.
    87  * @param callback The callback function to call after resolving.
    88  * @param data     Extra data to pass to the callback function.
    89  *
    90  * @return NULL if there was an error, otherwise return a reference to
    91  *         a data structure that can be used to cancel the pending
    92  *         DNS query, if needed.
    93  */
    94 PurpleDnsQueryData *purple_dnsquery_a(const char *hostname, int port, PurpleDnsQueryConnectFunction callback, gpointer data);
    95 
    96 /**
    97  * Cancel a DNS query and destroy the associated data structure.
    98  *
    99  * @param query_data The DNS query to cancel.  This data structure
   100  *        is freed by this function.
   101  */
   102 void purple_dnsquery_destroy(PurpleDnsQueryData *query_data);
   103 
   104 /**
   105  * Sets the UI operations structure to be used when doing a DNS
   106  * resolve.  The UI operations need only be set if the UI wants to
   107  * handle the resolve itself; otherwise, leave it as NULL.
   108  *
   109  * @param ops The UI operations structure.
   110  */
   111 void purple_dnsquery_set_ui_ops(PurpleDnsQueryUiOps *ops);
   112 
   113 /**
   114  * Returns the UI operations structure to be used when doing a DNS
   115  * resolve.
   116  *
   117  * @return The UI operations structure.
   118  */
   119 PurpleDnsQueryUiOps *purple_dnsquery_get_ui_ops(void);
   120 
   121 /**
   122  * Get the host associated with a PurpleDnsQueryData
   123  *
   124  * @param query_data The DNS query
   125  * @return The host.
   126  */
   127 char *purple_dnsquery_get_host(PurpleDnsQueryData *query_data);
   128 
   129 /**
   130  * Get the port associated with a PurpleDnsQueryData
   131  *
   132  * @param query_data The DNS query
   133  * @return The port.
   134  */
   135 unsigned short purple_dnsquery_get_port(PurpleDnsQueryData *query_data);
   136 
   137 /**
   138  * Initializes the DNS query subsystem.
   139  */
   140 void purple_dnsquery_init(void);
   141 
   142 /**
   143  * Uninitializes the DNS query subsystem.
   144  */
   145 void purple_dnsquery_uninit(void);
   146 
   147 /*@}*/
   148 
   149 #ifdef __cplusplus
   150 }
   151 #endif
   152 
   153 #endif /* _PURPLE_DNSQUERY_H_ */
adium-1.4