Functions
void	session_properties_listener_register (SESSION_T *session, const SESSION_PROPERTIES_REGISTRATION_PARAMS_T params)
	Register a listener for changes to other clients' properties.

void	get_session_properties (SESSION_T *session, const GET_SESSION_PROPERTIES_PARAMS_T params)
	Request properties of a connected client.

bool	diffusion_set_session_properties (SESSION_T session, const DIFFUSION_SET_SESSION_PROPERTIES_PARAMS_T params, DIFFUSION_API_ERROR api_error)
	Send a request to the server to change the user-defined session properties for a session.

bool	diffusion_set_session_properties_filter (SESSION_T session, const DIFFUSION_SET_SESSION_PROPERTIES_FILTER_PARAMS_T params, DIFFUSION_API_ERROR api_error)
	Send a request to the server to set all sessions that satisfy a session filter with the new user-defined session properties.

bool	diffusion_change_roles_with_session_id (SESSION_T session, const DIFFUSION_CHANGE_ROLES_WITH_SESSION_ID_PARAMS_T params, DIFFUSION_API_ERROR api_error)
	Changes the assigned roles of another session.

bool	diffusion_change_roles_with_filter (SESSION_T session, const DIFFUSION_CHANGE_ROLES_WITH_FILTER_PARAMS_T params, DIFFUSION_API_ERROR api_error)
	Allows a session to change the assigned roles of all sessions that satisfy a given session filter.

bool	diffusion_client_close_with_session (SESSION_T session, const DIFFUSION_CLIENT_CLOSE_WITH_SESSION_PARAMS_T params, DIFFUSION_API_ERROR api_error)
	Close a client session.

bool	diffusion_client_close_with_filter (SESSION_T session, const DIFFUSION_CLIENT_CLOSE_WITH_FILTER_PARAMS_T params, DIFFUSION_API_ERROR api_error)
	Close all client sessions matching a given session filter.

bool	diffusion_client_set_conflated_with_filter (SESSION_T session, const DIFFUSION_CLIENT_SET_CONFLATED_WITH_FILTER_PARAMS_T params, DIFFUSION_API_ERROR api_error)
	Control client queue conflation.

Detailed Description

Function Documentation

◆ diffusion_change_roles_with_filter()

bool diffusion_change_roles_with_filter	(	SESSION_T *	session,
		const DIFFUSION_CHANGE_ROLES_WITH_FILTER_PARAMS_T	params,
		DIFFUSION_API_ERROR *	api_error
	)

Allows a session to change the assigned roles of all sessions that satisfy a given session filter.

Initially a session has a set of roles assigned during authentication. A current roles set can be obtained from the $Roles session property.

When a set of session roles changes, its $Roles property changes accordingly. As a role can constrain 'topic' permissions, session subscriptions are re-evaluated based on the new roles set.

The same role must not occur in both params.roles_to_remove and params.roles_to_add sets. Either set can be an empty (or NULL) set but not both.

Parameters

session	The current session. If NULL, this function returns immediately.
params	Parameter structure describing which client and properties we're interested in, and the callbacks to be invoked.
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_change_roles_with_session_id()

bool diffusion_change_roles_with_session_id	(	SESSION_T *	session,
		const DIFFUSION_CHANGE_ROLES_WITH_SESSION_ID_PARAMS_T	params,
		DIFFUSION_API_ERROR *	api_error
	)

Changes the assigned roles of another session.

Initially a session has a set of roles assigned during authentication. The set of assigned roles can be obtained from the session's $Roles session property.

When a session's assigned roles change, its $Roles property changes accordingly. Changing the assigned roles can change the READ_TOPIC permissions granted to the session. The session's subscriptions will be updated accordingly.

The same role must not occur in both params.roles_to_remove and params.roles_to_add sets. Either set can be an empty (or NULL) set but not both.

Parameters

session	The current session. If NULL, this function returns immediately.
params	Parameter structure describing which client and properties we're interested in, and the callbacks to be invoked.
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_client_close_with_filter()

bool diffusion_client_close_with_filter	(	SESSION_T *	session,
		const DIFFUSION_CLIENT_CLOSE_WITH_FILTER_PARAMS_T	params,
		DIFFUSION_API_ERROR *	api_error
	)

Close all client sessions matching a given session filter.

Parameters

session	The current session. If NULL, this function returns immediately.
params	Parameter structure describing which client and properties we're interested in, and the callbacks to be invoked.
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_client_close_with_session()

bool diffusion_client_close_with_session	(	SESSION_T *	session,
		const DIFFUSION_CLIENT_CLOSE_WITH_SESSION_PARAMS_T	params,
		DIFFUSION_API_ERROR *	api_error
	)

Close a client session.

Parameters

session	The current session. If NULL, this function returns immediately.
params	Parameter structure describing which client and properties we're interested in, and the callbacks to be invoked.
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_client_set_conflated_with_filter()

bool diffusion_client_set_conflated_with_filter	(	SESSION_T *	session,
		const DIFFUSION_CLIENT_SET_CONFLATED_WITH_FILTER_PARAMS_T	params,
		DIFFUSION_API_ERROR *	api_error
	)

Control client queue conflation.

Each session begins with conflation enabled or disabled based on the queue configuration of the connector it is using. This method allows conflation to be enabled or disabled for a set of sessions matching a filter at runtime. For more detail on specifying session filters see session.h

Conflation is the process of merging or discarding topic updates queued for a session to reduce the server memory footprint and network data. Conflation needs to be enabled for a session and a policy configured for the topic to have an effect.

Parameters

session	The current session. If NULL, this function returns immediately.
params	Parameter structure describing which client and properties we're interested in, and the callbacks to be invoked.
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_set_session_properties()

bool diffusion_set_session_properties	(	SESSION_T *	session,
		const DIFFUSION_SET_SESSION_PROPERTIES_PARAMS_T	params,
		DIFFUSION_API_ERROR *	api_error
	)

Send a request to the server to change the user-defined session properties for a session.

It is also permissible to change the values of the following fixed session properties :-

$Country - will be normalised to upper case $Language - will be normalised to lower case $Latitude - Invalid value will be set to "NaN" $Longitude - Invalid value will be set to "NaN"

If values are provided for any other fixed session properties they will be ignored.

Parameters

session	The current session. If NULL, this function returns immediately.
params	Parameters defining the `diffusion_set_session_properties` request and callbacks.
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_set_session_properties_filter()

bool diffusion_set_session_properties_filter	(	SESSION_T *	session,
		const DIFFUSION_SET_SESSION_PROPERTIES_FILTER_PARAMS_T	params,
		DIFFUSION_API_ERROR *	api_error
	)

Send a request to the server to set all sessions that satisfy a session filter with the new user-defined session properties.

It is also permissible to change the values of the following fixed session properties :-

$Country - will be normalised to upper case $Language - will be normalised to lower case $Latitude - Invalid value will be set to "NaN" $Longitude - Invalid value will be set to "NaN"

If values are provided for any other fixed session properties they will be ignored.

Parameters

session	The current session. If NULL, this function returns immediately.
params	Parameters defining the `diffusion_set_session_properties_filter` request and callbacks.
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.

◆ get_session_properties()

void get_session_properties	(	SESSION_T *	session,
		const GET_SESSION_PROPERTIES_PARAMS_T	params
	)

Request properties of a connected client.

Parameters

session	The current session. If NULL, this function returns immediately.
params	Parameter structure describing which client and properties we're interested in, and the callbacks to be invoked.

◆ session_properties_listener_register()

void session_properties_listener_register	(	SESSION_T *	session,
		const SESSION_PROPERTIES_REGISTRATION_PARAMS_T	params
	)

Register a listener for changes to other clients' properties.

Parameters

session	The current session. If NULL, this function returns immediately.
params	Parameter structure describing which properties should be reported, and the callbacks to be invoked.

Functions

Detailed Description

Function Documentation

◆ diffusion_change_roles_with_filter()

◆ diffusion_change_roles_with_session_id()

◆ diffusion_client_close_with_filter()

◆ diffusion_client_close_with_session()

◆ diffusion_client_set_conflated_with_filter()

◆ diffusion_set_session_properties()

◆ diffusion_set_session_properties_filter()

◆ get_session_properties()

◆ session_properties_listener_register()