libpurple/dnssrv.h

   1 /**
   2  * @file dnssrv.h
   3  */
   4
   5 /* purple
   6  *
   7  * Copyright (C) 2005, Thomas Butter <butter@uni-mannheim.de>
   8  *
   9  * This program is free software; you can redistribute it and/or modify
  10  * it under the terms of the GNU General Public License as published by
  11  * the Free Software Foundation; either version 2 of the License, or
  12  * (at your option) any later version.
  13  *
  14  * This program is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17  * GNU General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU General Public License
  20  * along with this program; if not, write to the Free Software
  21  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
  22  */
  23
  24 #ifndef _PURPLE_DNSSRV_H
  25 #define _PURPLE_DNSSRV_H
  26
  27 #ifdef __cplusplus
  28 extern "C" {
  29 #endif
  30
  31 typedef struct _PurpleSrvTxtQueryData PurpleSrvTxtQueryData;
  32 typedef struct _PurpleSrvResponse PurpleSrvResponse;
  33 typedef struct _PurpleTxtResponse PurpleTxtResponse;
  34
  35 /* For compatibility, should be removed for 3.0.0
  36  */
  37 typedef struct _PurpleSrvTxtQueryData PurpleSrvQueryData;
  38
  39 #include <glib.h>
  40
  41 enum PurpleDnsType {
  42         PurpleDnsTypeTxt = 16,
  43         PurpleDnsTypeSrv = 33
  44 };
  45
  46 struct _PurpleSrvResponse {
  47         char hostname[256];
  48         int port;
  49         int weight;
  50         int pref;
  51 };
  52
  53 struct _PurpleTxtResponse {
  54         char *content;
  55 };
  56
  57 typedef void  (*PurpleSrvTxtQueryResolvedCallback) (PurpleSrvTxtQueryData *query_data, GList *records);
  58 typedef void  (*PurpleSrvTxtQueryFailedCallback) (PurpleSrvTxtQueryData *query_data, const gchar *error_message);
  59
  60 /**
  61  * SRV Request UI operations;  UIs should implement this if they want to do SRV
  62  * lookups themselves, rather than relying on the core.
  63  *
  64  * @see @ref ui-ops
  65  */
  66 typedef struct
  67 {
  68         /** If implemented, return TRUE if the UI takes responsibility for SRV
  69           * queries. When returning FALSE, the standard implementation is used.
  70           * These callbacks MUST be called asynchronously. */
  71         gboolean (*resolve)(PurpleSrvTxtQueryData *query_data,
  72                             PurpleSrvTxtQueryResolvedCallback resolved_cb,
  73                             PurpleSrvTxtQueryFailedCallback failed_cb);
  74
  75         /** Called just before @a query_data is freed; this should cancel any
  76          *  further use of @a query_data the UI would make. Unneeded if
  77          *  #resolve_host is not implemented.
  78          */
  79         void (*destroy)(PurpleSrvTxtQueryData *query_data);
  80
  81         void (*_purple_reserved1)(void);
  82         void (*_purple_reserved2)(void);
  83         void (*_purple_reserved3)(void);
  84         void (*_purple_reserved4)(void);
  85 } PurpleSrvTxtQueryUiOps;
  86
  87 /**
  88  * @param resp An array of PurpleSrvResponse of size results.  The array
  89  *        is sorted based on the order described in the DNS SRV RFC.
  90  *        Users of this API should try each record in resp in order,
  91  *        starting at the beginning.
  92  */
  93 typedef void (*PurpleSrvCallback)(PurpleSrvResponse *resp, int results, gpointer data);
  94
  95 /**
  96  * Callback that returns the data retrieved from a DNS TXT lookup.
  97  *
  98  * @param responses   A GList of PurpleTxtResponse objects.
  99  * @param data        The extra data passed to purple_txt_resolve.
 100  */
 101 typedef void (*PurpleTxtCallback)(GList *responses, gpointer data);
 102
 103 /**
 104  * Queries an SRV record.
 105  *
 106  * @param account the account that the query is being done for (or NULL)
 107  * @param protocol Name of the protocol (e.g. "sip")
 108  * @param transport Name of the transport ("tcp" or "udp")
 109  * @param domain Domain name to query (e.g. "blubb.com")
 110  * @param cb A callback which will be called with the results
 111  * @param extradata Extra data to be passed to the callback
 112  *
 113  * @since 2.8.0
 114  */
 115 PurpleSrvTxtQueryData *purple_srv_resolve_account(PurpleAccount *account, const char *protocol, const char *transport, const char *domain, PurpleSrvCallback cb, gpointer extradata);
 116
 117 #if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_DNSSRV_C_)
 118 /**
 119  * Queries an SRV record.
 120  *
 121  * @param protocol Name of the protocol (e.g. "sip")
 122  * @param transport Name of the transport ("tcp" or "udp")
 123  * @param domain Domain name to query (e.g. "blubb.com")
 124  * @param cb A callback which will be called with the results
 125  * @param extradata Extra data to be passed to the callback
 126  *
 127  * @deprecated Use purple_srv_resolve_account instead
 128  */
 129 PurpleSrvTxtQueryData *purple_srv_resolve(const char *protocol, const char *transport, const char *domain, PurpleSrvCallback cb, gpointer extradata);
 130 #endif
 131
 132 /**
 133  * Cancel an SRV or DNS query.
 134  *
 135  * @param query_data The request to cancel.
 136  */
 137 void purple_srv_cancel(PurpleSrvTxtQueryData *query_data);
 138
 139 /**
 140  * Queries an TXT record.
 141  *
 142  * @param account the account that the query is being done for (or NULL)
 143  * @param owner Name of the protocol (e.g. "_xmppconnect")
 144  * @param domain Domain name to query (e.g. "blubb.com")
 145  * @param cb A callback which will be called with the results
 146  * @param extradata Extra data to be passed to the callback
 147  *
 148  * @since 2.8.0
 149  */
 150 PurpleSrvTxtQueryData *purple_txt_resolve_account(PurpleAccount *account, const char *owner, const char *domain, PurpleTxtCallback cb, gpointer extradata);
 151
 152 #if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_DNSSRV_C_)
 153 /**
 154  * Queries an TXT record.
 155  *
 156  * @param owner Name of the protocol (e.g. "_xmppconnect")
 157  * @param domain Domain name to query (e.g. "blubb.com")
 158  * @param cb A callback which will be called with the results
 159  * @param extradata Extra data to be passed to the callback
 160  *
 161  * @deprecated Use purple_txt_resolve_account instead
 162  *
 163  * @since 2.6.0
 164  */
 165 PurpleSrvTxtQueryData *purple_txt_resolve(const char *owner, const char *domain, PurpleTxtCallback cb, gpointer extradata);
 166 #endif
 167
 168 /**
 169  * Cancel an TXT DNS query.
 170  *
 171  * @param query_data The request to cancel.
 172  * @since 2.6.0
 173  */
 174 void purple_txt_cancel(PurpleSrvTxtQueryData *query_data);
 175
 176 /**
 177  * Get the value of the current TXT record.
 178  *
 179  * @param response  The TXT response record
 180  * @returns The value of the current TXT record.
 181  * @since 2.6.0
 182  */
 183 const gchar *purple_txt_response_get_content(PurpleTxtResponse *response);
 184
 185 /**
 186  * Destroy a TXT DNS response object.
 187  *
 188  * @param response The PurpleTxtResponse to destroy.
 189  * @since 2.6.0
 190  */
 191 void purple_txt_response_destroy(PurpleTxtResponse *response);
 192
 193 /**
 194  * Cancel a SRV/TXT query and destroy the associated data structure.
 195  *
 196  * @param query_data The SRV/TXT query to cancel.  This data structure
 197  *        is freed by this function.
 198  */
 199 void purple_srv_txt_query_destroy(PurpleSrvTxtQueryData *query_data);
 200
 201 /**
 202  * Sets the UI operations structure to be used when doing a SRV/TXT
 203  * resolve.  The UI operations need only be set if the UI wants to
 204  * handle the resolve itself; otherwise, leave it as NULL.
 205  *
 206  * @param ops The UI operations structure.
 207  */
 208 void purple_srv_txt_query_set_ui_ops(PurpleSrvTxtQueryUiOps *ops);
 209
 210 /**
 211  * Returns the UI operations structure to be used when doing a SRV/TXT
 212  * resolve.
 213  *
 214  * @return The UI operations structure.
 215  */
 216 PurpleSrvTxtQueryUiOps *purple_srv_txt_query_get_ui_ops(void);
 217
 218 /**
 219  * Get the query from a PurpleDnsQueryData
 220  *
 221  * @param query_data The SRV/TXT query
 222  * @return The query.
 223  */
 224 char *purple_srv_txt_query_get_query(PurpleSrvTxtQueryData *query_data);
 225
 226 /**
 227  * Get the type from a PurpleDnsQueryData (TXT or SRV)
 228  *
 229  * @param query_data The query
 230  * @return The query.
 231  */
 232 int purple_srv_txt_query_get_type(PurpleSrvTxtQueryData *query_data);
 233
 234 #ifdef __cplusplus
 235 }
 236 #endif
 237
 238 #endif /* _PURPLE_DNSSRV_H */