Files
file	subscription-control.h
	This feature allows a session to subscribe or unsubscribe other sessions to topics, on a single server or across a cluster.

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

Function Documentation

◆ diffusion_get_topic_selections()

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.

Each scope will have an ordered list of selections and/or deselections.

The server conflates selections, so if there has been a selection that is later rendered redundant by a deselection it will not be present. A scope that has been used but fully deselected will therefore not be present in the map and therefore no entry will have an empty list.

If the session has no current selections the map will be empty.

Parameters

session	The session handle. If NULL, this function returns immediately.
params	Parameters describing the `diffusion_get_topic_selections` request and callback handlers which may be invoked in response.
api_error	Populated on API error. Can be NULL.

Returns: True if the operation was successful. False, otherwise. In this case, if a non-NULL api_error pointer has been provided, this will be populated with the error information and should be freed with diffusion_api_error_free.

Since: 6.12

◆ diffusion_subscribe_by_filter()

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.

In a clustered environment the filter will be applied to all servers in the cluster.

This is equivalent to calling diffusion_subscribe_client_by_filter_with_scope specifying the DEFAULT_SELECTION_SCOPE as the selection scope.

Parameters

session	The session handle. If NULL, this function returns immediately.
params	Parameters describing the `diffusion_subscribe_by_filter` request and callback handlers which may be invoked in response.
api_error	Populated on API error. Can be NULL.

Returns: True if the operation was successful. False, otherwise. In this case, if a non-NULL api_error pointer has been provided, this will be populated with the error information and should be freed with diffusion_api_error_free.

◆ diffusion_subscribe_client_by_filter_with_scope()

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.

In a clustered environment the filter will be applied to all servers in the cluster.

For each session (anywhere in a cluster) that matches the filter, new subscriptions will be established for existing topics that match the provided topic selector and for which the sessions has READ_TOPIC permission. The topic selector will be added to the topic selections of the subscribed session, and re-evaluated when new topics are added or the session's security roles change.

A session that does not have SELECT_TOPIC permission for a topic cannot subscribe directly, but can be subscribed indirectly using this method.

Parameters

session	The session handle. If NULL, this function returns immediately.
scope	Specifies the scope of the selection. If NULL, this function returns immediately.
params	Parameters describing the `diffusion_subscribe_client_by_filter_with_scope` request and callback handlers which may be invoked in response.
api_error	Populated on API error. Can be NULL.

Returns: True if the operation was successful. False, otherwise. In this case, if a non-NULL api_error pointer has been provided, this will be populated with the error information and should be freed with diffusion_api_error_free.

Since: 6.12

◆ diffusion_subscribe_client_with_scope()

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.

New subscriptions will be established for existing topics that match the provided topic selector and for which the subscribed session has READ_TOPIC permission. The topic selector will be added to the topic selections of the subscribed session, and re-evaluated when new topics are added or the session's security roles change.

A session that does not have SELECT_TOPIC permission for a topic cannot subscribe directly, but can be subscribed indirectly using this method.

Parameters

session	The session handle. If NULL, this function returns immediately.
scope	Specifies the scope of the selection. If NULL, this function returns immediately.
params	Parameters describing the subscription control request and callback handlers which may be invoked in response.
api_error	Populated on API error. Can be NULL.

Returns: True if the operation was successful. False, otherwise. In this case, if a non-NULL api_error pointer has been provided, this will be populated with the error information and should be freed with diffusion_api_error_free.

Since: 6.12

◆ diffusion_unsubscribe_by_filter()

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.

This is equivalent to calling diffusion_unsubscribe_client_by_filter_with_scope specifying the DEFAULT_SELECTION_SCOPE as the selection scope.

Parameters

session	The session handle. If NULL, this function returns immediately.
params	Parameters describing the `diffusion_unsubscribe_by_filter` request and callback handlers which may be invoked in response.
api_error	Populated on API error. Can be NULL.

Returns: True if the operation was successful. False, otherwise. In this case, if a non-NULL api_error pointer has been provided, this will be populated with the error information and should be freed with diffusion_api_error_free.

◆ diffusion_unsubscribe_client_all_scopes()

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.

This can be used at any time whilst connected to reduce the set of topics to which the session is subscribed or negate earlier subscription requests and will apply to all scopes in use.

Parameters

session	The session handle. If NULL, this function returns immediately.
params	Parameters describing the `diffusion_unsubscribe_client_all_scopes` request and callback handlers which may be invoked in response.
api_error	Populated on API error. Can be NULL.

Returns: True if the operation was successful. False, otherwise. In this case, if a non-NULL api_error pointer has been provided, this will be populated with the error information and should be freed with diffusion_api_error_free.

Since: 6.12

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

Unsubscribe sessions that satisfy a given session filter from topics for all scopes. In a clustered environment the filter will be applied to all servers in the cluster.

Parameters

session	The session handle. If NULL, this function returns immediately.
params	Parameters describing the `diffusion_unsubscribe_client_all_scopes` request and callback handlers which may be invoked in response.
api_error	Populated on API error. Can be NULL.

Returns: True if the operation was successful. False, otherwise. In this case, if a non-NULL api_error pointer has been provided, this will be populated with the error information and should be freed with diffusion_api_error_free.

Since: 6.12

◆ diffusion_unsubscribe_client_by_filter_with_scope()

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.

Parameters

session	The session handle. If NULL, this function returns immediately.
scope	Specifies the scope of the selection. If NULL, this function returns immediately.
params	Parameters describing the `diffusion_unsubscribe_client_by_filter_with_scope` request and callback handlers which may be invoked in response.
api_error	Populated on API error. Can be NULL.

Returns: True if the operation was successful. False, otherwise. In this case, if a non-NULL api_error pointer has been provided, this will be populated with the error information and should be freed with diffusion_api_error_free.

Since: 6.12

◆ diffusion_unsubscribe_client_with_scope()

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.

This function requests that a client (anywhere in a cluster) is unsubscribed from the topics specified by a topic selector.

Parameters

session	The session handle. If NULL, this function returns immediately.
scope	Specifies the scope of the selection. If NULL, this function returns immediately.
params	Parameters describing the subscription control request and callback handlers which may be invoked in response.
api_error	Populated on API error. Can be NULL.

Returns: True if the operation was successful. False, otherwise. In this case, if a non-NULL api_error pointer has been provided, this will be populated with the error information and should be freed with diffusion_api_error_free.

Since: 6.12

◆ subscribe_client()

void subscribe_client	(	SESSION_T *	session,
		const SUBSCRIPTION_CONTROL_PARAMS_T	params
	)

Subscribe another session to topics.

This is equivalent to calling diffusion_subscribe_client_with_scope specifying the DEFAULT_SELECTION_SCOPE as the selection scope.

Parameters

session	The session handle. If NULL, this function returns immediately.
params	Parameters describing the subscription control request and callback handlers which may be invoked in response.

◆ unsubscribe_client()

void unsubscribe_client	(	SESSION_T *	session,
		const SUBSCRIPTION_CONTROL_PARAMS_T	params
	)

Unsubscribe another session from topics.

This is equivalent to calling diffusion_unsubscribe_client_with_scope specifying the DEFAULT_SELECTION_SCOPE as the selection scope.

Parameters

session	The session handle. If NULL, this function returns immediately.
params	Parameters describing the subscription control request and callback handlers which may be invoked in response.

Files

Functions

Detailed Description

Function Documentation

◆ diffusion_get_topic_selections()

◆ diffusion_subscribe_by_filter()

◆ diffusion_subscribe_client_by_filter_with_scope()

◆ diffusion_subscribe_client_with_scope()

◆ diffusion_unsubscribe_by_filter()

◆ diffusion_unsubscribe_client_all_scopes()

◆ diffusion_unsubscribe_client_by_filter_all_scopes()

◆ diffusion_unsubscribe_client_by_filter_with_scope()

◆ diffusion_unsubscribe_client_with_scope()

◆ subscribe_client()

◆ unsubscribe_client()