# HG changeset patch
# User Myhailo Danylenko <isbear@ukrpost.net>
# Date 1361077129 -7200
# Node ID f4ad0e7bf1ef0caee91596f577236230db98f5c6
# Parent  b0b6e8307e38e88ead63fd03dfceb11572d2a74d
Add short api description

diff -r b0b6e8307e38 -r f4ad0e7bf1ef docs/api.mdwn
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/api.mdwn	Sun Feb 17 06:58:49 2013 +0200
@@ -0,0 +1,69 @@
+
+# Service Discovery Requests
+
+## Overview
+
+This module provides C API for other MCabber modules to perform disco requests.
+Currently module does not support x-data forms in disco results, so, this part of
+information will be silently omitted from results.
+
+Module provides three functions:
+
+gpointer disco_info_request (gchar *, gchar *, disco_info_handler_t, gpointer, GDestroyNotify)
+:   Perform disco#info request on entity.
+
+gpointer disco_items_request (gchar *, gchar *, disco_items_handler_t, gpointer, GDestroyNotify)
+:   Perform disco#items request on entity.
+
+void disco_cancel_request (gpointer)
+:   Cancel not yet finished request.
+
+When you create new request, corresponding function returns ID, that can be used
+to cancel it. Otherwise it is not useful for anything and may be ignored. When
+module will receive reply to request, it will call handler, that user provided. If
+request for some reason fails, handler will be called with NULL as results.
+Currently, request can fail under next circumstances:
+
+ - MCabber is not connected;
+ - Loudmouth returned error, when trying to send request message;
+ - MCabber lost connection before reply arrived;
+ - Module is being unloaded.
+
+In first two cases, as well as if you do not specify handler for request results,
+function will return NULL instead of ID. Handler will not be called, however, if
+you cancel request yourself. Note, that DestroyNotify function (if specified)
+will be **always** called, even if function returns NULL, which means, that
+userdata may no longer exist after a call to request-making function. Though, you
+can detect this case by checking returned ID.
+
+## Simple example
+
+    static void info_handler (GSList *identities, GSList *features, gpointer userdata)
+    {
+        gchar *jid = userdata;
+        while ( identities ) {
+            disco_identity_t *identity = identities -> data;
+            identities = identities -> next;
+            if (!g_strcmp0 (identity -> category, "proxy") &&
+                !g_strcmp0 (identity -> type, "bytestreams")) {
+                // do something with jid of SOCKS5
+                // bytestreams proxy of your server
+            }
+        }
+    }
+    
+    static void items_handler (GSList *items, gpointer userdata)
+    {
+        while ( items ) {
+            disco_item_t *item = items -> data;
+            items = items -> next;
+            disco_info_request (item -> jid, NULL, info_handler,
+                                g_strdup (item -> jid), g_free);
+        }
+    }
+    
+    ...
+        const gchar *jid = lm_connection_get_jid (lconnection);
+        disco_items_request (jid, NULL, items_handler, NULL, NULL);
+    ...
+
diff -r b0b6e8307e38 -r f4ad0e7bf1ef docs/index.mdwn
--- a/docs/index.mdwn	Sun Feb 17 06:00:16 2013 +0200
+++ b/docs/index.mdwn	Sun Feb 17 06:58:49 2013 +0200
@@ -6,4 +6,4 @@
 Module allows to send Service Discovery requests and
 examine results.
 
-[ [[!hg mcabber-disco desc="SOURCE"]] ] [ [[README|readme]] ] [ [[TODO|todo]] ] [ [[RC|disco.rc]] ]
+[ [[!hg mcabber-disco desc="SOURCE"]] ] [ [[README|readme]] ] [ [[TODO|todo]] ] [ [[API|api]] ] [ [[RC|disco.rc]] ]
diff -r b0b6e8307e38 -r f4ad0e7bf1ef docs/todo.mdwn
--- a/docs/todo.mdwn	Sun Feb 17 06:00:16 2013 +0200
+++ b/docs/todo.mdwn	Sun Feb 17 06:58:49 2013 +0200
@@ -1,4 +1,4 @@
 
 * Use caps cache
-* Document api
+* Improve documentation