1 

     2 # Events interface

     3 

     4 Events are currently designed for useage with pep notifications, but

     5 potentially could be used with any notification system, eg a module, that adds

     6 currently playing song to your status.

     7 

     8 Every module pair (eg pep_tune and tune) use a pair of hooks. One for incoming

     9 notifications ('*-in') and one for the cases, when server needs to be notified

    10 about user state change ('*-out'). Note, that '*-out' causes server

    11 notification, not vice versa. In general, these hooks have the same set of fields,

    12 except that incoming events also have 'from' field, that is mandatory.

    13 

    14 For more clear description of fields and what can be put in there, refer to

    15 corresponding XEPs.

    16 

    17 * [XEP-0118](http://xmpp.org/extensions/xep-0118.html) - tune

    18 * [XEP-0107](http://xmpp.org/extensions/xep-0107.html) - mood

    19 * [XEP-0108](http://xmpp.org/extensions/xep-0108.html) - activity

    20 * [XEP-0080](http://xmpp.org/extensions/xep-0080.html) - geoloc

    21 

    22 ## tune-*

    23 * argtist

    24 * length

    25 * rating

    26 * source

    27 * title

    28 * track

    29 * uri

    30 * state (stop, pause, play)

    31 

    32 ## mood-*

    33 * mood

    34 * text

    35 

    36 ## activity-*

    37 * major

    38 * minor

    39 * text

    40 

    41 ## geoloc-*

    42 * accuracy

    43 * alt

    44 * area

    45 * bearing

    46 * building

    47 * country

    48 * datum

    49 * description

    50 * error

    51 * floor

    52 * lat

    53 * locality

    54 * lon

    55 * postalcode

    56 * region

    57 * room

    58 * speed

    59 * street

    60 * text

    61 * timestamp

    62 * uri

    63 

    64 # C interface

    65 

    66 ## general conventions

    67 

    68 ### NS_*

    69 XMLNS namespace constants.

    70 

    71 ### HOOK_*

    72 Hook name constants. Usually are the same as actual hook name, but

    73 uppercased, with 'HOOK_' added and with underscores instead of dashes.

    74 

    75 ### OPT_*

    76 MCabber option names. Should not be enclosed in braces.

    77 

    78 ### pep_*_request ( to, error )

    79 Request corresponding data from the jid, specified in 'to'.

    80 'error' may be used for error control. If no error occured,

    81 and remote side have replied with notification stanza, call

    82 to one of this functions will eventually result in corresponding

    83 event '*-in'. Currently there's no way to detect an

    84 error on the remote side (eg, if it does not support PEP).

    85 

    86 ## pep

    87 

    88 ### (*pep_xmlns_handler_t) ( from, node, n, id, userdata )

    89 Type of function to supply as a handler for pep xmlns namespace.

    90 'from' is a jid.

    91 'node' is pep node.

    92 'n' is loudmouth message node object, containing xmlns-specific data.

    93 'userdata' is pointer to data, passed at registration time.

    94 

    95 ### pep_register_xmlns_handler ( xmlns, handler, userdata, notify )

    96 Specify a handler for xmlns namespace.

    97 'userdata' will be directly specified.

    98 'notify' is a function, that may be called for userdata destruction.

    99 

   100 ### pep_unregister_xmlns_handler ( xmlns )

   101 Remove handler from given xmlns namespace.

   102 

   103 <!-- -->