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

Allows the creation and removal of topics and notification of missing topics. More...

Data Structures

struct  add_topic_callback_s
 add_topic_from_specification callback More...
 
struct  topic_removal_handlers_s
 
struct  topic_removal_params_s
 Structure passed to topic_removal(). 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 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
DIFFUSION_TOPIC_REMOVAL_RESULT_T 
DIFFUSION_TOPIC_REMOVAL_RESULT_T
 An opaque topic removal result struct.
 
typedef int(* on_topic_removal_cb )(SESSION_T *session, const DIFFUSION_TOPIC_REMOVAL_RESULT_T *result, 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_missing_topic_request_s 
SVC_MISSING_TOPIC_REQUEST_T
 Structure of a request to register for missing topic notifications. More...
 
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_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_EXISTS_INCOMPATIBLE
}
 

Functions

int diffusion_topic_removal_result_removed_count (const DIFFUSION_TOPIC_REMOVAL_RESULT_T *topic_removal_result)
 The number of topics removed in the topic removal result. 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...
 
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 subscribe. More...
 
void missing_topic_deregister_handler (SESSION_T *session, const CONVERSATION_ID_T *conversation_id)
 Cease receiving missing topic notifications. More...
 
 DEPRECATED (void missing_topic_proceed(SESSION_T *session, SVC_MISSING_TOPIC_REQUEST_T *request))
 Proceed (retry) after a processing a missing topic notification. More...
 

Detailed Description

Allows the creation and removal of topics and notification of missing topics.

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

Called when a session subscribes using a topic selector that matches no existing topics.

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_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 DIFFUSION_TOPIC_REMOVAL_RESULT_T *result, void *context)

Callback for topic_removal() handlers.

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

Structure of a request to register for missing topic notifications.

Notification that a session has made a subscription request using a selector that does not match any topics.

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_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_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_proceedSESSION_T *session, SVC_MISSING_TOPIC_REQUEST_T *request)

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

This method is a no-op. In previous releases this would cause the selector to be added to the sessions's selections and the selection to be re-evaluated. Since 6.6, the selector is always added to the session's selections before this notification is issued.

Parameters
sessionThe current session.
requestThe request which gave rise to the missing topic notification.
Deprecated:
since 6.6
int diffusion_topic_removal_result_removed_count ( const DIFFUSION_TOPIC_REMOVAL_RESULT_T topic_removal_result)

The number of topics removed in the topic removal result.

Parameters
topic_removal_resultTopic removal result to query
Returns
the number of topics removed. -1 is returned if the topic removal result is NULL.