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 _PurpleSrvQueryData PurpleSrvQueryData;
  32 typedef struct _PurpleSrvResponse PurpleSrvResponse;
  33 typedef struct _PurpleTxtResponse PurpleTxtResponse;
  34
  35 #include <glib.h>
  36
  37 struct _PurpleSrvResponse {
  38         char hostname[256];
  39         int port;
  40         int weight;
  41         int pref;
  42 };
  43
  44 /**
  45  * @param resp An array of PurpleSrvResponse of size results.  The array
  46  *        is sorted based on the order described in the DNS SRV RFC.
  47  *        Users of this API should try each record in resp in order,
  48  *        starting at the beginning.
  49  */
  50 typedef void (*PurpleSrvCallback)(PurpleSrvResponse *resp, int results, gpointer data);
  51
  52 /**
  53  * Callback that returns the data retrieved from a DNS TXT lookup.
  54  *
  55  * @param responses   A GList of PurpleTxtResponse objects.
  56  * @param data        The extra data passed to purple_txt_resolve.
  57  */
  58 typedef void (*PurpleTxtCallback)(GList *responses, gpointer data);
  59
  60 /**
  61  * Queries an SRV record.
  62  *
  63  * @param protocol Name of the protocol (e.g. "sip")
  64  * @param transport Name of the transport ("tcp" or "udp")
  65  * @param domain Domain name to query (e.g. "blubb.com")
  66  * @param cb A callback which will be called with the results
  67  * @param extradata Extra data to be passed to the callback
  68  */
  69 PurpleSrvQueryData *purple_srv_resolve(const char *protocol, const char *transport, const char *domain, PurpleSrvCallback cb, gpointer extradata);
  70
  71 /**
  72  * Cancel an SRV DNS query.
  73  *
  74  * @param query_data The request to cancel.
  75  */
  76 void purple_srv_cancel(PurpleSrvQueryData *query_data);
  77
  78 /**
  79  * Queries an TXT record.
  80  *
  81  * @param owner Name of the protocol (e.g. "_xmppconnect")
  82  * @param domain Domain name to query (e.g. "blubb.com")
  83  * @param cb A callback which will be called with the results
  84  * @param extradata Extra data to be passed to the callback
  85  *
  86  * @since 2.6.0
  87  */
  88 PurpleSrvQueryData *purple_txt_resolve(const char *owner, const char *domain, PurpleTxtCallback cb, gpointer extradata);
  89
  90 /**
  91  * Cancel an TXT DNS query.
  92  *
  93  * @param query_data The request to cancel.
  94  * @since 2.6.0
  95  */
  96 void purple_txt_cancel(PurpleSrvQueryData *query_data);
  97
  98 /**
  99  * Get the value of the current TXT record.
 100  *
 101  * @param response  The TXT response record
 102  * @returns The value of the current TXT record.
 103  * @since 2.6.0
 104  */
 105 const gchar *purple_txt_response_get_content(PurpleTxtResponse *response);
 106
 107 /**
 108  * Destroy a TXT DNS response object.
 109  *
 110  * @param response The PurpleTxtResponse to destroy.
 111  * @since 2.6.0
 112  */
 113 void purple_txt_response_destroy(PurpleTxtResponse *response);
 114
 115 #ifdef __cplusplus
 116 }
 117 #endif
 118
 119 #endif /* _PURPLE_DNSSRV_H */