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

<!-- -->