Diffusion C API  6.4.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  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. More...
 
#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 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

 DEPRECATED (typedef struct svc_remove_topics_response_s{}SVC_REMOVE_TOPICS_RESPONSE_T)
 Structure describing a "remove topic" response. More...
 
 DEPRECATED (typedef int(*on_remove_topics_cb)(SESSION_T *session, const SVC_REMOVE_TOPICS_RESPONSE_T *response, void *context))
 Callback for remove_topics() handlers. More...
 
 DEPRECATED (typedef struct remove_topics_params_s{REMOVE_TOPICS_HANDLERSconst char *topic_selector;void *context;}REMOVE_TOPICS_PARAMS_T)
 Structure passed to remove_topics(). More...
 
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...
 
 DEPRECATED (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...
 
 DEPRECATED (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.

Macro Definition Documentation

#define REMOVE_TOPICS_HANDLERS

User-specified callbacks that may be invoked in response to issuing a "remove topic" request to Diffusion.

Deprecated:
Since 6.4.2. Please use topic_removal, as it is more powerful and works correctly with replicated topics. This will be removed in a future release

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_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 
Deprecated:
Slave topics are deprecated. This value will be removed in a future release. 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.

Function Documentation

DEPRECATED ( typedef struct svc_remove_topics_response_s{}  SVC_REMOVE_TOPICS_RESPONSE_T)

Structure describing a "remove topic" response.

Deprecated:
Since 6.4.2. Please use topic_removal, as it is more powerful and works correctly with replicated topics. This will be removed in a future release
DEPRECATED ( typedef int(*)(SESSION_T *session, const SVC_REMOVE_TOPICS_RESPONSE_T *response, void *context)  on_remove_topics_cb)

Callback for remove_topics() handlers.

Deprecated:
Since 6.4.2. Please use topic_removal, as it is more powerful and works correctly with replicated topics. This will be removed in a future release
Parameters
sessionThe current active session.
responseThe response message from Diffusion.
contextUser-supplied context from the remove_topics() call.
Returns
HANDLER_SUCCESS or HANDLER_FAILURE.
DEPRECATED ( typedef struct remove_topics_params_s{REMOVE_TOPICS_HANDLERSconst char *topic_selector;void *context;}  REMOVE_TOPICS_PARAMS_T)

Structure passed to remove_topics().

Deprecated:
Since 6.4.2. Please use topic_removal, as it is more powerful and works correctly with replicated topics. This will be removed in a future release
Parameters
REMOVE_TOPICS_PARAMS_TSelector describing topics to remove. User-supplied context returned to callbacks.
DEPRECATED ( void   missing_topic_cancelSESSION_T *session, SVC_MISSING_TOPIC_REQUEST_T *request)

Cancel the operation leading to this missing topic notification.

Deprecated:
Since 6.4. This is only useful when using the deprecated fetch mechanism. It will be removed when that mechanism is removed.

To be called in a missing topic notification handler, this notifies Diffusion that it should not continue processing the original request.

Parameters
sessionThe current session.
requestThe request which gave rise to the missing topic notification.