Sintaxis
Parámetros
targetEndpointCount uint32_t
El número de puntos de conexión de destino en la matriz targetEndpoints. Puede ser cero para difundir a todos los puntos de conexión remotos de la red. Un dispositivo que reciba un mensaje de difusión tendrá los campos de punto de conexión de destino del PartyEndpointMessageReceivedStateChange rellenados con todos los puntos de conexión locales del dispositivo.
targetEndpoints PartyEndpointArraymatriz de entrada de tamaño
targetEndpointCount
La matriz de targetEndpointCount entradas de punteros a objetos PartyEndpoint de destino a los que se debe enviar el mensaje. Se omite cuando targetEndpointCount es cero.
options PartySendMessageOptions
Cero o más marcas de opción que describen cómo enviar el mensaje.
queuingConfiguration PartySendMessageQueuingConfiguration*opcional Una estructura opcional que describe cómo debe comportarse el mensaje mientras está en cola localmente y esperando una oportunidad para transmitirse. Puede ser nullptr para usar el comportamiento de puesta en cola predeterminado.
dataBufferCount uint32_t
El número de estructuras de búfer proporcionadas en la matriz dataBuffers. Debe ser mayor que 0.
dataBuffers PartyDataBuffer*matriz de entrada de tamaño
dataBufferCount
La matriz de dataBufferCount entradas de estructuras PartyDataBuffer que describen la carga del mensaje que se va a enviar.
messageIdentifier void*opcional Un puntero de contexto opaco y específico del autor de la llamada que la biblioteca Party incluirá en cualquier cambio de estado que haga referencia a este mensaje. No se interpreta ni se transmite de forma remota. Puede ser nullptr si no se necesita un contexto de identificación de mensajes.
Valor devuelto
PartyErrorc_partyErrorSuccess si la puesta en cola del mensaje para su transmisión se realizó correctamente o un código de error en caso contrario. Si este método produce un error, no se generará ningún cambio de estado relacionado. La forma legible del código de error se puede recuperar mediante PartyManager::GetErrorMessage().
Comentarios
El envío de mensajes a puntos de conexión locales no se admite actualmente. Si la matriz de puntos de conexión de destino incluye algún destino local, esta llamada producirá un error de forma sincrónica.Todos los puntos de conexión de destino de un dispositivo determinado recibirán un único PartyEndpointMessageReceivedStateChange con cada punto de conexión local de destino proporcionado en la matriz receiverEndpoints del PartyEndpointMessageReceivedStateChange.
Si la matriz de puntos de conexión de destino se especifica con cero entradas, el mensaje se difunde a todos los puntos de conexión remotos que se encuentran actualmente en la red.
Los autores de las llamadas proporcionan 1 o más estructuras PartyDataBuffer en la matriz
dataBuffers. La memoria a la que hacen referencia las estructuras no tiene que ser contigua, lo que facilita, por ejemplo, tener un búfer de encabezado fijo seguido de una carga variable. Los búferes se ensamblarán en orden, se transmitirán y se entregarán a los puntos de conexión de destino como un único bloque de datos contiguo en un PartyEndpointMessageReceivedStateChange. La biblioteca Party no gasta ancho de banda transmitiendo metadatos para describir la segmentación original de los PartyDataBuffer. De forma predeterminada, los búferes descritos en la matriz
dataBuffers del autor de la llamada se copian en un búfer asignado antes de que SendMessage() vuelva. Especificar PartySendMessageOptions::DontCopyDataBuffers evitará este paso de copia adicional y, en su lugar, requerirá que el autor de la llamada mantenga la memoria especificada en cada búfer válida y sin modificar hasta que un PartyDataBuffersReturnedStateChange devuelva la propiedad de la memoria al autor de la llamada. Las estructuras PartyDataBuffer en sí no necesitan seguir siendo válidas después de que vuelva la llamada a SendMessage(), solo la memoria a la que hacen referencia. Los autores de las llamadas que usen PartySendMessageOptions::DontCopyDataBuffers pueden proporcionar un contexto
messageIdentifier específico del autor de la llamada. Este valor del tamaño de un puntero se incluirá con todos los PartyDataBuffersReturnedStateChange para que el autor de la llamada pueda acceder fácilmente a su propia información privada de seguimiento de mensajes. El valor real se trata como opaco y la biblioteca Party no lo interpreta ni lo transmite de forma remota. Es responsabilidad del autor de la llamada garantizar que cualquier memoria propia que messageIdentifier pueda representar siga siendo válida hasta que el último cambio de estado solicitado asociado al mensaje y al messageIdentifier asociado se haya procesado y devuelto mediante PartyManager::FinishProcessingStateChanges(). Es posible que los mensajes no se transmitan a los puntos de conexión de destino de inmediato en función de factores como la calidad de la conexión y la capacidad de respuesta del receptor. La cola de envío local crecerá si envía más rápido de lo que se estima que admite actualmente la conexión a un punto de conexión. Esto aumenta el uso de memoria y puede dar lugar a aumentos en la latencia percibida de los mensajes, por lo que se recomienda encarecidamente a los autores de las llamadas que supervisen y administren las colas de envío locales. Puede recuperar información sobre la cola de envío mediante PartyLocalEndpoint::GetEndpointStatistics(). Puede administrar la cola de envío reduciendo el tamaño o la frecuencia del envío, usando la configuración opcional
queuingConfiguration para configurar tiempos de espera que expiren automáticamente los mensajes que han estado en cola durante demasiado tiempo, o usando PartyLocalEndpoint::CancelMessages() para eliminar explícitamente algunos o todos los mensajes en cola. Cuando este método devuelve un resultado correcto, el mensaje ha comenzado a transmitirse o se ha puesto en cola correctamente para una transmisión futura. En particular, un resultado correcto de este método no implica que el mensaje se haya entregado correctamente a ningún destinatario. La API de Party no proporciona actualmente una forma de realizar un seguimiento de la entrega y el procesamiento de mensajes individuales. Los métodos PartyNetwork::GetNetworkStatistics() y GetEndpointStatistics() se pueden usar para consultar estadísticas agregadas para la red en su conjunto o para un punto de conexión local individual, respectivamente.
Si
options incluye PartySendMessageOptions::GuaranteedDelivery y el mensaje no se pudo entregar correctamente al servidor de retransmisión transparente en la nube para su reenvío a los puntos de conexión de destino, se generará un PartyNetworkDestroyedStateChange. En otras palabras, los mensajes con un requisito de entrega garantizada se entregarán o el cliente emisor se desconectará de la red. Cuando el servidor de retransmisión transparente en la nube reenvía el mensaje de entrega garantizada a cada dispositivo remoto que contiene uno o más puntos de conexión de destino, si el mensaje no se pudo entregar, el dispositivo remoto se desconectará igualmente de la red, lo que se indica mediante un PartyNetworkDestroyedStateChange. En otras palabras, un dispositivo que no reciba un mensaje con un requisito de entrega garantizada se desconectará de la red. La biblioteca Party fragmenta y vuelve a ensamblar automáticamente los mensajes grandes que superan el tamaño máximo admitido por el entorno, de modo que los autores de las llamadas no tengan que administrar esto. Sin embargo, hay una pequeña sobrecarga asociada a la fragmentación. Los autores de las llamadas que puedan enviar mensajes más pequeños o que puedan dividir de forma natural y eficiente por sí mismos las cargas de estado grandes pueden preferir hacerlo.
Si se invoca SendMessage() con una matriz de puntos de conexión de destino de cero entradas antes de autenticar correctamente a un primer usuario en la red, aunque no se haya notificado ningún punto de conexión remoto mediante cambios de estado PartyEndpointCreatedStateChange (y, por lo tanto, no se sepa que existen en la red), el mensaje se pondrá en cola de todos modos. Una vez que el primer usuario se haya autenticado correctamente y este punto de conexión local emisor se haya creado correctamente, el mensaje en cola se dirigirá entonces a todos los puntos de conexión remotos que existan en la red en ese momento posterior. Dado que en este caso el estado futuro de la red y el conjunto de puntos de conexión que finalmente recibirán el mensaje no se conocen en el momento de la llamada a SendMessage(), los títulos deben tener cuidado con el contenido que se coloca en dichos mensajes de difusión diferidos, o simplemente abstenerse de enviarlos hasta que este dispositivo local y este punto de conexión participen plenamente en la red.
Requisitos
Encabezado: Party.hConsulte también
PartyLocalEndpointPartySendMessageOptions
PartySendMessageQueuingConfiguration
PartyDataBuffersReturnedStateChange
PartyEndpointMessageReceivedStateChange
PartyNetwork::GetNetworkStatistics
PartyLocalEndpoint::GetEndpointStatistics
PartyLocalEndpoint::FlushMessages