Publishing Container Objects

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 and store the container in the cache.

ds_data_t *dsdata;

dsdata = ds_init_container("/CONTAINER",F_CREATEPARENT|F_CREATEOBJECT);
ds_add_container_symbol(dsdata, "/RECORD/MSFT");
ds_add_container_symbol(dsdata, "/NEWS");
packet_contrib(dsdata,NULL,PACKET_FREE|PACKET_PUBLISH|PACKET_STORE);

Example: Change the contents of an existing container

ds_data_t *dsdata;

dsdata = ds_init_container("/CONTAINER",F_CREATEPARENT|F_CREATEOBJECT);
ds_remove_container_symbol(dsdata, "/RECORD/MSFT");
ds_add_container_symbol(dsdata, "/RECORD/ORCL");
packet_contrib(dsdata,NULL,PACKET_FREE|PACKET_PUBLISH|PACKET_STORE);