topics.h File Reference

Subscription to topics and fetching topic data. More...

Data Structures
struct	subscription_handlers_s
struct	subscription_params_s
	Structure supplied when subscribing to a topic. More...
struct	svc_notify_subscription_request_s
	Structure describing an incoming notification that the client has been subscribed to a topic. More...
struct	notify_subscription_handlers_s
struct	notify_subscription_params_s
	Structure supplied when registering to receive topic subscription notifications. More...
struct	unsubscription_handlers_s
struct	unsubscription_params_s
	Structure supplied when unsubscribing from a topic. More...
struct	svc_notify_unsubscription_request_s
	Structure describing an incoming unsubscription notification. More...
struct	notify_unsubscription_handlers_s
struct	notify_unsubscription_params_s
	Structure supplied when registering to receive topic unsubscription notifications. More...

Macros
#define	SUBSCRIPTION_HANDLERS
	Callback handlers that may be registered to deal with messages sent by Diffusion in response to the subscription request.
#define	NOTIFY_SUBSCRIPTION
	Callback handlers for subscription notification messages.
#define	UNSUBSCRIPTION_HANDLERS
	Callback handlers that may be registered to deal with messages sent by Diffusion in response to the unsubscription request.
#define	NOTIFY_UNSUBSCRIPTION
	Callback handlers for unsubscription notification callbacks.

Typedefs
typedef int(*	on_subscribe_cb) (SESSION_T *session, void *context)
	Callback for on_subscribe().
typedef struct subscription_params_s	SUBSCRIPTION_PARAMS_T
	Structure supplied when subscribing to a topic.
typedef struct svc_notify_subscription_request_s	SVC_NOTIFY_SUBSCRIPTION_REQUEST_T
	Structure describing an incoming notification that the client has been subscribed to a topic.
typedef int(*	on_notify_subscription_cb) (SESSION_T *session, const SVC_NOTIFY_SUBSCRIPTION_REQUEST_T *request, void *context)
	Callback for notify_subscription_register().
typedef struct notify_subscription_params_s	NOTIFY_SUBSCRIPTION_PARAMS_T
	Structure supplied when registering to receive topic subscription notifications.
typedef int(*	on_unsubscribe_cb) (SESSION_T *session, void *context)
	Callback for on_unsubscribe().
typedef struct unsubscription_params_s	UNSUBSCRIPTION_PARAMS_T
	Structure supplied when unsubscribing from a topic.
typedef struct svc_notify_unsubscription_request_s	SVC_NOTIFY_UNSUBSCRIPTION_REQUEST_T
	Structure describing an incoming unsubscription notification.
typedef int(*	on_notify_unsubscription_cb) (SESSION_T *session, const SVC_NOTIFY_UNSUBSCRIPTION_REQUEST_T *request, void *context)
	Callback for notify_unsubscription_register.
typedef struct notify_unsubscription_params_s	NOTIFY_UNSUBSCRIPTION_PARAMS_T
	Structure supplied when registering to receive topic unsubscription notifications.

Enumerations
enum	NOTIFY_UNSUBSCRIPTION_REASON_T {   UNSUBSCRIPTION_REASON_REQUESTED , UNSUBSCRIPTION_REASON_CONTROL , UNSUBSCRIPTION_REASON_REMOVAL , UNSUBSCRIPTION_REASON_AUTHORIZATION ,   UNSUBSCRIPTION_REASON_UNKNOWN_UNSUBSCRIBE_REASON , UNSUBSCRIPTION_REASON_BACK_PRESSURE , UNSUBSCRIPTION_REASON_BRANCH_MAPPINGS , UNSUBSCRIPTION_REASON_SUBSCRIPTION_REFRESH ,   UNSUBSCRIPTION_REASON_STREAM_CHANGE }
	Reason for unsubscription. More...

Functions
TOPIC_HANDLER_T	subscribe (SESSION_T *session, const SUBSCRIPTION_PARAMS_T params)
	Subscribe to topics.
void	notify_subscription_register (SESSION_T *session, const NOTIFY_SUBSCRIPTION_PARAMS_T params)
	Register to receive subscription notifications.
void	unsubscribe (SESSION_T *session, const UNSUBSCRIPTION_PARAMS_T params)
	Unsubscribe from one or more topics.
void	notify_unsubscription_register (SESSION_T *session, const NOTIFY_UNSUBSCRIPTION_PARAMS_T params)
	Register to receive unsubscription notifications.
DIFFUSION_FETCH_REQUEST_T *	diffusion_fetch_request_init (SESSION_T *session)
	Creates an unconfigured fetch request.
DIFFUSION_FETCH_REQUEST_T *	diffusion_fetch_request_dup (const DIFFUSION_FETCH_REQUEST_T *fetch_request)
	Create a duplicate (copy) of an existing DIFFUSION_FETCH_REQUEST_T.
void	diffusion_fetch_request_free (DIFFUSION_FETCH_REQUEST_T *fetch_request)
	Free a memory allocated DIFFUSION_FETCH_REQUEST_T

Detailed Description

Subscription to topics and fetching topic data.

Typedef Documentation

on_notify_subscription_cb

typedef int(* on_notify_subscription_cb) (SESSION_T *session, const SVC_NOTIFY_SUBSCRIPTION_REQUEST_T *request, void *context)

Callback for notify_subscription_register().

Parameters

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

Returns

HANDLER_SUCCESS or HANDLER_FAILURE.

on_notify_unsubscription_cb

typedef int(* on_notify_unsubscription_cb) (SESSION_T *session, const SVC_NOTIFY_UNSUBSCRIPTION_REQUEST_T *request, void *context)

Callback for notify_unsubscription_register.

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_subscribe_cb

typedef int(* on_subscribe_cb) (SESSION_T *session, void *context)

Callback for on_subscribe().

Parameters

session	The current active session.
context	User-supplied context from the initial subscribe() call.

Returns

HANDLER_SUCCESS or HANDLER_FAILURE.

on_unsubscribe_cb

typedef int(* on_unsubscribe_cb) (SESSION_T *session, void *context)

Callback for on_unsubscribe().

Parameters

session	The current active session.
context	User-supplied context from the initial unsubscribe() call.

Returns

HANDLER_SUCCESS or HANDLER_FAILURE.

Enumeration Type Documentation

NOTIFY_UNSUBSCRIPTION_REASON_T

enum NOTIFY_UNSUBSCRIPTION_REASON_T

Reason for unsubscription.

Enumerator
UNSUBSCRIPTION_REASON_REQUESTED	Unsubscribed by the subscribing client. @since 5.6
UNSUBSCRIPTION_REASON_CONTROL	The unsubscription was requested either by another client or by the server. Since 5.6
UNSUBSCRIPTION_REASON_REMOVAL	The unsubscription occurred because the topic was removed. @since 5.6
UNSUBSCRIPTION_REASON_AUTHORIZATION	The unsubscription occurred because the session is no longer authorized to access the topic. Since 5.9
UNSUBSCRIPTION_REASON_UNKNOWN_UNSUBSCRIBE_REASON	A reason that is unsupported by the session. @since 6.1
UNSUBSCRIPTION_REASON_BACK_PRESSURE	The server has a significant backlog of messages for the session, and the topic specification has the DIFFUSION_CONFLATION topic property set to "unsubscribe". The session can resubscribe to the topic. The unsubscription is not persisted to the cluster, if the session fails over to a different server it will be resubscribed to the topic. Since 6.1
UNSUBSCRIPTION_REASON_BRANCH_MAPPINGS	The unsubscription occurred because branch mapping rules changed. @since 6.7
UNSUBSCRIPTION_REASON_SUBSCRIPTION_REFRESH	The server has re-subscribed this session to the topic. Existing streams are unsubscribed because the topic type and other attributes may have changed. This can happen if a set of servers is configured to use session replication, and a session connected to one server reconnects ("fails over") to a different server. A stream that receives an unsubscription notification with this reason will also receive a subscription notification with the new topic specification. Since 5.9
UNSUBSCRIPTION_REASON_STREAM_CHANGE	A fallback stream has been unsubscribed due to the addition of a stream that selects the topic. Since 5.9