Syntax
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
PartyErrorc_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 withnetworkDescriptor 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.Requirements
Header: Party.hSee also
PartyManagerPartyConnectToNetworkCompletedStateChange
PartyNetworkDestroyedStateChange
PartyNetworkConfiguration
PartyManager::CreateNewNetwork
PartyManager::GetNetworks
PartyNetwork::AuthenticateLocalUser
PartyNetwork::RemoveLocalUser
PartyNetwork::CreateInvitation
PartyNetwork::RevokeInvitation
PartyNetwork::CreateEndpoint
PartyNetwork::LeaveNetwork