通过

PartyLocalEndpoint::SendMessage

  • 项目

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

语法

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

参数

targetEndpointCount uint32_t

targetEndpoints 数组中的目标终结点数量。 广播到网络中的所有远程终结点时可能为零。 接收广播消息的设备将使用该设备的所有本地终结点填充 PartyEndpointMessageReceivedStateChange 的目标终结点字段。

targetEndpoints PartyEndpointArray
大小的输入数组targetEndpointCount

消息应发送到的目标 PartyEndpoint 对象指针的 targetEndpointCount 条目数组。 如果 targetEndpointCount 为零，此项将被忽略。

options PartySendMessageOptions

描述如何发送消息的零个或多个选项标志。

queuingConfiguration PartySendMessageQueuingConfiguration*
可选

描述消息在本地排队和等待传输机会时的行为方式的可选结构。 使用默认队列行为时可能为 nullptr。

dataBufferCount uint32_t

dataBuffers 数组中提供的缓冲区结构数量。 必须大于 0。

dataBuffers PartyDataBuffer*
大小的输入数组dataBufferCount

PartyDataBuffer 结构的 dataBufferCount 条目数组，描述要发送的消息有效负载。

messageIdentifier void*
可选

一个不透明的、特定于调用方的上下文指针，Party 库将包含在引用此消息的任何状态更改中。 它不会被远程解释或传输。 如果不需要消息标识上下文，则可能为 nullptr。

返回值

PartyError

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

备注

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

将为给定设备上的所有目标终结点提供一个单独的 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，并且无法将消息成功传递到透明云中继服务器以转发到目标终结点，则将生成 PartyNetworkDestestedStateChange。 换句话说，具有保证传递需求的消息将被传递，否则发送客户端将与网络断开连接。 当透明云中继服务器将保证传递的消息转发到包含一个或多个目标终结点的各个远程设备时，如果无法传递该消息，则远程设备将同样断开与网络的连接，由 PartyNetworkDestestedStateChange 指示。 换句话说，无法接收具有保证传递要求的消息的设备将断开与网络的连接。

Party 库自动对超过环境支持的最大大小的大型消息进行分段和重新汇编，这样调用方就无需对此进行管理。 但是，存在与碎片相关的少量开销。 能够发送较小消息或以其他方式自然有效地分解大型状态有效负载的调用方可能希望这样做。

如果在成功验证第一个用户进入网络之前使用零条目目标端点数组调用 SendMessage()，那么即使没有远程端点通过 PartyEndpointCreatedStateChange 状态更改报告 (且因此已知存在于网络中)，消息仍将排队。 一旦第一个用户成功进行身份验证，并且该发送的本地端点成功创建，那么排队的消息随后就会面向网络中存在的所有远程端点。 因为在这种情况下，网络的未来状态和最终接收端点的集合在 SendMessage() 时并不为人所知，所以游戏应该谨慎对待这种延迟广播消息中放置的内容，或者干脆不提交，直到该本地设备和端点完全参与网络。

要求

标题： Party.h

另请参阅

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