Syntax
Parameters
targetEndpointCount uint32_t
targetEndpoints 배열의 대상 엔드포인트 수입니다. 네트워크의 모든 원격 엔드포인트에 브로드캐스트하려면 0일 수 있습니다. 브로드캐스트 메시지를 수신하는 디바이스는 PartyEndpointMessageReceivedStateChange의 대상 엔드포인트 필드가 해당 디바이스의 모든 로컬 엔드포인트로 채워집니다.
targetEndpoints PartyEndpointArray크기가
targetEndpointCount인 입력 배열
메시지를 보내야 하는 대상 PartyEndpoint 객체 포인터로 구성된 targetEndpointCount 항목 배열입니다. targetEndpointCount가 0인 경우 이 항목은 무시됩니다.
options PartySendMessageOptions
메시지 전송 방법을 설명하는 0개 이상의 옵션 플래그입니다.
queuingConfiguration PartySendMessageQueuingConfiguration*선택 사항 메시지가 로컬로 큐에 저장되고 전송 기회를 기다리는 동안의 동작 방식을 설명하는 선택적 구조체입니다. 기본 큐 동작을 사용하려면 nullptr일 수 있습니다.
dataBufferCount uint32_t
dataBuffers 배열에 제공된 버퍼 구조체의 수입니다. 0보다 커야 합니다.
dataBuffers PartyDataBuffer*크기가
dataBufferCount인 입력 배열
보낼 메시지 페이로드를 설명하는 PartyDataBuffer 구조체의 dataBufferCount 항목 배열입니다.
messageIdentifier void*선택 사항 이 메시지를 참조하는 모든 상태 변경에 Party 라이브러리가 포함할 불투명한 호출자 관련 컨텍스트 포인터입니다. 이는 해석되거나 원격으로 전송되지 않습니다. 메시지 식별 컨텍스트가 필요하지 않은 경우 nullptr일 수 있습니다.
Return value
PartyError 전송을 위해 메시지를 큐에 넣는 것이 성공한 경우c_partyErrorSuccess, 그렇지 않으면 오류 코드입니다. 이 메서드가 실패하면 관련 상태 변경이 생성되지 않습니다. 오류 코드의 사람이 읽을 수 있는 형식은 PartyManager::GetErrorMessage()를 통해 검색할 수 있습니다.
Remarks
로컬 엔드포인트로 메시지를 보내는 것은 현재 지원되지 않습니다. 대상 엔드포인트 배열에 로컬 대상이 포함되어 있으면 이 호출은 동기적으로 실패합니다.지정된 디바이스의 대상이 되는 모든 엔드포인트에는 단일 PartyEndpointMessageReceivedStateChange가 제공되며, 모든 대상 로컬 엔드포인트가 PartyEndpointMessageReceivedStateChange의 receiverEndpoints 배열에 제공됩니다.
대상 엔드포인트 배열이 0개 항목으로 지정되면 메시지가 현재 네트워크에 있는 모든 원격 엔드포인트에 브로드캐스트됩니다.
호출자는
dataBuffers 배열에 1개 이상의 PartyDataBuffer 구조체를 제공합니다. 구조체가 참조하는 메모리는 연속적일 필요가 없으므로, 예를 들어 고정 헤더 버퍼 뒤에 가변 페이로드가 오도록 하기가 쉽습니다. 버퍼는 순서대로 조립되어 전송되며, PartyEndpointMessageReceivedStateChange에서 하나의 연속된 데이터 블록으로 대상 엔드포인트에 전달됩니다. Party 라이브러리는 원래 PartyDataBuffer 분할을 설명하는 메타데이터를 전송하는 데 대역폭을 사용하지 않습니다. 기본적으로 호출자의
dataBuffers 배열에 설명된 버퍼는 SendMessage()가 반환되기 전에 할당된 버퍼에 복사됩니다. PartySendMessageOptions::DontCopyDataBuffers를 지정하면 이 추가 복사 단계를 피할 수 있지만, 대신 PartyDataBuffersReturnedStateChange가 메모리 소유권을 호출자에게 반환할 때까지 각 버퍼에 지정된 메모리를 유효하고 수정되지 않은 상태로 유지해야 합니다. PartyDataBuffer 구조체 자체는 SendMessage() 호출이 반환된 후에도 유효 상태로 유지될 필요가 없으며, 참조하는 메모리만 유지되어야 합니다. PartySendMessageOptions::DontCopyDataBuffers를 사용하는 호출자는 호출자별
messageIdentifier 컨텍스트를 제공할 수 있습니다. 이 포인터 크기의 값은 모든 PartyDataBuffersReturnedStateChange에 포함되므로 호출자가 자신의 프라이빗 메시지 추적 정보에 쉽게 액세스할 수 있습니다. 실제 값은 불투명하게 처리되며 Party 라이브러리에 의해 해석되지 않고 원격으로 전송되지도 않습니다. messageIdentifier가 나타낼 수 있는 호출자 자신의 메모리가 메시지 및 연결된 messageIdentifier와 관련된 최종 요청 상태 변경이 처리되어 PartyManager::FinishProcessingStateChanges()를 통해 반환될 때까지 유효한 상태로 유지되도록 보장하는 것은 호출자의 책임입니다. 연결 품질 및 수신자 응답성과 같은 요인에 따라 메시지가 대상 엔드포인트로 즉시 전송되지 않을 수 있습니다. 엔드포인트에 대한 연결이 현재 지원할 수 있다고 추정되는 속도보다 빠르게 보내면 로컬 전송 큐가 커집니다. 이는 메모리 사용량을 증가시키고 인지되는 메시지 지연 시간을 증가시킬 수 있으므로, 호출자는 로컬 전송 큐를 모니터링하고 관리하는 것이 강력히 권장됩니다. PartyLocalEndpoint::GetEndpointStatistics()를 사용하여 전송 큐에 대한 정보를 검색할 수 있습니다. 전송 크기 및/또는 빈도를 줄이거나,
queuingConfiguration 선택적 설정을 사용하여 너무 오래 큐에 있는 메시지를 자동으로 만료시키는 타임아웃을 구성하거나, PartyLocalEndpoint::CancelMessages()를 사용하여 큐에 있는 일부 또는 모든 메시지를 명시적으로 제거하여 전송 큐를 관리할 수 있습니다. 이 메서드가 성공을 반환하면 메시지가 전송을 시작했거나 향후 전송을 위해 성공적으로 큐에 들어간 것입니다. 특히, 이 메서드에서 성공적으로 반환되었다고 해서 메시지가 어떤 수신자에게 성공적으로 전달되었음을 의미하지는 않습니다. Party API는 현재 개별 메시지의 전달 및 처리를 추적하는 방법을 제공하지 않습니다. PartyNetwork::GetNetworkStatistics() 및 GetEndpointStatistics() 메서드를 사용하여 각각 네트워크 전체 또는 개별 로컬 엔드포인트에 대한 집계 통계를 쿼리할 수 있습니다.
options에 PartySendMessageOptions::GuaranteedDelivery가 포함되어 있고 대상 엔드포인트로의 전달을 위해 투명 클라우드 릴레이 서버로 메시지가 성공적으로 전달되지 못한 경우 PartyNetworkDestroyedStateChange가 생성됩니다. 다시 말해, 보장된 전달 요구 사항이 있는 메시지는 전달되거나, 그렇지 않으면 보내는 클라이언트가 네트워크에서 연결 해제됩니다. 투명 클라우드 릴레이 서버가 보장된 전달 메시지를 하나 이상의 대상 엔드포인트를 포함하는 각 원격 디바이스로 전달할 때, 메시지를 전달할 수 없으면 원격 디바이스도 마찬가지로 네트워크에서 연결 해제되며 PartyNetworkDestroyedStateChange로 표시됩니다. 다시 말해, 보장된 전달 요구 사항이 있는 메시지를 수신하지 못한 디바이스는 네트워크에서 연결 해제됩니다. Party 라이브러리는 환경에서 지원하는 최대 크기를 초과하는 큰 메시지를 자동으로 조각화하고 재조립하므로 호출자가 이를 관리할 필요가 없습니다. 그러나 조각화와 관련된 약간의 오버헤드가 있습니다. 더 작은 메시지를 보낼 수 있거나 큰 상태 페이로드를 효율적으로 자연스럽게 나눌 수 있는 호출자는 그렇게 하는 것을 원할 수 있습니다.
네트워크에 첫 번째 사용자를 성공적으로 인증하기 전에 SendMessage()가 항목이 0인 대상 엔드포인트 배열로 호출된 경우, PartyEndpointCreatedStateChange 상태 변경을 통해 원격 엔드포인트가 보고되지 않았더라도(따라서 네트워크에 존재한다고 알려지지 않았더라도) 메시지가 큐에 저장됩니다. 첫 번째 사용자가 성공적으로 인증되고 이 보내는 로컬 엔드포인트가 성공적으로 만들어지면, 큐에 저장된 메시지는 이후 시점에 네트워크에 존재하는 모든 원격 엔드포인트를 대상으로 지정합니다. 이 경우 SendMessage() 시점에 네트워크의 미래 상태와 최종적으로 수신하는 엔드포인트의 집합을 알 수 없으므로, 타이틀은 그러한 지연된 브로드캐스트 메시지에 배치되는 콘텐츠에 주의를 기울이거나, 이 로컬 디바이스와 엔드포인트가 네트워크에 완전히 참여할 때까지 아예 제출을 삼가야 합니다.
Requirements
Header: Party.hSee also
PartyLocalEndpointPartySendMessageOptions
PartySendMessageQueuingConfiguration
PartyDataBuffersReturnedStateChange
PartyEndpointMessageReceivedStateChange
PartyNetwork::GetNetworkStatistics
PartyLocalEndpoint::GetEndpointStatistics
PartyLocalEndpoint::FlushMessages