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

Topic control feature. More...

Data Structures

struct  add_topic_callback_s
 add_topic_from_specification callback More...
 
struct  svc_topic_removal_response_s
 Structure describing a "topic removal" response. More...
 
struct  topic_removal_handlers_s
 
struct  topic_removal_params_s
 Structure passed to topic_removal(). More...
 
struct  svc_remove_topics_response_s
 Structure describing a "remove topic" response. More...
 
struct  remove_topics_handlers_s
 
struct  remove_topics_params_s
 Structure passed to remove_topics(). More...
 
struct  session_wills_remove_topic_handlers_s
 
struct  session_wills_remove_topic_params_s
 Structure supplied when registering a topic will to remove topics. More...
 
struct  svc_missing_topic_request_s
 Structure of a request to register for missing topic notifications. More...
 
struct  missing_topic_handlers_s
 
struct  missing_topic_params_s
 Structure supplied when registering to receive missing topic notifications. More...
 

Macros

#define TOPIC_REMOVAL_HANDLERS
 User-specified callbacks that may be invoked in response to issuing a "topic removal" request to Diffusion.
 
#define REMOVE_TOPICS_HANDLERS
 User-specified callbacks that may be invoked in response to issuing a "remove topic" request to Diffusion.
 
#define SESSION_WILLS_REMOVE_TOPIC_HANDLERS
 User callbacks that may be defined when registering a session will pertaining to topic removal.
 
#define MISSING_TOPIC_HANDLERS
 Callback handlers for missing topic notification messages.
 

Typedefs

typedef int(* on_topic_add_cb )(SESSION_T *session, TOPIC_ADD_RESULT_CODE result_code, void *context)
 Callback for add_topic_from_specification(). More...
 
typedef int(* on_topic_add_failed_cb )(SESSION_T *session, TOPIC_ADD_FAIL_RESULT_CODE result_code, const DIFFUSION_ERROR_T *error, void *context)
 Callback for add_topic_from_specification(). More...
 
typedef struct add_topic_callback_s ADD_TOPIC_CALLBACK_T
 add_topic_from_specification callback
 
typedef struct
svc_topic_removal_response_s 
SVC_TOPIC_REMOVAL_RESPONSE_T
 Structure describing a "topic removal" response.
 
typedef int(* on_topic_removal_cb )(SESSION_T *session, const SVC_TOPIC_REMOVAL_RESPONSE_T *response, void *context)
 Callback for topic_removal() handlers. More...
 
typedef struct
topic_removal_params_s 
TOPIC_REMOVAL_PARAMS_T
 Structure passed to topic_removal().
 
typedef struct
svc_remove_topics_response_s 
SVC_REMOVE_TOPICS_RESPONSE_T
 Structure describing a "remove topic" response.
 
typedef int(* on_remove_topics_cb )(SESSION_T *session, const SVC_REMOVE_TOPICS_RESPONSE_T *response, void *context)
 Callback for remove_topics() handlers. More...
 
typedef struct
remove_topics_params_s 
REMOVE_TOPICS_PARAMS_T
 Structure passed to remove_topics().
 
typedef int(* on_session_will_registration_cb )(SESSION_T *session, const char *topic_path, void *context)
 callback for session_wills_remove_topics(). More...
 
typedef struct
session_wills_remove_topic_params_s 
SESSION_WILLS_REMOVE_TOPIC_PARAMS_T
 Structure supplied when registering a topic will to remove topics.
 
typedef struct
svc_missing_topic_request_s 
SVC_MISSING_TOPIC_REQUEST_T
 Structure of a request to register for missing topic notifications.
 
typedef int(* on_missing_topic_cb )(SESSION_T *session, const SVC_MISSING_TOPIC_REQUEST_T *request, void *context)
 Callback for missing_topic_register_handler(). More...
 
typedef struct
missing_topic_params_s 
MISSING_TOPIC_PARAMS_T
 Structure supplied when registering to receive missing topic notifications.
 

Enumerations

enum  SVC_ADD_TOPIC_FAILURE_REASON_T {
  ADD_TOPIC_FAILURE_REASON_SUCCESS, ADD_TOPIC_FAILURE_REASON_EXISTS, ADD_TOPIC_FAILURE_REASON_EXISTS_MISMATCH, ADD_TOPIC_FAILURE_REASON_INVALID_NAME,
  ADD_TOPIC_FAILURE_REASON_INVALID_DETAILS, ADD_TOPIC_FAILURE_REASON_USER_CODE_ERROR, ADD_TOPIC_FAILURE_REASON_PERMISSIONS_FAILURE, ADD_TOPIC_FAILURE_REASON_INITIALISE_ERROR,
  ADD_TOPIC_FAILURE_REASON_UNEXPECTED_ERROR
}
 
enum  TOPIC_ADD_FAIL_RESULT_CODE {
  TOPIC_ADD_FAIL_EXISTS_MISMATCH, TOPIC_ADD_FAIL_INVALID_NAME, TOPIC_ADD_FAIL_INVALID_DETAILS, TOPIC_ADD_FAIL_PERMISSIONS_FAILURE,
  TOPIC_ADD_FAIL_UNEXPECTED_ERROR, TOPIC_ADD_FAIL_CLUSTER_REPARTITION, TOPIC_ADD_FAIL_EXCEEDED_LICENSE_LIMIT, TOPIC_ADD_FAIL_INCOMPATIBLE_PARENT,
  TOPIC_ADD_FAIL_INCOMPATIBLE_MASTER, TOPIC_ADD_FAIL_EXISTS_INCOMPATIBLE
}
 

Functions

void add_topic_from_specification (SESSION_T *session, const char *topic_path, const TOPIC_SPECIFICATION_T *specification, const ADD_TOPIC_CALLBACK_T callback)
 Add a topic to Diffusion. More...
 
void topic_removal (SESSION_T *session, const TOPIC_REMOVAL_PARAMS_T params)
 Remove topics from Diffusion. More...
 
void remove_topics (SESSION_T *session, const REMOVE_TOPICS_PARAMS_T params)
 Remove topics from Diffusion. More...
 
void session_wills_remove_topics (SESSION_T *session, const SESSION_WILLS_REMOVE_TOPIC_PARAMS_T params)
 Register a topic removal session will. More...
 
CONVERSATION_ID_Tmissing_topic_register_handler (SESSION_T *session, const MISSING_TOPIC_PARAMS_T params)
 Register to receive notifications about missing topics that clients attempt to fetch/subscribe. More...
 
void missing_topic_deregister_handler (SESSION_T *session, const CONVERSATION_ID_T *conversation_id)
 Cease receiving missing topic notifications. More...
 
void missing_topic_proceed (SESSION_T *session, SVC_MISSING_TOPIC_REQUEST_T *request)
 Proceed (retry) after a processing a missing topic notification. More...
 
void missing_topic_cancel (SESSION_T *session, SVC_MISSING_TOPIC_REQUEST_T *request)
 Cancel the operation leading to this missing topic notification. More...
 

Detailed Description

Topic control feature.

Typedef Documentation

typedef int(* on_missing_topic_cb)(SESSION_T *session, const SVC_MISSING_TOPIC_REQUEST_T *request, void *context)

Callback for missing_topic_register_handler().

Parameters
sessionThe current active session.
requestThe incoming notification message.
contextUser-supplied context from the initial registration call.
Returns
HANDLER_SUCCESS or HANDLER_FAILURE.
typedef int(* on_remove_topics_cb)(SESSION_T *session, const SVC_REMOVE_TOPICS_RESPONSE_T *response, void *context)

Callback for remove_topics() handlers.

Parameters
sessionThe current active session.
responseThe response message from Diffusion.
contextUser-supplied context from the remove_topics() call.
Returns
HANDLER_SUCCESS or HANDLER_FAILURE.
typedef int(* on_session_will_registration_cb)(SESSION_T *session, const char *topic_path, void *context)

callback for session_wills_remove_topics().

Parameters
sessionThe current active session.
topic_pathThe path on which the will has been registered.
contextUser-supplied context from the initial session_wills_remove_topics() call.
Returns
HANDLER_SUCCESS or HANDLER_FAILURE.
typedef int(* on_topic_add_cb)(SESSION_T *session, TOPIC_ADD_RESULT_CODE result_code, void *context)

Callback for add_topic_from_specification().

Parameters
sessionThe current active session.
result_codeThe result code from the topic add request.
contextUser-supplied context from the initial add_topic_from_specification() call.
Returns
HANDLER_SUCCESS or HANDLER_FAILURE.
typedef int(* on_topic_add_failed_cb)(SESSION_T *session, TOPIC_ADD_FAIL_RESULT_CODE result_code, const DIFFUSION_ERROR_T *error, void *context)

Callback for add_topic_from_specification().

Parameters
sessionThe current active session.
result_codeThe topic add failure result code
errorThe error reason. This will only be set if this function is called through the callback
contextUser-supplied context from the initial add_topic_from_specification() call.
Returns
HANDLER_SUCCESS or HANDLER_FAILURE.
typedef int(* on_topic_removal_cb)(SESSION_T *session, const SVC_TOPIC_REMOVAL_RESPONSE_T *response, void *context)

Callback for topic_removal() handlers.

Parameters
sessionThe current active session.
responseThe response message from Diffusion.
contextUser-supplied context from the topic_removal() call.
Returns
HANDLER_SUCCESS or HANDLER_FAILURE.

Enumeration Type Documentation

Enumerator
ADD_TOPIC_FAILURE_REASON_SUCCESS 

No error while adding topic.

ADD_TOPIC_FAILURE_REASON_EXISTS 

Topic already existed with exactly the same details.

ADD_TOPIC_FAILURE_REASON_EXISTS_MISMATCH 

Topic already exists with the same name but different details.

ADD_TOPIC_FAILURE_REASON_INVALID_NAME 

The name of the topic was found to be invalid.

ADD_TOPIC_FAILURE_REASON_INVALID_DETAILS 

Some aspect of the details failed validation.

ADD_TOPIC_FAILURE_REASON_USER_CODE_ERROR 
Deprecated:
This failure reason is deprecated from version 6.2 onwards and will be removed in a future release.
    A user supplied class could either not be found or could
    not be instantiated at the server.  
ADD_TOPIC_FAILURE_REASON_PERMISSIONS_FAILURE 

The client was denied permission to add a topic of the specified type a the given point in the topic hierarchy.

ADD_TOPIC_FAILURE_REASON_INITIALISE_ERROR 

Initialisation of topic with the supplied content failed, possibly because it was of the wrong format.

ADD_TOPIC_FAILURE_REASON_UNEXPECTED_ERROR 

An unexpected error occurred whilst attempting to create the topic.

Enumerator
TOPIC_ADD_FAIL_EXISTS_MISMATCH 

A topic already exists with the same path but a different specification.

TOPIC_ADD_FAIL_INVALID_NAME 

The supplied topic path is invalid.

TOPIC_ADD_FAIL_INVALID_DETAILS 

Some aspect of the topic specification failed validation.

TOPIC_ADD_FAIL_PERMISSIONS_FAILURE 

The client was denied permission to add a topic of the specified type at the given point in the topic hierarchy.

TOPIC_ADD_FAIL_UNEXPECTED_ERROR 

An unexpected error occurred whilst attempting to create the topic.

See the server log for more details.

TOPIC_ADD_FAIL_CLUSTER_REPARTITION 

Adding the topic failed because the cluster was repartitioning due to a server starting, stopping, or failing.

The operation can be retried.

TOPIC_ADD_FAIL_EXCEEDED_LICENSE_LIMIT 

Adding the topic failed because of a license limit.

TOPIC_ADD_FAIL_INCOMPATIBLE_PARENT 

Adding the topic failed because a topic owned by a publisher is already bound to the parent path.

TOPIC_ADD_FAIL_INCOMPATIBLE_MASTER 

Adding a slave topic failed because a topic owned by a publisher is already bound to the specified master path.

TOPIC_ADD_FAIL_EXISTS_INCOMPATIBLE 

Adding the topic failed because a topic is already bound to the specified path but the caller does not have the rights to manage it.