Diffusion C API  6.3.3
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
session-factory.h File Reference

Functions relating to a session and session management. More...

Typedefs

typedef struct
DIFFUSION_SESSION_FACTORY_T 
DIFFUSION_SESSION_FACTORY_T
 An opaque diffusion session factory struct.
 

Functions

DIFFUSION_SESSION_FACTORY_Tdiffusion_session_factory_init (void)
 Create a memory allocated DIFFUSION_SESSION_FACTORY_T More...
 
void diffusion_session_factory_session_listener (const DIFFUSION_SESSION_FACTORY_T *session_factory, SESSION_LISTENER_T *listener)
 Nominates a listener for session events from a session. More...
 
void diffusion_session_factory_principal (const DIFFUSION_SESSION_FACTORY_T *session_factory, const char *principal)
 Sets the security principal. More...
 
void diffusion_session_factory_no_credentials (const DIFFUSION_SESSION_FACTORY_T *session_factory)
 Set credentials to credentials_create_none() More...
 
void diffusion_session_factory_credentials (const DIFFUSION_SESSION_FACTORY_T *session_factory, const CREDENTIALS_T *credentials)
 Set credentials. More...
 
void diffusion_session_factory_password (const DIFFUSION_SESSION_FACTORY_T *session_factory, const char *password)
 Set credentials of type PLAIN_PASSWORD. More...
 
void diffusion_session_factory_custom_credentials (const DIFFUSION_SESSION_FACTORY_T *session_factory, const BUF_T *bytes)
 Set credentials of type CUSTOM. More...
 
void diffusion_session_factory_connection_timeout (const DIFFUSION_SESSION_FACTORY_T *session_factory, uint32_t connection_timeout)
 Sets the connection timeout. More...
 
void diffusion_session_factory_no_reconnection (const DIFFUSION_SESSION_FACTORY_T *session_factory)
 Disable reconnection. More...
 
void diffusion_session_factory_reconnection_timeout (const DIFFUSION_SESSION_FACTORY_T *session_factory, int reconnection_timeout)
 Sets the reconnection timeout. More...
 
void diffusion_session_factory_reconnection_strategy (const DIFFUSION_SESSION_FACTORY_T *session_factory, RECONNECTION_STRATEGY_T *reconnection_strategy)
 Sets the reconnection strategy. More...
 
void diffusion_session_factory_input_buffer_size (const DIFFUSION_SESSION_FACTORY_T *session_factory, uint32_t input_buffer_size)
 Sets the input buffer size for socket connection buffers and message receiving buffers. More...
 
void diffusion_session_factory_output_buffer_size (const DIFFUSION_SESSION_FACTORY_T *session_factory, uint32_t output_buffer_size)
 Sets the output buffer size for socket connection buffers and message sending buffers. More...
 
void diffusion_session_factory_write_timeout (const DIFFUSION_SESSION_FACTORY_T *session_factory, uint32_t write_timeout)
 Sets the write timeout value for blocking writes. More...
 
void diffusion_session_factory_maximum_message_size (const DIFFUSION_SESSION_FACTORY_T *session_factory, uint32_t maximum_message_size)
 Set the maximum message size. More...
 
void diffusion_session_factory_server_host (const DIFFUSION_SESSION_FACTORY_T *session_factory, const char *server_host)
 Set the host name of the server to connect the session to. More...
 
void diffusion_session_factory_server_port (const DIFFUSION_SESSION_FACTORY_T *session_factory, int server_port)
 Set the port of the server to connect the session to. More...
 
void diffusion_session_factory_secure_transport (const DIFFUSION_SESSION_FACTORY_T *session_factory, bool secure_transport)
 Set if a secure transport should be used. More...
 
void diffusion_session_factory_request_path (const DIFFUSION_SESSION_FACTORY_T *session_factory, const char *request_path)
 Set the path used for HTTP requests. More...
 
void diffusion_session_factory_recovery_buffer_size (const DIFFUSION_SESSION_FACTORY_T *session_factory, uint32_t recovery_buffer_size)
 Set the recovery buffer size. More...
 
void diffusion_session_factory_maximum_queue_size (const DIFFUSION_SESSION_FACTORY_T *session_factory, uint32_t maximum_queue_size)
 Sets the maximum size of the outbound message queue for the connection. More...
 
void diffusion_session_factory_property (const DIFFUSION_SESSION_FACTORY_T *session_factory, const char *key, const char *value)
 Sets a user-defined session property value. More...
 
void diffusion_session_factory_properties (const DIFFUSION_SESSION_FACTORY_T *session_factory, const HASH_T *properties)
 Sets user-defined session property values. More...
 
void diffusion_session_factory_free (DIFFUSION_SESSION_FACTORY_T *session_factory)
 Free a memory allocated DIFFUSION_SESSION_FACTORY_T More...
 

Detailed Description

Functions relating to a session and session management.

Function Documentation

void diffusion_session_factory_connection_timeout ( const DIFFUSION_SESSION_FACTORY_T session_factory,
uint32_t  connection_timeout 
)

Sets the connection timeout.

This constrains the time taken to establish an initial connection to the server. The write timeout} constrains the time to send the connection request. The server is responsible for limiting the overall time taken to complete a connection once it has received the request.

The default is DIFFUSION_DEFAULT_CONNECTION_TIMEOUT

Parameters
session_factorythe session factory to mutate. If NULL, this function is a no-op.
timeoutthe default connection timeout in milliseconds. If this exceeds one hour (3600000ms) a warning will be logged and the time-out will be set to one hour. If this value is 0, this function is a no-op.
void diffusion_session_factory_credentials ( const DIFFUSION_SESSION_FACTORY_T session_factory,
const CREDENTIALS_T credentials 
)

Set credentials.

The default is credentials_create_none

Parameters
session_factorythe session factory to mutate. If NULL, this function is a no-op.
credentialsthe credentials. If NULL, this function is a no-op.
void diffusion_session_factory_custom_credentials ( const DIFFUSION_SESSION_FACTORY_T session_factory,
const BUF_T bytes 
)

Set credentials of type CUSTOM.

The default is NONE.

Parameters
session_factorythe session factory to mutate. If NULL, this function is a no-op.
bytesthe credentials as bytes. If NULL, this function is a no-op.
void diffusion_session_factory_free ( DIFFUSION_SESSION_FACTORY_T session_factory)

Free a memory allocated DIFFUSION_SESSION_FACTORY_T

Parameters
session_factorythe session factory to be freed
DIFFUSION_SESSION_FACTORY_T* diffusion_session_factory_init ( void  )

Create a memory allocated DIFFUSION_SESSION_FACTORY_T

Returns
a diffusion session factory
void diffusion_session_factory_input_buffer_size ( const DIFFUSION_SESSION_FACTORY_T session_factory,
uint32_t  input_buffer_size 
)

Sets the input buffer size for socket connection buffers and message receiving buffers.

This controls both how much pending data the socket can accommodate and how much available data will be read by the input tasks. In general setting both this and diffusion_session_factory_output_buffer_size to the same reasonable size will result in higher network throughput. The cost of the receiving buffer is only incurred when actually reading data for processing. The cost of the socket buffer is always incurred and may be modified by the operating system.

The default is DIFFUSION_DEFAULT_INPUT_BUFFER_SIZE.

Parameters
session_factorythe session factory to mutate. If NULL, this function is a no-op.
sizeinput buffer size in bytes. This may not be less than DIFFUSION_MAXIMUM_MESSAGE_SIZE_MINIMUM, if so, this function is a no-op.
void diffusion_session_factory_maximum_message_size ( const DIFFUSION_SESSION_FACTORY_T session_factory,
uint32_t  maximum_message_size 
)

Set the maximum message size.

This constrains the size of messages that will be accepted from the server and thus the size of any content that can be received. The limit is simply to protect against unexpectedly large messages.

By default, the size of received messages is unconstrained – see DIFFUSION_DEFAULT_MAXIMUM_MESSAGE_SIZE.

Parameters
session_factorythe session factory to mutate. If NULL, this function is a no-op.
sizethe maximum message size in bytes. This must not be less than DIFFUSION_MAXIMUM_MESSAGE_SIZE_MINIMUM.
void diffusion_session_factory_maximum_queue_size ( const DIFFUSION_SESSION_FACTORY_T session_factory,
uint32_t  maximum_queue_size 
)

Sets the maximum size of the outbound message queue for the connection.

The outbound message queue should be large enough to accommodate all the messages sent to the server. This would include topic updates, messages sent using messaging, messaging-control and servicerequests such as registering a handler.

It may be necessary to increase this value for applications that send messages in bursts, or continue to send messages when a session is disconnected and reconnecting. Larger values allow more messages to be queued, and increase the memory footprint of the session.

If the outbound message queue fills, sending a message will cause the session to close with an error.

The default is DIFFUSION_DEFAULT_MAXIMUM_QUEUE_SIZE.

Parameters
session_factorythe session factory to mutate. If NULL, this function is a no-op.
sizea positive integer indicating the maximum number of messages that may be queued
void diffusion_session_factory_no_credentials ( const DIFFUSION_SESSION_FACTORY_T session_factory)

Set credentials to credentials_create_none()

This is the default.

Parameters
session_factorythe session factory to mutate. If NULL, this function is a no-op.
void diffusion_session_factory_no_reconnection ( const DIFFUSION_SESSION_FACTORY_T session_factory)

Disable reconnection.

Sessions will not attempt to reconnect in the event of unexpected connection loss.

This is equivalent to calling diffusion_session_factory_reconnection_timeout with a timeout of 0

Parameters
session_factorythe session factory to mutate. If NULL, this function is a no-op.
void diffusion_session_factory_output_buffer_size ( const DIFFUSION_SESSION_FACTORY_T session_factory,
uint32_t  output_buffer_size 
)

Sets the output buffer size for socket connection buffers and message sending buffers.

This controls both how much pending data the socket can accommodate and how much data will be batched by sending messages. In general setting both this and diffusion_session_factory_input_buffer_size to the same reasonable size will result in higher network throughput. The cost of the sending buffer is only incurred when actually queuing data for output. The cost of the socket buffer is always incurred and may be modified by the operating system.

The default is DIFFUSION_DEFAULT_OUTPUT_BUFFER_SIZE.

Parameters
session_factorythe session factory to mutate. If NULL, this function is a no-op.
sizeoutput buffer size in bytes. This may not be less than DIFFUSION_MAXIMUM_MESSAGE_SIZE_MINIMUM, if so, this function is a no-op.
void diffusion_session_factory_password ( const DIFFUSION_SESSION_FACTORY_T session_factory,
const char *  password 
)

Set credentials of type PLAIN_PASSWORD.

The default is NONE.

Parameters
session_factorythe session factory to mutate. If NULL, this function is a no-op.
passwordthe password. If NULL, this function is a no-op.
void diffusion_session_factory_principal ( const DIFFUSION_SESSION_FACTORY_T session_factory,
const char *  principal 
)

Sets the security principal.

By default this will be an anonymous principal.

Parameters
session_factorythe session factory to mutate. If NULL, this function is a no-op.
principalthe principal
void diffusion_session_factory_properties ( const DIFFUSION_SESSION_FACTORY_T session_factory,
const HASH_T properties 
)

Sets user-defined session property values.

Supplied session properties will be provided to the server when a session is created using this session factory. The supplied properties will be validated during authentication and may be discarded or changed.

The specified properties will be added to any existing properties set for this session factory. If any of the keys have been previously declared then they will be overwritten with the new values.

For details of how session properties are used see Session.

Parameters
session_factorythe session factory to mutate. If NULL, this function is a no-op.
propertiesa map of user-defined session properties
void diffusion_session_factory_property ( const DIFFUSION_SESSION_FACTORY_T session_factory,
const char *  key,
const char *  value 
)

Sets a user-defined session property value.

Supplied session properties will be provided to the server when a session is created using this session factory. The supplied properties will be validated during authentication and may be discarded or changed.

The specified property will be added to any existing properties set for this session factory.

For details of how session properties are used see Session.

Parameters
session_factorythe session factory to mutate. If NULL, this function is a no-op.
keythe property key
valuethe property value
void diffusion_session_factory_reconnection_strategy ( const DIFFUSION_SESSION_FACTORY_T session_factory,
RECONNECTION_STRATEGY_T reconnection_strategy 
)

Sets the reconnection strategy.

If reconnection is enabled, this strategy will be called in the event of an unexpected connection loss.

If the reconnection timeout has been set, but not a strategy, sessions will use a default strategy that attempts to reconnect on a regular basis of 5 seconds until the reconnection timeout is exceeded.

Parameters
session_factorythe session factory to mutate. If NULL, this function is a no-op.
strategythe reconnection strategy to use
void diffusion_session_factory_reconnection_timeout ( const DIFFUSION_SESSION_FACTORY_T session_factory,
int  reconnection_timeout 
)

Sets the reconnection timeout.

This determines the duration that sessions will attempt to reconnect for, in the event of unexpected connection loss.

The default is DIFFUSION_DEFAULT_RECONNECTION_TIMEOUT.

A timeout value of 0 or less is equivalent to to calling diffusion_session_factory_no_reconnection.

Parameters
session_factorythe session factory to mutate. If NULL, this function is a no-op.
timeoutthe timeout duration to use when attempting to reconnect, in milliseconds
void diffusion_session_factory_recovery_buffer_size ( const DIFFUSION_SESSION_FACTORY_T session_factory,
uint32_t  recovery_buffer_size 
)

Set the recovery buffer size.

If the server is configured to support reconnection, a session established with a non-zero reconnection time retains a buffer of sent messages. If the session disconnects and reconnects, this buffer is used to re-send messages that the server has not received.

The default is DIFFUSION_DEFAULT_RECOVERY_BUFFER_SIZE. Higher values increase the chance of successful reconnection, but increase the per-session memory footprint.

Parameters
session_factorythe session factory to mutate. If NULL, this function is a no-op.
recovery_buffer_sizethe recovery buffer size in messages; can be 0
void diffusion_session_factory_request_path ( const DIFFUSION_SESSION_FACTORY_T session_factory,
const char *  request_path 
)

Set the path used for HTTP requests.

This value is only used if a URL is not provided when opening a session. The path must start with a '/' and end with '/diffusion'.

The default is DIFFUSION_DEFAULT_REQUEST_PATH.

Parameters
session_factorythe session factory to mutate. If NULL, this function is a no-op.
request_paththe path used for HTTP requests
void diffusion_session_factory_secure_transport ( const DIFFUSION_SESSION_FACTORY_T session_factory,
bool  secure_transport 
)

Set if a secure transport should be used.

This value is only used if a URL is not provided when opening a session. Enables or disables the use of transport layer security.

Parameters
session_factorythe session factory to mutate. If NULL, this function is a no-op.
secure_transportif transport layer security is enabled
void diffusion_session_factory_server_host ( const DIFFUSION_SESSION_FACTORY_T session_factory,
const char *  server_host 
)

Set the host name of the server to connect the session to.

This value is only used if a URL is not provided when opening a session.

Parameters
session_factorythe session factory to mutate. If NULL, this function is a no-op.
server_hostthe host name of the server
void diffusion_session_factory_server_port ( const DIFFUSION_SESSION_FACTORY_T session_factory,
int  server_port 
)

Set the port of the server to connect the session to.

This value is only used if a URL is not provided when opening a session. If the port is not set using this method or a URL, the port will be inferred based on the transport and security configuration.

The provided value must be within the range used for port numbers.

Parameters
session_factorythe session factory to mutate. If NULL, this function is a no-op.
server_portthe port of the server
void diffusion_session_factory_session_listener ( const DIFFUSION_SESSION_FACTORY_T session_factory,
SESSION_LISTENER_T listener 
)

Nominates a listener for session events from a session.

If not specified, there will be no session listener.

Parameters
session_factorythe session factory to mutate. If NULL, this function is a no-op.
listenerspecifies a listener to be used for subsequent sessions that are created. NULL may be specified to remove any previously specified listener
void diffusion_session_factory_write_timeout ( const DIFFUSION_SESSION_FACTORY_T session_factory,
uint32_t  write_timeout 
)

Sets the write timeout value for blocking writes.

Blocking writes are only used for the initial connection request. If it is not possible to complete the write within this time, the connection is closed.

The default is DIFFUSION_DEFAULT_WRITE_TIMEOUT.

Parameters
session_factorythe session factory to mutate. If NULL, this function is a no-op.
timeoutthe write timeout in milliseconds. If this exceeds one hour (3600000ms) a warning will be logged and the time-out will be set to one hour. If this value is 0, this function is a no-op.