QuantumGate::Local::ConnectTo

Initiates a connection to a peer on the network. If there was an existing connection to that peer, that connection is re-used. When the connection is established, or when it fails, the optional ConnectCallback function gets called. When a successfully established connection breaks, the optional DisconnectCallback function gets called.

Signature

const std::pair<Result, std::optional<PeerLUID>> ConnectTo(const IPEndPoint& endpoint,
                                                 ConnectCallback&& connect_func = nullptr,
                                                 DisconnectCallback&& disconnect_func = nullptr) noexcept;

const std::pair<Result, std::optional<PeerLUID>> ConnectTo(const IPEndPoint& endpoint,
                                                 const UInt8 relay_hops,						  
                                                 const std::optional<PeerLUID>& via_peer = std::nullopt,
                                                 ConnectCallback&& connect_func = nullptr,
                                                 DisconnectCallback&& disconnect_func = nullptr) noexcept;

Parameters

Name	Description
endpoint	A QuantumGate::IPEndPoint object containing the endpoint to connect to. See QuantumGate::IPEndPoint for more details.
relay_hops	The number of hops to establish a relayed connection. See QuantumGate Relays for more details.
via_peer	Optionally the QuantumGate::PeerLUID of an existing connected peer through which to establish the relayed connection. If none is specified, QuantumGate will randomly choose an existing connection if available.
connect_func	A QuantumGate::ConnectCallback object containing the function to call when the connection was successful or unsuccessful. Defaults to nullptr. This function doesn't get called when an existing connection is re-used. See QuantumGate Callbacks for more details.
disconnect_func	A QuantumGate::DisconnectCallback object containing the function to call when the connection closes after having been established. Defaults to nullptr. This function doesn't get called when an existing connection is re-used. See QuantumGate Callbacks for more details.

Return values

Returns a std::pair containing a QuantumGate::Result and a std::optional containing a QuantumGate::PeerLUID. The QuantumGate::PeerLUID contains the Locally Unique Identifier for the peer upon successful initiation of the connection. The QuantumGate::Result object can contain one of the following QuantumGate::ResultCodes:

Value	Description
QuantumGate::ResultCode::Succeeded	The operation succeeded.
QuantumGate::ResultCode::SucceededAlreadyConnected	The operation succeeded and an existing connection is being re-used. The PeerLUID of the existing connection is returned.
QuantumGate::ResultCode::Failed	The operation failed.
QuantumGate::ResultCode::FailedRetry	The operation failed but a retry can be successful.
QuantumGate::ResultCode::FailedNotRunning	The operation failed because the instance isn't running.
QuantumGate::ResultCode::FailedNotAllowed	The operation failed because a connection to the specified endpoint is not allowed by the configured security and access settings.
QuantumGate::ResultCode::FailedNoPeersForRelay	The operation failed because there were no connected peers through which to establish a relayed connection.