Sintaxe
Parâmetros
targetEndpointCount uint32_t
O número de pontos de extremidade de destino na matriz targetEndpoints. Pode ser zero para transmitir a todos os pontos de extremidade remotos da rede. Um dispositivo que recebe uma mensagem de difusão terá os campos de ponto de extremidade de destino do PartyEndpointMessageReceivedStateChange preenchidos com todos os pontos de extremidade locais do dispositivo.
targetEndpoints PartyEndpointArraymatriz de entrada de tamanho
targetEndpointCount
A matriz de targetEndpointCount entradas de ponteiros de objetos PartyEndpoint de destino para os quais a mensagem deve ser enviada. Isso é ignorado quando targetEndpointCount é zero.
options PartySendMessageOptions
Zero ou mais sinalizadores de opção que descrevem como enviar a mensagem.
queuingConfiguration PartySendMessageQueuingConfiguration*opcional Uma estrutura opcional que descreve como a mensagem deve se comportar enquanto estiver enfileirada localmente e aguardando uma oportunidade de transmissão. Pode ser nullptr para usar o comportamento de enfileiramento padrão.
dataBufferCount uint32_t
O número de estruturas de buffer fornecidas na matriz dataBuffers. Deve ser maior que 0.
dataBuffers PartyDataBuffer*matriz de entrada de tamanho
dataBufferCount
A matriz de dataBufferCount entradas de estruturas PartyDataBuffer que descrevem a carga da mensagem a ser enviada.
messageIdentifier void*opcional Um ponteiro de contexto opaco, específico do chamador, que a biblioteca do Party incluirá em todas as alterações de estado que fizerem referência a esta mensagem. Ele não é interpretado nem transmitido remotamente. Pode ser nullptr se nenhum contexto de identificação de mensagem for necessário.
Valor retornado
PartyErrorc_partyErrorSuccess se o enfileiramento da mensagem para transmissão tiver êxito ou um código de erro caso contrário. Se este método falhar, nenhuma alteração de estado relacionada será gerada. A forma legível do código de erro pode ser obtida por meio de PartyManager::GetErrorMessage().
Comentários
No momento, não há suporte para o envio de mensagens para pontos de extremidade locais. Se a matriz de pontos de extremidade de destino incluir algum destino local, esta chamada falhará de forma síncrona.Todos os pontos de extremidade de destino em um determinado dispositivo receberão um único PartyEndpointMessageReceivedStateChange com todos os pontos de extremidade locais de destino fornecidos na matriz receiverEndpoints do PartyEndpointMessageReceivedStateChange.
Se a matriz de pontos de extremidade de destino for especificada sem entradas, a mensagem será transmitida a todos os pontos de extremidade remotos presentes na rede no momento.
Os chamadores fornecem 1 ou mais estruturas PartyDataBuffer na matriz
dataBuffers. A memória referenciada pelas estruturas não precisa ser contígua, o que facilita ter, por exemplo, um buffer de cabeçalho fixo seguido de uma carga variável. Os buffers serão montados em ordem, transmitidos e entregues aos pontos de extremidade de destino como um único bloco de dados contíguo em um PartyEndpointMessageReceivedStateChange. A biblioteca do Party não gasta largura de banda transmitindo metadados para descrever a segmentação original dos PartyDataBuffer. Por padrão, os buffers descritos na matriz
dataBuffers do chamador são copiados para um buffer alocado antes que SendMessage() retorne. Especificar PartySendMessageOptions::DontCopyDataBuffers evita essa etapa de cópia adicional e, em vez disso, exige que o chamador mantenha a memória especificada em cada buffer válida e sem modificações até que um PartyDataBuffersReturnedStateChange devolva a propriedade da memória ao chamador. As próprias estruturas PartyDataBuffer não precisam permanecer válidas após o retorno da chamada a SendMessage(), apenas a memória que elas referenciam. Os chamadores que usam PartySendMessageOptions::DontCopyDataBuffers podem fornecer um contexto
messageIdentifier específico do chamador. Esse valor do tamanho de um ponteiro será incluído em todos os PartyDataBuffersReturnedStateChanges para que o chamador possa acessar facilmente suas próprias informações privadas de acompanhamento de mensagens. O valor real é tratado como opaco e não é interpretado pela biblioteca do Party nem transmitido remotamente. É responsabilidade do chamador garantir que qualquer memória própria que messageIdentifier possa representar permaneça válida até que a última alteração de estado solicitada associada à mensagem e ao messageIdentifier associado tenha sido processada e devolvida por meio de PartyManager::FinishProcessingStateChanges(). As mensagens podem não ser transmitidas imediatamente aos pontos de extremidade de destino, com base em fatores como a qualidade da conexão e a capacidade de resposta do receptor. A fila de envio local crescerá se você estiver enviando mais rápido do que a conexão com um ponto de extremidade suporta, segundo as estimativas atuais. Isso aumenta o uso de memória e pode aumentar a latência percebida das mensagens; portanto, é altamente recomendável que os chamadores monitorem e gerenciem as filas de envio locais. Você pode recuperar informações sobre a fila de envio usando PartyLocalEndpoint::GetEndpointStatistics(). Você pode gerenciar a fila de envio reduzindo o tamanho e/ou a frequência dos envios, usando as configurações opcionais de
queuingConfiguration para configurar tempos limite que expiram automaticamente as mensagens enfileiradas há muito tempo ou usando PartyLocalEndpoint::CancelMessages() para remover explicitamente algumas ou todas as mensagens enfileiradas. Quando este método retorna êxito, a mensagem começou a ser transmitida ou foi enfileirada com êxito para transmissão futura. Em particular, um retorno bem-sucedido deste método não implica que a mensagem tenha sido entregue com êxito a algum destinatário. Atualmente, a API do Party não oferece uma forma de acompanhar a entrega e o processamento de mensagens individuais. Os métodos PartyNetwork::GetNetworkStatistics() e GetEndpointStatistics() podem ser usados para consultar estatísticas agregadas da rede como um todo ou de um ponto de extremidade local individual, respectivamente.
Se
options incluir PartySendMessageOptions::GuaranteedDelivery e a mensagem não puder ser entregue com êxito ao servidor transparente de retransmissão na nuvem para encaminhamento aos pontos de extremidade de destino, um PartyNetworkDestroyedStateChange será gerado. Em outras palavras, as mensagens com requisito de entrega garantida serão entregues ou o cliente remetente será desconectado da rede. Quando o servidor transparente de retransmissão na nuvem encaminha a mensagem com entrega garantida a cada dispositivo remoto que contém um ou mais pontos de extremidade de destino, se a mensagem não puder ser entregue, o dispositivo remoto também será desconectado da rede, o que é indicado por um PartyNetworkDestroyedStateChange. Em outras palavras, um dispositivo que não conseguir receber uma mensagem com requisito de entrega garantida será desconectado da rede. A biblioteca do Party fragmenta e remonta automaticamente as mensagens grandes que excedem o tamanho máximo suportado pelo ambiente, para que os chamadores não precisem gerenciar isso. No entanto, há uma pequena sobrecarga associada à fragmentação. Os chamadores que conseguem enviar mensagens menores ou dividir com eficiência grandes cargas de estado por conta própria podem preferir fazê-lo.
Se SendMessage() for invocado com uma matriz de pontos de extremidade de destino sem entradas antes da autenticação bem-sucedida de um primeiro usuário na rede, mesmo que nenhum ponto de extremidade remoto tenha sido relatado por meio de alterações de estado PartyEndpointCreatedStateChange (e, portanto, conhecidos como existentes na rede), a mensagem ainda será enfileirada. Depois que o primeiro usuário tiver se autenticado com êxito e este ponto de extremidade local remetente tiver sido criado com êxito, a mensagem enfileirada terá como destino todos os pontos de extremidade remotos existentes na rede nesse momento posterior. Como o estado futuro da rede e o conjunto de pontos de extremidade que efetivamente receberão a mensagem não são conhecidos no momento da chamada a SendMessage() nesse caso, os títulos devem ter cautela quanto ao conteúdo colocado nessas mensagens de difusão adiadas ou simplesmente evitar enviá-las até que este dispositivo local e o ponto de extremidade estejam participando plenamente da rede.
Requisitos
Cabeçalho: Party.hConfira também
PartyLocalEndpointPartySendMessageOptions
PartySendMessageQueuingConfiguration
PartyDataBuffersReturnedStateChange
PartyEndpointMessageReceivedStateChange
PartyNetwork::GetNetworkStatistics
PartyLocalEndpoint::GetEndpointStatistics
PartyLocalEndpoint::FlushMessages