PartyDirectPeerConnectivityOptions

Article
08/08/2024

Flags controlling the attempted use of direct peer-to-peer connectivity among devices in a network.

Syntax

enum class PartyDirectPeerConnectivityOptions  : int32_t  
{  
    None = 0x0,  
    SamePlatformType = 0x1,  
    DifferentPlatformType = 0x2,  
    AnyPlatformType = SamePlatformType | DifferentPlatformType,  
    SameEntityLoginProvider = 0x4,  
    DifferentEntityLoginProvider = 0x8,  
    AnyEntityLoginProvider = SameEntityLoginProvider | DifferentEntityLoginProvider,  
    OnlyServers = 0x10,  
}

Constants

Constant	Description
None	No flags are specified. The absence of flags means that no direct peer connectivity attempts are permitted. All endpoint messages and chat data between devices will always be transmitted via transparent cloud relay servers, and no IP address information will ever be exchanged.
SamePlatformType	Direct peer-to-peer connections may be attempted between devices of the same platform type. A pair of devices will attempt to establish direct peer-to-peer connections if they're identified as having the same type of hardware and/or OS platform (for example, Windows PCs, Xbox gaming consoles, iOS-based mobile devices) associated with the specific Party library they use. Note that this flag doesn't permit any direct peer-to-peer connectivity attempts by itself. It must be combined with one or both of the `SameEntityLoginProvider` and `DifferentEntityLoginProvider` flags. This flag can't be combined with the `OnlyServers` flag in the PartyNetworkConfiguration structure. It may be combined with `OnlyServers` as part of the PartyOption::LocalDeviceDirectPeerConnectivityOptionsMask value.
DifferentPlatformType	Direct peer-to-peer connections may be attempted between devices with differing platform types. A pair of devices will attempt to establish direct peer-to-peer connections if they're identified as having different types of hardware and/or OS platforms (for example, Windows PCs, Xbox gaming consoles, iOS-based mobile devices) associated with the specific Party libraries each device uses. Note that this flag doesn't permit any direct peer-to-peer connectivity attempts by itself. It must be combined with one or both of the `SameEntityLoginProvider` and `DifferentEntityLoginProvider` flags. This flag can't be combined with the `OnlyServers` flag in the PartyNetworkConfiguration structure. It may be combined with `OnlyServers` as part of the PartyOption::LocalDeviceDirectPeerConnectivityOptionsMask value.
AnyPlatformType	Direct peer-to-peer connections may be attempted between devices regardless of their platform types. This flag is equivalent to `SamePlatformType \| DifferentPlatformType`.
SameEntityLoginProvider	Direct peer-to-peer connections may be attempted between devices that have authenticated user PlayFab Entity IDs that were logged in using the same provider. A device that's initially authenticating a local user into the network will attempt to establish direct peer-to- peer connections with remote devices that have at least one authenticated user PlayFab Entity ID that was logged in using the same provider (for example, Xbox Live, Facebook, iOS, Google) as the newly authenticating user. Note that this flag doesn't permit any direct peer-to-peer connectivity attempts by itself. It must be combined with one or both of the `SamePlatformType` and `DifferentPlatformType` flags. This flag can't be combined with the `OnlyServers` flag in the PartyNetworkConfiguration structure. It may be combined with `OnlyServers` as part of the PartyOption::LocalDeviceDirectPeerConnectivityOptionsMask value.
DifferentEntityLoginProvider	Direct peer-to-peer connections may be attempted between devices with authenticated user PlayFab Entity IDs that that were logged in using different providers. A device that's initially authenticating a local user into the network will attempt to establish direct peer-to- peer connections with remote devices that don't have any authenticated user PlayFab Entity IDs that were logged in using the same provider (for example, Xbox Live, Facebook, iOS, Google) as the newly authenticating user. Note that this flag doesn't permit any direct peer-to-peer connectivity attempts by itself. It must be combined with one or both of the `SamePlatformType` and `DifferentPlatformType` flags. This flag can't be combined with the `OnlyServers` flag in the PartyNetworkConfiguration structure. It may be combined with `OnlyServers` as part of the PartyOption::LocalDeviceDirectPeerConnectivityOptionsMask value.
AnyEntityLoginProvider	Direct peer-to-peer connections may be attempted between devices regardless of the provider used to login authenticated user PlayFab Entity IDs. This flag is equivalent to `SameEntityLoginProvider \| DifferentEntityLoginProvider`.
OnlyServers	Direct peer-to-peer connections may be attempted between devices if at least one of the devices has an authenticated user with a PlayFab Entity type of `game_server`. A device that's initially authenticating a local user into the network will attempt to establish direct peer-to- peer connections with remote devices if either the local user or a user on the remote device is a `game_server` PlayFab Entity type, as specified to PartyManager::CreateLocalUserWithEntityType(). In other words, players' devices will never connect directly to one another, only to server devices. Server devices will attempt to connect directly to all player and other server devices. This flag can't be combined with any of the `SamePlatformType`, `DifferentPlatformType`, `SameEntityLoginProvider`, or `DifferentEntityLoginProvider` flags in the PartyNetworkConfiguration structure. It may be combined with those flags as part of the PartyOption::LocalDeviceDirectPeerConnectivityOptionsMask value.

Remarks

As part of successfully authenticating an initial user into a network, a device may attempt to establish direct peer-to-peer connections with other devices already participating in the network when permitted by these flags declared in the network's PartyNetworkConfiguration structure. For attempts that are successful, endpoint messages and chat data between the devices will be transmitted using those direct connections. For attempts that fail due to environmental incompatibilities between the devices, all communication between those devices will be transmitted via transparent cloud relay servers instead. If the devices aren't permitted to attempt direct peer connections by these flags, then they never exchange IP address information and will always transmit endpoint messages and chat data via transparent cloud relay servers.

You can determine whether the local device actually established a direct peer-to-peer connection to a specific remote device by calling PartyNetwork::GetDeviceConnectionType().

Successful direct peer connectivity may provide lower latency between some devices, though attempting to establish it also requires users to disclose their devices' IP addresses to others, which may be a concern for privacy or for enabling malicious users to potentially attack peers' devices and Internet connections outside of the title. It also may not be permitted on certain platforms for policy reasons. Be sure to use the appropriate flags for your performance and security goals.

Besides a specific network's PartyNetworkConfiguration::directPeerConnectivityOptions value, the flags may optionally be further constrained by a device for all networks into which it authenticates by using PartyManager::SetOption() to set PartyOption::LocalDeviceDirectPeerConnectivityOptionsMask. All flags are evaluated using a bitwise AND operation. That is, a particular flag is only in effect for a given network's pair of devices if it's enabled in three places: the network's PartyNetworkConfiguration structure, and both devices' respective local mask options. Even if the Party network permits direct peer connectivity of the relevant form, either device can unilaterally opt out of the IP address disclosure and direct connection attempts between them by not enabling the flag. The PartyOption::LocalDeviceDirectPeerConnectivityOptionsMask value defaults to permitting all direct peer connections enabled by networks, so you only need to configure it if you have device-specific requirements to prevent some or all direct peer connectivity involving it.

To avoid excessive resource consumption, the Party library will also internally prevent any given device from attempting to establish more than a configured maximum number of direct peer connections across all networks in which it's currently participating, even if permitted by these flags. This doesn't affect the device's ability to participate in large or multiple networks with more remote devices. Communication with extra devices will simply be transmitted via transparent cloud relay servers. To modify that maximum number of direct peer connections, use PartyManager::SetOption() to set PartyOption::LocalDeviceMaxDirectPeerConnections.

It's recommended that you don't actively enforce the availability of a direct peer-to-peer connection for any given pair of devices (that is, don't call PartyNetwork::LeaveNetwork() if PartyNetwork::GetDeviceConnectionType() reports a value other than PartyDeviceConnectionType::DirectPeerConnection) since the specific underlying transmission method in use doesn't alter the overall logical ability to communicate. If your game design has stringent requirements for maximum message latency that encourage direct peer connectivity, it's better to take action on the current concrete observations of that latency as reported by the PartyEndpointStatistic::AverageDeviceRoundTripLatencyInMilliseconds statistic rather than make abstract assumptions based on transmission mechanism. Otherwise you might continually hinder users trying to play with the same set of friends who always need to use nearby transparent cloud relay servers due to environmental factors beyond their control.

Requirements

Header: Party.h

Partager via

PartyDirectPeerConnectivityOptions

Syntax

Constants

Remarks

Requirements

See also

Commentaires

Ressources supplémentaires