Diffusion C API  6.7.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_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 struct
DIFFUSION_REMOTE_SERVER_T 
DIFFUSION_REMOTE_SERVER_T
 Opaque remote server struct. More...
 
typedef struct
DIFFUSION_REMOTE_SERVER_BUILDER_T 
DIFFUSION_REMOTE_SERVER_BUILDER_T
 Opaque remote server builder struct. More...
 
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

char * diffusion_remote_server_get_name (DIFFUSION_REMOTE_SERVER_T *remote_server)
 Returns the remote server name. More...
 
char * diffusion_remote_server_get_url (DIFFUSION_REMOTE_SERVER_T *remote_server)
 Returns the url for connection to primary server. More...
 
char * diffusion_remote_server_get_principal (DIFFUSION_REMOTE_SERVER_T *remote_server)
 Returns the principal used for the remote server connection. More...
 
HASH_NUM_Tdiffusion_remote_server_get_connection_options (DIFFUSION_REMOTE_SERVER_T *remote_server)
 Returns the remote server connection options. More...
 
char * diffusion_remote_server_get_missing_topic_notification_filter (DIFFUSION_REMOTE_SERVER_T *remote_server)
 Return the missing topic notification filter expression or NULL if one has not been specified. More...
 
void diffusion_remote_server_free (DIFFUSION_REMOTE_SERVER_T *remote_server)
 Free a remote server. More...
 
DIFFUSION_REMOTE_SERVER_BUILDER_Tdiffusion_remote_server_builder_init ()
 Initialize a new remote server builder. More...
 
DIFFUSION_REMOTE_SERVER_BUILDER_Tdiffusion_remote_server_builder_reset (DIFFUSION_REMOTE_SERVER_BUILDER_T *builder)
 Reset the builder. More...
 
DIFFUSION_REMOTE_SERVER_BUILDER_Tdiffusion_remote_server_builder_principal (DIFFUSION_REMOTE_SERVER_BUILDER_T *builder, char *principal)
 Specifies the name of a principal used by the remote server to connect to the primary server. More...
 
DIFFUSION_REMOTE_SERVER_BUILDER_Tdiffusion_remote_server_builder_connection_option (DIFFUSION_REMOTE_SERVER_BUILDER_T *builder, DIFFUSION_REMOTE_SERVER_CONNECTION_OPTION_T option, char *value)
 Specifies a single connection option. More...
 
DIFFUSION_REMOTE_SERVER_BUILDER_Tdiffusion_remote_server_builder_connection_options (DIFFUSION_REMOTE_SERVER_BUILDER_T *builder, HASH_NUM_T *connection_options)
 Specifies a map of DIFFUSION_REMOTE_SERVER_CONNECTION_OPTION_T settings. More...
 
DIFFUSION_REMOTE_SERVER_BUILDER_Tdiffusion_remote_server_builder_credentials (DIFFUSION_REMOTE_SERVER_BUILDER_T *builder, CREDENTIALS_T *credentials)
 Specifies the credentials to use when connecting to the primary server. More...
 
DIFFUSION_REMOTE_SERVER_BUILDER_Tdiffusion_remote_server_builder_missing_topic_notification_filter (DIFFUSION_REMOTE_SERVER_BUILDER_T *builder, char *filter)
 Specifies a topic selector expression which will filter missing topic notifications propagated from secondary to primary server. More...
 
void diffusion_remote_server_builder_free (DIFFUSION_REMOTE_SERVER_BUILDER_T *builder)
 Free a remote server builder. More...
 
DIFFUSION_REMOTE_SERVER_Tdiffusion_remote_server_builder_create (DIFFUSION_REMOTE_SERVER_BUILDER_T *builder, char *name, char *url, DIFFUSION_API_ERROR *api_error)
 Creates a remote server struct using the current values known to this builder. More...
 
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...
 
char * diffusion_check_remote_server_response_get_failure_message (DIFFUSION_CHECK_REMOTE_SERVER_RESPONSE_T *response)
 Returns a memory allocated copy of the check remote server response failure message. 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

Opaque remote server builder struct.

Since
6.7

Opaque remote server struct.

Since
6.7
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.
char* diffusion_check_remote_server_response_get_failure_message ( DIFFUSION_CHECK_REMOTE_SERVER_RESPONSE_T response)

Returns a memory allocated copy of the check remote server response failure message.

   `free` should be called on this pointer when no longer needed.
Parameters
responsethe check remote server response
Returns
the check remote server response's failure message
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.
DIFFUSION_REMOTE_SERVER_BUILDER_T* diffusion_remote_server_builder_connection_option ( DIFFUSION_REMOTE_SERVER_BUILDER_T builder,
DIFFUSION_REMOTE_SERVER_CONNECTION_OPTION_T  option,
char *  value 
)

Specifies a single connection option.

This will add to the options currently specified to this builder, or will replace a value if it has already been specified.

Parameters
builderthe remote server builder.
optionthe connection option
valuethe connection option value or NULL to remove the option.
Returns
the remote server builder.
Since
6.7
DIFFUSION_REMOTE_SERVER_BUILDER_T* diffusion_remote_server_builder_connection_options ( DIFFUSION_REMOTE_SERVER_BUILDER_T builder,
HASH_NUM_T connection_options 
)

Specifies a map of DIFFUSION_REMOTE_SERVER_CONNECTION_OPTION_T settings.

This will replace any options currently set for this builder. Any options not supplied will take their default values. If no connection options are specified, either using this method or diffusion_remote_server_builder_connection_option then all options will take their default value.

Parameters
builderthe remote server builder.
connection_optionsmap of options.
Returns
the remote server builder.
Since
6.7
DIFFUSION_REMOTE_SERVER_T* diffusion_remote_server_builder_create ( DIFFUSION_REMOTE_SERVER_BUILDER_T builder,
char *  name,
char *  url,
DIFFUSION_API_ERROR api_error 
)

Creates a remote server struct using the current values known to this builder.

Parameters
builderthe remote server builder.
namethe name of the remote server.
urlthe URL to use to connect to the primary server.
errorpopulated on API error. Can be NULL.
Returns
a new remote server struct is the operation was successful, NULL otherwise. In this case, 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.
Since
6.7
DIFFUSION_REMOTE_SERVER_BUILDER_T* diffusion_remote_server_builder_credentials ( DIFFUSION_REMOTE_SERVER_BUILDER_T builder,
CREDENTIALS_T credentials 
)

Specifies the credentials to use when connecting to the primary server.

The default, if not specified, is NONE.

Parameters
builderthe remote server builder.
credentialsthe credentials to use.
Returns
the remote server builder.
Since
6.7
void diffusion_remote_server_builder_free ( DIFFUSION_REMOTE_SERVER_BUILDER_T builder)

Free a remote server builder.

Parameters
builderthe remote server builder.
Since
6.7
DIFFUSION_REMOTE_SERVER_BUILDER_T* diffusion_remote_server_builder_init ( )

Initialize a new remote server builder.

   <code>diffusion_remote_server_builder_free</code> should be called on this pointer
   when no longer needed.
Returns
the remote server builder.
Since
6.7
DIFFUSION_REMOTE_SERVER_BUILDER_T* diffusion_remote_server_builder_missing_topic_notification_filter ( DIFFUSION_REMOTE_SERVER_BUILDER_T builder,
char *  filter 
)

Specifies a topic selector expression which will filter missing topic notifications propagated from secondary to primary server.

Missing topic notifications are notified when a client subscribes using a topic selector that matches no existing topics. By specifying a missing topic selector filter, all notifications that match the filter on the secondary server will be propagated to the primary server.

A match occurs if the path prefix of the subscription selector matches the path prefix of the specified selector. If no filter is specified then no missing topic notifications will be propagated.

The special selector expressions *.* may be used to indicate that all missing topic notifications should be propagated.

Only the path prefix of the specified selector(s) is considered when matching, therefore any use of regular expressions would be ignored.

Parameters
builderthe remote server builder.
filtera topic selector expression specifying the filter to apply, or NULL to remove any existing filter.
Returns
the remote server builder.
Since
6.7
DIFFUSION_REMOTE_SERVER_BUILDER_T* diffusion_remote_server_builder_principal ( DIFFUSION_REMOTE_SERVER_BUILDER_T builder,
char *  principal 
)

Specifies the name of a principal used by the remote server to connect to the primary server.

The default, if not specified, is the anonymous principal.

Parameters
builderthe remote server builder.
principalpricipal name or a zero length string to indicate an anonymous connection.
Returns
the remote server builder.
Since
6.7
DIFFUSION_REMOTE_SERVER_BUILDER_T* diffusion_remote_server_builder_reset ( DIFFUSION_REMOTE_SERVER_BUILDER_T builder)

Reset the builder.

Parameters
builderthe remote server builder.
Returns
the remote server builder.
Since
6.7
void diffusion_remote_server_free ( DIFFUSION_REMOTE_SERVER_T remote_server)

Free a remote server.

Parameters
remote_serverthe remote server.
Since
6.7
HASH_NUM_T* diffusion_remote_server_get_connection_options ( DIFFUSION_REMOTE_SERVER_T remote_server)

Returns the remote server connection options.

hash_num_free should be called on this pointer when no longer needed.

Parameters
remote_serverthe remote server.
Returns
the remote server connection options.
Since
6.7
char* diffusion_remote_server_get_missing_topic_notification_filter ( DIFFUSION_REMOTE_SERVER_T remote_server)

Return the missing topic notification filter expression or NULL if one has not been specified.

free should be called on this pointer when no longer needed, if not NULL.

Parameters
remote_serverthe remote server.
Returns
the missing topic notification filter if specified, NULL otherwise.
Since
6.7
char* diffusion_remote_server_get_name ( DIFFUSION_REMOTE_SERVER_T remote_server)

Returns the remote server name.

free should be called on this pointer when no longer needed.

Parameters
remote_serverthe remote server.
Returns
the remote server name.
Since
6.7
char* diffusion_remote_server_get_principal ( DIFFUSION_REMOTE_SERVER_T remote_server)

Returns the principal used for the remote server connection.

free should be called on this pointer when no longer needed.

Parameters
remote_serverthe remote server.
Returns
the principal used for the remote server connection.
Since
6.7
char* diffusion_remote_server_get_url ( DIFFUSION_REMOTE_SERVER_T remote_server)

Returns the url for connection to primary server.

free should be called on this pointer when no longer needed.

Parameters
remote_serverthe remote server.
Returns
the url for connection to primary server.
Since
6.7
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.