PartyManager::CreateNewNetwork

Stellt einen asynchronen Versuch in die Warteschlange, ein neues Netzwerk zu erstellen.

Syntax

PartyError CreateNewNetwork(  
    const PartyLocalUser* localUser,  
    const PartyNetworkConfiguration* networkConfiguration,  
    uint32_t regionCount,  
    const PartyRegion* regions,  
    const PartyInvitationConfiguration* initialInvitationConfiguration,  
    void* asyncIdentifier,  
    PartyNetworkDescriptor* networkDescriptor,  
    char* appliedInitialInvitationIdentifier  
)  

Parameter

localUser PartyLocalUser*

Der lokale Benutzer, dem die Netzwerkerstellung und Relayzuordnung zugeordnet werden.

networkConfiguration PartyNetworkConfiguration*

Netzwerkkonfigurationseigenschaften wie maximale Benutzeranzahl und maximale Geräteanzahl. Diese Eigenschaften gelten für die Lebensdauer des Netzwerks und können nicht geändert werden.

regionCount uint32_t

Die Anzahl der Regionen, die im Array bevorzugter Regionen bereitgestellt werden, die über angegeben werden regions. Wenn dieser Wert 0 ist, verwendet die Bibliothek alle Regionen, in denen der Titel konfiguriert ist, sortiert nach der niedrigsten Roundtriplatenz von diesem Gerät.

regions PartyRegion*

Das Array der bevorzugten Regionen, in denen das Netzwerk erstellt werden soll. Das Netzwerk wird in der ersten verfügbaren Region erstellt.

initialInvitationConfiguration PartyInvitationConfiguration*
Optional

Eine optional angegebene Konfiguration für die erste Einladung.

Wenn dieser Wert NULL ist, werden Standardkonfigurationswerte verwendet. Standardmäßig generiert PlayFab Party einen eindeutigen Einladungsbezeichner für den Titel, die Widerrufbarkeit ist PartyInvitationRevocability::Anyone, und die PlayFab-Entitäts-ID-Liste ist leer, sodass jeder Benutzer mit der Einladung beitreten kann.

Wenn eine Konfiguration angegeben wird, kann der Titel optional den Bezeichner für die Konfiguration angeben. Wenn der Bezeichner nullptr oder eine leere Zeichenfolge ist, generiert die PlayFab Party-Bibliothek einen Bezeichner für den Titel, der sich garantiert von allen Bezeichnern unterscheidet, die die PlayFab Party-Bibliothek für alle zukünftigen Einladungen in diesem Netzwerk auf allen Geräten generiert. Titel können ihren eigenen Bezeichner angeben, indem in der Konfiguration ein wert ungleich NULL angegeben wird. Wenn der Titel den Bezeichner angibt, liegt es in der Verantwortung des Titels sicherzustellen, dass dieser Bezeichner nicht mit den Bezeichnern zukünftiger Einladungen kollidiert, die in diesem Netzwerk über PartyNetwork::CreateInvitation() auf einem beliebigen Gerät erstellt wurden.

Wenn eine Konfiguration bereitgestellt wird, muss ihre Widerrufbarkeit PartyInvitationRevocability::Anyone lauten.

Wenn eine Konfiguration bereitgestellt wird und die Liste der PlayFab-Entitäts-IDs leer ist, können alle Benutzer mit der neuen Einladung beitreten.

asyncIdentifier Leere*
Optional

Ein optionaler, app-definierter Kontextwert in Zeigergröße, der verwendet werden kann, um die Änderung des Abschlusszustands diesem Aufruf zuzuordnen.

networkDescriptor PartyNetworkDescriptor*
Optionale Ausgabe

Der optionale Ausgabenetzwerkdeskriptor, der verwendet werden kann, um eine Verbindung des lokalen Geräts sofort über ConnectToNetwork() mit dem neu erstellten Netzwerk in die Warteschlange zu stellen.

appliedInitialInvitationIdentifier Char*
Optionaler Ausgabezeichenfolgenpuffer der Größe c_maxInvitationIdentifierStringLength+1

Der optionale Ausgabepuffer, in den der Bezeichner der ersten Einladung geschrieben wird. Wenn initialInvitationConfiguration mit einem Nicht-NULL-Bezeichner bereitgestellt wird, wird dieser Puffer mit demselben Bezeichner gefüllt. Wenn keine anfängliche Konfiguration angegeben wird oder die bereitgestellte Konfiguration einen leeren oder NULL-Bezeichner aufweist, generiert die PlayFab Party-Bibliothek einen und gibt sie an den Titel in diesem Puffer zurück.

Rückgabewert

PartyError

c_partyErrorSuccess , wenn der asynchrone Vorgang zum Erstellen eines neuen Netzwerks gestartet wurde, oder andernfalls ein Fehlercode. Wenn bei dieser Methode ein Fehler auftritt, werden keine zugehörigen Zustandsänderungen generiert. Die lesbare Form des Fehlercodes kann über GetErrorMessage() abgerufen werden.

Hinweise

Ein PartyNetwork ist eine Gruppe von Geräten, die über eine Client-Server-Topologie mit einem transparenten Cloudrelayserver verbunden sind. Jedes Gerät im Netzwerk enthält eine Sammlung von Endpunkten, die dem Netzwerk zugeordnet sind. gerichtete Nachrichten können von einem Endpunkt auf dem lokalen Gerät an eine beliebige Gruppe von Endpunkten gesendet oder an alle Endpunkte übertragen werden. Mit dieser Methode wird versucht, ein Relay zuzuweisen, wodurch ein neues Netzwerk im Namen des von localUser dargestellten Benutzers erstellt wird, das lokale Gerät wird jedoch nicht mit dem Netzwerk verbunden.

Wenn innerhalb von 10 Minuten nach der Erstellung des Relays keine Geräte mit dem Netzwerk verbunden sind, wird es heruntergefahren. Das Netzwerk bleibt unbegrenzt aktiv, während mindestens ein Gerät verbunden ist und bei Bedarf zu einem neuen Relay migriert wird. Wenn keine Geräte mit dem Netzwerk verbunden sind, wird das Relay inaktiv und wird nach 1 Minute Inaktivität heruntergefahren.

Das lokale Gerät kann einen Versuch, eine Verbindung mit dem neuen Netzwerk herzustellen, in die Warteschlange stellen, indem es sofort an ConnectToNetwork() übergibtnetworkDescriptor. Die Verwendung dieses Deskriptors mit SerializeNetworkDescriptor() schlägt fehl, da der Deskriptor nicht genügend Informationen enthält, damit ein Remotegerät eine Verbindung mit dem Netzwerk herstellen kann. Der Netzwerkdeskriptor ändert sich und wird serialisierbar, wenn partyCreateNewNetworkCompletedStateChange angegeben wird und auf erfolg hindeutet. Der aktualisierte Netzwerkdeskriptor wird als Feld in PartyCreateNewNetworkCompletedStateChange bereitgestellt. Der Deskriptor kann auch nach dem Herstellen einer Verbindung mit dem Netzwerk mithilfe von PartyNetwork::GetNetworkDescriptor() abgerufen werden.

Das Netzwerk wird in der ersten verfügbaren Region mit der in regionsangegebenen Reihenfolge erstellt. Wenn keine der angegebenen Regionen verfügbar ist, wird das Netzwerk nicht erstellt. Wenn Sie 0 für regionCount angeben, werden standardmäßig alle Regionen verwendet, in denen der Titel konfiguriert ist, geordnet nach der niedrigsten Latenz für dieses Gerät. Dabei handelt es sich um das gleiche Array, das von GetRegions() zurückgegeben wird.

Die Standardbereichsauswahl umfasst nur Latenzmessungen von diesem Gerät und nicht von anderen Geräten. Titel mit einer Gruppe von Teilnehmern für die Sitzung, die im Vorfeld bekannt sind, sollten vor dem Erstellen des Netzwerks Messungen von allen Geräten sammeln und ein neues regions Array erstellen, das nach der niedrigsten Aggregatlatenz für die gesamte Gruppe sortiert ist.

Bei Titeln, die den Beitritt unterstützen, kann sich die Region mit der besten Gesamtlatenz für die Gruppe der verbundenen Teilnehmer ändern, wenn Geräte beitreten und diese verlassen. Titel sollten die Unterstützung der Partei für die gleichzeitige Verbindung mit mehreren Netzwerken nutzen, um Geräte nahtlos in ein Netzwerk zu migrieren, das in einer Region mit besserer aggregierter Latenz für die Gruppe erstellt wurde. Der Titel kann Regionslatenzmessungen über Nachrichten über das ursprüngliche Parteinetzwerk oder Informationen erfassen, die in einen externen Dienst hochgeladen wurden, ein neues Parteinetzwerk in einer Region mit geringerer aggregierter Latenz erstellen und alle Geräte anweisen, eine Verbindung mit dem günstigeren Netzwerk herzustellen und die Verbindung mit dem ursprünglichen Netzwerk zu trennen.

Wenn die Option PartyOption::RegionUpdateConfiguration verwendet wurde, um einen Updatemodus von PartyRegionUpdateMode::D eferred zu konfigurieren, wurde das Abrufen der verfügbaren Regionen und das Messen der Verbindungsqualität für sie möglicherweise noch nicht gestartet, oder das letzte Update hat möglicherweise das konfigurierte Aktualisierungsintervallalter überschritten. Die Angabe von 0 für regionCount für CreateNewNetwork() stellt sicher, dass alle verzögerten Regionsupdates gestartet wurden und das zugehörige PartyRegionsChangedStateChange vor dem Abschluss des Aufrufs PartyCreateNewNetworkCompletedStateChange bereitgestellt wird.

Die anfängliche Einladung für das neu erstellte Netzwerk gehört keinem Benutzer. Daher wird beim Aufrufen von PartyInvitation::GetCreatorEntityId() nullptr für die anfängliche Einladung zurückgegeben. Die anfängliche Einladung bleibt auch für die Lebensdauer des Netzwerks bestehen, bis sie über PartyNetwork::RevokeInvitation() ausdrücklich widerrufen wird. Neue Einladungen können für das Netzwerk über PartyNetwork::CreateInvitation() von lokalen Benutzern erstellt werden, die beim Netzwerk authentifiziert sind, und diese Einladungen bleiben bestehen, bis ihre erstellenden lokalen Benutzer aus dem Netzwerk entfernt werden. Benutzer treten dem Netzwerk über PartyNetwork::AuthenticateLocalUser() bei, indem sie den Bezeichner einer Einladung angeben, die erfolgreich erstellt wurde, nicht widerrufen wurde und ihnen die Teilnahme zulässt.

Wiederholen eines Fehlers

Wenn CreateNewNetwork() asynchron fehlschlägt, wird ein PartyCreateNewNetworkCompletedStateChange von StartProcessingStateChanges bereitgestellt, der das Ergebnis angibt. Der Vorgang kann je nach bereitgestelltem PartyStateChangeResult nach einer Verzögerung wiederholt werden.

Ergebnis	Wiederholungsverhalten
InternetConnectivityError	Wiederholen Sie den Vorgang mit einer kleinen Verzögerung von nicht weniger als 10 Sekunden. Für Ihre App ist es möglicherweise besser geeignet, den Fehler dem Benutzer sofort anzuzeigen, anstatt es automatisch erneut zu versuchen.
PartyServiceError	Wiederholen Sie den Vorgang mit einem exponentiellen Backoff. Beginnen Sie mit einer mindestverzögerten Verzögerung von nicht weniger als 10 Sekunden, wobei die Verzögerung bei jedem Wiederholungsversuch verdoppelt wird.
NoServersAvailable	Wiederholen Sie den Vorgang mit einem exponentiellen Backoff. Beginnen Sie mit einer mindestverzögerten Verzögerung von nicht weniger als 30 Sekunden, wobei die Verzögerung bei jedem Wiederholungsversuch verdoppelt wird. Für Ihre App ist es möglicherweise besser geeignet, den Fehler dem Benutzer sofort anzuzeigen, anstatt es automatisch erneut zu versuchen.
UserNotAuthorized	Dieses Ergebnis kann bedeuten, dass das Entitätstoken des Benutzers ungültig oder abgelaufen ist oder dass der Benutzer aus anderen Gründen nicht autorisiert wurde. Wiederholen Sie den Vorgang nicht mehr als einmal, und erst, nachdem Sie ein neues Entitätstoken für den Benutzer abgerufen und PartyLocalUser::UpdateEntityToken()aufgerufen haben.
UserCreateNetworkThrottled	Wiederholen Sie den Vorgang nicht automatisch. Zeigen Sie dem Benutzer stattdessen eine Meldung an, und warten Sie, bis der Benutzer einen weiteren Versuch initiiert.
FailedToBindToLocalUdpSocket	Dies bedeutet, dass die Bibliothek nicht an den lokalen UDP-Socket gebunden werden konnte, der in der Option PartyOption::LocalUdpSocketBindAddress angegeben ist. Der Titel muss seine instance der Bibliothek sauber, die Option PartyOption::LocalUdpSocketBindAddress auf eine gültige, verfügbare Bindungsadresse aktualisieren und die Bibliothek erneut initialisieren.

Voraussetzungen

Header: Party.h

Weitere Informationen

PartyManager
PartyCreateNewNetworkCompletedStateChange
PartyManager::ConnectToNetwork
PartyNetwork::AuthenticateLocalUser
PartyNetwork::LeaveNetwork
PartyNetwork::RevokeInvitation
PartyNetwork::CreateInvitation
PartyInvitation
PartyInvitationConfiguration