Diffusion C API  6.5.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 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

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 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.

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 
Deprecated:
This failure reason is deprecated and unused from version 6.5. The value will be removed in a future release.
TOPIC_ADD_FAIL_INCOMPATIBLE_MASTER 

a future release.

Deprecated:
Slave topics are deprecated since version 6.4. This failure
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 ( 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. In the future (when the legacy fetch mechanism is removed) the behavior when a subscription selector matches with no topics will be to add the selector to the session's topic selections regardless of whether this is called, and this method will become a no-op and will eventually be 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.
void missing_topic_proceed ( SESSION_T session,
SVC_MISSING_TOPIC_REQUEST_T request 
)

Proceed (retry) after a processing a missing topic notification.

To be called in a missing topic notification handler, this notifies Diffusion that it may complete processing of the original request.

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