# 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-*
* artist
* 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.

<!-- -->