DbEnv::repmgr_set_socket()

#include <db_cxx.h>
 
int
DbEnv::repmgr_set_socket(int (*approval_func)(DB_ENV *dbenv,
    DB_REPMGR_SOCKET socket, int *result, u_int32_t flags));

The DbEnv::repmgr_set_socket() method specifies a socket callback. The socket callback enables an application to exert additional control over the connections used by Replication Manager.

Replication Manager creates IPv6 connections whenever possible but also supports IPv4. In cases where there are multiple addresses defined for a site, Replication Manager attempts connections first on any IPv6 addresses and then on any IPv4 addresses until one succeeds. Replication Manager relies on platform configuration settings and defaults to govern the use of IPv4-mapped IPv6 addresses in cases where one site is using IPv6 and the other site is using IPv4.

If your application requires more precise control over connections, you can use this method to provide a socket callback. The socket callback provides access to each socket before it is used in a connection attempt and provides the ability to accept or reject the socket. Within the socket callback's approval_func, you can test socket properties such as address characteristics (e.g. whether it is IPv6 or IPv4) and socket options. You can optionally change the IPV6_V6ONLY socket option to enable or disable use of IPv4-mapped IPv6 addresses. If the socket callback rejects a socket or if a connection attempt does not succeed, Replication Manager tries any other addresses defined for the site.

The only supported change to the socket in this callback is the IPV6_V6ONLY socket option. Any other changes may adversely affect the operation of Replication Manager's TCP/IP communications infrastructure.

The DbEnv::repmgr_set_socket() method configures operations performed using the specified DbEnv handle, not all operations performed on the underlying database environment.

The DbEnv::repmgr_set_socket() method either returns a non-zero error value or throws an exception that encapsulates a non-zero error value on failure, and returns 0 on success.

Note

Berkeley DB is not re-entrant. The callback function for this method should not attempt to make library calls (for example, to release locks or close open handles). Re-entering Berkeley DB is not guaranteed to work correctly, and the results are undefined.

Parameters

approval_func

The approval_func callback function determines whether a particular socket should be used in a connection attempt to a site. The parameters to approval_func are as follows:

  • dbenv

    The dbenv parameter is the enclosing database environment handle.

  • socket

    The socket parameter is the socket that is about to be used in a connection attempt to a site.

  • result

    The result parameter is an output parameter indicating whether to use this socket. Set it to 0 to reject this socket or to a non-zero value to accept this socket.

  • flags

    The flags parameter is currently unused.

The approval function must return 0 on success and non-zero on failure. If the approval function fails, the environment will panic.

Errors

The DbEnv::repmgr_set_socket() method may fail and throw a DbException exception, encapsulating one of the following non-zero errors, or return one of the following non-zero errors:

EINVAL

If this method is called from a base replication API application; or if an invalid flag value or parameter was specified.

Class

DbEnv

See Also

Replication and Related Methods