Diffusion C API  6.10.2
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Session management.

Functions

RECONNECTION_STRATEGY_Tmake_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. More...
 
RECONNECTION_STRATEGY_Tmake_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. More...
 
void free_reconnection_strategy (RECONNECTION_STRATEGY_T *strategy)
 Frees memory associated with a reconnection strategy. More...
 
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. More...
 
SESSION_Tsession_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. More...
 
SESSION_Tsession_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. More...
 
SESSION_Tsession_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. More...
 
SESSION_Tsession_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. More...
 
SESSION_Tsession_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. More...
 
SESSION_Tsession_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. More...
 
void session_free (SESSION_T *session)
 Free memory associated with a session. More...
 
int session_close (SESSION_T *session, DIFFUSION_ERROR_T *error)
 Stop accepting messages from a Diffusion server and close the connection. More...
 
SESSION_STATE_T session_state_get (SESSION_T *session)
 Returns the current session state. More...
 
CONNECTION_RESPONSE_CODE_T session_connection_response_code (SESSION_T *session)
 Returns the last connection response code. More...
 
const char * session_state_as_string (const SESSION_STATE_T state)
 Returns a human-readable representation of the session state. More...
 
int session_is_connected (const SESSION_T *session)
 Determines if a session is connected to a server. More...
 
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. More...
 
int session_is_closed (const SESSION_T *session)
 Determines if a session is closed. More...
 
char * session_id_to_string (const SESSION_ID_T *session_id)
 Takes a session ID and produces a human-readable string. More...
 
SESSION_ID_Tsession_id_create_from_string (const char *str)
 Given a session id in string form, this function returns it to the internal structure form. More...
 
void session_id_free (SESSION_ID_T *session_id)
 Free memory associated with a session ID structure. More...
 
int session_id_cmp (const SESSION_ID_T s1, const SESSION_ID_T s2)
 Compare two session IDs. More...
 
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. More...
 

Detailed Description

Function Documentation

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
strategyThe reconnection strategy to be freed. MUST NOT be NULL.
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_countThe number of attempts to make.
retry_delayThe 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.
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_cbA function to be called that will return RECONNECTION_ATTEMPT_ACTION_START when a reconnection should be tried, else RECONNECTION_ATTEMPT_ACTION_ABORT.
argsPointer 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_cbIf not NULL, a function to be invoked on successful reconnection.
failure_cbIf 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.
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
strategyThe reconnection strategy for this client session. MUST NOT be NULL.
timeoutAfter this timeout (in milliseconds) has elapsed, no further reconnection attempts will be made for this URL.
int session_close ( SESSION_T session,
DIFFUSION_ERROR_T error 
)

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

Parameters
sessionThe session handle. If NULL, an error is returned.
errorA structure for storing error messages, or NULL if detailed error reporting is not required.
Return values
int0 on error
int1 on success
CONNECTION_RESPONSE_CODE_T session_connection_response_code ( SESSION_T session)

Returns the last connection response code.

Parameters
sessionThe session handle. May not be NULL.
Return values
CONNECTION_RESPONSE_CODE_TThe last connection response code.
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_strA URL describing the endpoint to connect to.
principalTypically, the username of the connecting user or application. NULL indicates that the principal will not be passed on connection.
credentialsThe credentials associated with the principal, or NULL. MUST be available for the duration of the session.
listenerA pointer to a SESSION_LISTENER_T structure containing callbacks to be called on session-specific events.
reconnection_strategyHow 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.
errorA 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.
NULLIf the session could not be created.
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_strA URL describing the endpoint to connect to.
principalTypically, the username of the connecting user or application. NULL indicates that the principal will not be passed on connection.
credentialsThe credentials associated with the principal, or NULL. MUST be available for the duration of the session.
listenerA pointer to a SESSION_LISTENER_T structure containing callbacks to be called on session-specific events.
reconnection_strategyHow 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.
callbacksA pointer to a structure containing callbacks for successful connection or error reporting.
errorA 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_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_factoryThe session factory to initiate the session from
callbacksA pointer to a structure containing callbacks for successful connection or error reporting.
url_strA 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.
NULLIf the session could not be created.
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_strA URL describing the endpoint to connect to.
principalTypically, the username of the connecting user or application. NULL indicates that the principal will not be passed on connection.
credentialsThe credentials associated with the principal, or NULL. MUST be available for the duration of the session.
listenerA pointer to a SESSION_LISTENER_T structure containing callbacks to be called on session-specific events.
reconnection_strategyHow 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.
callbacksA pointer to a structure containing callbacks for successful connection or error reporting.
user_contextUser-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.
errorA 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_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_factoryThe session factory to initiate the session from
url_strA 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.
NULLIf the session could not be created.
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_strA URL describing the endpoint to connect to.
principalTypically, the username of the connecting user or application. NULL indicates that the principal will not be passed on connection.
credentialsThe credentials associated with the principal, or NULL. MUST be available for the duration of the session.
listenerA pointer to a SESSION_LISTENER_T structure containing callbacks to be called on session-specific events.
reconnection_strategyHow 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_contextUser-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.
errorA 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.
NULLIf the session could not be created.
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
sessionThe session to be freed.
int session_id_cmp ( const SESSION_ID_T  s1,
const SESSION_ID_T  s2 
)

Compare two session IDs.

Parameters
s1The first session ID to compare.
s2The second session ID to compare.
Return values
0if the session IDs are equal.
1if only their server instances are equal.
-1otherwise.
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
strThe session id as a string. If NULL, this function returns NULL.
Return values
SESSION_ID_T *A populated session id structure.
NULLIf an error occurs.
void session_id_free ( SESSION_ID_T session_id)

Free memory associated with a session ID structure.

Parameters
session_idThe session id structure. If NULL, this function has no effect.
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_idA 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.
NULLIf an error occurs.
int session_is_closed ( const SESSION_T session)

Determines if a session is closed.

Parameters
sessionA session handle. A NULL value returns DIFFUSION_TRUE.
Return values
DIFFUSION_TRUEIf the session is closed.
DIFFUSION_FALSEIf the session is not closed.
int session_is_connected ( const SESSION_T session)

Determines if a session is connected to a server.

Parameters
sessionA session handle. A NULL value returns DIFFUSION_FALSE.
Return values
DIFFUSION_TRUEIf the session is connected.
DIFFUSION_FALSEIf the session is not connected.
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
sessionA session handle. A NULL value returns DIFFUSION_FALSE.
Return values
DIFFUSION_TRUEIf the session is recovering.
DIFFUSION_FALSEIf the session is not recovering.
const char* session_state_as_string ( const SESSION_STATE_T  state)

Returns a human-readable representation of the session state.

Parameters
stateA session state value.
Returns
A textual representation of the session state.
SESSION_STATE_T session_state_get ( SESSION_T session)

Returns the current session state.

Parameters
sessionThe session handle. If NULL, SESSION_STATE_UNKNOWN is returned.
Return values
SESSION_STATE_TThe session state, or SESSION_STATE_UNKNOWN if session is NULL.
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
sessionThe session handle. MUST NOT be NULL.
handlerPointer to a function which will receive the unhandled messages, or NULL to reset to the default handler.
Return values
Theprevious topic handler.