Metronome allows MUC related modules to perform default actions overriding like pluggable muc configuration via eventing.
Pluggable MUC Configuration
To note there’re some definite differences regarding the room object methods with Prosody in particular the set_option method, and I’ll describe it here as it’s very important for pluggable config. Instead of having methods to deal with default configuration there’s just one being set_option this function takes three arguments two mandatory ones being the name of the config value, the value itself, and as optional one a table which will contain changed directives (“dirty”) in the form.
I’ll below list the events and which arguments will be passed to each callback:
- muc-fields, whenever a room configuration form is invoked Metronome will fire this local host event for eventual muc plugins to be able to append custom directives to the layout:
- 1) the room object itself
- 2) the layout of the form, it uses util.dataforms default format
- muc-fields-process, whenever a room config. form is completed and submitted back to the server, plugins hostwise can hook to this event to process and save custom fields:
- 1) the room object itself
- 2) a dictionary (table) containing all the fields in the format of name, value pairs
- 3) the submitted form iq stanza
- 4) a table which contains dirty (changed) values, format is: “changed configuration directive name”, “true”
- muc-fields-submitted, after configuration is processed and saved the the MUC library form processing function will first assert if there’re modified values by calling next() on the “changed” table if so it will call this event to allow plugins to optionally append additional status codes to the message broadcasted to occupants which informs of configuration changes:
- 1) the room object itself
- 2) the message stanza object to append elements to or alter
- muc-occupant-joined, whenever an occupant joins this event will be fired as sometimes it’s necessary to inform a certain, configurable, feature is activated by adding status codes to the user reflected presence:
- 1) the room object itself
- 2) the user presence object
A fair amount of real usage of this API can be found in both mod_muc_limits and mod_muc_log.
Other MUC Events
These are utility events to perform additional manipulation of message stanzas directed to internal MUC components:
- muc-host-used, this event is fired each time a stanza is sent to a muc component room together with “last_used” variables on room objects it’s useful to create synchronous timer tasks as util.timer performs asynchronously and could cause issues with the environment:
- 1) the rooms container object
- 2) the current epoch timestamp
- 3) the bare room jid
- muc-disco-info-features, this event is fired each time a room returns disco info features after a request and it will allow to append features after default ones (or override those) before the muc info dataform is added:
- 1) the room object
- 2) the partial reply stanza
See mod_muc_log_mam for an example usage.
NOTE: This is only available into current trunk