PubSub+ Messaging API For C  7.30.0.2
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
solCache.h File Reference

Include file for the Solace Corporation Messaging API for C. More...

#include "solClient.h"

Data Structures

struct  solCache_eventCallbackInfo
 SolCache event callback information. More...
 

Macros

#define SOLCLIENT_CACHESESSION_PROP_CACHE_NAME   "CACHESESSION_CACHE_NAME"
 The identifier for the Distributed Cache to send cache requests to. More...
 
#define SOLCLIENT_CACHESESSION_PROP_MAX_MSGS   "CACHESESSION_MAX_MSGS"
 The maximum number of messages to retrieve from the cache for any one Topic. More...
 
#define SOLCLIENT_CACHESESSION_PROP_MAX_AGE   "CACHESESSION_MAX_AGE"
 The oldest message (in seconds) to retrieve from the cache. More...
 
#define SOLCLIENT_CACHESESSION_PROP_REQUESTREPLY_TIMEOUT_MS   "CACHESESSION_RR_TIMEOUT_MS"
 The timeout period (in milliseconds) to wait for a response from the cache. More...
 
#define SOLCLIENT_CACHESESSION_PROP_REPLY_TO   "CACHESESSION_REPLY_TO"
 Deprecated: The reply-to topic for the cache request. More...
 
#define SOLCACHE_INVALID_TOPICSEQUENCE_NUMBER   0LL
 A sequence number that is never used by the appliance. More...
 
Default cacheSession Configuration Properties

Default values for cacheSession configuration properties that are not explicitly set.

#define SOLCLIENT_CACHESESSION_PROP_DEFAULT_CACHE_NAME   ""
 There is no default cache name. More...
 
#define SOLCLIENT_CACHESESSION_PROP_DEFAULT_MAX_MSGS   "1"
 The default maximum number of message to retrieve from the cache for any one topic is 1. More...
 
#define SOLCLIENT_CACHESESSION_PROP_DEFAULT_MAX_AGE   "0"
 Default maximum age is no maximum age (set to zero). More...
 
#define SOLCLIENT_CACHESESSION_PROP_DEFAULT_REQUESTREPLY_TIMEOUT_MS   "10000"
 The default timeout (in milliseconds) to wait for a response from the cache is 10000 (10 seconds). More...
 
#define SOLCLIENT_CACHESESSION_PROP_DEFAULT_REPLY_TO   ""
 The default when no reply-to topic is specified is the SOLCLIENT_SESSION_PROP_P2PINBOX_IN_USE for the Session. More...
 
#define SOLCLIENT_CACHESESSION_MAX_CACHE_NAME_SIZE   200
 
CacheRequest Flag Types

Values that can be used as part of the cacheRequestFlags field to solClient_cacheSession_sendCacheRequest().

The following live data actions determine when a cache request completes and how live data is handled while the cache request is outstanding. The actions are mutually exclusive, and one must be specified.

  • SOLCLIENT_CACHEREQUEST_FLAGS_LIVEDATA_FULFILL
  • SOLCLIENT_CACHEREQUEST_FLAGS_LIVEDATA_QUEUE
  • SOLCLIENT_CACHEREQUEST_FLAGS_LIVEDATA_FLOWTHRU

The following flags can be added to the live data action to further modify the behavior of the cache request:

  • SOLCLIENT_CACHEREQUEST_FLAGS_NO_SUBSCRIBE
  • SOLCLIENT_CACHEREQUEST_FLAGS_NOWAIT_REPLY
#define SOLCLIENT_CACHEREQUEST_FLAGS_NO_SUBSCRIBE   (0x01)
 Do not send a subscription request to the appliance before sending the cache request. More...
 
#define SOLCLIENT_CACHEREQUEST_FLAGS_LIVEDATA_FULFILL   (0x02)
 The cache request completes when the cache response is returned or when live data that matches the cache request topic arrives, whichever happens first. More...
 
#define SOLCLIENT_CACHEREQUEST_FLAGS_LIVEDATA_QUEUE   (0x04)
 The cache request completes when the cache response is returned. More...
 
#define SOLCLIENT_CACHEREQUEST_FLAGS_LIVEDATA_FLOWTHRU   (0x08)
 The cache request completes when the cache response is returned. More...
 
#define SOLCLIENT_CACHEREQUEST_FLAGS_NOWAIT_REPLY   (0x10)
 By default, solClient_cacheSession_sendCacheRequest blocks until the cache request completes and then returns the cache request status. More...
 

Typedefs

typedef enum solCache_event solCache_event_t
 SolCache events. More...
 
typedef void * solClient_opaqueCacheSession_pt
 An opaque pointer to a cache session. More...
 
typedef struct
solCache_eventCallbackInfo 
solCache_eventCallbackInfo_t
 SolCache event callback information. More...
 
typedef struct
solCache_eventCallbackInfo
solCache_eventCallbackInfo_pt
 
typedef void(* solCache_eventCallbackFunc_t )(solClient_opaqueSession_pt opaqueSession_p, solCache_eventCallbackInfo_pt eventInfo_p, void *user_p)
 A prototype for the eventCallback function that can be registered by the application. More...
 
typedef solClient_uint32_t solClient_cacheRequestFlags_t
 A set of flags that can be provided to the solClient_cacheSession_sendCacheRequest() see CacheRequest Flag Types. More...
 

Enumerations

enum  solCache_event { SOLCACHE_EVENT_REQUEST_COMPLETED_NOTICE }
 SolCache events. More...
 

Functions

solClient_dllExport const char * solClient_cacheSession_eventToString (solCache_event_t cacheEvent)
 Returns a string representation of the cache event passed in. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_session_createCacheSession (const char *const *props, solClient_opaqueSession_pt opaqueSession_p, solClient_opaqueCacheSession_pt *opaqueCacheSession_p)
 Create a cache session object that is used in subsequent cacheRequests on the Session. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_cacheSession_destroy (solClient_opaqueCacheSession_pt *opaqueCacheSession_p)
 Destroy a cache session object. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_cacheSession_sendCacheRequest (solClient_opaqueCacheSession_pt opaqueCacheSession_p, const char *topic_p, solClient_uint64_t cacheRequestId, solCache_eventCallbackFunc_t callback_p, void *user_p, solClient_cacheRequestFlags_t cacheflags, solClient_subscribeFlags_t subscribeFlags)
 Send a cache request message. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_cacheSession_sendCacheRequestSequence (solClient_opaqueCacheSession_pt opaqueCacheSession_p, const char *topic_p, solClient_uint64_t cacheRequestId, solCache_eventCallbackFunc_t callback_p, void *user_p, solClient_cacheRequestFlags_t cacheflags, solClient_subscribeFlags_t subscribeFlags, solClient_int64_t startSeqId, solClient_int64_t endSeqId)
 Send a Cache Request Message. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_cacheSession_cancelCacheRequests (solClient_opaqueCacheSession_pt opaqueCacheSession_p)
 Cancel all in progress cache requests for a given cache session. More...
 

Detailed Description

Include file for the Solace Corporation Messaging API for C.

Copyright 2008-2024 Solace Corporation. All rights reserved.

This include file provides the public constants and API calls for applications that interface to the Solace Corporation SolCache.

Macro Definition Documentation

#define SOLCACHE_INVALID_TOPICSEQUENCE_NUMBER   0LL

A sequence number that is never used by the appliance.

When passed as an argument to solClient_cacheSession_sendCacheRequestSequence(), it is taken to mean oldest or newest sequence number for the start sequence number and end sequence number, respectively.

#define SOLCLIENT_CACHEREQUEST_FLAGS_LIVEDATA_FLOWTHRU   (0x08)

The cache request completes when the cache response is returned.

Live data matching the cache request topic is delivered immediately to the application while the cache request is outstanding. SOLCLIENT_CACHEREQUEST_FLAGS_LIVEDATA_FLOWTHRU is the only live data action that supports wildcard topic cache requests.

#define SOLCLIENT_CACHEREQUEST_FLAGS_LIVEDATA_FULFILL   (0x02)

The cache request completes when the cache response is returned or when live data that matches the cache request topic arrives, whichever happens first.

In the latter case, the cache request completes as soon as live data arrives. The status of the cache response is SOLCLIENT_OK, unless part of the response is flagged as suspect, in which case the response is SOLCLIENT_INCOMPLETE. This is a typical last value cache mode where only the most recent data is of interest and the application is not interested in all data available on the topic.

#define SOLCLIENT_CACHEREQUEST_FLAGS_LIVEDATA_QUEUE   (0x04)

The cache request completes when the cache response is returned.

Live data matching the cache request topic is queued until the cache request completes. Data from the cache-response is delivered before queued live data. The queued live data is delivered to the application before the cache request completes. It is possible for queued live data to duplicate data in the cache-response. It is the responsibility of the application to handle duplication by some application specific method. For example, by using an end-to-end message-id in the message meta-data.

Examples:
ex/asyncCacheRequest.c, ex/ios/examples/AsyncCacheRequestExample.m, ex/ios/examples/SyncCacheRequestExample.m, and ex/syncCacheRequest.c.
#define SOLCLIENT_CACHEREQUEST_FLAGS_NO_SUBSCRIBE   (0x01)

Do not send a subscription request to the appliance before sending the cache request.

This flag is used if the client is already subscribed to the cache request topic.

#define SOLCLIENT_CACHEREQUEST_FLAGS_NOWAIT_REPLY   (0x10)

By default, solClient_cacheSession_sendCacheRequest blocks until the cache request completes and then returns the cache request status.

If the cache request flag SOLCLIENT_CACHEREQUEST_FLAGS_NOWAIT_REPLY is set, solClient_cacheSession_sendCacheRequest returns immediately with the status SOLCLIENT_IN_PROGRESS, and the cache request status is returned through a callback when it completes.

Examples:
ex/asyncCacheRequest.c, and ex/ios/examples/AsyncCacheRequestExample.m.
#define SOLCLIENT_CACHESESSION_MAX_CACHE_NAME_SIZE   200
Examples:
ex/common.h.
#define SOLCLIENT_CACHESESSION_PROP_DEFAULT_CACHE_NAME   ""

There is no default cache name.

#define SOLCLIENT_CACHESESSION_PROP_DEFAULT_MAX_AGE   "0"

Default maximum age is no maximum age (set to zero).

#define SOLCLIENT_CACHESESSION_PROP_DEFAULT_MAX_MSGS   "1"

The default maximum number of message to retrieve from the cache for any one topic is 1.

#define SOLCLIENT_CACHESESSION_PROP_DEFAULT_REPLY_TO   ""

The default when no reply-to topic is specified is the SOLCLIENT_SESSION_PROP_P2PINBOX_IN_USE for the Session.

#define SOLCLIENT_CACHESESSION_PROP_DEFAULT_REQUESTREPLY_TIMEOUT_MS   "10000"

The default timeout (in milliseconds) to wait for a response from the cache is 10000 (10 seconds).

Typedef Documentation

SolCache events.

The list of events that can be passed to the event callback function.

typedef void(* solCache_eventCallbackFunc_t)(solClient_opaqueSession_pt opaqueSession_p, solCache_eventCallbackInfo_pt eventInfo_p, void *user_p)

A prototype for the eventCallback function that can be registered by the application.

SolCache event callback information.

When the application registers an event callback pointer with a cache request (for asynchronous cache requests), the callback function receives a pointer to the event callback information structure.

typedef solClient_uint32_t solClient_cacheRequestFlags_t

A set of flags that can be provided to the solClient_cacheSession_sendCacheRequest() see CacheRequest Flag Types.

An opaque pointer to a cache session.

Enumeration Type Documentation

SolCache events.

The list of events that can be passed to the event callback function.

Enumerator
SOLCACHE_EVENT_REQUEST_COMPLETED_NOTICE 

Cache Request has finished.

The event returnCode and subCode provide status information

Function Documentation

solClient_dllExport solClient_returnCode_t solClient_cacheSession_cancelCacheRequests ( solClient_opaqueCacheSession_pt  opaqueCacheSession_p)

Cancel all in progress cache requests for a given cache session.

This function is thread safe and can be called from any thread. When this function is invoked:

  • All blocked synchronous cache requests return immediately with SOLCLIENT_INCOMPLETE return code and 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.
  • Live messages that have been queued (if any) will be delivered.
  • The associated cache session is still valid to use.
Parameters
opaqueCacheSession_pOpaque cache session pointer that was returned when the cache session was created.
Returns
SOLCLIENT_OK, SOLCLIENT_FAIL
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of subcodes.
solClient_dllExport solClient_returnCode_t solClient_cacheSession_destroy ( solClient_opaqueCacheSession_pt opaqueCacheSession_p)

Destroy a cache session object.

This function is thread safe and can be called from any thread. When this function is invoked:

  • All blocked synchronous cache requests return immediately with SOLCLIENT_INCOMPLETE return code and SOLCLIENT_SUBCODE_PARAM_NULL_PTR subcode.
  • Live messages that have been queued (if any) will be delivered.
Parameters
opaqueCacheSession_pPointer to opaque cache session pointer that was returned when the cache session was created.
Returns
SOLCLIENT_OK, SOLCLIENT_FAIL
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of subcodes.
Examples:
ex/asyncCacheRequest.c, ex/ios/examples/AsyncCacheRequestExample.m, ex/ios/examples/SyncCacheRequestExample.m, and ex/syncCacheRequest.c.
solClient_dllExport const char* solClient_cacheSession_eventToString ( solCache_event_t  cacheEvent)

Returns a string representation of the cache event passed in.

Parameters
cacheEventThe Session event to convert to a string representation.
Returns
A pointer to a constant character string. This pointer is never NULL.
Examples:
ex/asyncCacheRequest.c, ex/common.c, ex/ios/Example.m, and ex/ios/examples/AsyncCacheRequestExample.m.
solClient_dllExport solClient_returnCode_t solClient_cacheSession_sendCacheRequest ( solClient_opaqueCacheSession_pt  opaqueCacheSession_p,
const char *  topic_p,
solClient_uint64_t  cacheRequestId,
solCache_eventCallbackFunc_t  callback_p,
void *  user_p,
solClient_cacheRequestFlags_t  cacheflags,
solClient_subscribeFlags_t  subscribeFlags 
)

Send a cache request message.

If the cache request flag SOLCLIENT_CACHEREQUEST_FLAGS_NOWAIT_REPLY is set, this function returns SOLCLIENT_IN_PROGRESS immediately upon successful buffering of the message for transmission. Otherwise this function waits for the cache response to be fulfilled according to the LIVEDATA handling options. When the function waits for the cache response the cache event callback is not invoked.

Irrespective of the cache request flag, SOLCLIENT_CACHEREQUEST_FLAGS_NOWAIT_REPLY, cache requests may be flow controlled if the underlying transport is flow controlled. The transport is considered flow controlled if the library is unable to write to the transport device (for example, the TCP socket is full), or if there are more than 1000 session requests (solClient_session_sendRequest() + solClient_cacheSession_sendCacheRequest()) outstanding. This causes solClient_cacheSession_sendCacheRequest() to block if the session property, SOLCLIENT_SESSION_PROP_SEND_BLOCKING is enabled. If SOLCLIENT_SESSION_PROP_SEND_BLOCKING is disabled and it is not possible to write the cache request to the underlying transport, SOLCLIENT_WOULD_BLOCK is returned.

Cached messages received in response to the cache request are delivered to the application through the usual receive message callback as the messages arrive. This function returns when all cache responses have been received, or the request is either completed by live data (SOLCLIENT_CACHEREQUEST_FLAGS_LIVEDATA_FULFILL) or by a timeout. If, and only if, SOLCLIENT_CACHEREQUEST_FLAGS_NOWAIT_REPLY is set, the cache request callback is invoked when any of these terminating conditions occurs.

Parameters
opaqueCacheSession_pAn opaque cache session pointer returned when the cache session was created.
topic_pThe string that contains the topic being requested from the cache.
cacheRequestIdThe 64-bit integer returned to the application in the cache request response; it is available in every cached message returned.
callback_pA callback pointer for an asynchronous reply to cache requests.
user_pA user pointer to return with the callback.
cacheflagscacheRequest flags to modify the cache request behavior.
subscribeFlagsSubscription flags (subscribeflags)
Returns
SOLCLIENT_OK, SOLCLIENT_NOT_READY, SOLCLIENT_FAIL, SOLCLIENT_INCOMPLETE, SOLCLIENT_IN_PROGRESS, SOLCLIENT_WOULD_BLOCK
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
This function can return SOLCLIENT_FAIL for any of the following reasons: When the SOLCLIENT_CACHEREQUEST_FLAGS_NOWAIT_REPLY is set in cacheFlags, the function returns SOLCLIENT_IN_PROGRESS and the subsequent callback indicates the final status of the cache request.

Otherwise the return code indicates the status of the cache request. SOLCLIENT_OK is returned when the cache request completes successfully and valid data is delivered. The solClient_subCode is never set when SOLCLIENT_OK is returned.

SOLCLIENT_INCOMPLETE may be returned if the cacheRequest or initial subscription request is sent but not completed successfully.

See Also
solClient_subCode for a description of all sub-codes.
Examples:
ex/asyncCacheRequest.c, ex/ios/examples/AsyncCacheRequestExample.m, ex/ios/examples/SyncCacheRequestExample.m, and ex/syncCacheRequest.c.
solClient_dllExport solClient_returnCode_t solClient_cacheSession_sendCacheRequestSequence ( solClient_opaqueCacheSession_pt  opaqueCacheSession_p,
const char *  topic_p,
solClient_uint64_t  cacheRequestId,
solCache_eventCallbackFunc_t  callback_p,
void *  user_p,
solClient_cacheRequestFlags_t  cacheflags,
solClient_subscribeFlags_t  subscribeFlags,
solClient_int64_t  startSeqId,
solClient_int64_t  endSeqId 
)

Send a Cache Request Message.

This function is used for SolCache-RS only.

If the cache request flag SOLCLIENT_CACHEREQUEST_FLAGS_NOWAIT_REPLY is set, this function returns SOLCLIENT_IN_PROGRESS immediately upon successful buffering of the message for transmission. Otherwise this function waits for the cache response to be fulfilled according to the LIVEDATA handling options. When the function waits for the cache response, the cache event callback is not invoked.

Irrespective of the cache request flag, SOLCLIENT_CACHEREQUEST_FLAGS_NOWAIT_REPLY, cache requests may be flow controlled if the underlying transport is flow controlled. This causes solClient_cacheSession_sendCacheRequest() to block if the session property, SOLCLIENT_SESSION_PROP_SEND_BLOCKING is enabled. If SOLCLIENT_SESSION_PROP_SEND_BLOCKING is disabled and it is not possible to write the cache request to the underlying transport, SOLCLIENT_WOULD_BLOCK is returned.

Cached messages received in response to the cache request are delivered to the application through the usual receive message callback as the messages arrive. This function returns when all cache responses have been returned, and the request is either completed by live data (SOLCLIENT_CACHEREQUEST_FLAGS_LIVEDATA_FULFILL), or by timeout. If, and only if, SOLCLIENT_CACHEREQUEST_FLAGS_NOWAIT_REPLY is set, the cache request callback is invoked when any of these terminating conditions occurs.

Parameters
opaqueCacheSession_pAn opaque cache session pointer returned when the cache session was created.
topic_pThe string that contains the topic being requested from the cache.
cacheRequestIdThe 64-bit integer returned to the application in the cache request response; it is available in every cached message returned.
callback_pA callback pointer for an asynchronous reply to cache requests.
user_pA user pointer to return with the callback.
cacheflagscacheRequest flags to modify the cache request behaviour
subscribeFlagsSubscription flags (subscribeflags)
startSeqIdStarting sequence number for retrieved messages. If set to SOLCACHE_INVALID_TOPICSEQUENCE_NUMBER, then start at the oldest available message.
Note
If both startSeqId and endSeqId are set to SOLCACHE_INVALID_TOPICSEQUENCE_NUMBER, only the newest message is retrieved.
Parameters
endSeqIdEnd sequence number for retrieved messages, if set to SOLCACHE_INVALID_TOPICSEQUENCE_NUMBER, then all available messages starting at startSeqId are retrieved.
Returns
SOLCLIENT_OK, SOLCLIENT_NOT_READY, SOLCLIENT_FAIL, SOLCLIENT_INCOMPLETE, SOLCLIENT_IN_PROGRESS, SOLCLIENT_WOULD_BLOCK
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
This function can return SOLCLIENT_FAIL for any of the following reasons: When the SOLCLIENT_CACHEREQUEST_FLAGS_NOWAIT_REPLY is set in cacheFlags, the function returns SOLCLIENT_IN_PROGRESS and the subsequent callback indicates the final status of the cache request.

Otherwise the return code indicates the status of the cache request. SOLCLIENT_OK is returned when the cache request completes successfully and valid data is delivered. The solClient_subCode is never set when SOLCLIENT_OK is returned.

SOLCLIENT_INCOMPLETE may be returned if the cacheRequest or initial subscription request is sent but not completed successfully.

See Also
solClient_subCode for a description of all sub-codes.
solClient_dllExport solClient_returnCode_t solClient_session_createCacheSession ( const char *const *  props,
solClient_opaqueSession_pt  opaqueSession_p,
solClient_opaqueCacheSession_pt opaqueCacheSession_p 
)

Create a cache session object that is used in subsequent cacheRequests on the Session.

Multiple cache session objects may be created on a Session. Each must be destroyed when the application no longer requires the object.

Parameters
propsArray of name/value string pair pointers to configure cache session properties.
opaqueSession_pSession in which the cache session is to be created.
opaqueCacheSession_pPointer to the location to contain the opaque cache session pointer on return.
Returns
SOLCLIENT_OK on success. SOLCLIENT_FAIL on failure.
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of subcodes.
Examples:
ex/asyncCacheRequest.c, ex/ios/examples/AsyncCacheRequestExample.m, ex/ios/examples/SyncCacheRequestExample.m, and ex/syncCacheRequest.c.