#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.
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.
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.
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: