EventsConnect

From TrillWiki

The eventsConnect function allows a plugin to attach to an event. When attached the callback provided will be called whenever the event is generated.

Compatibility: 2.0 and higher

Contents 1 Syntax 2 Parameters 3 Return Value 4 Remarks

Syntax

plugin_send(MYGUID, "eventsConnect", struct event_connect_t *);

Note that all Trillian functions and notifications begin with a lower-case letter, despite the Wiki requirement that all pages start with a capital letter.

Parameters

EventsConnect utilitizes the event_connect_t structure.

struct event_connect_t {  
 	unsigned int			struct_size; 
 							 
 	char				*type; 
 							 
 	int				event_id; 
 							 
 	ttkCallback			callback; 
 	void				*data; 
 };

type

The event type to connect to.

callback

The callback to use when the event is generated. This may be called up to 3 times, for each state of the event. The event name will be sent to the callback as the event parameter. The data passed to the callback is an event_variables_t.

data

The data to send with the above callback.

Return Value

Negative value on error, event id on success.

Remarks

Be sure to disconnect from the event using eventsDisconnect when the plugin stops.

The event parameter passed to the callback will be the type of event registered for. The data passed to the callback will be an event_variables_t structure.

struct event_variables_t
{
	unsigned int			struct_size;
								
	char				*variable_name;
	char				*variable_type; //string, integer, float, callback, unknown/custom
								
	void				*variable_data;
	unsigned int			variable_size;
								
	struct event_variables_t	*next_evt;
};

variable_name

The name of the variable.

variable_type

The type of the variable_data. This is one of: string, integer, float, callback, unknown/custom.

variable_data

The value of the variable. For integers and floats, this will be a pointer to the integer/float rather than the value itself.

variable_size

The size of the variable_data. This is useful for string and unknown/custom data.

next_evt

The next variable in the list. If NULL, this is the last variable.

Which variables are supplied depends on the event that triggers the action.

For non-discrete events, the first variable will be an integer called "id", whose value will be one of EVENTS_START, EVENTS_EXECUTE, or EVENTS_END, to indicate the current state of the event. The main event happens with EVENTS_EXECUTE.

For the remaining variables, see EventVariablesForBuiltinEvents for a list of the variables supplied by built-in events, or EventVariablesForPluginEvents for a list of the variables supplied by known plugin events.