Diffusion C API  6.6.0-preview.1
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
remote-servers.h File Reference

Remote Servers feature. More...

Data Structures

struct  diffusion_remote_server_s
 
struct  diffusion_create_remote_server_params_s
 
struct  diffusion_remove_remote_server_params_s
 
struct  diffusion_list_remote_servers_params_s
 
struct  diffusion_check_remote_server_params_s
 

Typedefs

typedef int(* on_remote_server_created_cb )(DIFFUSION_REMOTE_SERVER_T *remote_server, LIST_T *errors, void *context)
 Callback when a remote server creation attempt has been made. More...
 
typedef int(* on_remote_server_removed_cb )(void *context)
 Callback when a remote server removal attempt has been made. More...
 
typedef int(* on_remote_servers_listed_cb )(LIST_T *remote_servers, void *context)
 Callback when a response is received from the server, returning a list of remote servers. More...
 
typedef struct
DIFFUSION_CHECK_REMOTE_SERVER_RESPONSE_T 
DIFFUSION_CHECK_REMOTE_SERVER_RESPONSE_T
 Opaque check remote server response struct.
 
typedef int(* on_remote_server_checked_cb )(DIFFUSION_CHECK_REMOTE_SERVER_RESPONSE_T *response, void *context)
 Callback when a response is received from the server, returning the details of the remote server state. More...
 

Enumerations

enum  DIFFUSION_REMOTE_SERVER_CONNECTION_OPTION_T {
  DIFFUSION_REMOTE_SERVER_CONNECTION_OPTION_RECONNECTION_TIMEOUT, DIFFUSION_REMOTE_SERVER_CONNECTION_OPTION_RETRY_DELAY, DIFFUSION_REMOTE_SERVER_CONNECTION_OPTION_RECOVERY_BUFFER_SIZE, DIFFUSION_REMOTE_SERVER_CONNECTION_OPTION_INPUT_BUFFER_SIZE,
  DIFFUSION_REMOTE_SERVER_CONNECTION_OPTION_OUTPUT_BUFFER_SIZE, DIFFUSION_REMOTE_SERVER_CONNECTION_OPTION_MAXIMUM_QUEUE_SIZE, DIFFUSION_REMOTE_SERVER_CONNECTION_OPTION_CONNECTION_TIMEOUT, DIFFUSION_REMOTE_SERVER_CONNECTION_OPTION_WRITE_TIMEOUT
}
 
enum  DIFFUSION_REMOTE_SERVER_CONNECTION_STATE_T {
  DIFFUSION_REMOTE_SERVER_CONNECTION_STATE_INACTIVE, DIFFUSION_REMOTE_SERVER_CONNECTION_STATE_CONNECTED, DIFFUSION_REMOTE_SERVER_CONNECTION_STATE_RETRYING, DIFFUSION_REMOTE_SERVER_CONNECTION_STATE_FAILED,
  DIFFUSION_REMOTE_SERVER_CONNECTION_STATE_MISSING
}
 

Functions

bool diffusion_create_remote_server (SESSION_T *session, const DIFFUSION_CREATE_REMOTE_SERVER_PARAMS_T params, DIFFUSION_API_ERROR *api_error)
 Create a new remote server instance with default connection options. More...
 
bool diffusion_remove_remote_server (SESSION_T *session, const DIFFUSION_REMOVE_REMOTE_SERVER_PARAMS_T params, DIFFUSION_API_ERROR *api_error)
 Remove a named remote server if it exists. More...
 
bool diffusion_list_remote_servers (SESSION_T *session, const DIFFUSION_LIST_REMOTE_SERVERS_PARAMS_T params, DIFFUSION_API_ERROR *api_error)
 Lists all the remote servers that have been created. More...
 
DIFFUSION_REMOTE_SERVER_CONNECTION_STATE_T diffusion_check_remote_server_response_get_state (DIFFUSION_CHECK_REMOTE_SERVER_RESPONSE_T *response)
 Returns the state of the connection of the remote server. More...
 
bool diffusion_check_remote_server (SESSION_T *session, const DIFFUSION_CHECK_REMOTE_SERVER_PARAMS_T params, DIFFUSION_API_ERROR *api_error)
 Checks the current state of a named remote server. More...
 

Detailed Description

Remote Servers feature.

This feature allows a client session to manage remote servers.

A remote server provides the configuration to connect to a Diffusion server belonging to a different cluster. Each server in the local cluster will establish a session with each remote server.

Higher level components, such as remote topic views, can specify the use of such remote servers by name. The connecting and disconnecting is handled automatically by the server (or servers in the same cluster) where the remote servers are defined.

A component can specify a remote server by name even if it does not exist (has not yet been created) and when the remote server is created the connection will take place automatically.

If a remote server is removed and there are components that depend upon it, those components will be disabled.

An example of the use of remote servers is within remote topic views (those that indicate that their source topics are to be taken from a different server) where the name of such a server can be specified.

Remote Server persistence and replication

Remote server configurations created through this feature are replicated across a cluster and persisted to disk.

Access control

The following access control restrictions are applied:

  • To create, remove or check a remote server, a session needs the GLOBAL_PERMISSION_CONTROL_SERVER permission.
  • To list remote servers, a session needs the GLOBAL_PERMISSION_VIEW_SERVER permission.

Typedef Documentation

typedef int(* on_remote_server_checked_cb)(DIFFUSION_CHECK_REMOTE_SERVER_RESPONSE_T *response, void *context)

Callback when a response is received from the server, returning the details of the remote server state.

Parameters
responseThe response from the server
contextUser supplied context.
Returns
HANDLER_SUCCESS or HANDLER_FAILURE.
typedef int(* on_remote_server_created_cb)(DIFFUSION_REMOTE_SERVER_T *remote_server, LIST_T *errors, void *context)

Callback when a remote server creation attempt has been made.

If the remote server definition is nil, this could mean an error has occured. These may include:

  • RemoteServerAlreadyExists - if a remote server with the given name already exists
  • ClusterRepartition - if the cluster was repartitioning
  • SessionSecurity - if the calling session does not have GLOBAL_PERMISSION_CONTROL_SERVER permission
  • SessionClosed - if the session is closed
Parameters
remote_serverThe remote server created if no errors are returned
errorsErrors encounted during the attempted creation of the remote server
contextUser supplied context.
Returns
HANDLER_SUCCESS or HANDLER_FAILURE.
typedef int(* on_remote_server_removed_cb)(void *context)

Callback when a remote server removal attempt has been made.

Parameters
contextUser supplied context.
Returns
HANDLER_SUCCESS or HANDLER_FAILURE.
typedef int(* on_remote_servers_listed_cb)(LIST_T *remote_servers, void *context)

Callback when a response is received from the server, returning a list of remote servers.

Parameters
remote_serversThe list of remote servers
contextUser supplied context.
Returns
HANDLER_SUCCESS or HANDLER_FAILURE.

Enumeration Type Documentation

Enumerator
DIFFUSION_REMOTE_SERVER_CONNECTION_OPTION_RECONNECTION_TIMEOUT 

Specifies the reconnection timeout session attribute.

This is the total time in milliseconds that will be allowed to reconnect a failed connection to the remote server for reconnection to work, the remove server connector must have been configured to support reconnection

If a value is not specified DIFFUSION_DEFAULT_RECONNECTION_TIMEOUT is used.

DIFFUSION_REMOTE_SERVER_CONNECTION_OPTION_RETRY_DELAY 

Specifies the delay after losing a connection before attempting a reconnection.

The value is specified in milliseconds, Default 1000 (1 second)

DIFFUSION_REMOTE_SERVER_CONNECTION_OPTION_RECOVERY_BUFFER_SIZE 

Specifies the recovery buffer size session attribute.

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

The default value is 10,000 messages. If reconnect-timeout is 0 then this value is ignored.

DIFFUSION_REMOTE_SERVER_CONNECTION_OPTION_INPUT_BUFFER_SIZE 

Specifies the input buffer size session attribute.

This is the size of the input buffer to use for the connection with the remote server. It is used to receive messages from the remote server. This should be set to the same size as the output buffer used at the remote server.

If not specified, a default of 1024k is used.

DIFFUSION_REMOTE_SERVER_CONNECTION_OPTION_OUTPUT_BUFFER_SIZE 

Specifies the output buffer size session attribute.

This is the size of the output buffer to use for the connection with the remote server. It is used to send messages to the remote server. This should be set to the same size as the input buffer used by the remote server.

If not specified, a default of 1024k is used.

DIFFUSION_REMOTE_SERVER_CONNECTION_OPTION_MAXIMUM_QUEUE_SIZE 

Specifies the maximum queue size session attribute.

This is the maximum number of messages that can be queued to send to the remote server. If this number is exceeded, the connection will be closed. This must be sufficient to cater for messages that may be queued whilst disconnected (awaiting reconnect).

The default value is 10,000 messages.

DIFFUSION_REMOTE_SERVER_CONNECTION_OPTION_CONNECTION_TIMEOUT 

Specifies the connection timeout session attribute value (in milliseconds).

  If a value is not specified `DIFFUSION_DEFAULT_CONNECTION_TIMEOUT`

is used.

DIFFUSION_REMOTE_SERVER_CONNECTION_OPTION_WRITE_TIMEOUT 

Specifies the write timeout session attribute value (in milliseconds).

Enumerator
DIFFUSION_REMOTE_SERVER_CONNECTION_STATE_INACTIVE 

The connection is inactive.

This means that the remote server can successfully connect but a physical connection is not being maintained as there are no components that require the remote server.

If in an inactive or failed state, a test connection will have been tried to check that the connection can be made and the connection will then have been closed.

DIFFUSION_REMOTE_SERVER_CONNECTION_STATE_CONNECTED 

The remote server is connected and actively in use by components that require it.

DIFFUSION_REMOTE_SERVER_CONNECTION_STATE_RETRYING 

The connection has failed but a retry is scheduled.

In this case diffusion_check_remote_server_response_get_failure_message will provide details of the failure that resulted in a retry.

DIFFUSION_REMOTE_SERVER_CONNECTION_STATE_FAILED 

The connection failed to establish.

If the connection was in an inactive or failed state state, a test connection was tried and failed.

In this case diffusion_check_remote_server_response_get_failure_message will provide more detail.

DIFFUSION_REMOTE_SERVER_CONNECTION_STATE_MISSING 

The named remote server did not exist.

Function Documentation

bool diffusion_check_remote_server ( SESSION_T session,
const DIFFUSION_CHECK_REMOTE_SERVER_PARAMS_T  params,
DIFFUSION_API_ERROR api_error 
)

Checks the current state of a named remote server.

Parameters
sessionThe current session. If NULL, this function returns immediately.
paramsParameters defining the diffusion_check_remote_server request and callbacks.
api_errorPopulated 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_REMOTE_SERVER_CONNECTION_STATE_T diffusion_check_remote_server_response_get_state ( DIFFUSION_CHECK_REMOTE_SERVER_RESPONSE_T response)

Returns the state of the connection of the remote server.

Parameters
responsethe check remote server response
Returns
the check remote server response's state
bool diffusion_create_remote_server ( SESSION_T session,
const DIFFUSION_CREATE_REMOTE_SERVER_PARAMS_T  params,
DIFFUSION_API_ERROR api_error 
)

Create a new remote server instance with default connection options.

If a remote server with the same name already exists an error will be returned.

Parameters
sessionThe current session. If NULL, this function returns immediately.
paramsParameters defining the diffusion_create_remote_server request and callbacks.
api_errorPopulated 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.
bool diffusion_list_remote_servers ( SESSION_T session,
const DIFFUSION_LIST_REMOTE_SERVERS_PARAMS_T  params,
DIFFUSION_API_ERROR api_error 
)

Lists all the remote servers that have been created.

Parameters
sessionThe current session. If NULL, this function returns immediately.
paramsParameters defining the diffusion_list_remote_servers request and callbacks.
api_errorPopulated 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.
bool diffusion_remove_remote_server ( SESSION_T session,
const DIFFUSION_REMOVE_REMOTE_SERVER_PARAMS_T  params,
DIFFUSION_API_ERROR api_error 
)

Remove a named remote server if it exists.

If the named remote server does not exist the callback will return without an error

When a named remote server is removed, any components that specify it would be disabled.

Parameters
sessionThe current session. If NULL, this function returns immediately.
paramsParameters defining the diffusion_remove_remote_server request and callbacks.
api_errorPopulated 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.