Macros
#define	DS_REQUEST_CACHE
	Flag indicating that this request is a result of a request from the active cache. More...

#define	DS_REQUEST_FAILOVER
	Flag indicated that this request is as a result of a failover between peers. More...

Functions
void	ds_discard_object (const char *name)
	Discard an object. More...

void	ds_discard_objects (int num, char **names)
	Discard a number of objects. More...

int	ds_get_num_services ()
	Return the number of services. More...

void *	ds_get_object_data (const char *name)
	Get an objects user data. More...

char **	ds_get_request_hints (const char name, int ret)
	Return an objects request hints. More...

char *	ds_get_service (const char *name)
	Return the service for an object. More...

int	ds_get_service_by_index (int index, char **name_ptr)
	Return the name/state of a service by index. More...

int	ds_object_available (const char *name)
	Determine whether this object can theoretically be requested. More...

int	ds_object_can_contrib (const char *name)
	Determine whether contributions can be sent for this object. More...

void	ds_purge_object (const char *name)
	Purge an object from our cache. More...

char *	ds_request_object (const char *name)
	Request an object. More...

char *	ds_request_object_with_flags (const char *name, int flags)
	Request an object. More...

int	ds_request_objects (int num, char names, char *services)
	Request a number of objects in one go. More...

int	ds_request_objects_with_flags (int num, char names, int flags, char *services)
	Request a number of objects in one go. More...

int	ds_required_services_status (char *buf, size_t buflen)
	Return whether all required services are ready. More...

int	ds_send_contribution (ds_data_t *dsdata)
	Contribute an object back to the peers that supplied it and support it. More...

void	ds_set_object_data (const char name, void data)
	Set an objects user data. More...

int	ds_set_request_hint (const char name, int num, char *hints)
	Set the objects hint peers. More...

Detailed Description

A DataSource which receives data from its peers is known as a DataSink.

Object updates are received using the recv_update_t callback. If you wish to receive dataupdates into your application, then this function should be implemented.

If an object has been deleted then a callback will be made to the DataSource's recv_nodata_t callback. Similarly, status messages are received by the recv_object_status_t callback.

Macro Definition Documentation

#define DS_REQUEST_CACHE

Flag indicating that this request is a result of a request from the active cache.

If a DataSource receives a call to the recv_request() callback with this flag set then the source should send the data related to these objects as broadcast data so that they are picked up by the active cache.

#define DS_REQUEST_FAILOVER

Flag indicated that this request is as a result of a failover between peers.

If a DataSource receives receives a call to the recv_request() callback with this bit set then the sink knows that the object exists and the source should not respond with a nodata message unless it is confident that the object does not exist

Function Documentation

void ds_discard_object ( const char * name )

Discard an object.

Parameters

name	The object name

Returns: Nothing

void ds_discard_objects	(	int	num,
		char **	names
	)

Discard a number of objects.

Parameters

num	Number of objects
names	Objects to discard

Returns: nothing

int ds_get_num_services ( )

Return the number of services.

Returns: Number of services

void* ds_get_object_data ( const char * name )

Get an objects user data.

Parameters

name	Object name

Note: This can be used to retrieve data attached to an object

char** ds_get_request_hints	(	const char *	name,
		int *	ret
	)

Return an objects request hints.

Parameters

name	Object name
ret	Pointer to place the number of returned labels

Returns: An array containing pointers to the labels

Note: Only the returned container should be free()'d - the elements within should not be

char* ds_get_service ( const char * name )

Return the service for an object.

Parameters

name	Object name

Returns: Service name or NULL

int ds_get_service_by_index	(	int	index,
		char **	name_ptr
	)

Return the name/state of a service by index.

Parameters

index	Service index number
name_ptr	Pointer to place the service name

Returns: State of the service

int ds_object_available ( const char * name )

Determine whether this object can theoretically be requested.

Parameters

name	- Name of the object

Return values

-3	- All required sources are broadcast
-2	- Object is defined as coming from a broadcast data set
-1	- Object is not available from any configured service
0	- Object can't be requested
1	- Object has mandatory data available
2	- Object has optional data available
3	- Object can be requested completely

int ds_object_can_contrib ( const char * name )

Determine whether contributions can be sent for this object.

Parameters

name	Object name

Return values

-1	- Unknown object/no mapping
0	- Can not take contributions, no configured peers
1	- Can take contributions

void ds_purge_object ( const char * name )

Purge an object from our cache.

Parameters

name	The object name

This function removes any reference to the object in the datasink side of the DataSource libraries. This function should be called when the application is purging any broadcast objects that have not updated within a certain time period.

char* ds_request_object ( const char * name )

Request an object.

Parameters

name	The object name

Returns: The service this object is associated with or NULL if not associated

See also: ds_request_object_with_flags()

If this function returns NULL, then the object hasn't been requested. The request will be outstanding for active-request-timeout seconds. Following this timeout, an F_NOTFOUND message will be sent to the sink via its recv_object_status_t callback.

char* ds_request_object_with_flags	(	const char *	name,
		int	flags
	)

Request an object.

Parameters

name	The object name
flags	Flags for this request

Returns: The service this object is associated with or NULL if not associated

See also: ds_request_object()

int ds_request_objects	(	int	num,
		char **	names,
		char ***	services
	)

Request a number of objects in one go.

Parameters

num	Number of objects
names	Names of the objects
services	Pointer to place the services in

Returns: The number of members in the populated array

The contents of the array should not be free(). Elements of the array may be null if an object couldn't be resolved to a service. The container should be though.

See also: ds_request_objects_with_flags()

int ds_request_objects_with_flags	(	int	num,
		char **	names,
		int	flags,
		char ***	services
	)

Request a number of objects in one go.

Parameters

num	Number of objects
names	Names of the objects
flags	Flags for these requests
services	Pointer to place the services in

Returns: The number of members in the populated array

The contents of the array should not be free(). Elements of the array may be null if an object couldn't be resolved to a service. The container should be though.

See also: ds_request_objects()

int ds_required_services_status	(	char *	buf,
		size_t	buflen
	)

Return whether all required services are ready.

Return values

0	- Not all required services are ready
1	- All required services are ready

int ds_send_contribution ( ds_data_t * dsdata )

Contribute an object back to the peers that supplied it and support it.

Parameters

dsdata ds_data_t to send back

Return values

n	- Number of peers data sent to
0	- Failure

Note: The dsdata should already have the named mapped.; The dsdata passed in will be automatically freed by this function

void ds_set_object_data	(	const char *	name,
		void *	data
	)

Set an objects user data.

Parameters

name	Object name
data	Pointer to opaque data

Note: This can be used to attach any data to an object

int ds_set_request_hint	(	const char *	name,
		int	num,
		char **	hints
	)

Set the objects hint peers.

Parameters

name	Object name
num	Number of hints
hints	Array of hints

Returns: Number of hints set

Each hint is a string containing a peer label

Macros

Functions

Detailed Description

Macro Definition Documentation

Function Documentation