PartyManager::CreateNewNetwork

아티클
02/09/2024

새 네트워크를 만들기 위한 비동기 시도를 큐에 넣습니다.

구문

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

매개 변수

localUserPartyLocalUser*

네트워크 만들기 및 릴레이 할당 자격이 있는 로컬 사용자입니다.

networkConfigurationPartyNetworkConfiguration*

최대 사용자 수, 최대 디바이스 수와 같은 네트워크 구성 속성입니다. 이러한 속성은 네트워크의 수명 동안 지속되며 변경할 수 없습니다.

regionCount uint32_t

regions을(를) 통해 지정된 기본 지역의 배열에 제공되는 지역 수입니다. 이 값이 0이면 라이브러리는 타이틀이 구성된 모든 영역을 사용하며, 이 디바이스에서 왕복 대기 시간이 가장 낮은 순으로 정렬됩니다.

regionsPartyRegion*

네트워크를 만들어야 하는 기본 지역의 배열입니다. 네트워크는 사용 가능한 첫 번째 영역에 만들어집니다.

initialInvitationConfigurationPartyInvitationConfiguration*
선택 사항

초기 초대에 대해 선택적으로 지정된 구성입니다.

이 값이 null이면 기본 구성 값이 사용됩니다. 기본적으로 PlayFab 파티에서는 타이틀에 고유한 초대 식별자를 생성합니다. 취소 가능성은 PartyInvitationRevocability::Anyone이고, PlayFab 엔터티 ID 목록은 비어 있으므로 모든 사용자가 초대를 사용하여 참가할 수 있습니다.

구성이 제공된 경우 타이틀은 필요에 따라 구성에서 식별자를 지정할 수 있습니다. 식별자가 nullptr 또는 빈 문자열인 경우 PlayFab 파티 라이브러리는 PlayFab 파티 라이브러리가 모든 디바이스에서 이 네트워크의 모든 향후 초대에 대해 생성할 모든 식별자와 다르게 보장되는 타이틀에 대한 식별자를 생성합니다. 타이틀은 구성에서 null이 아니고 비어 있지 않은 값을 제공하여 고유 식별자를 지정할 수 있습니다. 타이틀이 식별자를 지정하는 경우 이 식별자가 모든 디바이스에서 PartyNetwork::CreateInvitation()을 통해 이 네트워크에 생성되는 이후 초대의 식별자와 충돌하지 않도록 하는 것은 타이틀의 책임입니다.

구성이 제공된 경우 취소 가능성은 PartyInvitationRevocability::Anyone입니다.

구성이 제공되고 PlayFab 엔터티 ID 목록이 비어 있으면 모든 사용자가 새 초대를 사용하여 참가할 수 있습니다.

asyncIdentifier void*
선택 사항

완료 상태 변경을 이 호출과 연결하는 데 사용할 수 있는 선택적 앱 정의 포인터 크기의 컨텍스트 값입니다.

networkDescriptorPartyNetworkDescriptor*
선택적 출력

ConnectToNetwork()를 통해 새로 만든 네트워크에 대한 로컬 디바이스의 연결을 즉시 큐에 추가하는 데 사용할 수 있는 선택적 출력 네트워크 설명자입니다.

appliedInitialInvitationIdentifier char*
크기의 선택적 출력 문자열 버퍼c_maxInvitationIdentifierStringLength+1

초기 초대의 식별자가 기록되는 선택적 출력 버퍼입니다. initialInvitationConfiguration이(가) null이 아닌 비어 있지 않은 식별자와 함께 제공된 경우 이 버퍼는 동일한 식별자로 채워집니다. 초기 구성이 제공되지 않았거나 제공된 구성에 빈 식별자나 null 식별자가 있는 경우 PlayFab 파티 라이브러리는 이를 생성하여 이 버퍼의 타이틀에 반환합니다.

반환 값

PartyError

c_partyErrorSuccess(새 네트워크를 만드는 비동기 작업이 시작되는 경우), 그렇지 않으면 오류 코드입니다. 이 메서드가 실패하면 관련 상태 변경 내용이 생성되지 않습니다. 사용자가 읽을 수 있는 형식의 오류 코드는 GetErrorMessage()를 통해 검색할 수 있습니다.

비고

PartyNetwork는 클라이언트 서버 토폴로지를 통해 투명한 클라우드 릴레이 서버에 연결되는 디바이스 집합입니다. 네트워크의 각 디바이스에는 네트워크와 연결된 엔드포인트 컬렉션이 포함됩니다. 전달된 메시지는 로컬 디바이스의 엔드포인트에서 모든 엔드포인트 집합으로 전송되거나 모든 엔드포인트로 브로드캐스트될 수 있습니다. 이 메서드는 릴레이 할당 시도를 큐에 추가하므로 localUser 표시되는 사용자를 대신하여 새 네트워크를 만들지만 로컬 디바이스를 네트워크에 연결하지는 않습니다.

릴레이 생성 후 10분 이내에 네트워크에 연결하는 디바이스가 없으면 종료됩니다. 하나 이상의 디바이스가 연결되어 있으면 네트워크는 무기한 활성 상태로 유지되고 필요한 경우 새 릴레이로 마이그레이션됩니다. 네트워크에 연결된 디바이스가 없으면 릴레이가 비활성 상태가 되고 1분 동안 활동이 없으면 종료됩니다.

로컬 디바이스는 networkDescriptor을(를) ConnectToNetwork()에 즉시 전달하여 새 네트워크에 연결하려는 시도를 큐에 추가할 수 있습니다. 설명자에 원격 디바이스가 네트워크에 연결하는 데 충분한 정보가 포함되어 있지 않으므로 이 설명자를 SerializeNetworkDescriptor()와 함께 사용할 수 없습니다. PartyCreateNewNetworkCompletedStateChange가 제공되고 성공을 나타내면 네트워크 설명자가 변경되고 직렬화할 수 있게 됩니다. 업데이트된 네트워크 설명자는 PartyCreateNewNetworkCompletedStateChange의 필드로 제공됩니다. PartyNetwork::GetNetworkDescriptor()를 사용하여 네트워크에 연결한 후 설명자를 검색할 수도 있습니다.

네트워크는 regions에 지정된 순서에 따라 사용 가능한 첫 번째 지역에 만들어집니다. 지정된 지역을 사용할 수 없는 경우 네트워크가 만들어지지 않습니다. 기본적으로 regionCount에 0을 지정하면 타이틀이 구성된 모든 영역을 사용하고, GetRegions()에서 반환하는 배열과 동일한 배열인 이 디바이스에 대한 가장 낮은 대기 시간으로 정렬됩니다.

기본 영역 선택에는 다른 디바이스가 아닌 이 디바이스의 대기 시간 측정만 포함됩니다. 세션에 대한 참가자 집합이 미리 알려진 타이틀은 네트워크를 만들기 전에 모든 디바이스의 측정값을 수집하고 전체 그룹에 대해 가장 낮은 집계 대기 시간을 기준으로 정렬된 새 regions 배열을 구성해야 합니다.

타이틀에서 진행 중 참가를 지원하는 경우 연결된 참가자 그룹에 대한 전체 대기 시간이 가장 적합한 지역은 디바이스가 들어오고 나갈 때마다 변경될 수 있습니다. 타이틀은 여러 네트워크에 동시에 연결하기 위한 Party의 지원을 활용하여 그룹에 대한 집계 대기 시간이 더 나은 지역에서 만든 네트워크로 디바이스를 원활하게 마이그레이션해야 합니다. 타이틀은 원래 파티 네트워크를 경유하는 메시지 또는 외부 명단 서비스에 업로드된 정보를 통해 지역 대기 시간 측정값을 수집하고, 집계 대기 시간이 낮은 지역에 새 파티 네트워크를 만들고, 모든 디바이스에 더 우호적인 네트워크에 연결하고 원래 네트워크와 연결을 끊도록 지시할 수 있습니다.

PartyOption::RegionUpdateConfiguration 옵션을 사용하여 PartyRegionUpdateMode::Deferred의 업데이트 모드를 구성한경우 사용 가능한 영역 집합을 검색하고 연결 품질을 측정하는 작업이 아직 시작되지 않았거나 마지막 업데이트가 구성된 새로 고침 간격 기간을 초과했을 수 있습니다. CreateNewNetwork()에 대해 regionCount에 0을 지정하면 지연된 영역 업데이트가 시작되고 이 호출의 PartyCreateNewNetworkCompletedStateChange 완료 전에 연결된 PartyRegionsChangedStateChange가 제공됩니다.

새로 만든 네트워크에 대한 초기 초대는 사용자가 소유하지 않습니다. 따라서 초기 초대에 대해 PartyInvitation::GetCreatorEntityId()를 호출하면 nullptr이 반환됩니다. 초기 초대는 PartyNetwork::RevokeInvitation()을 통해 특별히 취소될 때까지 네트워크의 수명 동안 유지됩니다. 네트워크에 인증된 로컬 사용자가 PartyNetwork::CreateInvitation()을 통해 네트워크에 대한 새 초대를 만들 수 있으며, 해당 초대는 생성한 로컬 사용자가 네트워크에서 제거될 때까지 유지됩니다. 사용자는 성공적으로 생성되고 해지되지 않은 초대의 식별자를 제공하여 PartyNetwork::AuthenticateLocalUser()를 통해 네트워크에 연결하여 참여할 수 있습니다.

실패 시 다시 시도

CreateNewNetwork()가 비동기적으로 실패하면 StartProcessingStateChanges에서 결과를 나타내는 PartyCreateNewNetworkCompletedStateChange가 제공됩니다. 제공된 PartyStateChangeResult에 따라 작업이 지연된 후 다시 시도될 수 있습니다.

결과	다시 시도 동작
InternetConnectivityError	10초 이하의 작은 지연으로 다시 시도하세요. 앱의 경우 자동으로 다시 시도하는 것보다 오류를 사용자에게 즉시 표시하는 것이 더 적합할 수 있습니다.
PartyServiceError	지수 백오프를 사용하여 다시 시도합니다. 최소 지연 시간(10초 이상)으로 시작하여 다시 시도할 때마다 지연 시간이 두 배로 증가합니다.
NoServersAvailable	지수 백오프를 사용하여 다시 시도합니다. 최소 지연 시간(30초 이상)으로 시작하여 다시 시도할 때마다 지연 시간이 두 배로 증가합니다. 앱의 경우 자동으로 다시 시도하는 것보다 오류를 사용자에게 즉시 표시하는 것이 더 적합할 수 있습니다.
UserNotAuthorized	이 결과는 사용자의 엔터티 토큰이 잘못되었거나 만료되었거나 다른 이유로 사용자에게 권한이 부여되지 않은 것을 의미할 수 있습니다. 사용자에 대한 새 엔터티 토큰을 가져오고 PartyLocalUser::UpdateEntityToken()을 호출한 이후에 한 번만 다시 시도합니다.
UserCreateNetworkThrottled	자동으로 다시 시도하지 마세요. 대신 사용자에게 메시지를 표시하고 사용자가 다른 시도를 시작할 때까지 기다립니다.
FailedToBindToLocalUdpSocket	이 결과는 라이브러리가 PartyOption::LocalUdpSocketBindAddress 옵션에 지정된 로컬 UDP 소켓에 바인딩할 수 없음을 의미합니다. 타이틀은 라이브러리의 인스턴스를 정리하고, PartyOption::LocalUdpSocketBindAddress 옵션을 유효한 사용 가능한 바인딩 주소로 업데이트하고, 라이브러리를 다시 초기화해야 합니다.

요구 사항

헤더: Party.h

참고 항목

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

다음을 통해 공유