Diffusion C API 6.12.0
Loading...
Searching...
No Matches
Management of Remote Servers.
Public API functions.

Typedefs

typedef struct DIFFUSION_REMOTE_SERVER_T DIFFUSION_REMOTE_SERVER_T
 Opaque remote server struct.
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.
typedef int(* on_remote_server_removed_cb) (void *context)
 Callback when a remote server removal attempt has been made.
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.
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.

Functions

DIFFUSION_REMOTE_SERVER_TYPE_T diffusion_remote_server_get_type (DIFFUSION_REMOTE_SERVER_T *remote_server)
 Returns the remote server type.
char * diffusion_remote_server_get_name (DIFFUSION_REMOTE_SERVER_T *remote_server)
 Returns the remote server name.
LIST_T * diffusion_remote_server_get_urls (DIFFUSION_REMOTE_SERVER_T *remote_server)
 Returns the urls for connection to secondary servers.
char * diffusion_remote_server_get_connector (DIFFUSION_REMOTE_SERVER_T *remote_server)
 Returns the connector that the primary initiator will use to establish a connection between the secondary server and the primary server.
int diffusion_remote_server_get_retry_delay (DIFFUSION_REMOTE_SERVER_T *remote_server)
 Returns the interval in milliseconds between connection retries.
char * diffusion_remote_server_get_url (DIFFUSION_REMOTE_SERVER_T *remote_server)
 Returns the url for connection to primary server.
char * diffusion_remote_server_get_principal (DIFFUSION_REMOTE_SERVER_T *remote_server)
 Returns the principal used for the remote server connection.
CREDENTIALS_T * diffusion_remote_server_get_credentials (DIFFUSION_REMOTE_SERVER_T *remote_server)
 Returns the credentials to use to authenticate the connection.
HASH_NUM_T * diffusion_remote_server_get_connection_options (DIFFUSION_REMOTE_SERVER_T *remote_server)
 Returns the remote server connection options.
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.
char * diffusion_remote_get_primary_host_name (DIFFUSION_REMOTE_SERVER_T *remote_server)
 Returns the primary server host name used in SSL validation.
void diffusion_remote_server_free (DIFFUSION_REMOTE_SERVER_T *remote_server)
 Free a remote server.
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.
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.
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.
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.
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.
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.

Detailed Description

Typedef Documentation

◆ DIFFUSION_REMOTE_SERVER_T

typedef struct DIFFUSION_REMOTE_SERVER_T DIFFUSION_REMOTE_SERVER_T

Opaque remote server struct.

Since
6.7

◆ on_remote_server_checked_cb

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.

◆ on_remote_server_created_cb

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 occurred. 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 encountered during the attempted creation of the remote server
contextUser supplied context.
Returns
HANDLER_SUCCESS or HANDLER_FAILURE.

◆ on_remote_server_removed_cb

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.

◆ on_remote_servers_listed_cb

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.

Function Documentation

◆ diffusion_check_remote_server()

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_check_remote_server_response_get_failure_message()

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_check_remote_server_response_get_state()

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

◆ diffusion_create_remote_server()

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.

◆ diffusion_list_remote_servers()

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_get_primary_host_name()

char * diffusion_remote_get_primary_host_name ( DIFFUSION_REMOTE_SERVER_T * remote_server)

Returns the primary server host name used in SSL validation.

This method is only applicable to DIFFUSION_REMOTE_SERVER_TYPE_SECONDARY_ACCEPTOR, and will return NULL otherwise.

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

Parameters
remote_serverthe secondary acceptor remote server.
Returns
the primary server host name.
Since
6.10

◆ diffusion_remote_server_free()

void diffusion_remote_server_free ( DIFFUSION_REMOTE_SERVER_T * remote_server)

Free a remote server.

Parameters
remote_serverthe remote server.
Since
6.7

◆ diffusion_remote_server_get_connection_options()

HASH_NUM_T * diffusion_remote_server_get_connection_options ( DIFFUSION_REMOTE_SERVER_T * remote_server)

Returns the remote server connection options.

This method is only applicable to DIFFUSION_REMOTE_SERVER_TYPE_SECONDARY_INITIATOR or DIFFUSION_REMOTE_SERVER_TYPE_SECONDARY_ACCEPTOR, and will return NULL otherwise.

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

◆ diffusion_remote_server_get_connector()

char * diffusion_remote_server_get_connector ( DIFFUSION_REMOTE_SERVER_T * remote_server)

Returns the connector that the primary initiator will use to establish a connection between the secondary server and the primary server.

This method is only applicable to DIFFUSION_REMOTE_SERVER_TYPE_PRIMARY_INITIATOR, and will return NULL otherwise.

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

Parameters
remote_serverthe primary initiator remote server.
Returns
the connector name.
Since
6.10

◆ diffusion_remote_server_get_credentials()

CREDENTIALS_T * diffusion_remote_server_get_credentials ( DIFFUSION_REMOTE_SERVER_T * remote_server)

Returns the credentials to use to authenticate the connection.

This method is only applicable to DIFFUSION_REMOTE_SERVER_TYPE_SECONDARY_INITIATOR or DIFFUSION_REMOTE_SERVER_TYPE_SECONDARY_ACCEPTOR, and will return NULL otherwise.

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

Parameters
remote_serverthe remote server.
Returns
the credentials to use.
Since
6.10

◆ diffusion_remote_server_get_missing_topic_notification_filter()

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.

This method is only applicable to DIFFUSION_REMOTE_SERVER_TYPE_SECONDARY_INITIATOR or DIFFUSION_REMOTE_SERVER_TYPE_SECONDARY_ACCEPTOR, and will return NULL otherwise.

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

◆ diffusion_remote_server_get_name()

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

◆ diffusion_remote_server_get_principal()

char * diffusion_remote_server_get_principal ( DIFFUSION_REMOTE_SERVER_T * remote_server)

Returns the principal used for the remote server connection.

This method is only applicable to DIFFUSION_REMOTE_SERVER_TYPE_SECONDARY_INITIATOR or DIFFUSION_REMOTE_SERVER_TYPE_SECONDARY_ACCEPTOR, and will return NULL otherwise.

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

◆ diffusion_remote_server_get_retry_delay()

int diffusion_remote_server_get_retry_delay ( DIFFUSION_REMOTE_SERVER_T * remote_server)

Returns the interval in milliseconds between connection retries.

This method is only applicable to DIFFUSION_REMOTE_SERVER_TYPE_PRIMARY_INITIATOR, and will return -1 otherwise.

If a primary initiator cannot connect to a secondary server, or loses the connection, this is the amount of time before it will try to connect again

Parameters
remote_serverthe primary initiator remote server.
Returns
the retry delay time in milliseconds.
Since
6.10

◆ diffusion_remote_server_get_type()

DIFFUSION_REMOTE_SERVER_TYPE_T diffusion_remote_server_get_type ( DIFFUSION_REMOTE_SERVER_T * remote_server)

Returns the remote server type.

Parameters
remote_serverthe remote server.
Returns
the type of remote server.
Since
6.10

◆ diffusion_remote_server_get_url()

char * diffusion_remote_server_get_url ( DIFFUSION_REMOTE_SERVER_T * remote_server)

Returns the url for connection to primary server.

This method is only applicable to DIFFUSION_REMOTE_SERVER_TYPE_SECONDARY_INITIATOR, and will return NULL otherwise.

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

◆ diffusion_remote_server_get_urls()

LIST_T * diffusion_remote_server_get_urls ( DIFFUSION_REMOTE_SERVER_T * remote_server)

Returns the urls for connection to secondary servers.

This method is only applicable to DIFFUSION_REMOTE_SERVER_TYPE_PRIMARY_INITIATOR, and will return NULL otherwise.

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

Parameters
remote_serverthe primary initiator remote server.
Returns
the list of urls for connection to secondary servers.
Since
6.10

◆ diffusion_remove_remote_server()

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.