|
1 |
|
2 # Service Discovery Requests |
|
3 |
|
4 ## Overview |
|
5 |
|
6 This module provides C API for other MCabber modules to perform disco requests. |
|
7 Currently module does not support x-data forms in disco results, so, this part of |
|
8 information will be silently omitted from results. |
|
9 |
|
10 Module provides three functions: |
|
11 |
|
12 gpointer disco_info_request (gchar *, gchar *, disco_info_handler_t, gpointer, GDestroyNotify) |
|
13 : Perform disco#info request on entity. |
|
14 |
|
15 gpointer disco_items_request (gchar *, gchar *, disco_items_handler_t, gpointer, GDestroyNotify) |
|
16 : Perform disco#items request on entity. |
|
17 |
|
18 void disco_cancel_request (gpointer) |
|
19 : Cancel not yet finished request. |
|
20 |
|
21 When you create new request, corresponding function returns ID, that can be used |
|
22 to cancel it. Otherwise it is not useful for anything and may be ignored. When |
|
23 module will receive reply to request, it will call handler, that user provided. If |
|
24 request for some reason fails, handler will be called with NULL as results. |
|
25 Currently, request can fail under next circumstances: |
|
26 |
|
27 - MCabber is not connected; |
|
28 - Loudmouth returned error, when trying to send request message; |
|
29 - MCabber lost connection before reply arrived; |
|
30 - Module is being unloaded. |
|
31 |
|
32 In first two cases, as well as if you do not specify handler for request results, |
|
33 function will return NULL instead of ID. Handler will not be called, however, if |
|
34 you cancel request yourself. Note, that DestroyNotify function (if specified) |
|
35 will be **always** called, even if function returns NULL, which means, that |
|
36 userdata may no longer exist after a call to request-making function. Though, you |
|
37 can detect this case by checking returned ID. |
|
38 |
|
39 ## Simple example |
|
40 |
|
41 static void info_handler (GSList *identities, GSList *features, gpointer userdata) |
|
42 { |
|
43 gchar *jid = userdata; |
|
44 while ( identities ) { |
|
45 disco_identity_t *identity = identities -> data; |
|
46 identities = identities -> next; |
|
47 if (!g_strcmp0 (identity -> category, "proxy") && |
|
48 !g_strcmp0 (identity -> type, "bytestreams")) { |
|
49 // do something with jid of SOCKS5 |
|
50 // bytestreams proxy of your server |
|
51 } |
|
52 } |
|
53 } |
|
54 |
|
55 static void items_handler (GSList *items, gpointer userdata) |
|
56 { |
|
57 while ( items ) { |
|
58 disco_item_t *item = items -> data; |
|
59 items = items -> next; |
|
60 disco_info_request (item -> jid, NULL, info_handler, |
|
61 g_strdup (item -> jid), g_free); |
|
62 } |
|
63 } |
|
64 |
|
65 ... |
|
66 const gchar *jid = lm_connection_get_jid (lconnection); |
|
67 disco_items_request (jid, NULL, items_handler, NULL, NULL); |
|
68 ... |
|
69 |