# 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

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-*

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

<!-- -->