annotate libpurple/dnssrv.h @ 28881:30f8f2105740

I believe this change fixes offline message retrieval. Fixes #10663
author Mark Doliner <mark@kingant.net>
date Wed, 04 Nov 2009 23:39:08 +0000
parents 63cb8c4f3c66
children 08dcd2d4f0b7
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
15374
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
1 /**
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
2 * @file dnssrv.h
20074
6bf32c9e15a7 remove gpl boilerplate from doxygen docs
Sean Egan <seanegan@gmail.com>
parents: 19680
diff changeset
3 */
6bf32c9e15a7 remove gpl boilerplate from doxygen docs
Sean Egan <seanegan@gmail.com>
parents: 19680
diff changeset
4
6bf32c9e15a7 remove gpl boilerplate from doxygen docs
Sean Egan <seanegan@gmail.com>
parents: 19680
diff changeset
5 /* purple
15374
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
6 *
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
7 * Copyright (C) 2005, Thomas Butter <butter@uni-mannheim.de>
20074
6bf32c9e15a7 remove gpl boilerplate from doxygen docs
Sean Egan <seanegan@gmail.com>
parents: 19680
diff changeset
8 *
15374
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
9 * This program is free software; you can redistribute it and/or modify
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
10 * it under the terms of the GNU General Public License as published by
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
11 * the Free Software Foundation; either version 2 of the License, or
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
12 * (at your option) any later version.
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
13 *
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
14 * This program is distributed in the hope that it will be useful,
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
17 * GNU General Public License for more details.
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
18 *
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
19 * You should have received a copy of the GNU General Public License
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
20 * along with this program; if not, write to the Free Software
19680
44b4e8bd759b The FSF changed its address a while ago; our files were out of date.
John Bailey <rekkanoryo@rekkanoryo.org>
parents: 15823
diff changeset
21 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA
15374
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
22 */
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
23
15823
32c366eeeb99 sed -ie 's/gaim/purple/g'
Sean Egan <seanegan@gmail.com>
parents: 15374
diff changeset
24 #ifndef _PURPLE_DNSSRV_H
32c366eeeb99 sed -ie 's/gaim/purple/g'
Sean Egan <seanegan@gmail.com>
parents: 15374
diff changeset
25 #define _PURPLE_DNSSRV_H
15374
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
26
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
27 #ifdef __cplusplus
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
28 extern "C" {
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
29 #endif
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
30
25593
affaa4c4836e * some code style adjustments in caps.c
Tobias Markmann <tfar@soc.pidgin.im>
parents: 20074
diff changeset
31 typedef struct _PurpleSrvQueryData PurpleSrvQueryData;
15823
32c366eeeb99 sed -ie 's/gaim/purple/g'
Sean Egan <seanegan@gmail.com>
parents: 15374
diff changeset
32 typedef struct _PurpleSrvResponse PurpleSrvResponse;
25593
affaa4c4836e * some code style adjustments in caps.c
Tobias Markmann <tfar@soc.pidgin.im>
parents: 20074
diff changeset
33 typedef struct _PurpleTxtResponse PurpleTxtResponse;
15374
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
34
26672
acee7d2b1983 Hide PurpleTxtResponse and use a more purple API
Paul Aurich <paul@darkrain42.org>
parents: 26671
diff changeset
35 #include <glib.h>
acee7d2b1983 Hide PurpleTxtResponse and use a more purple API
Paul Aurich <paul@darkrain42.org>
parents: 26671
diff changeset
36
15823
32c366eeeb99 sed -ie 's/gaim/purple/g'
Sean Egan <seanegan@gmail.com>
parents: 15374
diff changeset
37 struct _PurpleSrvResponse {
15374
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
38 char hostname[256];
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
39 int port;
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
40 int weight;
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
41 int pref;
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
42 };
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
43
27295
3e516701dd33 Changes to our DNS SRV record sorting, care of Vijay Vijay Raghunathan
Mark Doliner <mark@kingant.net>
parents: 26672
diff changeset
44 /**
3e516701dd33 Changes to our DNS SRV record sorting, care of Vijay Vijay Raghunathan
Mark Doliner <mark@kingant.net>
parents: 26672
diff changeset
45 * @param resp An array of PurpleSrvResponse of size results. The array
3e516701dd33 Changes to our DNS SRV record sorting, care of Vijay Vijay Raghunathan
Mark Doliner <mark@kingant.net>
parents: 26672
diff changeset
46 * is sorted based on the order described in the DNS SRV RFC.
3e516701dd33 Changes to our DNS SRV record sorting, care of Vijay Vijay Raghunathan
Mark Doliner <mark@kingant.net>
parents: 26672
diff changeset
47 * Users of this API should try each record in resp in order,
3e516701dd33 Changes to our DNS SRV record sorting, care of Vijay Vijay Raghunathan
Mark Doliner <mark@kingant.net>
parents: 26672
diff changeset
48 * starting at the beginning.
3e516701dd33 Changes to our DNS SRV record sorting, care of Vijay Vijay Raghunathan
Mark Doliner <mark@kingant.net>
parents: 26672
diff changeset
49 */
26672
acee7d2b1983 Hide PurpleTxtResponse and use a more purple API
Paul Aurich <paul@darkrain42.org>
parents: 26671
diff changeset
50 typedef void (*PurpleSrvCallback)(PurpleSrvResponse *resp, int results, gpointer data);
25593
affaa4c4836e * some code style adjustments in caps.c
Tobias Markmann <tfar@soc.pidgin.im>
parents: 20074
diff changeset
51
26672
acee7d2b1983 Hide PurpleTxtResponse and use a more purple API
Paul Aurich <paul@darkrain42.org>
parents: 26671
diff changeset
52 /**
acee7d2b1983 Hide PurpleTxtResponse and use a more purple API
Paul Aurich <paul@darkrain42.org>
parents: 26671
diff changeset
53 * Callback that returns the data retrieved from a DNS TXT lookup.
acee7d2b1983 Hide PurpleTxtResponse and use a more purple API
Paul Aurich <paul@darkrain42.org>
parents: 26671
diff changeset
54 *
27431
a71cc338f0fd A couple more s/GSList/GList/ changes as fallout from the last change.
Etan Reisner <pidgin@unreliablesource.net>
parents: 27295
diff changeset
55 * @param responses A GList of PurpleTxtResponse objects.
26672
acee7d2b1983 Hide PurpleTxtResponse and use a more purple API
Paul Aurich <paul@darkrain42.org>
parents: 26671
diff changeset
56 * @param data The extra data passed to purple_txt_resolve.
acee7d2b1983 Hide PurpleTxtResponse and use a more purple API
Paul Aurich <paul@darkrain42.org>
parents: 26671
diff changeset
57 */
27431
a71cc338f0fd A couple more s/GSList/GList/ changes as fallout from the last change.
Etan Reisner <pidgin@unreliablesource.net>
parents: 27295
diff changeset
58 typedef void (*PurpleTxtCallback)(GList *responses, gpointer data);
15374
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
59
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
60 /**
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
61 * Queries an SRV record.
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
62 *
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
63 * @param protocol Name of the protocol (e.g. "sip")
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
64 * @param transport Name of the transport ("tcp" or "udp")
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
65 * @param domain Domain name to query (e.g. "blubb.com")
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
66 * @param cb A callback which will be called with the results
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
67 * @param extradata Extra data to be passed to the callback
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
68 */
15823
32c366eeeb99 sed -ie 's/gaim/purple/g'
Sean Egan <seanegan@gmail.com>
parents: 15374
diff changeset
69 PurpleSrvQueryData *purple_srv_resolve(const char *protocol, const char *transport, const char *domain, PurpleSrvCallback cb, gpointer extradata);
15374
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
70
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
71 /**
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
72 * Cancel an SRV DNS query.
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
73 *
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
74 * @param query_data The request to cancel.
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
75 */
15823
32c366eeeb99 sed -ie 's/gaim/purple/g'
Sean Egan <seanegan@gmail.com>
parents: 15374
diff changeset
76 void purple_srv_cancel(PurpleSrvQueryData *query_data);
15374
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
77
25593
affaa4c4836e * some code style adjustments in caps.c
Tobias Markmann <tfar@soc.pidgin.im>
parents: 20074
diff changeset
78 /**
affaa4c4836e * some code style adjustments in caps.c
Tobias Markmann <tfar@soc.pidgin.im>
parents: 20074
diff changeset
79 * Queries an TXT record.
affaa4c4836e * some code style adjustments in caps.c
Tobias Markmann <tfar@soc.pidgin.im>
parents: 20074
diff changeset
80 *
affaa4c4836e * some code style adjustments in caps.c
Tobias Markmann <tfar@soc.pidgin.im>
parents: 20074
diff changeset
81 * @param owner Name of the protocol (e.g. "_xmppconnect")
affaa4c4836e * some code style adjustments in caps.c
Tobias Markmann <tfar@soc.pidgin.im>
parents: 20074
diff changeset
82 * @param domain Domain name to query (e.g. "blubb.com")
affaa4c4836e * some code style adjustments in caps.c
Tobias Markmann <tfar@soc.pidgin.im>
parents: 20074
diff changeset
83 * @param cb A callback which will be called with the results
affaa4c4836e * some code style adjustments in caps.c
Tobias Markmann <tfar@soc.pidgin.im>
parents: 20074
diff changeset
84 * @param extradata Extra data to be passed to the callback
26672
acee7d2b1983 Hide PurpleTxtResponse and use a more purple API
Paul Aurich <paul@darkrain42.org>
parents: 26671
diff changeset
85 *
acee7d2b1983 Hide PurpleTxtResponse and use a more purple API
Paul Aurich <paul@darkrain42.org>
parents: 26671
diff changeset
86 * @since 2.6.0
25593
affaa4c4836e * some code style adjustments in caps.c
Tobias Markmann <tfar@soc.pidgin.im>
parents: 20074
diff changeset
87 */
affaa4c4836e * some code style adjustments in caps.c
Tobias Markmann <tfar@soc.pidgin.im>
parents: 20074
diff changeset
88 PurpleSrvQueryData *purple_txt_resolve(const char *owner, const char *domain, PurpleTxtCallback cb, gpointer extradata);
affaa4c4836e * some code style adjustments in caps.c
Tobias Markmann <tfar@soc.pidgin.im>
parents: 20074
diff changeset
89
affaa4c4836e * some code style adjustments in caps.c
Tobias Markmann <tfar@soc.pidgin.im>
parents: 20074
diff changeset
90 /**
affaa4c4836e * some code style adjustments in caps.c
Tobias Markmann <tfar@soc.pidgin.im>
parents: 20074
diff changeset
91 * Cancel an TXT DNS query.
affaa4c4836e * some code style adjustments in caps.c
Tobias Markmann <tfar@soc.pidgin.im>
parents: 20074
diff changeset
92 *
affaa4c4836e * some code style adjustments in caps.c
Tobias Markmann <tfar@soc.pidgin.im>
parents: 20074
diff changeset
93 * @param query_data The request to cancel.
26672
acee7d2b1983 Hide PurpleTxtResponse and use a more purple API
Paul Aurich <paul@darkrain42.org>
parents: 26671
diff changeset
94 * @since 2.6.0
25593
affaa4c4836e * some code style adjustments in caps.c
Tobias Markmann <tfar@soc.pidgin.im>
parents: 20074
diff changeset
95 */
affaa4c4836e * some code style adjustments in caps.c
Tobias Markmann <tfar@soc.pidgin.im>
parents: 20074
diff changeset
96 void purple_txt_cancel(PurpleSrvQueryData *query_data);
affaa4c4836e * some code style adjustments in caps.c
Tobias Markmann <tfar@soc.pidgin.im>
parents: 20074
diff changeset
97
26672
acee7d2b1983 Hide PurpleTxtResponse and use a more purple API
Paul Aurich <paul@darkrain42.org>
parents: 26671
diff changeset
98 /**
acee7d2b1983 Hide PurpleTxtResponse and use a more purple API
Paul Aurich <paul@darkrain42.org>
parents: 26671
diff changeset
99 * Get the value of the current TXT record.
acee7d2b1983 Hide PurpleTxtResponse and use a more purple API
Paul Aurich <paul@darkrain42.org>
parents: 26671
diff changeset
100 *
28493
63cb8c4f3c66 Fix a bunch of doxygen warnings.
Paul Aurich <paul@darkrain42.org>
parents: 27431
diff changeset
101 * @param response The TXT response record
26672
acee7d2b1983 Hide PurpleTxtResponse and use a more purple API
Paul Aurich <paul@darkrain42.org>
parents: 26671
diff changeset
102 * @returns The value of the current TXT record.
acee7d2b1983 Hide PurpleTxtResponse and use a more purple API
Paul Aurich <paul@darkrain42.org>
parents: 26671
diff changeset
103 * @since 2.6.0
acee7d2b1983 Hide PurpleTxtResponse and use a more purple API
Paul Aurich <paul@darkrain42.org>
parents: 26671
diff changeset
104 */
28493
63cb8c4f3c66 Fix a bunch of doxygen warnings.
Paul Aurich <paul@darkrain42.org>
parents: 27431
diff changeset
105 const gchar *purple_txt_response_get_content(PurpleTxtResponse *response);
26672
acee7d2b1983 Hide PurpleTxtResponse and use a more purple API
Paul Aurich <paul@darkrain42.org>
parents: 26671
diff changeset
106
acee7d2b1983 Hide PurpleTxtResponse and use a more purple API
Paul Aurich <paul@darkrain42.org>
parents: 26671
diff changeset
107 /**
acee7d2b1983 Hide PurpleTxtResponse and use a more purple API
Paul Aurich <paul@darkrain42.org>
parents: 26671
diff changeset
108 * Destroy a TXT DNS response object.
acee7d2b1983 Hide PurpleTxtResponse and use a more purple API
Paul Aurich <paul@darkrain42.org>
parents: 26671
diff changeset
109 *
acee7d2b1983 Hide PurpleTxtResponse and use a more purple API
Paul Aurich <paul@darkrain42.org>
parents: 26671
diff changeset
110 * @param response The PurpleTxtResponse to destroy.
acee7d2b1983 Hide PurpleTxtResponse and use a more purple API
Paul Aurich <paul@darkrain42.org>
parents: 26671
diff changeset
111 * @since 2.6.0
acee7d2b1983 Hide PurpleTxtResponse and use a more purple API
Paul Aurich <paul@darkrain42.org>
parents: 26671
diff changeset
112 */
28493
63cb8c4f3c66 Fix a bunch of doxygen warnings.
Paul Aurich <paul@darkrain42.org>
parents: 27431
diff changeset
113 void purple_txt_response_destroy(PurpleTxtResponse *response);
26672
acee7d2b1983 Hide PurpleTxtResponse and use a more purple API
Paul Aurich <paul@darkrain42.org>
parents: 26671
diff changeset
114
15374
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
115 #ifdef __cplusplus
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
116 }
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
117 #endif
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
118
15823
32c366eeeb99 sed -ie 's/gaim/purple/g'
Sean Egan <seanegan@gmail.com>
parents: 15374
diff changeset
119 #endif /* _PURPLE_DNSSRV_H */