# 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

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

### *_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).

### *_publish ( ... )
Publish supplied data as corresponding user's update. Note,
that this function bypasses event interface, thus, it can
be used to publish *only* via PEP. In general, it is
suggested to use event (hooks) interface, as it allows
multiplexing and non-breaking extensibility.

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

## tune
'tune_publish' takes list of key-value pairs.

## mood
'mood_publish' takes two string arguments - mood and mood message.

## activity
'activity_publish' takes three string arguments - major activity, minor, and
activity message.

## geoloc
'geoloc_publish' takes list of key-value pairs.

<!-- -->