PartyLocalEndpoint::SendMessage

Sendet eine Nachricht an andere Endpunkte im Netzwerk.

Syntax

PartyError SendMessage(  
    uint32_t targetEndpointCount,  
    PartyEndpointArray targetEndpoints,  
    PartySendMessageOptions options,  
    const PartySendMessageQueuingConfiguration* queuingConfiguration,  
    uint32_t dataBufferCount,  
    const PartyDataBuffer* dataBuffers,  
    void* messageIdentifier  
)  

Parameter

targetEndpointCount uint32_t

Die Anzahl der Zielendpunkte im targetEndpoints Array. Kann null für die Übertragung an alle Remoteendpunkte im Netzwerk sein. Auf einem Gerät, das eine Broadcastnachricht empfängt, werden die Zielendpunktfelder von PartyEndpointMessageReceivedStateChange mit allen lokalen Endpunkten des Geräts aufgefüllt.

targetEndpoints PartyEndpointArray
Eingabearray der Größe targetEndpointCount

Das targetEndpointCount Einstiegsarray der Ziel-PartyEndpoint-Objektzeiger, an die die Nachricht gesendet werden soll. Dies wird ignoriert, wenn targetEndpointCount null ist.

options PartySendMessageOptions

Null oder mehr Optionsflags, die beschreiben, wie die Nachricht gesendet wird.

queuingConfiguration PartySendMessageQueuingConfiguration*
Optional

Eine optionale Struktur, die beschreibt, wie sich die Nachricht verhalten soll, während sie lokal in die Warteschlange eingereiht wird und auf eine Übertragungschance wartet. Kann nullptr sein, um standardmäßiges Warteschlangenverhalten zu verwenden.

dataBufferCount uint32_t

Die Anzahl der im dataBuffers Array bereitgestellten Pufferstrukturen. Muss größer als 0 sein.

dataBuffers PartyDataBuffer*
Eingabearray der Größe dataBufferCount

Das dataBufferCount Einstiegsarray von PartyDataBuffer-Strukturen, die die zu sendende Nachrichtennutzlast beschreiben.

messageIdentifier Leere*
Optional

Ein nicht transparenter, aufruferspezifischer Kontextzeiger, der von der Parteibibliothek in alle Zustandsänderungen eingeschlossen wird, die auf diese Nachricht verweisen. Es wird nicht interpretiert oder remote übertragen. Kann nullptr sein, wenn kein Nachrichtenidentifikationskontext erforderlich ist.

Rückgabewert

PartyError

c_partyErrorSuccess , wenn das Einreihen der Nachricht für die Übertragung erfolgreich war oder andernfalls ein Fehlercode vorhanden ist. Wenn bei dieser Methode ein Fehler auftritt, werden keine zugehörigen Zustandsänderungen generiert. Die lesbare Form des Fehlercodes kann über PartyManager::GetErrorMessage() abgerufen werden.

Hinweise

Das Senden von Nachrichten an lokale Endpunkte wird derzeit nicht unterstützt. Wenn das Array von Zielendpunkten lokale Ziele enthält, schlägt dieser Aufruf synchron fehl.

Allen Zielendpunkten auf einem bestimmten Gerät wird ein einzelner PartyEndpointMessageReceivedStateChange mit jedem lokalen Zielendpunkt bereitgestellt, der im Array "PartyEndpointMessageReceivedStateChange receiverEndpoints " bereitgestellt wird.

Wenn das Array von Zielendpunkten als null Einträge angegeben wird, wird die Nachricht an alle Remoteendpunkte übertragen, die sich derzeit im Netzwerk befinden.

Aufrufer stellen 1 oder mehr PartyDataBuffer-Strukturen im dataBuffers Array bereit. Der Speicher, auf den die Strukturen verweisen, muss nicht zusammenhängend sein, sodass beispielsweise ein fester Headerpuffer gefolgt von einer Variablennutzlast problemlos vorhanden ist. Die Puffer werden in der Reihenfolge zusammengestellt, übertragen und als einzelner zusammenhängender Datenblock in einem PartyEndpointMessageReceivedStateChange an die Zielendpunkte übermittelt. Die Parteibibliothek verbraucht keine Bandbreite zur Übertragung von Metadaten, um die ursprüngliche PartyDataBuffer-Segmentierung zu beschreiben.

Standardmäßig werden die im Array des dataBuffers Aufrufers beschriebenen Puffer in einen zugeordneten Puffer kopiert, bevor SendMessage() zurückgibt. Durch die Angabe von PartySendMessageOptions::D ontCopyDataBuffers wird dieser zusätzliche Kopierschritt vermieden. Stattdessen muss der Aufrufer den in jedem Puffer angegebenen Arbeitsspeicher gültig und unverändert lassen, bis ein PartyDataBuffersReturnedStateChange den Besitz des Speichers an den Aufrufer zurückgibt. Die PartyDataBuffer-Strukturen selbst müssen nicht gültig bleiben, nachdem der SendMessage()-Aufruf zurückgegeben wird, nur der Speicher, auf den sie verweisen.

Aufrufer, die PartySendMessageOptions::D ontCopyDataBuffers verwenden, können einen aufruferspezifischen messageIdentifier Kontext bereitstellen. Dieser Wert mit Zeigergröße wird in allen PartyDataBuffersReturnedStateChanges enthalten sein, sodass der Aufrufer problemlos auf seine eigenen Nachverfolgungsinformationen für private Nachrichten zugreifen kann. Der tatsächliche Wert wird als undurchsichtig behandelt und von der Parteibibliothek weder interpretiert noch remote übertragen. Es liegt in der Verantwortung des Aufrufers sicherzustellen, dass sein eigener Speicher, der möglicherweise repräsentiert, gültig bleibt, messageIdentifier bis die letzte angeforderte Zustandsänderung, die der Nachricht zugeordnet und zugeordnet messageIdentifier ist, verarbeitet und über PartyManager::FinishProcessingStateChanges()zurückgegeben wurde.

Nachrichten können basierend auf Faktoren wie Verbindungsqualität und Empfängerreaktionsfähigkeit nicht sofort an Zielendpunkte übertragen werden. Die lokale Sendewarteschlange wird vergrößert, wenn Sie schneller senden, als die Verbindung mit einem Endpunkt derzeit unterstützt wird. Dies erhöht die Arbeitsspeicherauslastung und kann zu einer erhöhung der wahrgenommenen Nachrichtenlatenz führen, sodass Anrufern dringend empfohlen wird, die lokalen Sendewarteschlangen zu überwachen und zu verwalten. Sie können Informationen zur Sendewarteschlange mithilfe von PartyLocalEndpoint::GetEndpointStatistics() abrufen. Sie können die Sendewarteschlange verwalten, indem Sie die Größe und/oder Häufigkeit des Sendens verringern, indem Sie die queuingConfiguration optionalen Einstellungen verwenden, um Timeouts zu konfigurieren, bei denen Nachrichten, die zu lange in die Warteschlange eingereiht wurden, automatisch ablaufen, oder indem Sie PartyLocalEndpoint::CancelMessages() verwenden, um einige oder alle Nachrichten in der Warteschlange explizit zu entfernen.

Wenn diese Methode den Erfolg zurückgibt, hat die Nachricht mit der Übertragung begonnen oder wurde erfolgreich für die zukünftige Übertragung in die Warteschlange eingereiht. Insbesondere bedeutet eine erfolgreiche Rückgabe dieser Methode nicht, dass die Nachricht erfolgreich an Empfänger übermittelt wurde. Die Party-API bietet derzeit keine Möglichkeit, die Übermittlung und Verarbeitung einzelner Nachrichten nachzuverfolgen. Die Methoden PartyNetwork::GetNetworkStatistics() und GetEndpointStatistics() können verwendet werden, um aggregierte Statistiken für das gesamte Netzwerk bzw. für einen einzelnen lokalen Endpunkt abzufragen.

Wenn optionsPartySendMessageOptions::GuaranteedDelivery umfasst und die Nachricht nicht erfolgreich an den Transparent Cloud Relay-Server zur Weiterleitung an die Zielendpunkte übermittelt werden konnte, wird ein PartyNetworkDestroyedStateChange generiert. Anders ausgedrückt: Nachrichten mit einer garantierten Übermittlungsanforderung werden entweder zugestellt, oder der sendende Client wird vom Netzwerk getrennt. Wenn der transparente Cloudrelayserver die garantierte Übermittlungsnachricht an jedes Remotegerät weiterleitet, das mindestens einen Zielendpunkt enthält, und wenn die Nachricht nicht übermittelt werden konnte, wird das Remotegerät ebenfalls vom Netzwerk getrennt, was durch einen PartyNetworkDestroyedStateChange angegeben wird. Anders ausgedrückt: Ein Gerät, das keine Nachricht mit einer garantierten Übermittlungsanforderung empfängt, wird vom Netzwerk getrennt.

Die Party-Bibliothek fragmentiert und zusammengesetzt automatisch große Nachrichten, die die maximale Größe überschreiten, die von der Umgebung unterstützt wird, sodass Aufrufer dies nicht verwalten müssen. Mit der Fragmentierung ist jedoch ein geringer Mehraufwand verbunden. Aufrufer, die in der Lage sind, kleinere Nachrichten zu senden oder auf andere Weise auf natürliche Weise große Zustandsnutzlasten effizient selbst aufzubrechen, können dies tun.

Wenn SendMessage() vor der erfolgreichen Authentifizierung eines ersten Benutzers im Netzwerk mit einem Nulleingabe-Zielendpunktarray aufgerufen wird, wird die Nachricht trotzdem in die Warteschlange gestellt, obwohl keine Remoteendpunkte über PartyEndpointCreatedStateChange-Statusänderungen gemeldet wurden (und daher bekannt ist, dass sie im Netzwerk vorhanden sind). Sobald der erste Benutzer erfolgreich authentifiziert wurde und dieser sendenden lokalen Endpunkt erfolgreich erstellt wurde, wird die Nachricht in der Warteschlange für alle Remoteendpunkte bestimmt, die zu diesem späteren Zeitpunkt im Netzwerk vorhanden sind. Da der zukünftige Zustand des Netzwerks und der Gruppe der letztendlich empfangenden Endpunkte in diesem Fall zum Zeitpunkt von SendMessage() nicht bekannt ist, sollten Titel vorsichtig sein, welche Inhalte in solchen verzögerten Broadcastnachrichten platziert werden, oder einfach davon absehen, sie zu übermitteln, bis dieses lokale Gerät und der Endpunkt vollständig am Netzwerk beteiligt sind.

Voraussetzungen

Header: Party.h

Weitere Informationen

PartyLocalEndpoint
PartySendMessageOptions
PartySendMessageQueuingConfiguration
PartyDataBuffersReturnedStateChange
PartyEndpointMessageReceivedStateChange
PartyNetwork::GetNetworkStatistics
PartyLocalEndpoint::GetEndpointStatistics
PartyLocalEndpoint::FlushMessages