Edit

PartyManager::GetRegions

  • Article

Gets an array containing the set of regions for which your title is configured, along with round trip latency information.

Syntax

PartyError GetRegions(  
    uint32_t* regionCount,  
    const PartyRegion** regions  
)

Parameters

regionCount   uint32_t*
output

The output number of regions provided in regions.

regions   PartyRegion**
library-allocated output array of size *regionCount

A library-allocated output array containing the set of regions.

Return value

PartyError

c_partyErrorSuccess if the call succeeded or an error code otherwise. The human-readable form of the error code can be retrieved via GetErrorMessage().

Remarks

The array provided by this method isn't populated until the first PartyRegionsChangedStateChange is provided. Each subsequent PartyRegionsChangedStateChange indicates an update to this set of regions. Background operations populating this set begin when Initialize() is called, unless the PartyOption::RegionUpdateConfiguration option was used to configure an update mode of PartyRegionUpdateMode::Deferred. The deferred mode means region retrieval and connection quality measurement doesn't begin until the application calls CreateNewNetwork() with a zero entry region array, or isn't connected to any network and calls PartyLocalChatControl::PopulateAvailableTextToSpeechProfiles(), PartyLocalChatControl::SetTextToSpeechProfile(), or PartyLocalChatControl::SetTranscriptionOptions() with option flags that include PartyVoiceChatTranscriptionOptions::TranscribeSelfRegardlessOfNetworkState. The PartyOption::RegionUpdateConfiguration option can also be used to configure the interval after which the regions array is to be refreshed.

The returned array is sorted in order of increasing latency. Latency for a region is defined as the end-to-end time it takes to send a UDP datagram to the region's PlayFab Quality of Service beacon and receive a response. The library measures latency for each region several times in order to calculate high fidelity results. Applications can alter low-level aspects of this connection quality measurement procedure using the PartyOption::RegionQualityMeasurementConfiguration option.

A latency equivalent to UINT32_MAX indicates that the region is supported but latency information couldn't be determined, either due to failures internal to the library or a timeout was reached without receiving a response from the beacon. This can be used for diagnostic purposes (a UINT32_MAX latency to every region likely indicates a local configuration problem) or used to filter out regions that are unlikely to be viable during region selection.

The returned names in the PartyRegion structures aren't localized to the current user's language, and showing the strings directly in UI isn't recommended outside of troubleshooting.

Don't assume the set of regions returned remain the same over the life of your title. The PlayFab Party library will automatically take advantage of additions and changes to available regions over time to continually improve the experience for end users.

Requirements

Header: Party.h

See also

PartyManager
PartyRegionsChangedStateChange
PartyManager::CreateNewNetwork