语法
成员
priority int8_t
本地排队消息相对于聊天数据或从其他本地端点发送的消息的优先级。
priority 必须是介于 c_minSendMessageQueuingPriority 与 c_maxSendMessageQueuingPriority 之间(含端点)的值。较高的数字相对于较低的数字表示较高的相对优先级(将优先传输)。当未向 PartyLocalEndpoint::SendMessage() 提供 PartySendMessageQueuingConfiguration 结构时,默认值为 c_defaultSendMessageQueuingPriority,恰好位于有符号整数范围的正中间(零)。发送队列优先级不会修改从给定本地端点发送的消息的传输或送达顺序。它只影响来自不同本地端点的消息之间的排序,或端点与内部传输的聊天数据之间的排序(后者使用优先级
c_chatSendMessageQueuingPriority)。具有最高优先级值消息的本地端点发送队列中的消息将首先有资格被传输。如果本地端点排队的所有剩余消息优先级相同,则各消息将按其 PartyLocalEndpoint::SendMessage() 调用发生的相同顺序有资格被传输。一种理解此行为的方式是:高优先级消息会自动将同一本地端点先前所有消息的优先级提升到相同值,以确保及时递送该高优先级消息,同时不打破本地端点先前传输消息的顺序递送预期。其他本地端点具有自身的发送序列,因此没有此类排序保证(尽管 Party 库会尽最大努力在可能的情况下保留其原始发送顺序)。
当由于连接质量或接收方响应能力问题导致要发送的字节数超过连接能承载的字节数时,消息的发送队列优先级才有意义。以较高优先级发送更重要的消息可确保它们优先使用有限的网络资源。如果继续以快于成功传输速度的速率发送消息,则较低优先级的消息可能会被”饿死”,并且相关联的本地端点发送队列将持续增长。请务必通过使用 PartyLocalEndpoint::CancelMessages() 取消多余消息、使用
timeoutInMilliseconds 字段自动使排队时间过长的消息超时,或者干脆减小 PartyLocalEndpoint::SendMessage() 调用的大小和/或频率,来管理这种潜在增长。
identityForCancelFilters uint32_t
一个调用方定义的值,在使用取消筛选器表达式评估消息是否适用时使用。
此消息标识值可以具有任何特定于调用方的含义,Party 库不会解释它,仅供 PartyLocalEndpoint::CancelMessages() 在评估该消息是否与可选提供的取消筛选器表达式匹配时使用。当未向 PartyLocalEndpoint::SendMessage() 提供 PartySendMessageQueuingConfiguration 结构时,使用默认值零。
取消消息有助于在网络状况不佳时防止本地发送队列过度增长。当您有某类消息会定期携带最新信息发送,应替换先前排队但可能仍在等待传输机会的过时消息时,取消与特定筛选器表达式匹配的消息标识非常有效。当您有某个实例或某类机会性消息,其丢失并非致命并且不值得为其花费带宽以代替更有价值的排队消息时,取消也可能有用。
此本地标识值不是传输的数据负载的一部分。一旦消息开始传输,此值将不再适用,并且无法再由 PartyLocalEndpoint::CancelMessages() 从本地发送队列中移除。
timeoutInMilliseconds uint32_t
消息在等待传输机会时允许留在由 Party 管理的发送队列中的最长时间(以毫秒为单位)。
如果由于连接质量或接收方响应能力问题,消息在此超时时间过后仍未开始传输,则该消息将被中止并从队列中移除,不会被发送。timeoutInMilliseconds 值为零表示不应有超时,消息应保持排队状态,直到它被成功传输、被显式取消或遇到某些传输失败(例如远程断开连接)。当未向 PartyLocalEndpoint::SendMessage() 提供 PartySendMessageQueuingConfiguration 结构时,默认为零。消息发送队列超时有助于在网络状况不佳时防止发送队列过度增长。它非常适用于包含时间敏感的周期性数据的消息,对于这些消息,由于会定期发送更新的完整替代消息,传输已过时的消息会浪费带宽,而任何单个消息的丢失都不是致命的。
此超时值仅影响由 Party 管理的发送队列。它不影响实际传输消息所需的时间(环境延迟),也不会改变(如果适用)等待接收方确认传输所需的时间。
在向没有直接对等连接的目标发送时,此超时值会被评估两次:一次用于发送客户端到透明云中继的本地发送队列(受本地环境条件和到中继的传输速率影响),第二次在中继本身进行(中继可能会因远程目标的网络条件、传输速率或响应能力不同而被迫在转发前对消息进行排队)。
要求
头文件: Party.h另请参阅
Party 成员PartyLocalEndpoint::SendMessage