使用C API与PubSub+缓存
当客户端应用程序与 Solace PubSub+ 事件代理建立会话后，可以创建缓存会话并发起对缓存消息的请求（即缓存请求）。
在会话中发起缓存请求的基本步骤如下：
- 创建缓存会话。参见“创建缓存会话”。
- 发送缓存请求。参见“发送缓存请求”。
- 接收请求的缓存消息。参见“接收缓存消息”。
- 销毁缓存会话。参见“销毁缓存会话”。
创建缓存会话
缓存会话包含静态缓存属性和缓存状态信息，允许存在多个未完成的缓存请求，并对这些请求进行同步。
要在已连接的会话中创建缓存会话，请调用 solClient_session_createCacheSession() 函数，并传入以下列出的缓存会话属性。一个会话可以有多个缓存会话。
| 参数 | 描述 |
|---|---|
| SOLCLIENT_CACHESESSION_PROP_CACHE_NAME | 要发送缓存请求的分布式缓存、缓存集群或 PubSub+ 缓存实例的标识名称。 |
| 建议指定分布式缓存，因为指定 PubSub+ 缓存实例会绕过缓存请求的冗余和负载均衡。 | |
| SOLCLIENT_CACHESESSION_PROP_MAX_AGE | 要检索的消息的最大年龄（以秒为单位）。缓存时间超过此值的消息不会被检索。 |
值为 0 时，将返回符合 SOLCLIENT_CACHESESSION_PROP_MAX_MSGS 定义的主题的所有可能消息。 | |
| SOLCLIENT_CACHESESSION_PROP_MAX_MSGS | 对于任何一个主题，要检索的缓存消息的最大数量。如果某个主题的缓存消息数量超过最大值，则返回最新的消息。 |
值为 0 时，将检索比 SOLCLIENT_CACHESESSION_PROP_MAX_AGE 更新的所有消息。 | |
| SOLCLIENT_CACHESESSION_PROP_REPLY_TO | 缓存请求的回复主题。 |
| 在大多数情况下，建议不要指定此属性，以便 API 使用会话点对点回复主题。 | |
（有关更多信息，请参阅 PubSub+ 消息 API C 参考中的 SOLCLIENT_SESSION_PROP_P2PINBOX_IN_USE）。 | |
| SOLCLIENT_CACHESESSION_PROP_REQUESTREPLY_TIMEOUT_MS | 等待缓存对缓存请求的响应的时间量（以毫秒为单位）。这是一个每个请求的超时，应用程序发送的每个请求都可能导致多个底层请求。 |
缓存会话属性
发送缓存请求
要发送针对特定主题发布的阻塞和非阻塞缓存请求，请调用 solClient_cacheSession_sendCacheRequest() 并传入下表中列出的参数。
客户端需要处理请求超时问题，因为缓存集群、事件代理或单独的 PubSub+ 缓存实例可能在缓存请求处理过程中失败或断开连接。缓存响应会指示 PubSub+ 缓存实例是否处于丢失消息状态。有关详细信息，请参阅“丢失消息状态”。
| 参数 | 描述 |
|---|---|
| topic_p | 请求从缓存中获取消息的主题。主题中不支持使用 #noexport。 |
| 仅支持 FLOW_THRU 缓存请求的通配符缓存请求。当通配符请求匹配多个缓存主题时，返回的各个主题之间没有时间顺序保证 | |
| （尽管特定主题的消息之间仍然会保留时间顺序）。 | |
| 仅支持 FLOW_THRU 缓存请求的通配符缓存请求。当通配符请求匹配多个缓存主题时，返回的各个主题之间没有时间顺序保证（尽管特定主题的消息之间仍然会保留时间顺序）。 | |
| cacheRequestId | 由应用程序提供的 64 位整数，在缓存请求响应中返回给应用程序。请求 ID 也包含在返回的每条缓存消息中。 |
| callback_p | 用于无等待（即非阻塞）回复缓存请求的回调指针。 |
| user_p | 与回调一起返回的用户指针。 |
| cacheflags | 用于进一步定义缓存请求行为的标志。可用标志及其描述的列表，请参阅下表。 |
| subscribeflags | 通过缓存请求进行的订阅的订阅标志与通过常规主题订阅进行的订阅相同。有关更多信息，请参阅 PubSub+ 消息 API C 参考中提供的 solClient_session_topicSubscribeExt 的文档。 |
当设置缓存请求标志 SOLCLIENT_CACHEREQUEST_FLAGS_NO_SUBSCRIBE 时，将忽略订阅标志。 |
缓存请求消息参数
下表列出了可以在缓存请求上设置的可选标志。
发送缓存请求时，必须始终指定一个且仅一个 LIVEDATA 标志选项（没有默认值）。
| SOLCLIENT_CACHEREQUEST_FLAGS_NO_SUBSCRIBE | 如果设置了此标志，则不要将订阅与缓存请求一起添加到事件代理。仅向缓存集群发送缓存请求。
默认情况下，会自动为该主题添加订阅，然后添加缓存请求。通过添加订阅，客户端在接收完所有缓存消息后，将接收相关的实时数据消息。 |
| SOLCLIENT_CACHEREQUEST_FLAGS_LIVEDATA_FULFILL | 如果设置了此标志，则当与未完成的缓存请求主题匹配的实时数据在缓存响应之前到达时，允许实时数据满足缓存请求。随后匹配的缓存数据消息将被丢弃。 |
| SOLCLIENT_CACHEREQUEST_FLAGS_LIVEDATA_QUEUE | 如果设置了此标志，则将匹配缓存请求主题的接收到的实时数据消息排队，直到缓存请求完成。 |
| SOLCLIENT_CACHEREQUEST_FLAGS_LIVEDATA_FLOWTHRU | 如果设置了此标志，则将匹配缓存请求主题的接收到的实时 数据消息传递给应用程序。缓存请求可以保持未完成状态，同时实时数据消息正在被传递。随后匹配的缓存数据消息也会传递给应用程序。
对于通配符缓存请求，必须设置 SOLCLIENT_CACHEREQUEST_FLAGS_LIVEDATA_FLOWTHRU 标志。 |
| SOLCLIENT_CACHEREQUEST_FLAGS_NOWAIT_REPLY | 如果设置了此标志，则缓存请求将立即返回 SOLCLIENT_IN_PROGRESS 事件；当缓存请求完成时，其状态通过回调返回。
默认情况下，未设置此标志，发送缓存请求函数将阻塞，直到缓存请求完成。 |
| SOLCLIENT_CACHEREQUEST_FLAGS_LIVEDATA_FLOWTHRU | 如果设置了此标志，则将匹配缓存请求主题的接收到的实时数据消息传递给应用程序。缓存请求可以保持未完成状态，同时实时数据消息正在被传递。随后匹配的缓存数据消息也会传递给应用程序。
对于通配符缓存请求，必须设置 SOLCLIENT_CACHEREQUEST_FLAGS_LIVEDATA_FLOWTHRU 标志。 |
| SOLCLIENT_CACHEREQUEST_FLAGS_NOWAIT_REPLY | 如果设置了此标志，则缓存请求将立即返回 SOLCLIENT_IN_PROGRESS 事件；当缓存请求完成时，其状态通过回调返回。
默认情况下，未设置此标志，发送缓存请求函数将阻塞，直到缓存请求完成。 |
缓存请求标志
接收缓存消息
缓存消息通过 rxMsgCallbackFunc_t 回调接收。API 不会尝试对跨不同缓存集群接收的缓存消息进行重新排序。此外，API 不会尝试丢弃来自缓存集群或实时发布者的重复消息。
缓存中的消息可能会被缓存捆绑在一起，但消息 API 会单独将 它们传递给应用程序。
如果应用程序为标记为 SOLCLIENT_CACHEREQUEST_FLAGS_NOWAIT_REPLY（即非阻塞）的缓存请求注册了事件回调指针，则缓存请求状态将返回在 solCache_eventCallbackInfo solCache_eventCallbackInfo_t 结构中。
C API 支持缓存请求的主题分发。但是，如果为会话启用了主题分发，则作为缓存请求返回的消息只有在会话具有匹配的订阅时才会传递给会话接收回调。
下表列出了可以返回的返回代码。尽管这些代码也返回用于连接到事件代理的客户端的非缓存请求 API 调用，但提供的描述指示了这些事件对缓存请求的含义。
| 事件 | 描述 |
|---|---|
| SOLCLIENT_OK | 表示： |
- 在计时器到期之前收到了所有缓存回复
- 接收到的缓存消息中没有可疑消息
- 至少有一个缓存回复包含数据 | | SOLCLIENT_INCOMPLETE | 表示返回了不完整的数据。原因可能包括：
- 所有的缓存回复都没有数据
- 至少有一条消息是可疑的 | | SOLCLIENT_FAIL | 表示在初始缓存请求期间发生了错误。可能的原因包括：
- 等待缓存响应超时
- 缓存错误响应
- 添加订阅错误响应
- 与事件代理通信时的传输错误
- 如果在初始缓存请求之后发生错误（例如，与缓存集群中的其他 PubSub+ 缓存实例通信时），则返回
SOLCLIENT_INCOMPLETE。 - 如果发生故障，API 不会自动重试任何未完成的缓存请求。此外，如果与事件代理的连接丢失，则取消所有未完成的缓存请求。 |
缓存请求事件
销毁缓存会话
要取消所有未完成的请求并销毁缓存会话，请调用 solClient_cacheSession_destroy() 函数。可以从任何线程安全地调用此函数。
调用 solClient_cacheSession_destroy() 时
，会发生以下情况：
- 所有未完成的缓存请求都被取消。
- 已排队的实时消息被传递。
- 所有阻塞的同步缓存请求立即返回，返回代码为
INCOMPLETE，子代码为SOLCLIENT_SUBCODE_PARAM_NULL_PTR，以及“缓存会话已被销毁”的错误字符串。 - 不会为正在进行的异步缓存请求生成事件。
取消缓存请求
要取消所有未完成的请求，而不销毁缓存会话，请调用 solClient_cacheSession_cancelCacheRequests() 函数。可以从任何线程安全地调用此函数，并且可以重复调用。
调用 solClient_cacheSession_cancelCacheRequests() 时，会发生以下情况：
- 所有未完成的缓存请求都被取消。
- 所有已排队的实时消息都被传递。
- 所有阻塞的同步缓存请求立即返回，返回代码为
INCOMPLETE，子代码为SOLCLIENT_SUBCODE_CACHE_REQUEST_CANCELLED。 - 为每个正在进行的异步缓存请求生成一个缓存事件
SOLCACHE_EVENT_REQUEST_COMPLETED_NOTICE，子代码为SOLCLIENT_SUBCODE_CACHE_REQUEST_CANCELLED。