subscription-control.h File Reference

This feature allows a session to subscribe or unsubscribe other sessions to topics, on a single server or across a cluster. More...

Data Structures
struct	subscription_control_params_s
struct	diffusion_subscribe_by_filter_s
	Structure supplied when issuing a diffusion_subscribe_by_filter call. More...
struct	diffusion_unsubscribe_by_filter_s
	Structure supplied when issuing a diffusion_unsubscribe_by_filter call. More...
struct	diffusion_get_topic_selections_s
	Structure supplied when issuing a diffusion_get_topic_selections call. More...

Macros
#define	SUBSCRIPTION_CONTROL_HANDLERS
	Callback handlers that may be registered so the caller may receive notification that a subscription or unsubscription request has completed.

Typedefs
typedef int(*	on_subscription_control_cb) (SESSION_T *session, void *context)
	Callback for subscribe_client() and unsubscribe_client().
typedef int(*	on_subscription_control_by_filter_cb) (const int number_selected, void *context)
	Callback for diffusion_subscribe_by_filter and diffusion_unsubscribe_by_filter.
typedef struct diffusion_subscribe_by_filter_s	DIFFUSION_SUBSCRIBE_BY_FILTER_PARAMS_T
	Structure supplied when issuing a diffusion_subscribe_by_filter call.
typedef struct diffusion_unsubscribe_by_filter_s	DIFFUSION_UNSUBSCRIBE_BY_FILTER_PARAMS_T
	Structure supplied when issuing a diffusion_unsubscribe_by_filter call.
typedef int(*	on_get_topic_selections_cb) (SESSION_T *session, HASH_T *topic_selections, void *context)
	Callback for diffusion_get_topic_selections().
typedef struct diffusion_get_topic_selections_s	DIFFUSION_GET_TOPIC_SELECTIONS_PARAMS_T
	Structure supplied when issuing a diffusion_get_topic_selections call.

Functions
void	subscribe_client (SESSION_T *session, const SUBSCRIPTION_CONTROL_PARAMS_T params)
	Subscribe another session to topics.
bool	diffusion_subscribe_client_with_scope (SESSION_T *session, const char *selection_scope, const SUBSCRIPTION_CONTROL_PARAMS_T params, DIFFUSION_API_ERROR *api_error)
	Subscribe another session to topics.
void	unsubscribe_client (SESSION_T *session, const SUBSCRIPTION_CONTROL_PARAMS_T params)
	Unsubscribe another session from topics.
bool	diffusion_unsubscribe_client_with_scope (SESSION_T *session, const char *selection_scope, const SUBSCRIPTION_CONTROL_PARAMS_T params, DIFFUSION_API_ERROR *api_error)
	Unsubscribe another session from topics.
bool	diffusion_subscribe_by_filter (SESSION_T *session, const DIFFUSION_SUBSCRIBE_BY_FILTER_PARAMS_T params, DIFFUSION_API_ERROR *api_error)
	Subscribe sessions that satisfy a given session filter to topics.
bool	diffusion_subscribe_client_by_filter_with_scope (SESSION_T *session, const char *selection_scope, const DIFFUSION_SUBSCRIBE_BY_FILTER_PARAMS_T params, DIFFUSION_API_ERROR *api_error)
	Subscribe sessions that satisfy a given session filter to topics.
bool	diffusion_unsubscribe_by_filter (SESSION_T *session, const DIFFUSION_UNSUBSCRIBE_BY_FILTER_PARAMS_T params, DIFFUSION_API_ERROR *api_error)
	Unsubscribe sessions (anywhere in a cluster) that satisfy a given session filter from topics.
bool	diffusion_unsubscribe_client_by_filter_with_scope (SESSION_T *session, const char *selection_scope, const DIFFUSION_UNSUBSCRIBE_BY_FILTER_PARAMS_T params, DIFFUSION_API_ERROR *api_error)
	Unsubscribe sessions (anywhere in a cluster) that satisfy a given session filter from topics.
bool	diffusion_unsubscribe_client_all_scopes (SESSION_T *session, const SUBSCRIPTION_CONTROL_PARAMS_T params, DIFFUSION_API_ERROR *api_error)
	Unsubscribe topics from all topic selection scopes.
bool	diffusion_unsubscribe_client_by_filter_all_scopes (SESSION_T *session, const DIFFUSION_UNSUBSCRIBE_BY_FILTER_PARAMS_T params, DIFFUSION_API_ERROR *api_error)
	Unsubscribe topics from all topic selection scopes.
bool	diffusion_get_topic_selections (SESSION_T *session, const DIFFUSION_GET_TOPIC_SELECTIONS_PARAMS_T params, DIFFUSION_API_ERROR *api_error)
	Returns a map of the current topic selection state for a specified session, keyed on topic selection scope.

Detailed Description

This feature allows a session to subscribe or unsubscribe other sessions to topics, on a single server or across a cluster.

Requests to subscribe sessions to topics can be submitted at any time even if the topics do not exist at the server. Topic selectors are used on subscription to match against topics at the server. The session will become subscribed to any topics that exist at the server that match the selector (unless they are already subscribed, or the session has insufficient permission). The subscription request is also retained at the server so that if any newly created topics match the selector, the session will then become subscribed to it (unless a subsequent unsubscription cancels it).

Specific sessions (anywhere in a cluster) may be subscribed/unsubscribed if the session_id is known.

Subscriptions may also be requested using 'session filters' (see session.h for a full description of session filters), where all sessions (anywhere in a cluster) that satisfy a particular filter expression will be subscribed/unsubscribed. The filter is only evaluated once against the current sessions that exist at the time - it is not retained and applied to any sessions that are created later. In order to be notified of new sessions as they are created session properties listeners can be used and those sessions subscribed as required based upon their session properties.

This feature also provides the ability to query the topic selections of another session.

Access control

To subscribe other sessions to topics, a session must have MODIFY_SESSION permission, and SELECT_TOPIC permission for the topic selector used for subscription. The subscribed sessions will only be subscribed to matching topics for which they have READ_TOPIC permission.

To unsubscribe other sessions, a session must have MODIFY_SESSION permission, and SELECT_TOPIC permission for the topic selector used for unsubscription.

Operations that identify sessions using a session filter require the VIEW_SESSION permission.

Getting the topic selections for a specified session requires VIEW_SESSION permission.

Typedef Documentation

on_get_topic_selections_cb

typedef int(* on_get_topic_selections_cb) (SESSION_T *session, HASH_T *topic_selections, void *context)

Callback for diffusion_get_topic_selections().

Parameters

session	The current active session.
topic_selections	The collections of topic selections.
context	User-supplied context from the originating call.

Returns

HANDLER_SUCCESS or HANDLER_FAILURE.

on_subscription_control_by_filter_cb

typedef int(* on_subscription_control_by_filter_cb) (const int number_selected, void *context)

Callback for diffusion_subscribe_by_filter and diffusion_unsubscribe_by_filter.

Parameters

number_selected	Number of sessions matching the filter.
context	User-supplied context from the originating call.

Returns

HANDLER_SUCCESS or HANDLER_FAILURE.

on_subscription_control_cb

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

Callback for subscribe_client() and unsubscribe_client().

Parameters

session	The current active session.
context	User-supplied context from the originating call.

Returns

HANDLER_SUCCESS or HANDLER_FAILURE.