PartyManager::ConnectToNetwork

Article
08/06/2024

Queues an asynchronous attempt to connect to a network.

Syntax

PartyError ConnectToNetwork(  
    const PartyNetworkDescriptor* networkDescriptor,  
    void* asyncIdentifier,  
    PartyNetwork** network  
)

Parameters

networkDescriptor PartyNetworkDescriptor*

The descriptor associated with the network to which a connection will be established.

asyncIdentifier void*
optional

An optional, app-defined, pointer-sized context value that can be used to associate the completion state change with this call.

network PartyNetwork**
optional, library-allocated output

The optional, output network object.

Return value

PartyError

c_partyErrorSuccess if the asynchronous operation to connect to a new network began, or an error code otherwise. If this method fails, no related state changes will be generated. The human-readable form of the error code can be retrieved via GetErrorMessage().

Remarks

This method queues an asynchronous attempt to connect to the network associated with networkDescriptor by negotiating and establishing a secure DTLS connection from the local device to the transparent cloud relay server. A PartyConnectToNetworkCompletedStateChange will be provided upon completion of the asynchronous operation, indicating success or failure. On success, the local device will have established a connection to the transparent cloud relay server. On failure, a PartyNetworkDestroyedStateChange will be generated. No other devices will become visible, and the local device won't be visible to any remote devices, until at least one local user is successfully authenticated via PartyNetwork::AuthenticateLocalUser().

After the device successfully connects to the network, it must authenticate into the network via PartyNetwork::AuthenticateLocalUser(). If the device is connected to the network but unauthenticated for more than one minute, the device will be disconnected and a PartyNetworkDestroyedStateChange will be generated. This will occur regardless of whether the device never authenticated or lost authentication after calling PartyNetwork::RemoveLocalUser().

This method optionally provides network as output that can immediately be used to perform asynchronous network operations, such as PartyNetwork::CreateInvitation() and PartyNetwork::CreateEndpoint(). These asynchronous operations will be internally queued until the connection completes, at which point they'll be processed. This network will also be provided on the resulting PartyConnectToNetworkCompletedStateChange where it will be fully connected and associated with the provided asyncIdentifier.

This operation will asynchronously fail with PartyConnectToNetworkCompletedStateChange::result set to PartyStateChangeResult::NetworkLimitReached if the limit of connected devices for the network has been reached as specified in the network's configuration when it was created via CreateNewNetwork().

On successful return, this method invalidates the memory for any array previously returned by GetNetworks(), as it synchronously adds the new network to the array. StartProcessingStateChanges() also invalidates the memory for the array. The returned network object will be valid until a PartyNetworkDestroyedStateChange has been generated and all state changes referencing the object have been returned to FinishProcessingStateChanges().

Retrying on failure

When ConnectToNetwork() fails asynchronously, a PartyConnectToNetworkCompletedStateChange is provided by StartProcessingStateChanges() indicating the result. The operation may be retried after a delay, depending on the PartyStateChangeResult provided.

Result	Retry behavior
InternetConnectivityError	Retry with a small delay of no less than 10 seconds. For your app, it may be more appropriate to display the error to the user immediately, rather than retrying automatically.
NetworkLimitReached	Don't retry automatically. Instead, display a message to the user and wait for the user to initiate another attempt.
NetworkNoLongerExists	Don't retry.
VersionMismatch	Don't retry.
FailedToBindToLocalUdpSocket	This result means that the library couldn't bind to the local UDP socket specified in the PartyOption::LocalUdpSocketBindAddress option. The title must clean up its instance of the library, update the PartyOption::LocalUdpSocketBindAddress option to a valid, available bind address, and reinitialize the library.

Requirements

Header: Party.h

Share via