Events

Listening for and emitting events. More...

Typedefs
typedef void	LIPCevent
typedef LIPCcode(*	LipcEventCallback) (LIPC *lipc, const char *name, LIPCevent *event, void *data)

Functions
LIPCevent *	LipcNewEvent (LIPC *lipc, const char *name)
void	LipcEventFree (LIPCevent *event)
LIPCcode	LipcSendEvent (LIPC *lipc, LIPCevent *event)
LIPCcode	LipcCreateAndSendEvent (LIPC *lipc, const char *name)
LIPCcode	LipcCreateAndSendEventWithParameters (LIPC *lipc, const char *name, const char *format,...)
LIPCcode	LipcCreateAndSendEventWithVAListParameters (LIPC *lipc, const char *name, const char *format, va_list ap)
const char *	LipcGetEventSource (LIPCevent *event)
const char *	LipcGetEventName (LIPCevent *event)
LIPCcode	LipcGetIntParam (LIPCevent *event, int *value)
LIPCcode	LipcAddIntParam (LIPCevent *event, int value)
LIPCcode	LipcGetStringParam (LIPCevent *event, char **value)
LIPCcode	LipcAddStringParam (LIPCevent *event, const char *value)
LIPCcode	LipcRewindParams (LIPCevent *event)
LIPCcode	LipcSetEventCallback (LIPC *lipc, LipcEventCallback callback)
LIPCcode	LipcSubscribe (LIPC *lipc, const char *service)
LIPCcode	LipcSubscribeExt (LIPC *lipc, const char *service, const char *name, LipcEventCallback callback, void *data)
LIPCcode	LipcUnsubscribeExt (LIPC *lipc, const char *service, const char *name, void **data)

Detailed Description

Listening for and emitting events.

Typedef Documentation

typedef void LIPCevent

LIPC event handler.

typedef LIPCcode(* LipcEventCallback) (LIPC *lipc, const char *name, LIPCevent *event, void *data)

Event dispatching callback function.

Parameters

lipc	LIPC library handler.
name	The event name.
event	The LIPC event handler.
data	Data pointer passed during subscription.

Returns

The status code.

Function Documentation

LIPCevent* LipcNewEvent	(	LIPC *	lipc,
		const char *	name
	)

Create a new event object.

In order to use this function the LIPC handler has to be opened with the service name given using LipcOpen() or LipcOpenEx().

Parameters

lipc	LIPC library handler.
name	The event name.

Returns

On success the LIPCevent handler is returned, which should be freed with the LipcEventFree(). Upon error this function returns NULL.

void LipcEventFree

(

LIPCevent *

event

)

Free memory allocated by the LIPC.

Parameters

event

LIPC event handler.

LIPCcode LipcSendEvent	(	LIPC *	lipc,
		LIPCevent *	event
	)

Send event object.

Parameters

lipc	LIPC library handler.
event	LIPC event handler.

Returns

The status code.

LIPCcode LipcCreateAndSendEvent	(	LIPC *	lipc,
		const char *	name
	)

Create and send event.

This function is an equivalent of using LipcNewEvent(), LipcSendEvent() and LipcEventFree() all together. If you want to send a simple event object - one without any parameters - use this function.

Parameters

lipc	LIPC library handler.
name	The event name.

Returns

The status code.

LIPCcode LipcCreateAndSendEventWithParameters	(	LIPC *	lipc,
		const char *	name,
		const char *	format,
			...
	)

Create and send event.

This function creates an event object and sets its parameters according to the format string. This function takes variable number of arguments.

LIPC supports two kinds of event parameters: integers and strings. It is possible to specify both of these types via the format string in the same way the printf() function family does. The format string can contain any number of "%d" or/and "%s" conversion specifiers. It is also possible to pass an empty string in the format argument, which will be an equivalent of calling the LipcCreateAndSendEvent().

The format string also supports the ".0" precision modifier. However, its purpose is yet to be discovered.

Parameters

lipc	LIPC library handler.
name	The event name.
format	The format string.
...	Variable list of parameters.

Returns

The status code.

LIPCcode LipcCreateAndSendEventWithVAListParameters	(	LIPC *	lipc,
		const char *	name,
		const char *	format,
		va_list	ap
	)

Create and send event.

This function creates an event object and sets its parameters according to the format string. Parameter values should be passed as a variable argument list. For the list of all supported formats, see the documentation of the LipcCreateAndSendEventWithParameters() function.

Parameters

lipc	LIPC library handler.
name	The event name.
format	The format string.
ap	Variable argument list.

Returns

The status code.

const char* LipcGetEventSource

(

LIPCevent *

event

)

Get the source name associated with the event.

Parameters

event

LIPC event handler.

Returns

The source name from where the event originates.

const char* LipcGetEventName

(

LIPCevent *

event

)

Get the name of the event.

Parameters

event

LIPC event handler.

Returns

The event name.

LIPCcode LipcGetIntParam	(	LIPCevent *	event,
		int *	value
	)

Get the integer parameter from the event.

Parameters

event	LIPC event handler.
value	The address where the integer value will be stored.

Returns

The status code.

LIPCcode LipcAddIntParam	(	LIPCevent *	event,
		int	value
	)

Add the integer parameter to the event.

Parameters

event	LIPC event handler.
value	The new value to add.

Returns

The status code.

LIPCcode LipcGetStringParam	(	LIPCevent *	event,
		char **	value
	)

Get the string parameter from the event.

Note

The obtained memory pointer should not be passed to the LipcFreeString() function. It seems, that the memory is managed internally by the library.

Parameters

event	LIPC event handler.
value	The address where the pointer to the string will be stored.

Returns

The status code.

LIPCcode LipcAddStringParam	(	LIPCevent *	event,
		const char *	value
	)

Add the string parameter to the event.

Parameters

event	LIPC event handler.
value	The new value to add.

Returns

The status code.

LIPCcode LipcRewindParams

(

LIPCevent *

event

)

Rewind parameters of the event.

Parameters

event

LIPC event handler.

Returns

The status code.

LIPCcode LipcSetEventCallback	(	LIPC *	lipc,
		LipcEventCallback	callback
	)

Set default event callback function.

The callback function will be called when one uses the LipcSubscribe() subscription mechanism. Note, that it is not possible to pass user-defined data via this approach - if one wants to pass extra data to the callback function, one should use the LipcSubscribeExt() instead.

Parameters

lipc	LIPC library handler.
callback	Event dispatching callback function.

Returns

The status code.

LIPCcode LipcSubscribe	(	LIPC *	lipc,
		const char *	service
	)

Subscribe for all events emitted by the service.

In order to receive event notifications, one has to set default callback function using the LipcSetEventCallback() function. Using them both, is an equivalent of using the extended version with parameters set as follows: LipcSubscribeExt(lipc, service, NULL, callback, NULL)

Parameters

lipc	LIPC library handler.
service	The service name.

Returns

The status code.

LIPCcode LipcSubscribeExt	(	LIPC *	lipc,
		const char *	service,
		const char *	name,
		LipcEventCallback	callback,
		void *	data
	)

Subscribe for events emitted by the service.

This function is an extended version of the LipcSubscribe(), which allows to set the event name for which one wants to subscribe and the user-defined data passed to the callback function. Passing NULL instead of the event name will subscribe for all events.

Parameters

lipc	LIPC library handler.
service	The service name.
name	The event name.
callback	Event dispatching callback function.
data	Data pointer passed to the callback function.

Returns

The status code.

LIPCcode LipcUnsubscribeExt	(	LIPC *	lipc,
		const char *	service,
		const char *	name,
		void **	data
	)

Unsubscribe from event or events.

If the event name is NULL, this function will unsubscribe from events delivered to the callback set with the LipcSetEventCallback().

Parameters

lipc	LIPC library handler.
service	The service name.
name	The event name or NULL.
data	Address where the data pointer is returned or NULL.

Returns

The status code.