Functions
RECONNECTION_STRATEGY_T *	make_reconnection_strategy_repeating_attempt (long retry_count, long retry_delay)
	Creates a reconnection strategy that will retry a connection for a given number of times, with a delay between retry attempts.

RECONNECTION_STRATEGY_T *	make_reconnection_strategy_user_function (PERFORM_RECONNECTION_CB reconnect_cb, void *args, PERFORM_RECONNECTION_AFTER_ACTION_CB success_cb, PERFORM_RECONNECTION_AFTER_ACTION_CB failure_cb)
	Create a new reconnection strategy whose behavior is determined by a user-supplied function.

void	free_reconnection_strategy (RECONNECTION_STRATEGY_T *strategy)
	Frees memory associated with a reconnection strategy.

void	reconnection_strategy_set_timeout (RECONNECTION_STRATEGY_T *strategy, long timeout)
	Explicitly requests the length of time that a session is available on the server in the event that this client is disconnected.

SESSION_T *	session_create (const char url_str, const char principal, CREDENTIALS_T credentials, SESSION_LISTENER_T listener, RECONNECTION_STRATEGY_T reconnection_strategy, DIFFUSION_ERROR_T error)
	Create a new session and synchronously open a connection to the Diffusion server at the endpoint specified by the URL.

SESSION_T *	session_create_with_user_context (const char url_str, const char principal, CREDENTIALS_T credentials, SESSION_LISTENER_T listener, RECONNECTION_STRATEGY_T reconnection_strategy, void user_context, DIFFUSION_ERROR_T *error)
	Create a new session and synchronously open a connection to the Diffusion server at the endpoint specified by the URL.

SESSION_T *	session_create_with_session_factory (const DIFFUSION_SESSION_FACTORY_T session_factory, const char url_str)
	Create a new session and synchronously open a connection to the Diffusion server with a `DIFFUSION_SESSION_FACTORY_T`.

SESSION_T *	session_create_async (const char url_str, const char principal, CREDENTIALS_T credentials, SESSION_LISTENER_T listener, RECONNECTION_STRATEGY_T reconnection_strategy, SESSION_CREATE_CALLBACK_T callbacks, DIFFUSION_ERROR_T *error)
	Create a new session, but do not wait for the connection handshake to be performed.

SESSION_T *	session_create_async_with_user_context (const char url_str, const char principal, CREDENTIALS_T credentials, SESSION_LISTENER_T listener, RECONNECTION_STRATEGY_T reconnection_strategy, SESSION_CREATE_CALLBACK_T callbacks, void user_context, DIFFUSION_ERROR_T error)
	Create a new session, but do not wait for the connection handshake to be performed.

SESSION_T *	session_create_async_with_session_factory (const DIFFUSION_SESSION_FACTORY_T session_factory, SESSION_CREATE_CALLBACK_T callbacks, const char *url_str)
	Create a new session and asynchronously open a connection to the Diffusion server with a `DIFFUSION_SESSION_FACTORY_T`.

void	session_free (SESSION_T *session)
	Free memory associated with a session.

int	session_close (SESSION_T session, DIFFUSION_ERROR_T error)
	Stop accepting messages from a Diffusion server and close the connection.

SESSION_STATE_T	session_state_get (SESSION_T *session)
	Returns the current session state.

CONNECTION_RESPONSE_CODE_T	session_connection_response_code (SESSION_T *session)
	Returns the last connection response code.

const char *	session_state_as_string (const SESSION_STATE_T state)
	Returns a human-readable representation of the session state.

int	session_is_connected (const SESSION_T *session)
	Determines if a session is connected to a server.

int	session_is_recovering (const SESSION_T *session)
	Determines if a session is in a recovering state, where it is trying to reconnect to a server.

int	session_is_closed (const SESSION_T *session)
	Determines if a session is closed.

char *	session_id_to_string (const SESSION_ID_T *session_id)
	Takes a session ID and produces a human-readable string.

SESSION_ID_T *	session_id_create_from_string (const char *str)
	Given a session id in string form, this function returns it to the internal structure form.

void	session_id_free (SESSION_ID_T *session_id)
	Free memory associated with a session ID structure.

int	session_id_cmp (const SESSION_ID_T s1, const SESSION_ID_T s2)
	Compare two session IDs.

TOPIC_HANDLER_T	set_global_topic_handler (SESSION_T *session, const TOPIC_HANDLER_T handler)
	Sets the handler for topics received but not subscribed to.

Detailed Description

Function Documentation

◆ free_reconnection_strategy()

void free_reconnection_strategy ( RECONNECTION_STRATEGY_T * strategy )

Frees memory associated with a reconnection strategy.

If a user-defined reconnection strategy is being used, then it is the user's responsibility to free memory associated with the args parameter passed to make_reconnection_strategy_user_function().

Parameters

strategy The reconnection strategy to be freed. MUST NOT be NULL.

◆ make_reconnection_strategy_repeating_attempt()

RECONNECTION_STRATEGY_T * make_reconnection_strategy_repeating_attempt	(	long	retry_count,
		long	retry_delay
	)

Creates a reconnection strategy that will retry a connection for a given number of times, with a delay between retry attempts.

free_reconnection_strategy should be called on the pointer when no longer needed.

A retry_count of 0 means that no reconnection attempts will be made.

A retry_delay greater than 0 and a retry_delay of 0 will retry for a set amount of time (DIFFUSION_DEFAULT_RECONNECT_TIMEOUT) before giving up.

Otherwise, retries will continue for (retry_count * retry_delay) seconds unless explicitly overridden with reconnection_strategy_set_timeout().

Parameters

retry_count	The number of attempts to make.
retry_delay	The time between connection attempts, in milliseconds, or 0 to request the system default timeout.

Return values

RECONNECTION_STRATEGY_T * A pointer to a new reconnection strategy that can be passed to a session creation function.

◆ make_reconnection_strategy_user_function()

RECONNECTION_STRATEGY_T * make_reconnection_strategy_user_function	(	PERFORM_RECONNECTION_CB	reconnect_cb,
		void *	args,
		PERFORM_RECONNECTION_AFTER_ACTION_CB	success_cb,
		PERFORM_RECONNECTION_AFTER_ACTION_CB	failure_cb
	)

Create a new reconnection strategy whose behavior is determined by a user-supplied function.

free_reconnection_strategy should be called on the pointer when no longer needed.

Parameters

reconnect_cb	A function to be called that will return RECONNECTION_ATTEMPT_ACTION_START when a reconnection should be tried, else RECONNECTION_ATTEMPT_ACTION_ABORT.
args	Pointer to user-defined data that can be used by the reconnection strategy callbacks. This data is not freed by free_reconnection_strategy(), nor is it copied during session_create() or session_create_async().
success_cb	If not NULL, a function to be invoked on successful reconnection.
failure_cb	If not NULL, a function to be invoked if the reconnection fails.

Return values

RECONNECTION_STRATEGY_T * A pointer to a new reconnection strategy that can then be passed to a session creation function.

◆ reconnection_strategy_set_timeout()

void reconnection_strategy_set_timeout	(	RECONNECTION_STRATEGY_T *	strategy,
		long	timeout
	)

Explicitly requests the length of time that a session is available on the server in the event that this client is disconnected.

A reconnection timeout of 0 means that no reconnection attempt will be made to the same server.

This is only effective when the session is created. If the timeout is changed after session_create() is called, there is no effect.

Parameters

strategy	The reconnection strategy for this client session. MUST NOT be NULL.
timeout	After this timeout (in milliseconds) has elapsed, no further reconnection attempts will be made for this URL.

◆ session_close()

int session_close	(	SESSION_T *	session,
		DIFFUSION_ERROR_T *	error
	)

Stop accepting messages from a Diffusion server and close the connection.

Parameters

session	The session handle. If NULL, an error is returned.
error	A structure for storing error messages, or NULL if detailed error reporting is not required.

Return values

int	0 on error
int	1 on success

◆ session_connection_response_code()

CONNECTION_RESPONSE_CODE_T session_connection_response_code ( SESSION_T * session )

Returns the last connection response code.

Parameters

session The session handle. May not be NULL.

Return values

CONNECTION_RESPONSE_CODE_T The last connection response code.

◆ session_create()

SESSION_T * session_create	(	const char *	url_str,
		const char *	principal,
		CREDENTIALS_T *	credentials,
		SESSION_LISTENER_T *	listener,
		RECONNECTION_STRATEGY_T *	reconnection_strategy,
		DIFFUSION_ERROR_T *	error
	)

Create a new session and synchronously open a connection to the Diffusion server at the endpoint specified by the URL.

Note: This call retains a reference to the memory allocated for the credentials and it is the callers' responsibility to ensure that this memory is not freed or overwritten for the lifetime of the session structure.; The error structure contains the result of the session creation attempt and will not be overwritten if the session is subsequently reconnected or fails over. Once session_create() returns, it is safe to release any memory owned by the error structure.

Parameters

url_str	A URL describing the endpoint to connect to.
principal	Typically, the username of the connecting user or application. NULL indicates that the principal will not be passed on connection.
credentials	The credentials associated with the principal, or NULL. MUST be available for the duration of the session.
listener	A pointer to a `SESSION_LISTENER_T` structure containing callbacks to be called on session-specific events.
reconnection_strategy	How to handle reconnection situations when the server is initially unavailable. If NULL, a default strategy is provided that attempts to connect every 5 seconds for up to 1 minute.
error	A pointer to an error structure, initialized to zero, which is populated in case of error, or NULL if not required.

Return values

SESSION_T *	A pointer to a session handle.
NULL	If the session could not be created.

◆ session_create_async()

SESSION_T * session_create_async	(	const char *	url_str,
		const char *	principal,
		CREDENTIALS_T *	credentials,
		SESSION_LISTENER_T *	listener,
		RECONNECTION_STRATEGY_T *	reconnection_strategy,
		SESSION_CREATE_CALLBACK_T *	callbacks,
		DIFFUSION_ERROR_T *	error
	)

Create a new session, but do not wait for the connection handshake to be performed.

Note: This call retains a reference to the memory allocated for the credentials, and it is the callers' responsibility to ensure that this memory is not freed or overwritten for the lifetime of the session structure.; The error structure contains the result of the session creation attempt and will not be overwritten if the session is subsequently reconnected or fails over. Since session_create_async() returns immediately, you must ensure the memory that this parameter points to is available until the session has been created, or the creation has failed. It is highly recommended that the error callback (see the callbacks parameter) is used instead, and NULL passed here.

Parameters

url_str	A URL describing the endpoint to connect to.
principal	Typically, the username of the connecting user or application. NULL indicates that the principal will not be passed on connection.
credentials	The credentials associated with the principal, or NULL. MUST be available for the duration of the session.
listener	A pointer to a SESSION_LISTENER_T structure containing callbacks to be called on session-specific events.
reconnection_strategy	How to handle reconnection situations when the server is initially unavailable. If NULL, a default strategy is provided that attempts to connect every 5 seconds for up to 1 minute.
callbacks	A pointer to a structure containing callbacks for successful connection or error reporting.
error	A pointer to an error structure to be asynchronously populated if an error occurs while the session is established, or NULL if not required. MUST be available for the duration of the session.

Return values

SESSION_T * A pointer to a session handle that should be closed and freed on exit. The session is not open when returned and you should use the on_connected callback to obtain a valid session. This handle is merely provided for proper cleanup.

◆ session_create_async_with_session_factory()

SESSION_T * session_create_async_with_session_factory	(	const DIFFUSION_SESSION_FACTORY_T *	session_factory,
		SESSION_CREATE_CALLBACK_T *	callbacks,
		const char *	url_str
	)

Create a new session and asynchronously open a connection to the Diffusion server with a DIFFUSION_SESSION_FACTORY_T.

Parameters

session_factory	The session factory to initiate the session from
callbacks	A pointer to a structure containing callbacks for successful connection or error reporting.
url_str	A URL describing the endpoint to connect to. This can be NULL if the supplied `session_factory` sufficiently describes the end point to connect to with `diffusion_session_factory_server_host`, `diffusion_session_factory_server_port` and `diffusion_session_factory_secure_transport`

Return values

SESSION_T *	A pointer to a session handle.
NULL	If the session could not be created.

◆ session_create_async_with_user_context()

SESSION_T * session_create_async_with_user_context	(	const char *	url_str,
		const char *	principal,
		CREDENTIALS_T *	credentials,
		SESSION_LISTENER_T *	listener,
		RECONNECTION_STRATEGY_T *	reconnection_strategy,
		SESSION_CREATE_CALLBACK_T *	callbacks,
		void *	user_context,
		DIFFUSION_ERROR_T *	error
	)

Create a new session, but do not wait for the connection handshake to be performed.

Note: This call retains a reference to the memory allocated for the credentials, and it is the callers' responsibility to ensure that this memory is not freed or overwritten for the lifetime of the session structure.; The error structure contains the result of the session creation attempt and will not be overwritten if the session is subsequently reconnected or fails over. Since session_create_async() returns immediately, you must ensure the memory that this parameter points to is available until the session has been created, or the creation has failed. It is highly recommended that the error callback (see the callbacks parameter) is used instead, and NULL passed here.

Parameters

url_str	A URL describing the endpoint to connect to.
principal	Typically, the username of the connecting user or application. NULL indicates that the principal will not be passed on connection.
credentials	The credentials associated with the principal, or NULL. MUST be available for the duration of the session.
listener	A pointer to a SESSION_LISTENER_T structure containing callbacks to be called on session-specific events.
reconnection_strategy	How to handle reconnection situations when the server is initially unavailable. If NULL, a default strategy is provided that attempts to connect every 5 seconds for up to 1 minute.
callbacks	A pointer to a structure containing callbacks for successful connection or error reporting.
user_context	User-supplied context for this session. It is the user's responsibility to free any memory that this points to when the session is no longer required.
error	A pointer to an error structure to be asynchronously populated if an error occurs while the session is established, or NULL if not required. MUST be available for the duration of the session.

Return values

SESSION_T * A pointer to a session handle that should be closed and freed on exit. The session is not open when returned and you should use the on_connected callback to obtain a valid session. This handle is merely provided for proper cleanup.

◆ session_create_with_session_factory()

SESSION_T * session_create_with_session_factory	(	const DIFFUSION_SESSION_FACTORY_T *	session_factory,
		const char *	url_str
	)

Create a new session and synchronously open a connection to the Diffusion server with a DIFFUSION_SESSION_FACTORY_T.

Parameters

session_factory	The session factory to initiate the session from
url_str	A URL describing the endpoint to connect to. This can be NULL if the supplied `session_factory` sufficiently describes the end point to connect to with `diffusion_session_factory_server_host`, `diffusion_session_factory_server_port` and `diffusion_session_factory_secure_transport`

Return values

SESSION_T *	A pointer to a session handle.
NULL	If the session could not be created.

◆ session_create_with_user_context()

SESSION_T * session_create_with_user_context	(	const char *	url_str,
		const char *	principal,
		CREDENTIALS_T *	credentials,
		SESSION_LISTENER_T *	listener,
		RECONNECTION_STRATEGY_T *	reconnection_strategy,
		void *	user_context,
		DIFFUSION_ERROR_T *	error
	)

Create a new session and synchronously open a connection to the Diffusion server at the endpoint specified by the URL.

Note: This call retains a reference to the memory allocated for the credentials and it is the callers' responsibility to ensure that this memory is not freed or overwritten for the lifetime of the session structure.; The error structure contains the result of the session creation attempt and will not be overwritten if the session is subsequently reconnected or fails over. Once session_create() returns, it is safe to release any memory owned by the error structure.

Parameters

url_str	A URL describing the endpoint to connect to.
principal	Typically, the username of the connecting user or application. NULL indicates that the principal will not be passed on connection.
credentials	The credentials associated with the principal, or NULL. MUST be available for the duration of the session.
listener	A pointer to a `SESSION_LISTENER_T` structure containing callbacks to be called on session-specific events.
reconnection_strategy	How to handle reconnection situations when the server is initially unavailable. If NULL, a default strategy is provided that attempts to connect every 5 seconds for up to 1 minute.
user_context	User-supplied context for this session. It is the user's responsibility to free any memory that this points to when the session is no longer required.
error	A pointer to an error structure, initialized to zero, which is populated in case of error, or NULL if not required.

Return values

SESSION_T *	A pointer to a session handle.
NULL	If the session could not be created.

◆ session_free()

void session_free ( SESSION_T * session )

Free memory associated with a session.

The session must be closed with session_close() prior to calling this function. If session is NULL, the function returns immediately.

Parameters

session The session to be freed.

◆ session_id_cmp()

int session_id_cmp	(	const SESSION_ID_T	s1,
		const SESSION_ID_T	s2
	)

Compare two session IDs.

Parameters

s1	The first session ID to compare.
s2	The second session ID to compare.

Return values

0	if the session IDs are equal.
1	if only their server instances are equal.
-1	otherwise.

◆ session_id_create_from_string()

SESSION_ID_T * session_id_create_from_string ( const char * str )

Given a session id in string form, this function returns it to the internal structure form.

Parameters

str	The session id as a string. If NULL, this function returns NULL.

Return values

SESSION_ID_T *	A populated session id structure.
NULL	If an error occurs.

◆ session_id_free()

void session_id_free ( SESSION_ID_T * session_id )

Free memory associated with a session ID structure.

Parameters

session_id The session id structure. If NULL, this function has no effect.

◆ session_id_to_string()

char * session_id_to_string ( const SESSION_ID_T * session_id )

Takes a session ID and produces a human-readable string.

It is the responsibility of the caller to free the memory allocated for the returned string.

Parameters

session_id A SESSION_ID_T. If the session ID is NULL, this function returns NULL.

Return values

char *	A string containing a textual representation of the session id.
NULL	If an error occurs.

◆ session_is_closed()

int session_is_closed ( const SESSION_T * session )

Determines if a session is closed.

Parameters

session A session handle. A NULL value returns DIFFUSION_TRUE.

Return values

DIFFUSION_TRUE	If the session is closed.
DIFFUSION_FALSE	If the session is not closed.

◆ session_is_connected()

int session_is_connected ( const SESSION_T * session )

Determines if a session is connected to a server.

Parameters

session A session handle. A NULL value returns DIFFUSION_FALSE.

Return values

DIFFUSION_TRUE	If the session is connected.
DIFFUSION_FALSE	If the session is not connected.

◆ session_is_recovering()

int session_is_recovering ( const SESSION_T * session )

Determines if a session is in a recovering state, where it is trying to reconnect to a server.

Parameters

session A session handle. A NULL value returns DIFFUSION_FALSE.

Return values

DIFFUSION_TRUE	If the session is recovering.
DIFFUSION_FALSE	If the session is not recovering.

◆ session_state_as_string()

const char * session_state_as_string ( const SESSION_STATE_T state )

Returns a human-readable representation of the session state.

Parameters

state A session state value.

Returns: A textual representation of the session state.

◆ session_state_get()

SESSION_STATE_T session_state_get ( SESSION_T * session )

Returns the current session state.

Parameters

session The session handle. If NULL, SESSION_STATE_UNKNOWN is returned.

Return values

SESSION_STATE_T The session state, or SESSION_STATE_UNKNOWN if session is NULL.

◆ set_global_topic_handler()

TOPIC_HANDLER_T set_global_topic_handler	(	SESSION_T *	session,
		const TOPIC_HANDLER_T	handler
	)

Sets the handler for topics received but not subscribed to.

If a topic message is received that does not have a registered handler, it is passed to the global topic handler. This function allows you to override the default handler (which does nothing).

Parameters

session	The session handle. MUST NOT be NULL.
handler	Pointer to a function which will receive the unhandled messages, or NULL to reset to the default handler.

Return values

The	previous topic handler.

Functions

Detailed Description

Function Documentation

◆ free_reconnection_strategy()

◆ make_reconnection_strategy_repeating_attempt()

◆ make_reconnection_strategy_user_function()

◆ reconnection_strategy_set_timeout()

◆ session_close()

◆ session_connection_response_code()

◆ session_create()

◆ session_create_async()

◆ session_create_async_with_session_factory()

◆ session_create_async_with_user_context()

◆ session_create_with_session_factory()

◆ session_create_with_user_context()

◆ session_free()

◆ session_id_cmp()

◆ session_id_create_from_string()

◆ session_id_free()

◆ session_id_to_string()

◆ session_is_closed()

◆ session_is_connected()

◆ session_is_recovering()

◆ session_state_as_string()

◆ session_state_get()

◆ set_global_topic_handler()