Working with the C API

When a session has been established with a Solace router, a client application can create a cache session and then make requests for cached messages (that is, cache requests).

The basic steps to make a cache request in a session are:

  1. Create a cache session. Refer to Creating Cache Sessions.
  2. Send a cache request. Refer to Sending Cache Requests.
  3. Receive requested cached messages. Refer toReceiving Cached Messages.
  4. Destroy the cache session. Refer to Destroying Cache Sessions.

Creating Cache Sessions

A cache session contains static cache properties and cache state information, and it allows multiple outstanding cache requests and synchronizes those requests.

To create a cache session in a connected session, call the solClient_session_
createCacheSession()
function and pass in the cache session properties listed below. A single session can have many cache sessions.

Cache Session Properties

Parameter

Description

SOLCLIENT_CACHESESSION_PROP_
CACHE_NAME

The identifying name of the Distributed Cache, Cache Cluster, or SolCache Instance to send the cache requests to.

Note:  Specifying the Distributed Cache is the preferred method because specifying a SolCache Instance bypasses redundancy and load balancing of cache requests.

SOLCLIENT_CACHESESSION_PROP_
MAX_AGE

The maximum age (in seconds) of the messages to retrieve. Messages that have been cached for more than this amount of time are not retrieved.

Note:  A value of 0 returns all possible messages for the topic, as defined by SOLCLIENT_
CACHESESSION_PROP_MAX_MSGS
.

SOLCLIENT_CACHESESSION_PROP_
MAX_MSGS

The maximum number of cached messages to retrieve for any one topic. If more messages are cached for a topic than the maximum value, the newest messages are returned.

Note:  A value of 0 retrieves all messages newer than SOLCLIENT_CACHESESSION_PROP_MAX_AGE.

SOLCLIENT_CACHESESSION_PROP_
REPLY_TO

The reply-to topic for the cache request.

For most situations, it is recommended that this property be left unspecified so that the API uses the session P2P Reply To Topic. (For more information, refer to SOLCLIENT_SESSION_PROP_
P2PINBOX_IN_USE
in C API Developer Reference).

SOLCLIENT_CACHESESSION_PROP_
REQUESTREPLY_TIMEOUT_MS

The amount of time (in milliseconds) to wait for a response to the cache request from the cache. This is a per-request timeout where each request sent by the application could result in multiple underlying requests.

Using Secure Connections

By default, the client connection that is established to a Solace router through a Session is unsecured. That is, the messaging data that is sent between a client and a router through the Session is transmitted using Solace Messaging Format (SMF) as plain text. However, it is also possible to establish a secure Session that uses Transport Layer Security (TLS)/ Secure Sockets Layer (SSL) protocols so that the SMF data is encrypted. For information on how to configure specific TLS/SSL Session properties and establish a secure Session, refer to Creating Secure Sessions.

To use secure connections, the Solace router must also be properly configured for TLS/ SSL service, and the appropriate server certificate must be in place. For information on configuring a Solace router to allow for secure connections, refer to Managing TLS/SSL Service.

Sending Cache Requests

To send a blocking and non-blocking cache request for messages published to a specific topic, call solClient_cacheSession_sendCacheRequest() and pass in the parameters listed in the table below.

Note:  It is up to the client to deal with request timeouts as it is possible that Cache Clusters, Solace routers, or individual SolCache Instances may fail or disconnect in the middle of cache request processing. The cache response indicates whether the SolCache Instance is in a lost message state. Refer to Lost Message State for details.

Cache Request Message Parameters

Parameter

Description

opaqueCacheSession_p

The opaque cache session pointer returned when the cache session was created.

topic_p

The topic for which messages are requested from the cache.

Note:  Wildcard cache requests are only supported for FLOW_THRU cache requests. When a wildcard request matches multiple cached subjects, there are no temporal ordering guarantees between the individual topics returned (although temporal ordering will still be preserved amongst the messages for a specific topic).

cacheRequestId

A 64-bit integer provided by the application that is returned to the application in the cache request response. The request ID is also available in every cached message returned.

callback_p

A callback pointer for a no-wait (that is non‑blocking) reply to cache requests.

user_p

A user pointer to return with a callback.

cacheflags

Flags that are used to further define the cache request behavior. For list of the available flags and their descriptions, refer to the following table.

subscribeflags

The subscription flags for a subscription made through a cache request are the same as those made through a regular topic subscription. For more information, refer to the documentation provided for solClient_session_
topicSubscribeExt
in the C API Developer Reference.

Note:  When the cache request flag SOLCLIENT_
CACHEREQUEST_FLAGS_NO_SUBSCRIBE
is set, subscription flags are ignored.

The following table lists the optional flags that can be set on a cache request.

Note:  When sending cache requests you must always specify one and only one of the LIVEDATA flag options (there is no default).

Cache Request Flags

Parameter

Description

SOLCLIENT_CACHEREQUEST_FLAGS_
NO_SUBSCRIBE

If this flag is set, do not include a subscription to the Solace router with the cache request. Only send a cache request to the Cache Cluster.

By default, a subscription is automatically added for the topic then the cache request is added. By adding the subscription, the client will receive relevant live data messages after it has received all of the cached messages.

SOLCLIENT_CACHEREQUEST_FLAGS_
LIVEDATA_FULFILL

If this flag is set, when live data that matches the outstanding cache request topic arrives before the cache response, allow the live data to fulfill the cache request. Any subsequent matching cached data messages are discarded.

SOLCLIENT_CACHEREQUEST_FLAGS_
LIVEDATA_QUEUE

If this flag is set, queue received live data messages that match the cache request topic until the cache request completes.

SOLCLIENT_CACHEREQUEST_FLAGS_
LIVEDATA_FLOWTHRU

If this flag is set, received live data messages that match the cache request topic are passed through to the application. A cache request can remain outstanding while live data messages are being passed through. The subsequent matching cached data messages are also delivered to the application.

Note:  The SOLCLIENT_CACHEREQUEST_FLAGS_
LIVEDATA_FLOWTHRU
flag must be set for wildcard cache requests.

SOLCLIENT_CACHEREQUEST_FLAGS_
NOWAIT_REPLY

If this flag is set, the cache request returns immediately with the SOLCLIENT_IN_PROGRESS event; when the cache request completes, its status is returned through a callback.

By default, this flag is not set, and the send cache request function blocks until the cache request is complete.

Receiving Cached Messages

Cached messages are received through the rxMsgCallbackFunc_t callback. The API does not attempt to reorder cached messages that are received across different Cache Clusters. In addition, the API does not attempt to drop duplicate messages received from Cache Clusters or live publishers.

Note:  Messages in cache responses may be bundled together by the cache, but they are delivered to applications individually by the messaging API.

If an application registers an event callback pointer with cache requests flagged as SOLCLIENT_CACHEREQUEST_FLAGS_NOWAIT_REPLY (that is, non-blocking), the cache request status is returned in the solCache_eventCallbackInfo solCache_eventCallbackInfo_t structure.

NOTICE: The C API supports topic dispatch on cache requests. However, if topic dispatch is enabled for a session, messages returned as part of a cache request are only delivered to the session receive callback if the session has a matching subscription.

The following table lists the return codes that can be returned. Although these codes are also returned for non-cache request API calls for clients connecting to a Solace router, the provided descriptions indicate what the events signify for a cache request.

Cache Request Events

Event

Description

SOLCLIENT_OK

Indicates that:

  • the cache replies were all received before the timer expired
  • none of the received cached messages were suspect
  • at least one cache reply had data

SOLCLIENT_INCOMPLETE

Indicates that incomplete data has been returned. Reasons might include:

  • all of the cache replies contained no data
  • at least one message was suspect

SOLCLIENT_FAIL

Indicates that an error occurred during the initial cache request. Possible reasons include:

  • timeout waiting for a cache response
  • a cache error response
  • an add subscription error response
  • a transport error when communicating with the Solace router

Note:  If an error occurs after the initial cache request (for example, when communicating with other SolCache instances in the Cache Cluster), then SOLCLIENT_INCOMPLETE is returned.

Note:  If a failure occurs, the API does not automatically retry any outstanding cache requests. In addition, if there is a loss of connection with the Solace router, any outstanding cache requests are canceled.

Destroying Cache Sessions

To cancel all outstanding requests and destroy the cache session, call the solClient_cacheSession_destroy() function. It is safe to call this function from any thread.

When solClient_cacheSession_destroy() is called, the following occurs:

  • all outstanding cache requests are canceled
  • live messages that have been queued are delivered
  • all blocked synchronous cache requests return immediately with an INCOMPLETE return code, a SOLCLIENT_SUBCODE_PARAM_NULL_PTR subcode, and a “Cache session has been destroyed” error string
  • no event is generated for in-progress asynchronous cache requests

Canceling Cache Requests

To cancel all outstanding requests, without destroying the cache session, call the solClient_cacheSession_cancelCacheRequests() function. It is safe to call this function from any thread, and it can be called repeatedly.

When solClient_cacheSession_cancelCacheRequests() is called, the following occurs:

  • all outstanding cache requests are canceled.
  • all live messages that have been queued are delivered
  • all blocked synchronous cache requests return immediately with an INCOMPLETE return code and a SOLCLIENT_SUBCODE_CACHE_REQUEST_
    CANCELLED
    subcode
  • a cache event SOLCACHE_EVENT_REQUEST_COMPLETED_NOTICE with a subcode of SOLCLIENT_SUBCODE_CACHE_REQUEST_CANCELLED is generated for each in‑progress asynchronous cache request