Register a callback as an Elgg event handler.Events are emitted by Elgg when certain actions occur. Plugins can respond to these events or halt them completely by registering a handler as a callback to an event. Multiple handlers can be registered for the same event and will be executed in order of $priority.

For most events, any handler returning false will halt the execution chain and cause the event to be "cancelled". For After Events, the return values of the handlers will be ignored and all handlers will be called.

This function is called with the event name, event type, and handler callback name. Setting the optional $priority allows plugin authors to specify when the callback should be run. Priorities for plugins should be 1-1000.

The callback is passed 3 arguments when called: $event, $type, and optional $params.

$event is the name of event being emitted. $type is the type of event or object concerned. $params is an optional parameter passed that can include a related object. See specific event documentation for details on which events pass what parameteres.

If a priority isn't specified it is determined by the order the handler was registered relative to the event and type. For plugins, this generally means the earlier the plugin is in the load order, the earlier the priorities are for any event handlers.

$event and $object_type can use the special keyword 'all'. Handler callbacks registered with $event = all will be called for all events of type $object_type. Similarly, callbacks registered with $object_type = all will be called for all events of type $event, regardless of $object_type. If $event and $object_type both are 'all', the handler callback will be called for all events.

Event handler callbacks are considered in the follow order:

Specific registration where 'all' isn't used.
Registration where 'all' is used for $event only.
Registration where 'all' is used for $type only.
Registration where 'all' is used for both.

Warning: If you use the 'all' keyword, you must have logic in the handler callback to test the passed parameters before taking an action.

When referring to events, the preferred syntax is "event, type".

Internal note: Events are stored in $CONFIG->events as: $CONFIG->events[$event][$type][$priority] = $callback;

Parameters

string	$event	The event type
string	$object_type	The object type
string	$callback	The handler callback
int	$priority	The priority - 0 is default, negative before, positive after

Returns: bool