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().
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().
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.
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.
typedef int(*	on_missing_topic_cb) (SESSION_T *session, const SVC_MISSING_TOPIC_REQUEST_T *request, void *context)
	Callback for missing_topic_register_handler().
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.
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.
void	topic_removal (SESSION_T *session, const TOPIC_REMOVAL_PARAMS_T params)
	Remove topics from Diffusion.
CONVERSATION_ID_T *	missing_topic_register_handler (SESSION_T *session, const MISSING_TOPIC_PARAMS_T params)
	Register to receive notifications about missing topics that clients attempt to subscribe.
void	missing_topic_deregister_handler (SESSION_T *session, const CONVERSATION_ID_T *conversation_id)
	Cease receiving missing topic notifications.

Detailed Description

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

Typedef Documentation

on_missing_topic_cb

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

session	The current active session.
request	The incoming notification message.
context	User-supplied context from the initial registration call.

Returns

HANDLER_SUCCESS or HANDLER_FAILURE.

on_topic_add_cb

typedef int(* on_topic_add_cb) (SESSION_T *session, TOPIC_ADD_RESULT_CODE result_code, void *context)

Callback for add_topic_from_specification().

Parameters

session	The current active session.
result_code	The result code from the topic add request.
context	User-supplied context from the initial add_topic_from_specification() call.

Returns

HANDLER_SUCCESS or HANDLER_FAILURE.

on_topic_add_failed_cb

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

session	The current active session.
result_code	The topic add failure result code
error	The error reason. This will only be set if this function is called through the callback
context	User-supplied context from the initial add_topic_from_specification() call.

Returns

HANDLER_SUCCESS or HANDLER_FAILURE.

on_topic_removal_cb

typedef int(* on_topic_removal_cb) (SESSION_T *session, const DIFFUSION_TOPIC_REMOVAL_RESULT_T *result, void *context)

Callback for topic_removal() handlers.

Parameters

session	The current active session.
result	The response message from Diffusion.
context	User-supplied context from the topic_removal() call.

Returns

HANDLER_SUCCESS or HANDLER_FAILURE.

SVC_MISSING_TOPIC_REQUEST_T

typedef struct svc_missing_topic_request_s SVC_MISSING_TOPIC_REQUEST_T

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

SVC_ADD_TOPIC_FAILURE_REASON_T

enum SVC_ADD_TOPIC_FAILURE_REASON_T

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.

TOPIC_ADD_FAIL_RESULT_CODE

enum TOPIC_ADD_FAIL_RESULT_CODE

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

diffusion_topic_removal_result_removed_count()

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_result

Topic removal result to query

Returns

the number of topics removed. -1 is returned if the topic removal result is NULL.