diff -r f23b9521b4d6 -r 0477d4800fbd docs/api.mdwn
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/api.mdwn	Mon Aug 20 18:53:05 2012 +0300
@@ -0,0 +1,103 @@
+
+# Events interface
+
+Events are currently designed for useage with pep notifications, but
+potentially could be used with any notification system, eg a module, that adds
+currently playing song to your status.
+
+Every module pair (eg pep_tune and tune) use a pair of hooks. One for incoming
+notifications ('*-in') and one for the cases, when server needs to be notified
+about user state change ('*-out'). Note, that '*-out' causes server
+notification, not vice versa. In general, these hooks have the same set of fields,
+except that incoming events also have 'from' field, that is mandatory.
+
+For more clear description of fields and what can be put in there, refer to
+corresponding XEPs.
+
+* [XEP-0118](http://xmpp.org/extensions/xep-0118.html) - tune
+* [XEP-0107](http://xmpp.org/extensions/xep-0107.html) - mood
+* [XEP-0108](http://xmpp.org/extensions/xep-0108.html) - activity
+* [XEP-0080](http://xmpp.org/extensions/xep-0080.html) - geoloc
+
+## tune-*
+* argtist
+* length
+* rating
+* source
+* title
+* track
+* uri
+* state (stop, pause, play)
+
+## mood-*
+* mood
+* text
+
+## activity-*
+* major
+* minor
+* text
+
+## geoloc-*
+* accuracy
+* alt
+* area
+* bearing
+* building
+* country
+* datum
+* description
+* error
+* floor
+* lat
+* locality
+* lon
+* postalcode
+* region
+* room
+* speed
+* street
+* text
+* timestamp
+* uri
+
+# C interface
+
+## general conventions
+
+### NS_*
+XMLNS namespace constants.
+
+### HOOK_*
+Hook name constants. Usually are the same as actual hook name, but
+uppercased, with 'HOOK_' added and with underscores instead of dashes.
+
+### OPT_*
+MCabber option names. Should not be enclosed in braces.
+
+### pep_*_request ( to, error )
+Request corresponding data from the jid, specified in 'to'.
+'error' may be used for error control. If no error occured,
+and remote side have replied with notification stanza, call
+to one of this functions will eventually result in corresponding
+event '*-in'. Currently there's no way to detect an
+error on the remote side (eg, if it does not support PEP).
+
+## pep
+
+### (*pep_xmlns_handler_t) ( from, node, n, id, userdata )
+Type of function to supply as a handler for pep xmlns namespace.
+'from' is a jid.
+'node' is pep node.
+'n' is loudmouth message node object, containing xmlns-specific data.
+'userdata' is pointer to data, passed at registration time.
+
+### pep_register_xmlns_handler ( xmlns, handler, userdata, notify )
+Specify a handler for xmlns namespace.
+'userdata' will be directly specified.
+'notify' is a function, that may be called for userdata destruction.
+
+### pep_unregister_xmlns_handler ( xmlns )
+Remove handler from given xmlns namespace.
+
+<!-- -->