> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# PartyManager::ConnectToNetwork

> Queues an asynchronous attempt to connect to a network.

Queues an asynchronous attempt to connect to a network.

## Syntax

```cpp theme={null}
PartyError ConnectToNetwork(  
    const PartyNetworkDescriptor* networkDescriptor,  
    void* asyncIdentifier,  
    PartyNetwork** network  
)  
```

### Parameters

**`networkDescriptor`**   [PartyNetworkDescriptor\*](https://docs.xbox.com/services/playfab/multiplayer/networking/reference/structs/partynetworkdescriptor.md)

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\*\*](https://docs.xbox.com/services/playfab/multiplayer/networking/reference/classes/PartyNetwork/partynetwork.md)\
*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()](https://docs.xbox.com/services/playfab/multiplayer/networking/reference/classes/PartyManager/methods/partymanager_geterrormessage.md).

## 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](https://docs.xbox.com/services/playfab/multiplayer/networking/reference/structs/partyconnecttonetworkcompletedstatechange.md) 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](https://docs.xbox.com/services/playfab/multiplayer/networking/reference/structs/partynetworkdestroyedstatechange.md) 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()](https://docs.xbox.com/services/playfab/multiplayer/networking/reference/classes/PartyNetwork/methods/partynetwork_authenticatelocaluser.md). \
\
 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()](https://docs.xbox.com/services/playfab/multiplayer/networking/reference/classes/PartyNetwork/methods/partynetwork_removelocaluser.md).   \
\
 This method optionally provides `network` as output that can immediately be used to perform asynchronous network operations, such as [PartyNetwork::CreateInvitation()](https://docs.xbox.com/services/playfab/multiplayer/networking/reference/classes/PartyNetwork/methods/partynetwork_createinvitation.md) and [PartyNetwork::CreateEndpoint()](https://docs.xbox.com/services/playfab/multiplayer/networking/reference/classes/PartyNetwork/methods/partynetwork_createendpoint.md). 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](https://docs.xbox.com/services/playfab/multiplayer/networking/reference/structs/partyconnecttonetworkcompletedstatechange.md) set to [PartyStateChangeResult::NetworkLimitReached](https://docs.xbox.com/services/playfab/multiplayer/networking/reference/enums/partystatechangeresult.md) 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()](https://docs.xbox.com/services/playfab/multiplayer/networking/reference/classes/PartyManager/methods/partymanager_createnewnetwork.md).   \
\
 On successful return, this method invalidates the memory for any array previously returned by [GetNetworks()](https://docs.xbox.com/services/playfab/multiplayer/networking/reference/classes/PartyManager/methods/partymanager_getnetworks.md), as it synchronously adds the new network to the array. [StartProcessingStateChanges()](https://docs.xbox.com/services/playfab/multiplayer/networking/reference/classes/PartyManager/methods/partymanager_startprocessingstatechanges.md) 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()](https://docs.xbox.com/services/playfab/multiplayer/networking/reference/classes/PartyManager/methods/partymanager_finishprocessingstatechanges.md).

### 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](https://docs.xbox.com/services/playfab/multiplayer/networking/reference/enums/partystatechangeresult.md) 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](https://docs.xbox.com/services/playfab/multiplayer/networking/reference/enums/partyoption.md) option. The title must clean up its instance of the library, update the [PartyOption::LocalUdpSocketBindAddress](https://docs.xbox.com/services/playfab/multiplayer/networking/reference/enums/partyoption.md) option to a valid, available bind address, and reinitialize the library. |

## Requirements

**Header:** Party.h

## See also

[PartyManager](https://docs.xbox.com/services/playfab/multiplayer/networking/reference/classes/PartyManager/partymanager.md)\
[PartyConnectToNetworkCompletedStateChange](https://docs.xbox.com/services/playfab/multiplayer/networking/reference/structs/partyconnecttonetworkcompletedstatechange.md)\
[PartyNetworkDestroyedStateChange](https://docs.xbox.com/services/playfab/multiplayer/networking/reference/structs/partynetworkdestroyedstatechange.md)\
[PartyNetworkConfiguration](https://docs.xbox.com/services/playfab/multiplayer/networking/reference/structs/partynetworkconfiguration.md)\
[PartyManager::CreateNewNetwork](https://docs.xbox.com/services/playfab/multiplayer/networking/reference/classes/PartyManager/methods/partymanager_createnewnetwork.md)\
[PartyManager::GetNetworks](https://docs.xbox.com/services/playfab/multiplayer/networking/reference/classes/PartyManager/methods/partymanager_getnetworks.md)\
[PartyNetwork::AuthenticateLocalUser](https://docs.xbox.com/services/playfab/multiplayer/networking/reference/classes/PartyNetwork/methods/partynetwork_authenticatelocaluser.md)\
[PartyNetwork::RemoveLocalUser](https://docs.xbox.com/services/playfab/multiplayer/networking/reference/classes/PartyNetwork/methods/partynetwork_removelocaluser.md)\
[PartyNetwork::CreateInvitation](https://docs.xbox.com/services/playfab/multiplayer/networking/reference/classes/PartyNetwork/methods/partynetwork_createinvitation.md)\
[PartyNetwork::RevokeInvitation](https://docs.xbox.com/services/playfab/multiplayer/networking/reference/classes/PartyNetwork/methods/partynetwork_revokeinvitation.md)\
[PartyNetwork::CreateEndpoint](https://docs.xbox.com/services/playfab/multiplayer/networking/reference/classes/PartyNetwork/methods/partynetwork_createendpoint.md)\
[PartyNetwork::LeaveNetwork](https://docs.xbox.com/services/playfab/multiplayer/networking/reference/classes/PartyNetwork/methods/partynetwork_leavenetwork.md)


## Related topics

- [PartyManager::GetNetworks](https://docs.xbox.com/services/playfab/multiplayer/networking/reference/classes/PartyManager/methods/partymanager_getnetworks.md)
- [PartyManager::DeserializeNetworkDescriptor](https://docs.xbox.com/services/playfab/multiplayer/networking/reference/classes/PartyManager/methods/partymanager_deserializenetworkdescriptor.md)
- [PartyManager::SerializeNetworkDescriptor](https://docs.xbox.com/services/playfab/multiplayer/networking/reference/classes/PartyManager/methods/partymanager_serializenetworkdescriptor.md)
- [PartyManager::CreateNewNetwork](https://docs.xbox.com/services/playfab/multiplayer/networking/reference/classes/PartyManager/methods/partymanager_createnewnetwork.md)
- [PartyConnectToNetworkCompletedStateChange](https://docs.xbox.com/services/playfab/multiplayer/networking/reference/structs/partyconnecttonetworkcompletedstatechange.md)