Properties

Accessing and exposing properties. More...

Macros
#define	LipcGetProperties(lipc, service, value)   LipcGetStringProperty(lipc, service, "_properties", value)
#define	LIPC_GETTER_VTOI(value)   (*(int *)(value))
#define	LIPC_SETTER_VTOI(value)   ((long int)(value))
#define	LIPC_GETTER_VTOS(value)   ((char *)(value))
#define	LIPC_SETTER_VTOS(value)   ((char *)(value))

Typedefs
typedef LIPCcode(*	LipcPropCallback) (LIPC *lipc, const char *property, void *value, void *data)

Functions
int	LipcGetPropAccessTimeout (LIPC *lipc)
LIPCcode	LipcGetIntProperty (LIPC *lipc, const char *service, const char *property, int *value)
LIPCcode	LipcSetIntProperty (LIPC *lipc, const char *service, const char *property, int value)
LIPCcode	LipcGetStringProperty (LIPC *lipc, const char *service, const char *property, char **value)
LIPCcode	LipcSetStringProperty (LIPC *lipc, const char *service, const char *property, const char *value)
LIPCcode	LipcAccessHasharrayProperty (LIPC *lipc, const char *service, const char *property, const LIPCha *ha, LIPCha **ha_out)
void	LipcFreeString (char *string)
LIPCcode	LipcRegisterIntProperty (LIPC *lipc, const char *property, LipcPropCallback getter, LipcPropCallback setter, void *data)
LIPCcode	LipcRegisterStringProperty (LIPC *lipc, const char *property, LipcPropCallback getter, LipcPropCallback setter, void *data)
LIPCcode	LipcRegisterHasharrayProperty (LIPC *lipc, const char *property, LipcPropCallback callback, void *data)
LIPCcode	LipcUnregisterProperty (LIPC *lipc, const char *property, void **data)

Detailed Description

Accessing and exposing properties.

Macro Definition Documentation

#define LipcGetProperties	(		lipc,
			service,
			value
	)		LipcGetStringProperty(lipc, service, "_properties", value)

Convenience macro for getting all properties of given service.

The list of properties is formated as a space-delimited string, where every element is in the format as follows: "<property> <type> <access> ". Note, that at the end of the string, there is always a hanging space character.

The access mode of the property can be either read-only: r, write-only: w, or both: rw.

Parameters

lipc	LIPC library handler.
service	The service name.
value	The address where the pointer to the string will stored.

Returns

The status code.

#define LIPC_GETTER_VTOI

(

value

)

(*(int *)(value))

Cast the value parameter of the getter callback into the integer type.

#define LIPC_SETTER_VTOI

(

value

)

((long int)(value))

Cast the value parameter of the setter callback into the integer type.

#define LIPC_GETTER_VTOS

(

value

)

((char *)(value))

Cast the value parameter of the getter callback into the char * type.

#define LIPC_SETTER_VTOS

(

value

)

((char *)(value))

Cast the value parameter of the setter callback into the char * type.

Typedef Documentation

typedef LIPCcode(* LipcPropCallback) (LIPC *lipc, const char *property, void *value, void *data)

Property getter/setter callback function.

This callback function can be used either for getting properties or for setting ones. However, there is a slight difference in both actions. Also, there is a difference when the callback function is called for getting a string, and when it is called for getting an integer.

When the getter is called for the integer property, one has to set the address pointed by the *value to the desired integer value.

When the getter is called for the string property, the buffer pointed by the *value is preallocated to the initial size. This size is available in the *data parameter. If the buffer is too small for storing desired string value, one should return the LIPC_ERROR_BUFFER_TOO_SMALL code and pass the required buffer size in the *data argument. In such a case, the callback function will be called again with the requested buffer size.

When the setter is called, the value parameter contains the integer value itself or it points to the memory buffer, respectively for the integer property or for the string property.

For convenience, one can use one of the helper macros (LIPC_GETTER_VTOI(), LIPC_SETTER_VTOI(), LIPC_GETTER_VTOS() or LIPC_SETTER_VTOS()) for casting the value parameter into the proper type based on the callback type.

In all cases, with the exception of the string property getter, the data parameter will contain the value passed during the property registration.

The return value of the callback function will be used as a return value for the caller, e.g. LipcGetIntProperty(). One exception from this rule is a getter for a string property, where the LIPC_ERROR_BUFFER_TOO_SMALL code is used internally by the LIPC library.

Parameters

lipc	LIPC library handler.
property	The property name.
value	Pointer to the memory area for a value storage.
data	Data passed during property registration.

Returns

The status code.

Function Documentation

int LipcGetPropAccessTimeout

(

LIPC *

lipc

)

Get property access timeout.

Note

The timeout value can be set via the file "/var/local/system/lipctimeout", otherwise it is set to the default 10000 ms.

Parameters

lipc	LIPC library handler.

Returns

The timeout value in milliseconds.

LIPCcode LipcGetIntProperty	(	LIPC *	lipc,
		const char *	service,
		const char *	property,
		int *	value
	)

Get the value of the integer property.

Parameters

lipc	LIPC library handler.
service	The service name.
property	The property name.
value	The address where the integer value will be stored.

Returns

The status code.

LIPCcode LipcSetIntProperty	(	LIPC *	lipc,
		const char *	service,
		const char *	property,
		int	value
	)

Set the value of the integer property.

Parameters

lipc	LIPC library handler.
service	The service name.
property	The property name.
value	The new value to set.

Returns

The status code.

LIPCcode LipcGetStringProperty	(	LIPC *	lipc,
		const char *	service,
		const char *	property,
		char **	value
	)

Get the value of the string property.

The memory for the returned string is allocated internally by the library and should be freed with the LipcFreeString().

Parameters

lipc	LIPC library handler.
service	The service name.
property	The property name.
value	The address where the pointer to the string will be stored.

Returns

The status code.

LIPCcode LipcSetStringProperty	(	LIPC *	lipc,
		const char *	service,
		const char *	property,
		const char *	value
	)

Set the value of the string property.

Parameters

lipc	LIPC library handler.
service	The service name.
property	The property name.
value	The new value to set.

Returns

The status code.

LIPCcode LipcAccessHasharrayProperty	(	LIPC *	lipc,
		const char *	service,
		const char *	property,
		const LIPCha *	ha,
		LIPCha **	ha_out
	)

Access the value of the hash-array property.

Parameters

lipc	LIPC library handler.
service	The service name.
property	The property name.
ha	An input LIPC hash-array handler or NULL if there is no input.
ha_out	The pointer to the address, where the output hash-array handler will be stored. If the output value is not desired, one can pass NULL value in this parameter.

Returns

The status code.

void LipcFreeString

(

char *

string

)

Free memory allocated by the LIPC.

Parameters

string

The string pointer.

LIPCcode LipcRegisterIntProperty	(	LIPC *	lipc,
		const char *	property,
		LipcPropCallback	getter,
		LipcPropCallback	setter,
		void *	data
	)

Register new integer property.

The access mode of the property is determined by the presence of the getter and/or the setter callback function. Passing NULL value in the getter and the setter parameters will make the property read-only, however it will not be possible to retrieve any value, so it is pointless to do so.

Parameters

lipc	LIPC library handler.
property	The property name.
getter	Getter callback if property is readable.
setter	Setter callback if property is writable.
data	Data pointer passed to the callback function.

Returns

The status code.

LIPCcode LipcRegisterStringProperty	(	LIPC *	lipc,
		const char *	property,
		LipcPropCallback	getter,
		LipcPropCallback	setter,
		void *	data
	)

Register new string property.

For the information about the property access mode, see the documentation of the LipcRegisterIntProperty().

Parameters

lipc	LIPC library handler.
property	The property name.
getter	Getter callback if property is readable.
setter	Setter callback if property is writable.
data	Data pointer passed to the callback function.

Returns

The status code.

LIPCcode LipcRegisterHasharrayProperty	(	LIPC *	lipc,
		const char *	property,
		LipcPropCallback	callback,
		void *	data
	)

Register new hash-array property.

Parameters

lipc	LIPC library handler.
property	The property name.
callback	Getter and setter callback function.
data	Data pointer passed to the callback function.

Returns

The status code.

LIPCcode LipcUnregisterProperty	(	LIPC *	lipc,
		const char *	property,
		void **	data
	)

Unregister property.

If the data parameter is not NULL, the address of the data pointer passed during the property registration will be stored in the address pointed by the *data.

Parameters

lipc	LIPC library handler.
property	The property name.
data	Address where the data pointer is returned.

Returns

The status code.