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