Syntaxe
enum class PartySendMessageOptions : int32_t
{
Default = 0x0000,
GuaranteedDelivery = 0x0001,
BestEffortDelivery = 0x0000,
SequentialDelivery = 0x0002,
NonsequentialDelivery = 0x0000,
CopyDataBuffers = 0x0000,
DontCopyDataBuffers = 0x0004,
CoalesceOpportunistically = 0x0000,
AlwaysCoalesceUntilFlushed = 0x0008,
RequireTimelyAcknowledgement = 0x0000,
AllowLazyAcknowledgement = 0x0010,
}
Constantes
| Constante | Description |
|---|---|
| Default | Utiliser les PartySendMessageOptions par défaut. Les options par défaut sont BestEffortDelivery, NonsequentialDelivery, CopyDataBuffers, CoalesceOpportunistically et RequireTimelyAcknowledgement. |
| GuaranteedDelivery | Garantir la remise du message à toutes les cibles, en le retransmettant si nécessaire. Cet indicateur d’option garantit que le message parviendra à chaque point de terminaison cible, quelle que soit la perte de paquets dans l’environnement, sauf si le point de terminaison cible est détruit. Les transmissions de paquets sont retentées si nécessaire. Cet indicateur d’option convient bien à l’envoi d’informations d’état importantes qui doivent toujours atteindre leur destination, faute de quoi la cible doit être retirée du réseau. Utilisez-le avec un contenu de message qui ne présente pas de redondance ni de possibilité d’interpolation ou d’extrapolation en cas de perte, et qui justifie l’augmentation potentielle de l’utilisation de la bande passante si des retransmissions de paquets sont nécessaires. La garantie de remise à elle seule n’implique pas la garantie d’un ordre de remise particulier; utilisez l’indicateur d’option SequentialDelivery pour imposer l’ordre. |
| BestEffortDelivery | Transmettre le message au mieux en ignorant toute perte de paquets. Cet indicateur d’option ne demande qu’une seule tentative de transmission du message. En cas de perte de paquets dans l’environnement, la transmission n’est pas retentée et l’application doit être prête à gérer l’absence du message. Cet indicateur d’option convient bien aux informations constamment mises à jour qui n’exigent pas que chaque mise à jour arrive. Utilisez-le avec un contenu de message qui présente déjà une redondance ou une possibilité d’interpolation ou d’extrapolation en cas de perte, et qui ne justifie pas de bande passante supplémentaire pour la retransmission. Il s’agit de la valeur par défaut si l’indicateur d’option GuaranteedDelivery n’est pas spécifié. |
| SequentialDelivery | Remettre le message dans l’ordre par rapport aux autres messages envoyés de façon séquentielle depuis ce point de terminaison local vers le point de terminaison cible. SequentialDelivery ne fournit aucune garantie quant à l’ordre des messages envoyés depuis différents points de terminaison locaux et/ou vers différents points de terminaison cibles. Chaque paire de points de terminaison doit être considérée comme un espace de séquence distinct. Aucune garantie n’est donnée quant à l’ordre des messages séquentiels par rapport aux messages non séquentiels. Cet indicateur d’option convient bien aux informations d’état qui doivent atteindre leur destination dans une séquence particulière, même si cela implique une efficacité réseau légèrement moindre et éventuellement une attente un peu plus longue pour les recevoir en cas de perte ou de réordonnancement des paquets par l’environnement. L’utilisation de SequentialDelivery avec GuaranteedDelivery peut entraîner la mise en file d’attente de messages sur le point de terminaison cible en attendant l’arrivée de messages séquentiels envoyés précédemment. Cela peut entraîner une augmentation perçue de la latence en cas de perte ou de réordonnancement des paquets dans l’environnement, mais le point de terminaison cible voit toujours chaque message, dans l’ordre dans lequel ils ont été envoyés. L’utilisation de SequentialDelivery avec BestEffortDelivery peut entraîner l’abandon de messages si l’un d’eux arrive au point de terminaison cible dans le désordre alors qu’un message séquentiel ultérieur a déjà été remis. Le point de terminaison cible voit toujours la séquence progresser, mais elle peut présenter des lacunes. Un message plus ancien n’est jamais remis après un message plus récent. |
| NonsequentialDelivery | Remettre le message aux cibles dès son arrivée. Les messages envoyés avec l’option de remise non séquentielle ne fournissent aucune garantie quant à l’ordre dans lequel ils sont remis par rapport à d’autres messages, séquentiels ou non. Ils sont remis aux cibles dès leur arrivée, ce qui peut ne pas correspondre à l’ordre dans lequel ils ont été envoyés en cas de perte ou de réordonnancement des paquets par l’environnement. Cet indicateur d’option convient bien aux messages qui peuvent être traités dans n’importe quel ordre ou qui contiennent déjà leurs propres informations d’ordre, et lorsque vous souhaitez une efficacité réseau maximale et la latence perçue la plus faible. Il s’agit de la valeur par défaut si l’indicateur d’option SequentialDelivery n’est pas spécifié. |
| CopyDataBuffers | Demande à la bibliothèque Party d’effectuer une copie des mémoires tampons de données fournies en vue de leur transmission ultérieure. Le contenu de la mémoire des structures PartyDataBuffer fournies est copié, de sorte que l’appelant n’a pas besoin de conserver les mémoires tampons après le retour de PartyLocalEndpoint::SendMessage(). Cette option est plus pratique, mais légèrement moins efficace que l’utilisation de l’indicateur d’option DontCopyDataBuffers. Il s’agit de la valeur par défaut si l’indicateur d’option DontCopyDataBuffers n’est pas spécifié. |
| DontCopyDataBuffers | Indique à la bibliothèque Party d’utiliser directement les mémoires tampons de données fournies et que l’appelant conservera la mémoire valide jusqu’à ce que la bibliothèque n’en ait plus besoin. La mémoire référencée par les structures PartyDataBuffer fournies n’est pas copiée; sa propriété est plutôt transférée temporairement à la bibliothèque Party afin que la mémoire puisse être accessible directement, sans surcharge de copie supplémentaire pendant le processus de transmission. Il incombe à l’appelant de s’assurer que les mémoires tampons restent valides et non modifiées jusqu’à ce que la bibliothèque n’en ait plus besoin et que leur propriété lui soit rendue au moyen d’un PartyDataBuffersReturnedStateChange. Cette option est plus efficace, mais peut être moins pratique que l’utilisation de l’option CopyDataBuffers. Les structures PartyDataBuffer elles-mêmes n’ont pas besoin de rester valides après le retour de l’appel à PartyLocalEndpoint::SendMessage(); seule la mémoire qu’elles référencent doit l’être. |
| CoalesceOpportunistically | Spécifie que ce message doit être regroupé avec les autres messages en file d’attente, mais ne doit pas retarder la transmission s’il n’y en a aucun en attente. Le regroupement de plusieurs messages en un seul paquet permet de maximiser l’efficacité de la bande passante (en réduisant la surcharge par paquet), au détriment potentiel de la latence perçue d’un message si vous retardez sa transmission pour le regrouper. L’envoi avec cet indicateur amène la bibliothèque Party à regrouper le message si d’autres messages en file d’attente sont disponibles, mais pas à attendre d’autres messages s’il n’y en a aucun et que ce message peut être transmis immédiatement. Utilisez cet indicateur si vous regroupez généralement vos mises à jour réseau en messages uniques et périodiques, peu susceptibles d’être mis en file d’attente en même temps que d’autres messages, et pour lesquels un retard n’améliorerait pas l’efficacité de la bande passante. Cet indicateur ne garantit pas que la transmission du message commence immédiatement. Si la qualité de la connexion ou la réactivité du destinataire ne semblent pas encore permettre l’envoi de données supplémentaires, le message peut être mis en file d’attente en attendant la prochaine occasion de transmission. Il s’agit de la valeur par défaut si l’indicateur d’option AlwaysCoalesceUntilFlushed n’est pas spécifié. |
| AlwaysCoalesceUntilFlushed | Spécifie que ce message doit toujours tenter d’être regroupé avec d’autres messages et attendre un appel à PartyLocalEndpoint::FlushMessages() pour commencer sa transmission. Le regroupement de plusieurs messages en un seul paquet permet de maximiser l’efficacité de la bande passante (en réduisant la surcharge par paquet), au détriment potentiel de la latence perçue d’un message si vous retardez sa transmission pour le regrouper. L’envoi avec cet indicateur amène la bibliothèque Party à toujours privilégier le regroupement du message et à retarder sa transmission jusqu’à l’appel de PartyLocalEndpoint::FlushMessages(). Envisagez d’utiliser cet indicateur si vous envoyez généralement de nombreux petits messages aux mêmes cibles dans la même boucle de mise à jour et que vous souhaitez indiquer explicitement à la bibliothèque Party quand l’itération complète de la boucle de mise à jour est terminée. Même avec cet indicateur, il existe des scénarios dans lesquels la transmission du message peut commencer sans appel explicite à PartyLocalEndpoint::FlushMessages(). Cela peut se produire lorsque d’autres messages en file d’attente sont déjà en cours de transmission pour d’autres raisons et que le paquet a de la place pour inclure ce message. De même, lorsqu’il existe suffisamment d’octets de données de messages pour envoyer un paquet complet et qu’aucun autre regroupement n’est possible, le paquet est envoyé. L’appel de PartyLocalEndpoint::FlushMessages() alors que la transmission de tous les messages a déjà commencé est sans conséquence. |
| RequireTimelyAcknowledgement | Indique que la réception de ce message doit être confirmée (si nécessaire) rapidement. Les destinataires accusent réception des messages pour informer l’expéditeur de la réussite ou de l’échec de la remise, afin qu’il puisse par exemple retenter l’envoi des paquets perdus contenant des messages envoyés avec l’indicateur d’option GuaranteedDelivery. Les accusés de réception sont souvent transportés par des paquets dans le cadre d’une communication bidirectionnelle classique; toutefois, si aucun paquet ne circule dans le sens retour, cet indicateur demande aux points de terminaison cibles de n’attendre qu’un court délai, géré en interne, des occasions de transport avant de forcer l’envoi de paquets d’accusé de réception pour informer l’expéditeur. Ce paquet dédié entraîne une légère surcharge, mais garantit que l’expéditeur obtient rapidement l’état nécessaire pour effectuer les nouvelles tentatives requises. L’utilisation de cet indicateur est recommandée pour la plupart des messages à remise garantie. Il convient bien aux messages sensibles à la latence. Il convient également lorsque les envois bidirectionnels à remise garantie sont peu fréquents ou imprévisibles. Il s’agit de la valeur par défaut si l’indicateur d’option AllowLazyAcknowledgement n’est pas spécifié. Cet indicateur est ignoré si l’indicateur d’option GuaranteedDelivery n’est pas spécifié. |
| AllowLazyAcknowledgement | Indique que la réception de ce message peut être confirmée au moment opportun plutôt qu’en urgence. Les destinataires accusent réception des messages pour informer l’expéditeur de la réussite ou de l’échec de la remise, afin qu’il puisse par exemple retenter l’envoi des paquets perdus contenant des messages envoyés avec l’indicateur d’option GuaranteedDelivery. Les accusés de réception sont souvent transportés par des paquets dans le cadre d’une communication bidirectionnelle classique; toutefois, si aucun paquet ne circule dans le sens retour, cet indicateur demande aux points de terminaison cibles d’attendre des occasions de transport sans forcer l’envoi de paquets d’accusé de réception pour informer l’expéditeur. Cela retarde le moment où l’expéditeur connaît l’état nécessaire aux éventuelles nouvelles tentatives, mais évite la surcharge supplémentaire d’un paquet dédié. Envisagez d’utiliser cet indicateur pour les messages à remise garantie de type « envoyer et oublier » qui ne sont pas sensibles à la latence. Il peut également réduire la surcharge lorsque les envois bidirectionnels sont fréquents. Cet indicateur est ignoré si l’indicateur d’option GuaranteedDelivery n’est pas également spécifié. |
Configuration requise
En-tête : Party.hVoir aussi
Membres de PartyPartySendMessageQueuingConfiguration
PartyDataBuffersReturnedStateChange
PartyLocalEndpoint::SendMessage
PartyLocalEndpoint::FlushMessages