Publishing Container Objects

Functions
void	ds_add_container_symbol (ds_data_t *data, const char *symbol)
	Add an object to the container. More...
void	ds_add_container_symbol_and_request (ds_data_t *data, const char *symbol, const int request)
	Add an object to the container, indicating whether it should then be requested. More...
void	ds_add_container_symbol_at_position (ds_data_t *data, int position, const char *symbol)
	Insert an object within a container at a particular position. More...
void	ds_cleardown_container_with_prefix (ds_data_t *data, const char *prefix)
	Remove a set of symbols from the container. More...
ds_data_t *	ds_init_container (const char *subject, const unsigned short flags)
	Initialise a container object. More...
void	ds_remove_container_symbol (ds_data_t *data, const char *symbol)
	Remove an object from the container. More...

Detailed Description

A container object represents a collection of objects that are related in some way.

This object type offers a convenient way of allowing Liberator clients to manage subscription to a collection of objects, subscribing and unsubscribing automatically to objects that are added to or removed from the container.

DataSource provides a container API which allows the creation of containers, and change of their composition - by adding, removing and moving constituent objects.

If a container is sent with the F_IMAGE flag, the cached container is cleared and replaced by any objects added in this container update. Otherwise, adding or removing just adjusts the existing cached container.

Note that 'adding' an object to the container merely adds the symbol name of that object to the container. The actual object itself needs to be created separately, or if the datasource is active, the ds_add_container_symbol_and_request() function can be used to indicate to the Liberator that the objects inside the container should be requested individually.

Example: Create a container with two constituents

ds_data_t *dsdata;
ds5_publisher_t *pub;

dsdata = ds_init_container("/CONTAINER",F_CREATEPARENT|F_CREATEOBJECT);
ds_add_container_symbol(dsdata, "/RECORD/MSFT");
ds_add_container_symbol(dsdata, "/NEWS");
ds5_publish_to_subscribed_peers(pub, dsdata);

Example: Change the contents of an existing container

ds_data_t *dsdata;
ds5_publisher_t *pub;

dsdata = ds_init_container("/CONTAINER",F_CREATEPARENT|F_CREATEOBJECT);
ds_remove_container_symbol(dsdata, "/RECORD/MSFT");
ds_add_container_symbol(dsdata, "/RECORD/ORCL");
ds5_publish_to_subscribed_peers(pub, dsdata);

Function Documentation

void ds_add_container_symbol	(	ds_data_t *	data,
		const char *	symbol
	)

Add an object to the container.

Parameters

data	- The container object
symbol	- The symbol of the object to be added

void ds_add_container_symbol_and_request	(	ds_data_t *	data,
		const char *	symbol,
		const int	request
	)

Add an object to the container, indicating whether it should then be requested.

Parameters

data	- The container object
symbol	- The symbol of the object to be added
request	- If non zero, a flag is sent to the receiving datasource indicating that it should request the object that has been added (this typically indicates that the object is being provided by an active source)

void ds_add_container_symbol_at_position	(	ds_data_t *	data,
		int	position,
		const char *	symbol
	)

Insert an object within a container at a particular position.

Parameters

data	- The container object
position	- The position to insert at
symbol	- The name of the object to be inserted

void ds_cleardown_container_with_prefix	(	ds_data_t *	data,
		const char *	prefix
	)

Remove a set of symbols from the container.

Parameters

data	- The container object
prefix	- The prefix to match

Note

All symbols whose subjects start with the given prefix will be removed.

ds_data_t* ds_init_container	(	const char *	subject,
		const unsigned short	flags
	)

Initialise a container object.

Parameters

subject	- The name of the container object
flags	- Object flags

void ds_remove_container_symbol	(	ds_data_t *	data,
		const char *	symbol
	)

Remove an object from the container.

Parameters

data	- The container object
symbol	- The symbol of the object to be removed