DataSource for C SDK  6.2.20.310828
Deprecated: Receiving Data From Peers

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
nameThe object name
Returns
Nothing
void ds_discard_objects ( int  num,
char **  names 
)

Discard a number of objects.

Parameters
numNumber of objects
namesObjects 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
nameObject 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
nameObject name
retPointer 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
nameObject 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
indexService index number
name_ptrPointer 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
nameObject 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
nameThe 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
nameThe 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
nameThe object name
flagsFlags 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
numNumber of objects
namesNames of the objects
servicesPointer 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
numNumber of objects
namesNames of the objects
flagsFlags for these requests
servicesPointer 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
dsdatads_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
nameObject name
dataPointer 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
nameObject name
numNumber of hints
hintsArray of hints
Returns
Number of hints set

Each hint is a string containing a peer label


Generated on Wed Jan 24 2018 12:22:46 for DataSource for C SDK