Diffusion C API  6.3.3
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
topic-update-control.h File Reference

Topic update control feature. More...

Data Structures

struct  svc_update_registration_response_s
 Structure describing the response to a topic update registration request. More...
 
struct  update_source_registration_handlers_s
 
struct  update_source_registration_params_s
 Structure passed when registering an update source. More...
 
struct  update_source_deregistration_handlers_s
 
struct  update_source_deregistration_params_s
 Structure passed when deregistering an update source. More...
 
struct  svc_update_response_s
 Structure describing the response to a topic update request. More...
 
struct  update_source_handlers_s
 
struct  update_source_params_s
 Structure passed when updating a topic. More...
 
struct  update_value_params_s
 

Macros

#define UPDATE_SOURCE_REGISTRATION_HANDLERS
 User-supplied handlers that may be invoked in response to a request to register a topic source.
 
#define UPDATE_SOURCE_HANDLERS
 User-supplied handlers that are invoked in response to sending an update request to a Diffusion topic.
 

Typedefs

typedef struct
svc_update_registration_response_s 
SVC_UPDATE_REGISTRATION_RESPONSE_T
 Structure describing the response to a topic update registration request.
 
typedef int(* on_update_source_registration_cb )(SESSION_T *session, const CONVERSATION_ID_T *updater_id, const SVC_UPDATE_REGISTRATION_RESPONSE_T *response, void *context)
 Callback for register_update_source(). More...
 
typedef struct
update_source_registration_params_s 
UPDATE_SOURCE_REGISTRATION_PARAMS_T
 Structure passed when registering an update source.
 
typedef int(* on_update_source_deregistration_cb )(SESSION_T *session, const CONVERSATION_ID_T *updater_id, void *context)
 Callback for deregiser_update_source(). More...
 
typedef struct
update_source_deregistration_params_s 
UPDATE_SOURCE_DEREGISTRATION_PARAMS_T
 Structure passed when deregistering an update source.
 
typedef struct
svc_update_response_s 
SVC_UPDATE_RESPONSE_T
 Structure describing the response to a topic update request.
 
typedef struct
update_source_params_s 
UPDATE_SOURCE_PARAMS_T
 Structure passed when updating a topic.
 

Enumerations

enum  UPDATE_SOURCE_STATE_T { UPDATE_SOURCE_STATE_INIT, UPDATE_SOURCE_STATE_ACTIVE, UPDATE_SOURCE_STATE_CLOSED, UPDATE_SOURCE_STATE_STANDBY }
 Service states that an update source may be in. More...
 
enum  UPDATE_RESPONSE_STATUS_T {
  UPDATE_RESPONSE_OK, UPDATE_RESPONSE_INCOMPATIBLE_UPDATE, UPDATE_RESPONSE_UPDATE_FAILED, UPDATE_RESPONSE_INVALID_UPDATER,
  UPDATE_RESPONSE_MISSING_TOPIC, UPDATE_RESPONSE_EXCLUSIVE_UPDATER_CONFLICT, UPDATE_RESPONSE_DELTA_WITHOUT_VALUE, UPDATE_RESPONSE_CLUSTER_REPARTITION,
  UPDATE_RESPONSE_INCOMPATIBLE_STATE
}
 Values indicating the result of an update request. More...
 

Functions

 DEPRECATED (UPDATE_T *update_create(const UPDATE_ACTION_T action, const UPDATE_TYPE_T type, const CONTENT_T *content))
 
 DEPRECATED (void update_free(UPDATE_T *update))
 
 DEPRECATED (BUF_T *update_marshal(const UPDATE_T *update))
 
 DEPRECATED (char *buf_read_update(const char *data, UPDATE_T **update))
 
 DEPRECATED (UPDATE_T *update_unmarshal(const char *str))
 
 DEPRECATED (UPDATE_T *update_dup(const UPDATE_T *src))
 
 DEPRECATED (CONVERSATION_ID_T *register_update_source(SESSION_T *session, const UPDATE_SOURCE_REGISTRATION_PARAMS_T params))
 Register a topic update source. More...
 
 DEPRECATED (void deregister_update_source(SESSION_T *session, const UPDATE_SOURCE_DEREGISTRATION_PARAMS_T params))
 Deregister a topic update source. More...
 
 DEPRECATED (void update(SESSION_T *session, const UPDATE_SOURCE_PARAMS_T params))
 Update topic content. More...
 
 DEPRECATED (void update_value(SESSION_T *session, const UPDATE_VALUE_PARAMS_T params))
 Update topic content. More...
 
 DEPRECATED (void update_value_with_datatype(SESSION_T *session, DIFFUSION_DATATYPE datatype, UPDATE_VALUE_PARAMS_T params))
 Update topic content. More...
 

Detailed Description

Topic update control feature.

Typedef Documentation

typedef int(* on_update_source_deregistration_cb)(SESSION_T *session, const CONVERSATION_ID_T *updater_id, void *context)

Callback for deregiser_update_source().

Parameters
sessionThe current active session.
responseThe deregistration response message from Diffusion.
contextUser-supplied context from the deregistration call.
Returns
HANDLER_SUCCESS or HANDLER_FAILURE.
typedef int(* on_update_source_registration_cb)(SESSION_T *session, const CONVERSATION_ID_T *updater_id, const SVC_UPDATE_REGISTRATION_RESPONSE_T *response, void *context)

Callback for register_update_source().

Parameters
sessionThe current active session.
updater_idThe updater_id identifying this updater.
responseThe registration response message from Diffusion.
contextUser-supplied context from the initial registration call.
Returns
HANDLER_SUCCESS or HANDLER_FAILURE.

Enumeration Type Documentation

Values indicating the result of an update request.

Enumerator
UPDATE_RESPONSE_OK 

The update request has been processed successfully.

UPDATE_RESPONSE_INCOMPATIBLE_UPDATE 

The update was of a type that is not compatible with the topic type or the topic does not support updating.

UPDATE_RESPONSE_UPDATE_FAILED 

The update failed, probably because the content sent with the update was invalid/incompatible with the topic type/data format.

UPDATE_RESPONSE_INVALID_UPDATER 

The updater is not active.

UPDATE_RESPONSE_MISSING_TOPIC 

The topic being updated does not exist.

UPDATE_RESPONSE_EXCLUSIVE_UPDATER_CONFLICT 

Attempt to perform a non exclusive update on a topic branch that already has an update source.

UPDATE_RESPONSE_DELTA_WITHOUT_VALUE 

An update has been attempted on a topic that has no value.

UPDATE_RESPONSE_CLUSTER_REPARTITION 

An update could not be applied because the cluster was repartitioning.

UPDATE_RESPONSE_INCOMPATIBLE_STATE 

An update could not be performed because the topic is managed by a component (e.g fan-out) that prohibits updates from the caller.

Service states that an update source may be in.

Remarks
Updates should only be performed when the registered source is an ACTIVE state.
Enumerator
UPDATE_SOURCE_STATE_INIT 

Initial source state, before state is received from the server.

UPDATE_SOURCE_STATE_ACTIVE 

Active state - the topic may be updated by this source.

UPDATE_SOURCE_STATE_CLOSED 

Terminal state; no further state changes may take place.

UPDATE_SOURCE_STATE_STANDBY 

Inactive state that permits being set to Active or Closed.

Function Documentation

DEPRECATED ( UPDATE_T update_createconst UPDATE_ACTION_T action, const UPDATE_TYPE_T type, const CONTENT_T *content)
Deprecated:
This function is deprecated from version 6.2 onwards, and will be removed in a future release.

Create a new UPDATE_T structure for updating topic content.

Parameters
actionThe operation that will be performed on the target topic data (refresh, update, match).
typeThe type of update being performed (typically, Content change).
contentThe data to be sent to Diffusion.
Returns
A new UPDATE_T structure, or NULL on error.
DEPRECATED ( void   update_freeUPDATE_T *update)
Deprecated:
This function is deprecated from version 6.2 onwards, and will be removed in a future release.

Free all memory associated with an UPDATE_T.

Parameters
updateThe UPDATE_T to be freed.
DEPRECATED ( BUF_T update_marshalconst UPDATE_T *update)
Deprecated:
This function is deprecated from version 6.2 onwards, and will be removed in a future release.

Serialise an UPDATE_T to bytes for transmission to Diffusion.

Parameters
updateThe UPDATE_T to be mashalled.
Returns
A pointer to a newly allocated BUF_T containing the serialised data, or NULL if an error occurs.
DEPRECATED ( char *  buf_read_updateconst char *data, UPDATE_T **update)
Deprecated:
This function is deprecated from version 6.2 onwards, and will be removed in a future release.

Read an UPDATE_T structure from a char array.

Parameters
dataThe char array containing the serialised UPDATE_T
updateThe location to store a newly allocated UPDATE_T
Returns
A pointer to the first char following the serialised UPDATE_T in the char array, or NULL on error.
DEPRECATED ( UPDATE_T update_unmarshalconst char *str)
Deprecated:
This function is deprecated from version 6.2 onwards, and will be removed in a future release.

Deserialise bytes from Diffusion to an UPDATE_T structure.

Parameters
strThe bytes to be unmarshalled.
Returns
A pointer to a newly allcoated UPDATE_T, or NULL if an error occurs.
DEPRECATED ( UPDATE_T update_dupconst UPDATE_T *src)
Deprecated:
This function is deprecated from version 6.2 onwards, and will be removed in a future release.

Create a deep copy of an UPDATE_T structure.

Parameters
srcThe UPDATE_T to copy.
Returns
A newly allocated UPDATE_T, or NULL on error.
DEPRECATED ( CONVERSATION_ID_T register_update_sourceSESSION_T *session, const UPDATE_SOURCE_REGISTRATION_PARAMS_T params)

Register a topic update source.

Deprecated:
This function is deprecated from version 6.2 onwards, and will be removed in a future release.

Registers an update source with Diffusion, requesting responsibility for managing topic state for all topics from a given point and below.

Parameters
sessionThe session handle. If NULL, this function returns immediately with a NULL value.
paramsParameter structure describing the registration request.
Returns
A conversation ID that can be used as a handle to future topic updates by this update source, or NULL if the supplied session is NULL.
DEPRECATED ( void   deregister_update_sourceSESSION_T *session, const UPDATE_SOURCE_DEREGISTRATION_PARAMS_T params)

Deregister a topic update source.

Deprecated:
This function is deprecated from version 6.2 onwards, and will be removed in a future release.

Deregisters an existing update source from Diffusion.

Parameters
sessionThe session handle. If NULL, this function returns immediately.
paramsParameter structure describing the deregistration request.
DEPRECATED ( void   updateSESSION_T *session, const UPDATE_SOURCE_PARAMS_T params)

Update topic content.

Deprecated:
This function is deprecated from version 6.2 onwards, and will be removed in a future release. Applications should now use the preferred update API in topic-update.h

Sends new topic content to Diffusion, for transmission to subscribed clients. Where possible, prefer update_value() to update().

Parameters
sessionThe session handle. If NULL, this function returns immediately.
paramsParameter structure describing which topic to update, the new content, how the update is to be applied, and callbacks to handle success or failure notifications.
DEPRECATED ( void   update_valueSESSION_T *session, const UPDATE_VALUE_PARAMS_T params)

Update topic content.

Deprecated:
This function is deprecated from version 6.2 onwards, and will be removed in a future release. Applications should now use the preferred update API in topic-update.h

Updates the content of a topic of a certain type (binary, JSON) but unlike update(), this may transparently send delta updates which require less network bandwidth. If possible, prefer this function to update().

Parameters
sessionThe session handle. If NULL, this function returns immediately.
paramsParameter structure describing which topic to update, the value that the topic on the server will contain and callbacks to handle success or failure notifications.
DEPRECATED ( void   update_value_with_datatypeSESSION_T *session, DIFFUSION_DATATYPE datatype, UPDATE_VALUE_PARAMS_T params)

Update topic content.

Deprecated:
This function is deprecated from version 6.2 onwards, and will be removed in a future release. Applications should now use the preferred update API in topic-update.h

Updates the content of a topic of a provided datatype. This is the preferred function for updating datatype topics (Binary, JSON, String, Int64, Double and Recordv2)

Parameters
sessionThe session handle. If NULL, this function returns immediately.
datatypeDIFFUSION_DATATYPE of the topic to be updated.
paramsParameter structure describing which topic to update, the value that the topic on the server will contain and callbacks to handle success or failure notifications.