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