Syntaxe
Paramètres
targetEndpointCount uint32_t
Le nombre de points de terminaison cibles dans le tableau targetEndpoints. Peut être zéro pour diffuser le message à tous les points de terminaison distants du réseau. Pour un appareil qui reçoit un message diffusé, les champs de points de terminaison cibles du PartyEndpointMessageReceivedStateChange sont renseignés avec tous les points de terminaison locaux de l’appareil.
targetEndpoints PartyEndpointArrayinput array of size
targetEndpointCount
Le tableau de targetEndpointCount entrées de pointeurs vers les objets PartyEndpoint cibles auxquels le message doit être envoyé. Il est ignoré lorsque targetEndpointCount vaut zéro.
options PartySendMessageOptions
Zéro ou plusieurs indicateurs d’option décrivant la façon d’envoyer le message.
queuingConfiguration PartySendMessageQueuingConfiguration*optional Une structure facultative décrivant le comportement du message lorsqu’il est en file d’attente localement en attendant une occasion d’être transmis. Peut être nullptr pour utiliser le comportement de mise en file d’attente par défaut.
dataBufferCount uint32_t
Le nombre de structures de mémoire tampon fournies dans le tableau dataBuffers. Doit être supérieur à 0.
dataBuffers PartyDataBuffer*input array of size
dataBufferCount
Le tableau de dataBufferCount entrées de structures PartyDataBuffer décrivant la charge utile du message à envoyer.
messageIdentifier void*optional Un pointeur de contexte opaque propre à l’appelant, que la bibliothèque Party inclut dans tous les changements d’état faisant référence à ce message. Il n’est ni interprété ni transmis à distance. Peut être nullptr si aucun contexte d’identification de message n’est nécessaire.
Valeur de retour
PartyErrorc_partyErrorSuccess si la mise en file d’attente du message pour transmission a réussi; sinon, un code d’erreur. Si cette méthode échoue, aucun changement d’état associé n’est généré. La forme lisible du code d’erreur peut être obtenue au moyen de PartyManager::GetErrorMessage().
Remarques
L’envoi de messages à des points de terminaison locaux n’est actuellement pas pris en charge. Si le tableau des points de terminaison cibles inclut des cibles locales, cet appel échoue de façon synchrone.Tous les points de terminaison ciblés d’un appareil donné reçoivent un seul PartyEndpointMessageReceivedStateChange, dans lequel chaque point de terminaison local ciblé figure dans le tableau receiverEndpoints du PartyEndpointMessageReceivedStateChange.
Si le tableau des points de terminaison cibles est spécifié comme ayant zéro entrée, le message est diffusé à tous les points de terminaison distants actuellement présents dans le réseau.
Les appelants fournissent 1 ou plusieurs structures PartyDataBuffer dans le tableau
dataBuffers. La mémoire référencée par ces structures n’a pas besoin d’être contiguë, ce qui permet par exemple d’avoir facilement une mémoire tampon d’en-tête fixe suivie d’une charge utile variable. Les mémoires tampons sont assemblées dans l’ordre, transmises et remises aux points de terminaison ciblés sous la forme d’un bloc de données contigu unique dans un PartyEndpointMessageReceivedStateChange. La bibliothèque Party ne consomme pas de bande passante pour transmettre des métadonnées décrivant la segmentation d’origine en PartyDataBuffer. Par défaut, les mémoires tampons décrites dans le tableau
dataBuffers de l’appelant sont copiées dans une mémoire tampon allouée avant le retour de SendMessage(). La spécification de PartySendMessageOptions::DontCopyDataBuffers évite cette étape de copie supplémentaire, mais oblige l’appelant à conserver la mémoire spécifiée dans chaque mémoire tampon valide et non modifiée jusqu’à ce qu’un PartyDataBuffersReturnedStateChange lui rende la propriété de cette mémoire. Les structures PartyDataBuffer elles-mêmes n’ont pas besoin de rester valides après le retour de l’appel à SendMessage(); seule la mémoire qu’elles référencent doit l’être. Les appelants qui utilisent PartySendMessageOptions::DontCopyDataBuffers peuvent fournir un contexte
messageIdentifier propre à l’appelant. Cette valeur de la taille d’un pointeur est incluse dans tous les PartyDataBuffersReturnedStateChanges afin que l’appelant puisse facilement accéder à ses propres informations privées de suivi des messages. La valeur réelle est traitée comme opaque et n’est ni interprétée par la bibliothèque Party, ni transmise à distance. Il incombe à l’appelant de s’assurer que toute mémoire lui appartenant que messageIdentifier pourrait représenter reste valide jusqu’à ce que le dernier changement d’état demandé associé au message et au messageIdentifier correspondant ait été traité et retourné au moyen de PartyManager::FinishProcessingStateChanges(). Les messages peuvent ne pas être transmis immédiatement aux points de terminaison cibles en raison de facteurs tels que la qualité de la connexion et la réactivité du destinataire. La file d’attente d’envoi locale grossit si vous envoyez plus rapidement que ce que la connexion à un point de terminaison est estimée pouvoir prendre en charge actuellement. Cela augmente l’utilisation de la mémoire et peut entraîner une augmentation de la latence perçue des messages; il est donc fortement recommandé aux appelants de surveiller et de gérer les files d’attente d’envoi locales. Vous pouvez récupérer des informations sur la file d’attente d’envoi à l’aide de PartyLocalEndpoint::GetEndpointStatistics(). Vous pouvez gérer la file d’attente d’envoi en réduisant la taille et/ou la fréquence des envois, en utilisant les paramètres facultatifs
queuingConfiguration pour configurer des délais d’expiration qui font expirer automatiquement les messages restés trop longtemps en file d’attente, ou en utilisant PartyLocalEndpoint::CancelMessages() pour supprimer explicitement tout ou partie des messages en file d’attente. Lorsque cette méthode retourne une réussite, la transmission du message a commencé ou le message a été mis en file d’attente avec succès en vue d’une transmission ultérieure. En particulier, un retour réussi de cette méthode n’implique pas que le message a été remis avec succès à des destinataires. L’API Party ne fournit actuellement aucun moyen de suivre la remise et le traitement des messages individuels. Les méthodes PartyNetwork::GetNetworkStatistics() et GetEndpointStatistics() peuvent être utilisées pour interroger des statistiques agrégées, respectivement pour l’ensemble du réseau ou pour un point de terminaison local individuel.
Si
options inclut PartySendMessageOptions::GuaranteedDelivery et que le message n’a pas pu être remis au serveur de relais infonuagique transparent pour être transféré aux points de terminaison cibles, un PartyNetworkDestroyedStateChange est généré. Autrement dit, les messages soumis à une exigence de remise garantie sont soit remis, soit le client émetteur est déconnecté du réseau. Lorsque le serveur de relais infonuagique transparent transfère le message à remise garantie à chaque appareil distant contenant un ou plusieurs points de terminaison cibles, si le message n’a pas pu être remis, l’appareil distant est également déconnecté du réseau, ce qui est signalé par un PartyNetworkDestroyedStateChange. Autrement dit, un appareil qui ne parvient pas à recevoir un message soumis à une exigence de remise garantie est déconnecté du réseau. La bibliothèque Party fragmente et réassemble automatiquement les messages volumineux qui dépassent la taille maximale prise en charge par l’environnement, afin que les appelants n’aient pas à le gérer. Toutefois, la fragmentation entraîne une légère surcharge. Les appelants qui peuvent envoyer des messages plus petits ou découper eux-mêmes efficacement les charges utiles d’état volumineuses peuvent souhaiter le faire.
Si SendMessage() est appelée avec un tableau de points de terminaison cibles sans entrée avant l’authentification réussie d’un premier utilisateur dans le réseau, le message est tout de même mis en file d’attente, même si aucun point de terminaison distant n’a été signalé au moyen de changements d’état PartyEndpointCreatedStateChange (et donc connu comme existant dans le réseau). Une fois que le premier utilisateur s’est authentifié avec succès et que ce point de terminaison local émetteur a été créé avec succès, le message en file d’attente cible alors tous les points de terminaison distants qui existent dans le réseau à ce moment-là. Comme l’état futur du réseau et l’ensemble des points de terminaison destinataires finaux ne sont pas connus au moment de l’appel à SendMessage() dans ce cas, les titres doivent faire preuve de prudence quant au contenu placé dans ces messages de diffusion différés, ou simplement s’abstenir de les soumettre tant que cet appareil local et ce point de terminaison ne participent pas pleinement au réseau.
Configuration requise
En-tête : Party.hVoir aussi
PartyLocalEndpointPartySendMessageOptions
PartySendMessageQueuingConfiguration
PartyDataBuffersReturnedStateChange
PartyEndpointMessageReceivedStateChange
PartyNetwork::GetNetworkStatistics
PartyLocalEndpoint::GetEndpointStatistics
PartyLocalEndpoint::FlushMessages