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  * @deprecated Use purple_srv_txt_query_destroy instead
 138  */
 139 void purple_srv_cancel(PurpleSrvTxtQueryData *query_data);
 140
 141 /**
 142  * Queries an TXT record.
 143  *
 144  * @param account the account that the query is being done for (or NULL)
 145  * @param owner Name of the protocol (e.g. "_xmppconnect")
 146  * @param domain Domain name to query (e.g. "blubb.com")
 147  * @param cb A callback which will be called with the results
 148  * @param extradata Extra data to be passed to the callback
 149  *
 150  * @since 2.8.0
 151  */
 152 PurpleSrvTxtQueryData *purple_txt_resolve_account(PurpleAccount *account, const char *owner, const char *domain, PurpleTxtCallback cb, gpointer extradata);
 153
 154 #if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_DNSSRV_C_)
 155 /**
 156  * Queries an TXT record.
 157  *
 158  * @param owner Name of the protocol (e.g. "_xmppconnect")
 159  * @param domain Domain name to query (e.g. "blubb.com")
 160  * @param cb A callback which will be called with the results
 161  * @param extradata Extra data to be passed to the callback
 162  *
 163  * @deprecated Use purple_txt_resolve_account instead
 164  *
 165  * @since 2.6.0
 166  */
 167 PurpleSrvTxtQueryData *purple_txt_resolve(const char *owner, const char *domain, PurpleTxtCallback cb, gpointer extradata);
 168 #endif
 169
 170 /**
 171  * Cancel an TXT DNS query.
 172  *
 173  * @param query_data The request to cancel.
 174  * @since 2.6.0
 175  *
 176  * @deprecated Use purple_srv_txt_query_destroy instead
 177  */
 178 void purple_txt_cancel(PurpleSrvTxtQueryData *query_data);
 179
 180 /**
 181  * Get the value of the current TXT record.
 182  *
 183  * @param response  The TXT response record
 184  * @returns The value of the current TXT record.
 185  * @since 2.6.0
 186  */
 187 const gchar *purple_txt_response_get_content(PurpleTxtResponse *response);
 188
 189 /**
 190  * Destroy a TXT DNS response object.
 191  *
 192  * @param response The PurpleTxtResponse to destroy.
 193  * @since 2.6.0
 194  */
 195 void purple_txt_response_destroy(PurpleTxtResponse *response);
 196
 197 /**
 198  * Cancel a SRV/TXT query and destroy the associated data structure.
 199  *
 200  * @param query_data The SRV/TXT query to cancel.  This data structure
 201  *        is freed by this function.
 202  */
 203 void purple_srv_txt_query_destroy(PurpleSrvTxtQueryData *query_data);
 204
 205 /**
 206  * Sets the UI operations structure to be used when doing a SRV/TXT
 207  * resolve.  The UI operations need only be set if the UI wants to
 208  * handle the resolve itself; otherwise, leave it as NULL.
 209  *
 210  * @param ops The UI operations structure.
 211  */
 212 void purple_srv_txt_query_set_ui_ops(PurpleSrvTxtQueryUiOps *ops);
 213
 214 /**
 215  * Returns the UI operations structure to be used when doing a SRV/TXT
 216  * resolve.
 217  *
 218  * @return The UI operations structure.
 219  */
 220 PurpleSrvTxtQueryUiOps *purple_srv_txt_query_get_ui_ops(void);
 221
 222 /**
 223  * Get the query from a PurpleDnsQueryData
 224  *
 225  * @param query_data The SRV/TXT query
 226  * @return The query.
 227  */
 228 char *purple_srv_txt_query_get_query(PurpleSrvTxtQueryData *query_data);
 229
 230 /**
 231  * Get the type from a PurpleDnsQueryData (TXT or SRV)
 232  *
 233  * @param query_data The query
 234  * @return The query.
 235  */
 236 int purple_srv_txt_query_get_type(PurpleSrvTxtQueryData *query_data);
 237
 238 #ifdef __cplusplus
 239 }
 240 #endif
 241
 242 #endif /* _PURPLE_DNSSRV_H */