PartyLocalEndpoint::SendMessage

向网络中的其他终结点发送消息。

Syntax

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

Parameters

targetEndpointCount uint32_t targetEndpoints 数组中目标终结点的数量。可以为零以向网络中的所有远程终结点广播。接收广播消息的设备的 PartyEndpointMessageReceivedStateChange 的目标终结点字段将填充该设备的所有本地终结点。 targetEndpoints PartyEndpointArray
input array of size targetEndpointCount 应向其发送消息的、包含 targetEndpointCount 个条目的目标 PartyEndpoint 对象指针数组。当 targetEndpointCount 为零时，将忽略此参数。 options PartySendMessageOptions 描述如何发送消息的零个或多个选项标志。 queuingConfiguration PartySendMessageQueuingConfiguration*
optional 描述消息在本地排队并等待传输机会时的行为方式的可选结构。可以为 nullptr 以使用默认排队行为。 dataBufferCount uint32_t dataBuffers 数组中提供的缓冲区结构的数量。必须大于 0。 dataBuffers PartyDataBuffer*
input array of size dataBufferCount 描述要发送的消息有效负载的、包含 dataBufferCount 个 PartyDataBuffer 结构条目的数组。 messageIdentifier void*
optional 一个不透明的、特定于调用方的上下文指针，Party 库将包含在引用此消息的任何状态更改中。它不会被解释或远程传输。如果不需要消息标识上下文，可以为 nullptr。

Return value

PartyError 如果将消息排队进行传输成功，则返回 c_partyErrorSuccess；否则返回错误代码。如果此方法失败，则不会生成相关的状态更改。可通过 PartyManager::GetErrorMessage() 检索错误代码的可读形式。

Remarks

当前不支持向本地终结点发送消息。如果目标终结点数组包含任何本地目标，此调用将同步失败。

给定设备上的所有目标终结点将获得单个 PartyEndpointMessageReceivedStateChange，每个目标本地终结点都会在 PartyEndpointMessageReceivedStateChange receiverEndpoints 数组中提供。

如果目标终结点数组被指定为具有零个条目，则消息将广播到当前网络中的所有远程终结点。

调用方在 dataBuffers 数组中提供 1 个或多个 PartyDataBuffer 结构。这些结构引用的内存不必是连续的，这使得例如轻松拥有一个固定标头缓冲区后跟一个可变有效负载成为可能。缓冲区将按顺序组装、传输，并作为单个连续数据块在 PartyEndpointMessageReceivedStateChange 中传递给目标终结点。Party 库不会消耗带宽来传输元数据以描述原始 PartyDataBuffer 分段。

默认情况下，在 SendMessage() 返回之前，调用方 dataBuffers 数组中描述的缓冲区将被复制到分配的缓冲区。指定 PartySendMessageOptions::DontCopyDataBuffers 将避免此额外的复制步骤，而要求调用方在 PartyDataBuffersReturnedStateChange 将内存的所有权返回给调用方之前，保持每个缓冲区中指定的内存有效且未修改。SendMessage() 调用返回后，PartyDataBuffer 结构本身不需要保持有效，只需要它们引用的内存保持有效。

使用 PartySendMessageOptions::DontCopyDataBuffers 的调用方可以提供特定于调用方的 messageIdentifier 上下文。此指针大小的值将包含在所有 PartyDataBuffersReturnedStateChanges 中，以便调用方可以轻松访问其自己的私有消息跟踪信息。实际值被视为不透明，Party 库不会解释它，也不会远程传输。调用方有责任确保 messageIdentifier 可能表示的任何其自己的内存在与消息及相关的 messageIdentifier 关联的最终请求状态更改已通过 PartyManager::FinishProcessingStateChanges() 处理并返回之前，保持有效。

由于连接质量和接收方响应能力等因素，消息可能不会立即传输到目标终结点。如果发送速度超过当前估计的连接支持速度，本地发送队列将会增长。这会增加内存使用量，并可能增加感知的消息延迟，因此强烈建议调用方监视和管理本地发送队列。可以使用 PartyLocalEndpoint::GetEndpointStatistics() 检索有关发送队列的信息。可以通过减小发送大小和/或频率、使用 queuingConfiguration 可选设置来配置超时以自动使排队时间过长的消息过期，或使用 PartyLocalEndpoint::CancelMessages() 显式删除部分或全部排队消息来管理发送队列。

当此方法返回成功时，消息已开始传输或已成功排队以供将来传输。特别是，此方法的成功返回并不意味着消息已成功传递给任何接收者。Party API 目前未提供跟踪单个消息传递和处理的方法。PartyNetwork::GetNetworkStatistics() 和 GetEndpointStatistics() 方法可分别用于查询整个网络或单个本地终结点的聚合统计信息。

如果 options 包括 PartySendMessageOptions::GuaranteedDelivery 并且消息无法成功传递到透明云中继服务器以转发到目标终结点，则将生成 PartyNetworkDestroyedStateChange。换句话说，具有保证传递要求的消息要么被传递，要么发送客户端将断开与网络的连接。当透明云中继服务器将保证传递消息转发到包含一个或多个目标终结点的每个远程设备时，如果消息无法传递，远程设备同样将从网络断开连接，由 PartyNetworkDestroyedStateChange 指示。换句话说，未能接收具有保证传递要求的消息的设备将从网络断开连接。

Party 库会自动分段和重组超过环境支持的最大大小的大型消息，因此调用方无需管理此操作。但是，与分段相关联有少量开销。能够发送较小消息或以其他方式自然地有效地分解大型状态有效负载的调用方可能希望这样做。

如果在成功地将第一个用户身份验证到网络之前调用了带有零条目目标终结点数组的 SendMessage()，那么即使尚未通过 PartyEndpointCreatedStateChange 状态更改报告任何远程终结点（因此已知在网络中存在），消息仍将排队。一旦第一个用户成功进行身份验证并且此发送本地终结点已成功创建，排队消息将随后针对该稍后时间在网络中存在的所有远程终结点。因为在这种情况下，SendMessage() 时未知网络的未来状态和最终接收终结点集，标题应谨慎处理放入此类延迟广播消息中的内容，或者干脆完全不提交它们，直到此本地设备和终结点完全参与网络。

Requirements

Header: Party.h

XBOX Services

PlayFab

Syntax

Parameters

Return value

Remarks

Requirements

See also

​Syntax

​Parameters

​Return value

​Remarks

​Requirements

​See also

Syntax

Parameters

Return value

Remarks

Requirements

See also