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

include file for Solace Corporation Messaging Buffer Management More...

#include "solClient.h"

Data Structures

struct  solClient_replicationGroupMessageId
 

Macros

Number of Message Size Quanta

The number of message size quanta available.

See Also
SOLCLIENT_GLOBAL_PROP_DBQUANTASIZE_0 through SOLCLIENT_GLOBAL_PROP_DBQUANTASIZE_4
#define SOLCLIENT_MSG_NUMDBQUANTA   (5)
 The number of message size quanta available. More...
 

Typedefs

typedef enum solClient_cacheStatus solClient_cacheStatus_t
 
typedef enum solClient_msg_stats solClient_msg_stats_t
 Type that indicates which message statistic. More...
 

Enumerations

enum  solClient_cacheStatus { SOLCLIENT_CACHE_INVALID_MESSAGE = -1, SOLCLIENT_CACHE_LIVE_MESSAGE = 0, SOLCLIENT_CACHE_MESSAGE = 1, SOLCLIENT_CACHE_SUSPECT_MESSAGE = 2 }
 Cache Status of received message, returned by solClient_msg_isCacheMsg() More...
 
enum  solClient_msg_stats {
  SOLCLIENT_MSG_STATS_TOTAL_MEMORY = 0, SOLCLIENT_MSG_STATS_ALLOC_MEMORY = 1, SOLCLIENT_MSG_STATS_MSG_ALLOCS = 2, SOLCLIENT_MSG_STATS_MSG_FREES = 3,
  SOLCLIENT_MSG_STATS_MSG_DUPS = 4, SOLCLIENT_MSG_STATS_MSG_REALLOCS = 5, SOLCLIENT_MSG_STATS_FREE_MSGS = 6, SOLCLIENT_MSG_STATS_ALLOC_MSGS = 7,
  SOLCLIENT_MSG_STATS_FREE_CONTAINERS = 8, SOLCLIENT_MSG_STATS_ALLOC_CONTAINERS = 9, SOLCLIENT_MSG_STATS_FREE_DATA_BLOCKS = 10, SOLCLIENT_MSG_STATS_ALLOC_DATA_BLOCKS = 11
}
 Statistics associated with message memory management. More...
 

solClient_msg_dumpExt mode flags

Options to control the message dump utility.

#define SOLCLIENT_MSGDUMP_BRIEF   (0)
 Display only the length of the binary attachment, XML attachment, and user property map. More...
 
#define SOLCLIENT_MSGDUMP_FULL   (1)
 Display the entire message. More...
 
#define solClient_msg_getSmfPtr   solClient_msg_getSMFPtr
 
#define SOLCLIENT_REPLICATION_GROUP_MESSAGE_ID_INITIALIZER   {{0}}
 
#define SOLCLIENT_REPLICATION_GROUP_MESSAGE_ID_SIZE   16
 
#define SOLCLIENT_REPLICATION_GROUP_MESSAGE_ID_STRING_LENGTH   41
 
typedef struct
solClient_replicationGroupMessageId 
solClient_replicationGroupMessageId_t
 
typedef struct
solClient_replicationGroupMessageId
solClient_replicationGroupMessageId_pt
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_alloc (solClient_opaqueMsg_pt *msg_p)
 Allocate a solClient Msg that can be used for storing and sending messages to and from the Solace Messaging Appliance. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_free (solClient_opaqueMsg_pt *msg_p)
 Free a solClient Msg previously allocated by solClient_msg_alloc(). More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_dup (solClient_opaqueMsg_pt msg_p, solClient_opaqueMsg_pt *dupMsg_p)
 Duplicate a message buffer and allocate a new msg which references all the same data. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_reset (solClient_opaqueMsg_pt msg_p)
 Release all memory associated with a message buffer. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_getUserPropertyMap (solClient_opaqueMsg_pt msg_p, solClient_opaqueContainer_pt *map_p)
 Given a msg_p, retrieve the user property Map from binary metadata. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_getBinaryAttachmentStream (solClient_opaqueMsg_pt msg_p, solClient_opaqueContainer_pt *stream_p)
 Given a msg_p, retrieve the contents of a binary attachment part as a stream. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_getBinaryAttachmentMap (solClient_opaqueMsg_pt msg_p, solClient_opaqueContainer_pt *map_p)
 Given a msg_p, retrieve the contents of a binary attachment part as a map. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_getBinaryAttachmentPtr (solClient_opaqueMsg_pt msg_p, solClient_opaquePointer_pt bufPtr_p, solClient_uint32_t *size_p)
 Given a msg_p, retrieve the contents of a binary attachment part and return the pointer and length. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_getBinaryAttachmentString (solClient_opaqueMsg_pt msg_p, const char **bufPtr_p)
 Given a msg_p, retrieve the contents of a binary attachment part if it is a JMS string and return a pointer to the string (NULL-terminated string). More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_getBinaryAttachmentContainerSize (solClient_opaqueMsg_pt msg_p, size_t *size_p)
 Given a msg_p, retrieve the size of the open container in the binary attachment. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_getCorrelationTagPtr (solClient_opaqueMsg_pt msg_p, solClient_opaquePointer_pt bufPtr_p, solClient_uint32_t *size_p)
 Given a msg_p, retrieve the contents of a Correlation Tag part (used by an application when sending Guaranteed messages and receiving Guaranteed message acknowledgments) and return the pointer and length. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_getUserDataPtr (solClient_opaqueMsg_pt msg_p, solClient_opaquePointer_pt bufPtr_p, solClient_uint32_t *size_p)
 Given a msg_p, retrieve the contents of a User Data part. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_getXmlPtr (solClient_opaqueMsg_pt msg_p, solClient_opaquePointer_pt bufPtr_p, solClient_uint32_t *size_p)
 Given a msg_p, retrieve the contents of a XML part of the message. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_getSMFPtr (solClient_opaqueMsg_pt msg_p, solClient_uint8_t **bufPtr_p, solClient_uint32_t *size_p)
 Given a msg_p, retrieve the raw Solace Message Format (SMF) message as originally received. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_setBinaryAttachmentPtr (solClient_opaqueMsg_pt msg_p, void *buf_p, solClient_uint32_t size)
 Given a msg_p, set the contents of a Binary Attachment Part to the given pointer and size. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_setBinaryAttachment (solClient_opaqueMsg_pt msg_p, const void *buf_p, solClient_uint32_t size)
 Given a msg_p, set the contents of the binary attachment part by copying in from the given pointer and size. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_setBinaryAttachmentString (solClient_opaqueMsg_pt msg_p, const char *buf_p)
 Given a msg_p, set the contents of the binary attachment part to a UTF-8 or ASCII string by copying in from the given pointer until null-terminated. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_setBinaryAttachmentContainer (solClient_opaqueMsg_pt msg_p, solClient_opaqueContainer_pt cont_p)
 Given a msg_p, set the contents of the binary attachment part to a Map or Stream, as referenced by the given solClient_opaqueContainer_pt. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_setBinaryAttachmentContainerPtr (solClient_opaqueMsg_pt msg_p, solClient_opaqueContainer_pt cont_p)
 Given a msg_p, set the contents of the binary attachment part to a Map or Stream, as referenced by the given solClient_opaqueContainer_pt. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_setUserDataPtr (solClient_opaqueMsg_pt msg_p, void *buf_p, solClient_uint32_t size)
 Given a msg_p, set the contents of a user data part to the given pointer and size. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_setUserData (solClient_opaqueMsg_pt msg_p, const void *buf_p, solClient_uint32_t size)
 Given a msg_p, set the contents of User Data Part by copying in from the given pointer and size. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_setXmlPtr (solClient_opaqueMsg_pt msg_p, void *buf_p, solClient_uint32_t size)
 Given a msg_p, set the contents of the XML part to the given pointer and size. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_setXml (solClient_opaqueMsg_pt msg_p, const void *buf_p, solClient_uint32_t size)
 Given a msg_p, set the contents of the XML part by copying in from the given pointer and size. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_setCorrelationTagPtr (solClient_opaqueMsg_pt msg_p, void *correlation_p, solClient_uint32_t size)
 Given a msg_p, set the Correlation Tag to the given pointer. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_setCorrelationTag (solClient_opaqueMsg_pt msg_p, const void *correlation_p, solClient_uint32_t size)
 Given a msg_p, save correlation information Part by copying in from the given pointer and size. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_setTopicPtr (solClient_opaqueMsg_pt msg_p, const char *topic_p)
 Given a msg_p, set the Topic of the message as a pointer to application space. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_setQueueNamePtr (solClient_opaqueMsg_pt msg_p, const char *queueName_p)
 Given a msg_p, set the QueueName destination of the message as a pointer to application space. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_getReplyTo (solClient_opaqueMsg_pt msg_p, solClient_destination_t *dest_p, size_t destSize)
 Given a msg_p, retrieve the replyTo destination and set the information in the passed in destination structure. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_setReplyTo (solClient_opaqueMsg_pt msg_p, const solClient_destination_t *dest_p, size_t destSize)
 Given a msg_p, set the ReplyTo destination. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_deleteReplyTo (solClient_opaqueMsg_pt msg_p)
 Given a msg_p, delete the ReplyTo destination. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_setDestination (solClient_opaqueMsg_pt msg_p, solClient_destination_t *dest_p, size_t destSize)
 Given a msg_p, set the Destination field (queue or topic). More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_getDestination (solClient_opaqueMsg_pt msg_p, solClient_destination_t *dest_p, size_t destSize)
 Given a msg_p, get the Destination field (queue or topic), which is the destination this message was published to. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_getSenderId (solClient_opaqueMsg_pt msg_p, const char **buf_p)
 Given a msg_p, copy the SenderID pointer into the given buffer. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_setSenderId (solClient_opaqueMsg_pt msg_p, const char *buf_p)
 Given a msg_p, set the SenderID. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_deleteSenderId (solClient_opaqueMsg_pt msg_p)
 Given a msg_p, delete the SenderId. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_getApplicationMsgType (solClient_opaqueMsg_pt msg_p, const char **msgType_p)
 Given a msg_p, copy the ApplicationMessageType topic pointer into the given pointer. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_setApplicationMsgType (solClient_opaqueMsg_pt msg_p, const char *msgType)
 Given a msg_p, set the ApplicationMessageType field. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_deleteApplicationMsgType (solClient_opaqueMsg_pt msg_p)
 Given a msg_p, delete the MsgType field. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_getApplicationMessageId (solClient_opaqueMsg_pt msg_p, const char **messageId_p)
 Given a msg_p, copy the ApplicationMessageId pointer into the given buffer. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_setApplicationMessageId (solClient_opaqueMsg_pt msg_p, const char *messageId_p)
 Given a msg_p, set the ApplicationMessageId field. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_deleteApplicationMessageId (solClient_opaqueMsg_pt msg_p)
 Given a msg_p, delete the Application MessageId field. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_getSequenceNumber (solClient_opaqueMsg_pt msg_p, solClient_int64_t *seqNum_p)
 Given a msg_p, copy the SequenceNo into the given buffer. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_setSequenceNumber (solClient_opaqueMsg_pt msg_p, solClient_uint64_t seqNum)
 Given a msg_p, set the Sequence Number field. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_deleteSequenceNumber (solClient_opaqueMsg_pt msg_p)
 Given a msg_p, delete the Sequence Number field. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_getCorrelationId (solClient_opaqueMsg_pt msg_p, const char **correlation_p)
 Given a msg_p, copy the CorrelationId pointer into the given buffer. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_setCorrelationId (solClient_opaqueMsg_pt msg_p, const char *correlation_p)
 Given a msg_p, set the CorrelationId field. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_deleteCorrelationId (solClient_opaqueMsg_pt msg_p)
 Given a msg_p, delete the Correlation Id field. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_getRcvTimestamp (solClient_opaqueMsg_pt msg_p, solClient_int64_t *timestamp_p)
 Given a msg_p, copy the Receive Timestamp into the given buffer. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_setSenderTimestamp (solClient_opaqueMsg_pt msg_p, solClient_int64_t timestamp)
 Given a msg_p, set the Sender Timestamp field. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_getSenderTimestamp (solClient_opaqueMsg_pt msg_p, solClient_int64_t *timestamp_p)
 Given a msg_p, copy the SenderTimestamp into the given buffer. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_deleteSenderTimestamp (solClient_opaqueMsg_pt msg_p)
 Given a msg_p, delete the SenderTimestamp. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_setExpiration (solClient_opaqueMsg_pt msg_p, solClient_int64_t timestamp)
 Given a msg_p, set the expiration time field. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_getExpiration (solClient_opaqueMsg_pt msg_p, solClient_int64_t *timestamp_p)
 Given a msg_p, copy the Message Expiration timestamp into the given buffer. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_getClassOfService (solClient_opaqueMsg_pt msg_p, solClient_uint32_t *cos_p)
 Given a msg_p, get the Class of Service from a message. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_setClassOfService (solClient_opaqueMsg_pt msg_p, solClient_uint32_t cos)
 Given a msg_p, set the Class of Service to use for transmission. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_getTimeToLive (solClient_opaqueMsg_pt msg_p, solClient_int64_t *ttl_p)
 Given a msg_p, get the Time To Live (TTL) from a message. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_setTimeToLive (solClient_opaqueMsg_pt msg_p, solClient_int64_t ttl)
 Given a msg_p, set the Time To Live (TTL) for a message. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_getDeliveryMode (solClient_opaqueMsg_pt msg_p, solClient_uint32_t *mode_p)
 Given a msg_p, return the delivery mode. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_setDeliveryMode (solClient_opaqueMsg_pt msg_p, solClient_uint32_t mode)
 Given a msg_p, set the delivery mode. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_getMsgId (solClient_opaqueMsg_pt msg_p, solClient_msgId_t *msgId_p)
 Given a msg_p, return the Guaranteed message Id. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_getTopicSequenceNumber (solClient_opaqueMsg_pt msg_p, solClient_int64_t *seqNum_p)
 Given a msg_p, return the Topic Sequence Number. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_getDeliveryCount (solClient_opaqueMsg_pt msg_p, solClient_int32_t *count_p)
 Given a msg_p, return the delivery count. More...
 
solClient_dllExport
solClient_bool_t 
solClient_msg_isRedelivered (solClient_opaqueMsg_pt msg_p)
 Given a msg_p, test the redeliver status. More...
 
solClient_dllExport
solClient_cacheStatus_t 
solClient_msg_isCacheMsg (solClient_opaqueMsg_pt msg_p)
 Given a msg_p, return the data source (live or cached message). More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_getCacheRequestId (solClient_opaqueMsg_pt msg_p, solClient_uint64_t *cacheRequestId_p)
 Given a msg_p containing a cached message, return the cache RequestId that the application set in the call to solClient_csession_sendCacheRequest(). More...
 
solClient_dllExport
solClient_bool_t 
solClient_msg_isDiscardIndication (solClient_opaqueMsg_pt msg_p)
 Given a msg_p, test the discard indication status. More...
 
solClient_dllExport
solClient_bool_t 
solClient_msg_isReplyMsg (solClient_opaqueMsg_pt msg_p)
 Given a msg_p, test the response attribute. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_setDMQEligible (solClient_opaqueMsg_pt msg_p, solClient_bool_t val)
 Given a msg_p, set the Dead Message Queue (DMQ) eligible property on a message. More...
 
solClient_dllExport
solClient_bool_t 
solClient_msg_isDMQEligible (solClient_opaqueMsg_pt msg_p)
 Given a msg_p, test the Dead Message Queue (DMQ) eligible property. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_setReplyToSuffix (solClient_opaqueMsg_pt msg_p, solClient_opaqueSession_pt opaqueSession_p, const char *suffix_p)
 Append an application-specified suffix to the default topic destination for the Session. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_getDestinationTopicSuffix (solClient_opaqueMsg_pt msg_p, solClient_opaqueSession_pt opaqueSession_p, const char **suffix_p)
 This utility returns the suffix of the topic string. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_setAsReplyMsg (solClient_opaqueMsg_pt msg_p, solClient_bool_t isReply)
 Set the reply attribute of the message. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_setElidingEligible (solClient_opaqueMsg_pt msg_p, solClient_bool_t elide)
 Given a msg_p, set the ElidingEligible property on a message. More...
 
solClient_dllExport
solClient_bool_t 
solClient_msg_isElidingEligible (solClient_opaqueMsg_pt msg_p)
 Given a msg_p, test the ElidingEligible attribute. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_createBinaryAttachmentMap (solClient_opaqueMsg_pt msg_p, solClient_opaqueContainer_pt *map_p, solClient_uint32_t size)
 Create a map container in the binary attachment of the message. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_createBinaryAttachmentStream (solClient_opaqueMsg_pt msg_p, solClient_opaqueContainer_pt *stream_p, solClient_uint32_t size)
 Create a stream container in the binary attachment of the message. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_createUserPropertyMap (solClient_opaqueMsg_pt msg_p, solClient_opaqueContainer_pt *map_p, solClient_uint32_t size)
 Create a User Property map in the binary metadata header. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_setUserPropertyMap (solClient_opaqueMsg_pt msg_p, solClient_opaqueContainer_pt map_p)
 Set the User Property map in the binary metadata header. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_getBinaryAttachmentField (solClient_opaqueMsg_pt msg_p, solClient_field_t *field_p, size_t fieldSize)
 Check the binary attachment in the message for structured data. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_getStat (solClient_msg_stats_t msgStatType, solClient_uint32_t statIndex, solClient_uint64_t *statValue_p)
 Returns the value of the specified message statistic. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_dumpExt (solClient_opaqueMsg_pt msg_p, char *buffer_p, size_t bufferSize, solClient_uint32_t flags)
 Display the contents of a message in human-readable form. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_dump (solClient_opaqueMsg_pt msg_p, char *buffer_p, size_t bufferSize)
 Display the contents of a message in human-readable form. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_setAckImmediately (solClient_opaqueMsg_pt msg_p, solClient_bool_t val)
 Given a msg_p, set the optional ACK Immediately message property. More...
 
solClient_dllExport
solClient_bool_t 
solClient_msg_isAckImmediately (solClient_opaqueMsg_pt msg_p)
 Given a msg_p, test if the ACK Immediately message property is set or not. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_getHttpContentType (solClient_opaqueMsg_pt msg_p, const char **type_p)
 Given a msg_p, retrieve the HTTP Content Type. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_getHttpContentEncoding (solClient_opaqueMsg_pt msg_p, const char **encoding_p)
 Given a msg_p, retrieve the HTTP Content Encoding. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_setHttpContentType (solClient_opaqueMsg_pt msg_p, const char *type_p)
 Given a msg_p, set or delete (if type_p == NULL) its HTTP Content Type. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_setHttpContentEncoding (solClient_opaqueMsg_pt msg_p, const char *encoding_p)
 Given a msg_p, set or delete (if encoding_p == NULL) its HTTP Content Encoding. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_deleteHttpContentType (solClient_opaqueMsg_pt msg_p)
 Given a msg_p, delete the HTTP Content Type. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_deleteHttpContentEncoding (solClient_opaqueMsg_pt msg_p)
 Given a msg_p, delete the HTTP Content Encoding. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_container_createMap (solClient_opaqueContainer_pt *newContainer_p, char *mem_p, size_t size)
 Create a map container in a memory location given by the caller. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_container_createStream (solClient_opaqueContainer_pt *newContainer_p, char *mem_p, size_t size)
 This function creates a stream container in a memory location given by the caller. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_container_openSubMap (solClient_opaqueContainer_pt container_p, solClient_opaqueContainer_pt *newContainer_p, const char *name)
 Open a nested subMap. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_container_openSubStream (solClient_opaqueContainer_pt container_p, solClient_opaqueContainer_pt *newContainer_p, const char *name)
 Open a nested subStream. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_container_closeMapStream (solClient_opaqueContainer_pt *container_p)
 Finish a map or stream. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_container_addNull (solClient_opaqueContainer_pt container_p, const char *name)
 Add a NULL to a map or stream. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_container_addBoolean (solClient_opaqueContainer_pt container_p, solClient_bool_t value, const char *name)
 Add a Boolean value to a map or stream. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_container_addUint8 (solClient_opaqueContainer_pt container_p, solClient_uint8_t value, const char *name)
 Add a unsigned 8-bit value to a map or stream. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_container_addInt8 (solClient_opaqueContainer_pt container_p, solClient_int8_t value, const char *name)
 Add a signed 8-bit value to a map or stream. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_container_addUint16 (solClient_opaqueContainer_pt container_p, solClient_uint16_t value, const char *name)
 Add an unsigned 16-bit value to a map or stream. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_container_addInt16 (solClient_opaqueContainer_pt container_p, solClient_int16_t value, const char *name)
 Add a signed 16-bit value to a map or stream. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_container_addUint32 (solClient_opaqueContainer_pt container_p, solClient_uint32_t value, const char *name)
 Add an unsigned 32-bit value to a map or stream. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_container_addInt32 (solClient_opaqueContainer_pt container_p, solClient_int32_t value, const char *name)
 Add a signed 32-bit value to a map or stream. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_container_addUint64 (solClient_opaqueContainer_pt container_p, solClient_uint64_t value, const char *name)
 Add a unsigned 64-bit value to a map or stream. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_container_addInt64 (solClient_opaqueContainer_pt container_p, solClient_int64_t value, const char *name)
 Add a signed 64-bit value to a map or stream. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_container_addChar (solClient_opaqueContainer_pt container_p, char value, const char *name)
 Add an ASCII character to a map or stream. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_container_addWchar (solClient_opaqueContainer_pt container_p, solClient_wchar_t value, const char *name)
 Add a unicode (wide) character to a map or stream. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_container_addByteArray (solClient_opaqueContainer_pt container_p, const solClient_uint8_t *arr_p, solClient_uint32_t length, const char *name)
 Add a byte array to a map or stream. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_container_addSmf (solClient_opaqueContainer_pt container_p, const solClient_uint8_t *smf_p, solClient_uint32_t length, const char *name)
 Add a Solace Message Format (SMF) message to a map or stream. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_container_addContainer (solClient_opaqueContainer_pt container_p, solClient_opaqueContainer_pt subContainer_p, const char *name)
 Add an existing container to a map or stream. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_container_addFloat (solClient_opaqueContainer_pt container_p, float value, const char *name)
 Add a 32-bit floating point number to a map or stream. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_container_addDouble (solClient_opaqueContainer_pt container_p, double value, const char *name)
 Add a 64-bit floating point number to a map or stream. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_container_addString (solClient_opaqueContainer_pt container_p, const char *value, const char *name)
 Add a null terminated string (ASCII or UTF-8) to a map or stream. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_container_addDestination (solClient_opaqueContainer_pt container_p, const solClient_destination_t *value, size_t destSize, const char *name)
 Add a Solace destination (queue or topic) to the container. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_container_addUnknownField (solClient_opaqueContainer_pt container_p, const solClient_uint8_t *field_p, size_t length, const char *name)
 Add an application-defined field to the container. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_container_rewind (solClient_opaqueContainer_pt container_p)
 Rewind a container. More...
 
solClient_dllExport
solClient_bool_t 
solClient_container_hasNextField (solClient_opaqueContainer_pt container_p)
 When iterating through a container (a map or stream), this function will return false when the end of the container is reached without advancing the read cursor. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_container_getNextField (solClient_opaqueContainer_pt container_p, solClient_field_t *field_p, size_t fieldSize, const char **name_p)
 Read the next field of the map (or stream, although this function is not preferred for streams). More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_container_getField (solClient_opaqueContainer_pt container_p, solClient_field_t *value, size_t fieldSize, const char *name)
 Get a field value from the map or stream. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_container_getSize (solClient_opaqueContainer_pt container_p, size_t *size_p)
 Return the size of the map or stream. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_container_getNull (solClient_opaqueContainer_pt container_p, const char *name)
 Get a NULL value from the map or stream. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_container_getBoolean (solClient_opaqueContainer_pt container_p, solClient_bool_t *value, const char *name)
 Get a Boolean value from the map or stream. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_container_getUint8 (solClient_opaqueContainer_pt container_p, solClient_uint8_t *value, const char *name)
 Get an unsigned 8-bit int from the map or stream. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_container_getInt8 (solClient_opaqueContainer_pt container_p, solClient_int8_t *value, const char *name)
 Get a signed 8-bit int from the map or stream. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_container_getUint16 (solClient_opaqueContainer_pt container_p, solClient_uint16_t *value, const char *name)
 Get an unsigned 16-bit int from the map or stream. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_container_getInt16 (solClient_opaqueContainer_pt container_p, solClient_int16_t *value, const char *name)
 Get a signed 16-bit int from the map or stream. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_container_getUint32 (solClient_opaqueContainer_pt container_p, solClient_uint32_t *value, const char *name)
 Get an unsigned 32-bit int from the map or stream. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_container_getInt32 (solClient_opaqueContainer_pt container_p, solClient_int32_t *value, const char *name)
 Get a signed 32-bit int from the map or stream. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_container_getUint64 (solClient_opaqueContainer_pt container_p, solClient_uint64_t *value, const char *name)
 Get an unsigned 64-bit int from the map or stream. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_container_getInt64 (solClient_opaqueContainer_pt container_p, solClient_int64_t *value, const char *name)
 Get a signed 64-bit int from the map or stream. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_container_getChar (solClient_opaqueContainer_pt container_p, char *value, const char *name)
 Get an ASCII character from the map or stream. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_container_getWchar (solClient_opaqueContainer_pt container_p, solClient_wchar_t *value, const char *name)
 Get a unicode character from the map or stream. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_container_getByteArrayPtr (solClient_opaqueContainer_pt container_p, solClient_uint8_t **array_p, solClient_uint32_t *arrayLength_p, const char *name)
 Get a pointer to a byte array from the map or stream. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_container_getByteArray (solClient_opaqueContainer_pt container_p, solClient_uint8_t *array_p, solClient_uint32_t *arrayLength_p, const char *name)
 Get the contents of a byte array from the map or stream. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_container_getSmfPtr (solClient_opaqueContainer_pt container_p, solClient_uint8_t **smf_p, solClient_uint32_t *smfLength_p, const char *name)
 Get a pointer to a Solace Message Format (SMF) message from the map or stream. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_container_getSmf (solClient_opaqueContainer_pt container_p, solClient_uint8_t *smf_p, solClient_uint32_t *smfLength_p, const char *name)
 Get contents of a Solace Message Format (SMF) message from the map or stream. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_container_getFloat (solClient_opaqueContainer_pt container_p, float *value, const char *name)
 Get a float from the map or stream. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_container_getDouble (solClient_opaqueContainer_pt container_p, double *value, const char *name)
 Get a double from the map or stream. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_container_getStringPtr (solClient_opaqueContainer_pt container_p, const char **string, const char *name)
 Get a null terminated string from the map or stream. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_container_getString (solClient_opaqueContainer_pt container_p, char *string, size_t size, const char *name)
 Copy a null terminated string from the map or stream. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_container_getDestination (solClient_opaqueContainer_pt container_p, solClient_destination_t *value, size_t destSize, const char *name)
 Get a destination. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_container_getSubMap (solClient_opaqueContainer_pt container_p, solClient_opaqueContainer_pt *value, const char *name)
 Get a container pointer for the SubMap found in the current container. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_container_getSubStream (solClient_opaqueContainer_pt container_p, solClient_opaqueContainer_pt *value, const char *name)
 Get a container pointer for the SubStream found in the current container. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_container_deleteField (solClient_opaqueContainer_pt container_p, const char *name)
 Remove a field from a map. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_decodeFromSmf (solClient_bufInfo_pt bufinfo_p, solClient_opaqueMsg_pt *msg_p)
 Create an initialized message block from the passed in serialized (or raw) SMF message. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_encodeToSMF (solClient_opaqueMsg_pt msg_p, solClient_bufInfo_pt bufinfo_p, solClient_opaqueDatablock_pt *datab_p)
 Encode a message in Solace Message Format (SMF) and save the SMF encodings in the message bufinfo part. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_getPriority (solClient_opaqueMsg_pt msg_p, solClient_int32_t *priority_p)
 Get message priority. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_setPriority (solClient_opaqueMsg_pt msg_p, solClient_int32_t priority)
 Set message priority. More...
 
solClient_dllExport
solClient_bool_t 
solClient_replicationGroupMessageId_isValid (solClient_replicationGroupMessageId_pt rgmid_p)
 Validate a Replication Group Message Id. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_replicationGroupMessageId_compare (solClient_replicationGroupMessageId_pt rgmid1_p, solClient_replicationGroupMessageId_pt rgmid2_p, int *compare_p)
 Compare two Replication Group Message Id. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_replicationGroupMessageId_toString (solClient_replicationGroupMessageId_pt rgmid_p, size_t size_rgmid, char *str, size_t size_str)
 Convert a Replication Group Message Id to a defined string format. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_replicationGroupMessageId_fromString (solClient_replicationGroupMessageId_pt rgmid_p, size_t size_rgmid, const char *rgmid_str)
 Create a Replication Group Message Id from the string format. More...
 
solClient_dllExport
solClient_returnCode_t 
solClient_msg_getReplicationGroupMessageId (solClient_opaqueMsg_pt msg_p, solClient_replicationGroupMessageId_pt rgmid_p, size_t size)
 Retrieve a Replication Group Message Id from a received message. More...
 

Detailed Description

include file for Solace Corporation Messaging Buffer Management

Copyright 2008-2024 Solace Corporation. All rights reserved.

Macro Definition Documentation

#define solClient_msg_getSmfPtr   solClient_msg_getSMFPtr
#define SOLCLIENT_MSG_NUMDBQUANTA   (5)

The number of message size quanta available.

#define SOLCLIENT_MSGDUMP_BRIEF   (0)

Display only the length of the binary attachment, XML attachment, and user property map.

#define SOLCLIENT_MSGDUMP_FULL   (1)

Display the entire message.

#define SOLCLIENT_REPLICATION_GROUP_MESSAGE_ID_INITIALIZER   {{0}}
#define SOLCLIENT_REPLICATION_GROUP_MESSAGE_ID_SIZE   16
#define SOLCLIENT_REPLICATION_GROUP_MESSAGE_ID_STRING_LENGTH   41

Typedef Documentation

Type that indicates which message statistic.

Enumeration Type Documentation

Cache Status of received message, returned by solClient_msg_isCacheMsg()

Enumerator
SOLCLIENT_CACHE_INVALID_MESSAGE 
SOLCLIENT_CACHE_LIVE_MESSAGE 
SOLCLIENT_CACHE_MESSAGE 
SOLCLIENT_CACHE_SUSPECT_MESSAGE 

Statistics associated with message memory management.

These statistics can be retrieved through solClient_msg_getStat().

Enumerator
SOLCLIENT_MSG_STATS_TOTAL_MEMORY 

Approximate amount of total memory consumed for message pool (allocated and on free list)

SOLCLIENT_MSG_STATS_ALLOC_MEMORY 

Approximate amount of allocated memory (in-use; not on free list)

SOLCLIENT_MSG_STATS_MSG_ALLOCS 

The number of message allocations performed – calls to solClient_msg_alloc()

SOLCLIENT_MSG_STATS_MSG_FREES 

The number of message frees performed – calls to solClient_msg_free()

SOLCLIENT_MSG_STATS_MSG_DUPS 

The number of message dups performed – calls to solClient_msg_dup()

SOLCLIENT_MSG_STATS_MSG_REALLOCS 

The number of message re-allocations performed (growth in a message buffer)

SOLCLIENT_MSG_STATS_FREE_MSGS 

The number of messages on message free list.

SOLCLIENT_MSG_STATS_ALLOC_MSGS 

The number of currently allocated messages.

SOLCLIENT_MSG_STATS_FREE_CONTAINERS 

The number of containers (streams or maps) on container free list.

SOLCLIENT_MSG_STATS_ALLOC_CONTAINERS 

The number of currently allocated containers (for example, stream or map).

SOLCLIENT_MSG_STATS_FREE_DATA_BLOCKS 

The number of free data blocks (of specified quanta size from 0 to SOLCLIENT_MSG_NUMDBQUANTA - 1)

SOLCLIENT_MSG_STATS_ALLOC_DATA_BLOCKS 

The number of allocated data blocks (of specified quanta size).

Quanta SOLCLIENT_MSG_NUMDBQUANTA indicates messages currently allocated that are larger than maximum quanta size.

Function Documentation

solClient_dllExport solClient_returnCode_t solClient_container_addBoolean ( solClient_opaqueContainer_pt  container_p,
solClient_bool_t  value,
const char *  name 
)

Add a Boolean value to a map or stream.

If the container is a stream, the name parameter must be NULL. If the container is a map, the name parameter must be non-NULL.

See Also
Solace Structured Data Maps.
Parameters
container_pAn opaque container pointer.
valueA Boolean value. Any non-zero value is encoded as 1.
nameThe name of a field for a Map. This parameter must be NULL for a stream.
See Also
Encoding Overhead of Data Types in Streams and Maps
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 all subcodes.
Examples:
ex/RRDirectReplier.c, and ex/RRGuaranteedReplier.c.
solClient_dllExport solClient_returnCode_t solClient_container_addByteArray ( solClient_opaqueContainer_pt  container_p,
const solClient_uint8_t arr_p,
solClient_uint32_t  length,
const char *  name 
)

Add a byte array to a map or stream.

If the container is a stream, the name parameter must be NULL. If the container is a map, the name parameter must be non-NULL.

See Also
Solace Structured Data Maps
Parameters
container_pAn opaque container pointer.
arr_pA pointer to the byte array.
lengthThe length of the byte array.
nameThe name of a field for a map. This parameter must be NULL for a stream.
See Also
Encoding Overhead of Data Types in Streams and Maps
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 all subcodes.
solClient_dllExport solClient_returnCode_t solClient_container_addChar ( solClient_opaqueContainer_pt  container_p,
char  value,
const char *  name 
)

Add an ASCII character to a map or stream.

If the container is a stream, the name parameter must be NULL. If the container is a map, the name parameter must be non-NULL.

See Also
Solace Structured Data Maps
Parameters
container_pAn opaque container pointer.
valueAn ASCII character.
nameThe name of a field for a map. This parameter must be NULL for a stream.
See Also
Encoding Overhead of Data Types in Streams and Maps
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 all subcodes.
solClient_dllExport solClient_returnCode_t solClient_container_addContainer ( solClient_opaqueContainer_pt  container_p,
solClient_opaqueContainer_pt  subContainer_p,
const char *  name 
)

Add an existing container to a map or stream.

If the container being added to is a stream, the name parameter must be NULL. If the container is a map, the name parameter must be non-NULL. This is a copy-in operation. Changing the subContainer after calling this function will not be reflected in the copy created by this function.

See Also
Solace Structured Data Maps
Parameters
container_pAn opaque container pointer.
subContainer_pAn opaque container pointer for the container to add.
nameThe name of a field for a map. This parameter must be NULL for a stream.
See Also
Encoding Overhead of Data Types in Streams and Maps
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 all subcodes.
solClient_dllExport solClient_returnCode_t solClient_container_addDestination ( solClient_opaqueContainer_pt  container_p,
const solClient_destination_t value,
size_t  destSize,
const char *  name 
)

Add a Solace destination (queue or topic) to the container.

If the container is a stream, the name parameter must be NULL. If the container is a map, the name parameter must be non-NULL.

See Also
Solace Structured Data Maps
Parameters
container_pAn opaque container pointer.
valueA pointer to a solClient_destination_t.
destSizeThe size of solClient_destination_t
nameThe name of a field for a map. This parameter must be NULL for a stream.
See Also
Encoding Overhead of Data Types in Streams and Maps
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 all subcodes.
solClient_dllExport solClient_returnCode_t solClient_container_addDouble ( solClient_opaqueContainer_pt  container_p,
double  value,
const char *  name 
)

Add a 64-bit floating point number to a map or stream.

If the container is a stream, the name parameter must be NULL. If the container is a map, the name parameter must be non-NULL.

See Also
Solace Structured Data Maps
Parameters
container_pAn opaque container pointer.
valueA 64-bit floating point number
nameThe name of a field for a map. This parameter must be NULL for a stream.
See Also
Encoding Overhead of Data Types in Streams and Maps
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 all subcodes.
Examples:
ex/ios/examples/SdtPubSubMsgDepExample.m, ex/ios/examples/SdtPubSubMsgIndepExample.m, ex/RRDirectReplier.c, ex/RRGuaranteedReplier.c, ex/sdtPubSubMsgDep.c, and ex/sdtPubSubMsgIndep.c.
solClient_dllExport solClient_returnCode_t solClient_container_addFloat ( solClient_opaqueContainer_pt  container_p,
float  value,
const char *  name 
)

Add a 32-bit floating point number to a map or stream.

If the container is a stream, the name parameter must be NULL. If the container is a map, the name parameter must be non-NULL.

See Also
Solace Structured Data Maps
Parameters
container_pAn opaque container pointer.
valueA 32-bit floating point number
nameThe name of a field for a map. This parameter must be NULL for a stream.
See Also
Encoding Overhead of Data Types in Streams and Maps
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 all subcodes.
solClient_dllExport solClient_returnCode_t solClient_container_addInt16 ( solClient_opaqueContainer_pt  container_p,
solClient_int16_t  value,
const char *  name 
)

Add a signed 16-bit value to a map or stream.

If the container is a stream, the name parameter must be NULL. If the container is a map, the name parameter must be non-NULL.

See Also
Solace Structured Data Maps
Parameters
container_pAn opaque container pointer.
valueA signed 16-bit value.
nameThe name of a field for a map. This parameter must be NULL for a stream.
See Also
Encoding Overhead of Data Types in Streams and Maps
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 all subcodes.
solClient_dllExport solClient_returnCode_t solClient_container_addInt32 ( solClient_opaqueContainer_pt  container_p,
solClient_int32_t  value,
const char *  name 
)

Add a signed 32-bit value to a map or stream.

If the container is a stream, the name parameter must be NULL. If the container is a map, the name parameter must be non-NULL.

See Also
Solace Structured Data Maps
Parameters
container_pAn opaque container pointer.
valueA signed 32-bit value.
nameThe name of a field for a map. This parameter must be NULL for a stream.
See Also
Encoding Overhead of Data Types in Streams and Maps
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 all subcodes.
Examples:
ex/ios/examples/SdtPubSubMsgDepExample.m, ex/ios/examples/SdtPubSubMsgIndepExample.m, ex/RRDirectRequester.c, ex/RRGuaranteedRequester.c, ex/sdtPubSubMsgDep.c, and ex/sdtPubSubMsgIndep.c.
solClient_dllExport solClient_returnCode_t solClient_container_addInt64 ( solClient_opaqueContainer_pt  container_p,
solClient_int64_t  value,
const char *  name 
)

Add a signed 64-bit value to a map or stream.

If the container is a stream, the name parameter must be NULL. If the container is a map, the name parameter must be non-NULL.

See Also
Solace Structured Data Maps
Parameters
container_pAn opaque container pointer.
valueA signed 64-bit value.
nameThe name of a field for a map. This parameter must be NULL for a stream.
See Also
Encoding Overhead of Data Types in Streams and Maps
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 all subcodes.
solClient_dllExport solClient_returnCode_t solClient_container_addInt8 ( solClient_opaqueContainer_pt  container_p,
solClient_int8_t  value,
const char *  name 
)

Add a signed 8-bit value to a map or stream.

If the container is a stream, the name parameter must be NULL. If the container is a map, the name parameter must be non-NULL.

See Also
Solace Structured Data Maps
Parameters
container_pAn opaque container pointer.
valueA signed 8-bit value.
nameThe name of a field for a map. This parameter must be NULL for a stream.
See Also
Encoding Overhead of Data Types in Streams and Maps
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 all subcodes.
Examples:
ex/RRDirectRequester.c, and ex/RRGuaranteedRequester.c.
solClient_dllExport solClient_returnCode_t solClient_container_addNull ( solClient_opaqueContainer_pt  container_p,
const char *  name 
)

Add a NULL to a map or stream.

If the container is a stream, the name parameter must be NULL. If the container is a map, the name parameter must be non-NULL.

See Also
Solace Structured Data Maps
Parameters
container_pAn opaque container pointer.
nameThe name of a field for a map. This parameter must be NULL for a stream.
See Also
Encoding Overhead of Data Types in Streams and Maps
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 all subcodes.
solClient_dllExport solClient_returnCode_t solClient_container_addSmf ( solClient_opaqueContainer_pt  container_p,
const solClient_uint8_t smf_p,
solClient_uint32_t  length,
const char *  name 
)

Add a Solace Message Format (SMF) message to a map or stream.

If the container is a stream, the name parameter must be NULL. If the container is a map, the name parameter must be non-NULL.

See Also
Solace Structured Data Maps
Parameters
container_pAn opaque container pointer.
smf_pA pointer to the SMF message.
lengthThe length of the SMF message.
nameThe name of a field for a map. This parameter must be NULL for a stream.
See Also
Encoding Overhead of Data Types in Streams and Maps
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 all subcodes.
solClient_dllExport solClient_returnCode_t solClient_container_addString ( solClient_opaqueContainer_pt  container_p,
const char *  value,
const char *  name 
)

Add a null terminated string (ASCII or UTF-8) to a map or stream.

If the container is a stream, the name parameter must be NULL. If the container is a map, the name parameter must be non-NULL.

See Also
Solace Structured Data Maps
Parameters
container_pAn opaque container pointer.
valueA pointer to a NULL-terminated string.
nameThe name of a field for a map. This parameter must be NULL for a stream.
See Also
Encoding Overhead of Data Types in Streams and Maps
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 all subcodes.
Examples:
ex/ios/examples/SdtPubSubMsgDepExample.m, ex/ios/examples/SdtPubSubMsgIndepExample.m, ex/messageSelectorsOnQueue.c, ex/sdtPubSubMsgDep.c, and ex/sdtPubSubMsgIndep.c.
solClient_dllExport solClient_returnCode_t solClient_container_addUint16 ( solClient_opaqueContainer_pt  container_p,
solClient_uint16_t  value,
const char *  name 
)

Add an unsigned 16-bit value to a map or stream.

If the container is a stream, the name parameter must be NULL. If the container is a map, the name parameter must be non-NULL.

See Also
Solace Structured Data Maps
Parameters
container_pAn opaque container pointer.
valueAn unsigned 16-bit.
nameThe name of a field for a map. This parameter must be NULL for a stream.
See Also
Encoding Overhead of Data Types in Streams and Maps
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 all subcodes.
solClient_dllExport solClient_returnCode_t solClient_container_addUint32 ( solClient_opaqueContainer_pt  container_p,
solClient_uint32_t  value,
const char *  name 
)

Add an unsigned 32-bit value to a map or stream.

If the container is a stream, the name parameter must be NULL. If the container is a map, the name parameter must be non-NULL.

See Also
Solace Structured Data Maps
Parameters
container_pAn opaque container pointer.
valueAn unsigned 32-bit value.
nameThe name of a field for a map. This parameter must be NULL for a stream.
See Also
Encoding Overhead of Data Types in Streams and Maps
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 all subcodes.
solClient_dllExport solClient_returnCode_t solClient_container_addUint64 ( solClient_opaqueContainer_pt  container_p,
solClient_uint64_t  value,
const char *  name 
)

Add a unsigned 64-bit value to a map or stream.

If the container is a stream, the name parameter must be NULL. If the container is a map, the name parameter must be non-NULL.

See Also
Solace Structured Data Maps
Parameters
container_pAn opaque container pointer.
valueAn unsigned 64-bit value.
nameThe name of a field for a map. This parameter must be NULL for a stream.
See Also
Encoding Overhead of Data Types in Streams and Maps
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 all subcodes.
solClient_dllExport solClient_returnCode_t solClient_container_addUint8 ( solClient_opaqueContainer_pt  container_p,
solClient_uint8_t  value,
const char *  name 
)

Add a unsigned 8-bit value to a map or stream.

If the container is a stream, the name parameter must be NULL. If the container is a map, the name parameter must be non-NULL.

See Also
Solace Structured Data Maps
Parameters
container_pAn opaque container pointer.
valueAn unsigned 8-bit value.
nameThe name of a field for a map. This parameter must be NULL for a stream.
See Also
Encoding Overhead of Data Types in Streams and Maps
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 all subcodes.
solClient_dllExport solClient_returnCode_t solClient_container_addUnknownField ( solClient_opaqueContainer_pt  container_p,
const solClient_uint8_t field_p,
size_t  length,
const char *  name 
)

Add an application-defined field to the container.

The field must be properly encoded according to the Solace-defined machine-independent coding rules. Typically, this function is only used by forwarding applications that need to forward unrecognized fields discovered by solClient_container_getField (field type is SOLCLIENT_UNKNOWN). If the container is a stream, the name parameter must be NULL. If the container is a map, the name parameter must be non-NULL.

See Also
Solace Structured Data Maps
Parameters
container_pAn opaque container pointer.
field_pA pointer to a byte array containing the encoded field.
lengthThe length of the field.
nameThe name of a field for a map. This parameter must be NULL for a stream.
See Also
Encoding Overhead of Data Types in Streams and Maps
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 all subcodes.
solClient_dllExport solClient_returnCode_t solClient_container_addWchar ( solClient_opaqueContainer_pt  container_p,
solClient_wchar_t  value,
const char *  name 
)

Add a unicode (wide) character to a map or stream.

If the container is a stream, the name parameter must be NULL. If the container is a map, the name parameter must be non-NULL.

See Also
Solace Structured Data Maps
Parameters
container_pAn opaque container pointer.
valueA 16-bit unicode character.
nameThe name of a field for a map. This parameter must be NULL for a stream.
See Also
Encoding Overhead of Data Types in Streams and Maps
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 all subcodes.
solClient_dllExport solClient_returnCode_t solClient_container_closeMapStream ( solClient_opaqueContainer_pt container_p)

Finish a map or stream.

This action makes the opaque container pointer invalid and fixes the structured data in memory.

Parameters
container_pA pointer to the opaque container pointer. The pointer is reset to NULL 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 all subcodes.
Examples:
ex/ios/examples/SdtPubSubMsgIndepExample.m, ex/messageSelectorsOnQueue.c, and ex/sdtPubSubMsgIndep.c.
solClient_dllExport solClient_returnCode_t solClient_container_createMap ( solClient_opaqueContainer_pt newContainer_p,
char *  mem_p,
size_t  size 
)

Create a map container in a memory location given by the caller.

It is the caller's responsibility to ensure that the memory pointer and size are valid. If the map that is created by subsequent calls to add structured data types exceeds size, the add operation fails and the error subCode is set to SOLCLIENT_SUBCODE_INSUFFICIENT_SPACE. The map is a multimap in which more than one value may be associated with a given field name. A call to solClient_container_addXyz() does not overwrite an existing field, instead it adds a new one. To overwrite an existing field, the field has to been deleted and then added with a new value. To get all values associated with a given field name, a linear search is required. Any existing data is overwritten with the map that is created by subsequent primitive data functions. The returned opaque container reference must be used for subsequent add functions. In addition, the returned opaque container can itself be added to other containers or directly to a message binary attachment part. The returned map must later be closed by a call to solClient_container_closeMapStream().

Parameters
newContainer_pA pointer location to receive the container pointer.
mem_pA pointer to memory that is used to build the map.
sizeThe maximum size of the map to be 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 all subcodes.
Examples:
ex/ios/examples/SdtPubSubMsgIndepExample.m, and ex/sdtPubSubMsgIndep.c.
solClient_dllExport solClient_returnCode_t solClient_container_createStream ( solClient_opaqueContainer_pt newContainer_p,
char *  mem_p,
size_t  size 
)

This function creates a stream container in a memory location given by the caller.

It is the caller's responsibility to ensure that the memory pointer and size are valid. If the stream that is built by subsequent calls to add structured data types exceeds the specified maximum size, the add operation fails and the error subCode is set to SOLCLIENT_SUBCODE_INSUFFICIENT_SPACE. Any existing data is overwritten with the stream that is created by subsequent primitive data functions. The returned opaque container reference must be used for subsequent add functions. In addition, the returned opaque container itself can be added to other containers or directly to a message binary attachment part. The returned stream must later be closed by a call to solClient_container_closeMapStream().

Parameters
newContainer_pA pointer location to receive the container pointer.
mem_pA pointer to memory that is used to build the stream.
sizeThe maximum size of the stream to be 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 all subcodes.
Examples:
ex/ios/examples/SdtPubSubMsgIndepExample.m, and ex/sdtPubSubMsgIndep.c.
solClient_dllExport solClient_returnCode_t solClient_container_deleteField ( solClient_opaqueContainer_pt  container_p,
const char *  name 
)

Remove a field from a map.

This function returns an error if called on a stream. The serialized map is scanned and the named field is removed. All subsequent fields in the serialized map are moved; this can be a slow operation.

Parameters
container_pAn opaque container pointer.
nameThe name of the field to remove.
Returns
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
Examples:
ex/ios/examples/SdtPubSubMsgDepExample.m, ex/ios/examples/SdtPubSubMsgIndepExample.m, ex/sdtPubSubMsgDep.c, and ex/sdtPubSubMsgIndep.c.
solClient_dllExport solClient_returnCode_t solClient_container_getBoolean ( solClient_opaqueContainer_pt  container_p,
solClient_bool_t value,
const char *  name 
)

Get a Boolean value from the map or stream.

For a map, the name pointer must not be NULL, and the field corresponding to the name is returned. For a stream, the name pointer must be NULL. The next field in the stream is extracted and the read position in the stream is advanced.

Parameters
container_pAn opaque container pointer.
valueA pointer to a Boolean, it contains binary 0 or 1 on successful return.
nameThe name of a field for a map. This parameter must be NULL for a stream.
Returns
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
Examples:
ex/RRDirectRequester.c, and ex/RRGuaranteedRequester.c.
solClient_dllExport solClient_returnCode_t solClient_container_getByteArray ( solClient_opaqueContainer_pt  container_p,
solClient_uint8_t array_p,
solClient_uint32_t *  arrayLength_p,
const char *  name 
)

Get the contents of a byte array from the map or stream.

For a map, the name pointer must not be NULL, and the field corresponding to the name is returned. For a stream, the name pointer must be NULL. The next field in the stream is extracted, and the read position in the stream is advanced.

Parameters
container_pAn opaque container pointer.
array_pA pointer to where the byte array is returned
arrayLength_pThe IN/OUT maximum length of array.
nameThe name of a field for a map. This parameter must be NULL for a stream.
Returns
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
solClient_dllExport solClient_returnCode_t solClient_container_getByteArrayPtr ( solClient_opaqueContainer_pt  container_p,
solClient_uint8_t **  array_p,
solClient_uint32_t *  arrayLength_p,
const char *  name 
)

Get a pointer to a byte array from the map or stream.

For a map, the name pointer must not be NULL, and the field corresponding to the name is returned. For a stream, the name pointer must be NULL. The next field in the stream is extracted and the read position in the stream is advanced.

Parameters
container_pAn opaque container pointer.
array_pThe address where the pointer to a byte array is returned.
arrayLength_pThe returned array length.
nameThe name of a field for a map. This parameter must be NULL for a stream.
Returns
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
solClient_dllExport solClient_returnCode_t solClient_container_getChar ( solClient_opaqueContainer_pt  container_p,
char *  value,
const char *  name 
)

Get an ASCII character from the map or stream.

For a map, the name pointer must not be NULL, and the field corresponding to the name is returned. For a stream, the name pointer must be NULL. The next field in the stream is extracted and the read position in the stream is advanced.

Parameters
container_pAn opaque container pointer.
valueA pointer to a char.
nameThe name of a field for a map. This parameter must be NULL for a stream.
Returns
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
solClient_dllExport solClient_returnCode_t solClient_container_getDestination ( solClient_opaqueContainer_pt  container_p,
solClient_destination_t value,
size_t  destSize,
const char *  name 
)

Get a destination.

For a map, the name pointer must not be NULL, and the field corresponding to the name is returned. For a stream, the name pointer must be NULL. The next field in the stream is extracted and the read position in the stream is advanced.

If the field is a destination, this function copies the destination information to the supplied 'destination' structure. Within the destination is a pointer to the destination name (a string within the message). This string is only valid as long as the solClient_msg is valid.

Parameters
container_pAn opaque container pointer.
valueA pointer to a solClient_destination_t.
destSizesizeof(solClient_destination_t). This parameter is used for backwards binary compatibility if solClient_destination_t changes in the future.
nameThe name of a field for a map. This parameter must be NULL for a stream.
Returns
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
solClient_dllExport solClient_returnCode_t solClient_container_getDouble ( solClient_opaqueContainer_pt  container_p,
double *  value,
const char *  name 
)

Get a double from the map or stream.

For a map, the name pointer must not be NULL, and the field corresponding to the name is returned. For a stream, the name pointer must be NULL. The next field in the stream is extracted, and the read position in the stream is advanced.

Parameters
container_pAn opaque container pointer.
valueA pointer to a double.
nameThe name of a field for a map. This parameter must be NULL for a stream.
Returns
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
Examples:
ex/RRDirectRequester.c, and ex/RRGuaranteedRequester.c.
solClient_dllExport solClient_returnCode_t solClient_container_getField ( solClient_opaqueContainer_pt  container_p,
solClient_field_t value,
size_t  fieldSize,
const char *  name 
)

Get a field value from the map or stream.

For a map, the name pointer must not be NULL, and the field corresponding to the name is returned. For a stream, the name pointer must be NULL. The next field in the stream is extracted, and the read position in the stream is advanced.

Note that normally the solClient_container_getXXX for a specific type is used, instead of solClient_container_getField. However, this function can be used to get a named field from a map, or the next field from a stream, without knowing its type in advance.

If the returned field is a container (map or stream), the container should later be closed by a call to solClient_container_closeMapStream(). However, if it is not, the container is automatically closed when the associated message is freed through a call to solClient_msg_free(), or if the parent container is closed. If the container is closed automatically, the application may not continue to use the container. Attempting to use a closed container will return an invalid pointer error (SOLCLIENT_SUBCODE_PARAM_NULL_PTR).

Parameters
container_pAn opaque container pointer.
valueA pointer to a solClient_field_t to receive the returned type and value.
fieldSizesizeof(solClient_field_t). This parameter is used for backwards binary compatibility if solClient_field_t grows.
nameThe name of a field for a map. This parameter must be NULL for a stream.
Returns
SOLCLIENT_OK on success, SOLCLIENT_EOS on the end of a stream, SOLCLIENT_NOT_FOUND if not found in a map, 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 all subcodes.
solClient_dllExport solClient_returnCode_t solClient_container_getFloat ( solClient_opaqueContainer_pt  container_p,
float *  value,
const char *  name 
)

Get a float from the map or stream.

For a map, the name pointer must not be NULL, and the field corresponding to the name is returned. For a stream, the name pointer must be NULL. The next field in the stream is extracted and the read position in the stream is advanced.

Parameters
container_pAn opaque container pointer.
valueA pointer to a float value.
nameThe name of a field for a map. This parameter must be NULL for a stream.
Returns
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
solClient_dllExport solClient_returnCode_t solClient_container_getInt16 ( solClient_opaqueContainer_pt  container_p,
solClient_int16_t value,
const char *  name 
)

Get a signed 16-bit int from the map or stream.

For a map, the name pointer must not be NULL, and the field corresponding to the name is returned. For a stream, the name pointer must be NULL. The next field in the stream is extracted and the read position in the stream is advanced.

Parameters
container_pAn opaque container pointer.
valueA pointer to a signed 16-bit int.
nameThe name of a field for a map. This parameter must be NULL for a stream.
Returns
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
solClient_dllExport solClient_returnCode_t solClient_container_getInt32 ( solClient_opaqueContainer_pt  container_p,
solClient_int32_t *  value,
const char *  name 
)

Get a signed 32-bit int from the map or stream.

For a map, the name pointer must not be NULL, and the field corresponding to the name is returned. For a stream, the name pointer must be NULL. The next field in the stream is extracted and the read position in the stream is advanced.

Parameters
container_pAn opaque container pointer.
valueA pointer to a signed 32-bit int.
nameThe name of a field for a map. This parameter must be NULL for a stream.
Returns
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
Examples:
ex/RRDirectReplier.c, and ex/RRGuaranteedReplier.c.
solClient_dllExport solClient_returnCode_t solClient_container_getInt64 ( solClient_opaqueContainer_pt  container_p,
solClient_int64_t value,
const char *  name 
)

Get a signed 64-bit int from the map or stream.

For a map, the name pointer must not be NULL, and the field corresponding to the name is returned. For a stream, the name pointer must be NULL. The next field in the stream is extracted, and the read position in the stream is advanced.

Parameters
container_pAn opaque container pointer.
valueA pointer to a signed 64-bit int.
nameThe name of a field for a map. This parameter must be NULL for a stream.
Returns
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
solClient_dllExport solClient_returnCode_t solClient_container_getInt8 ( solClient_opaqueContainer_pt  container_p,
solClient_int8_t value,
const char *  name 
)

Get a signed 8-bit int from the map or stream.

For a map, the name pointer must not be NULL, and the field corresponding to the name is returned. For a stream, the name pointer must be NULL. The next field in the stream is extracted and the read position in the stream is advanced.

Parameters
container_pAn opaque container pointer.
valueA pointer to a signed 8-bit int.
nameThe name of a field for a map. This parameter must be NULL for a stream.
Returns
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
Examples:
ex/RRDirectReplier.c, and ex/RRGuaranteedReplier.c.
solClient_dllExport solClient_returnCode_t solClient_container_getNextField ( solClient_opaqueContainer_pt  container_p,
solClient_field_t field_p,
size_t  fieldSize,
const char **  name_p 
)

Read the next field of the map (or stream, although this function is not preferred for streams).

For a map, this returns the next field in the map, including the name of the field. This allows the application to iterate over the contents of the map.

While this function will work for a stream, it is preferable to use solClient_container_getField or solClient_container_getXXX for a specific field type. If this routine is used, a NULL pointer is returned for the field name if the provided pointer to the field name is not NULL.

If the returned field is a container (map or stream), the container should later be closed by a call to solClient_container_closeMapStream(). However, if it is not, the container is automatically closed when the associated message is freed through a call to solClient_msg_free(), or if the parent container is closed. If the container is closed automatically, the application may not continue to use the container. Attempting to use a closed container will return an invalid pointer error (SOLCLIENT_SUBCODE_PARAM_NULL_PTR).

Parameters
container_pAn opaque container pointer.
field_pThe address of solClient_field_t where the API will return field type and value.
fieldSizesizeof(solClient_field_t). This parameter is used for backwards binary compatibility if solClient_field_t grows.
name_pThe address of the pointer where API will return a pointer to the NULL-terminated field name. For a stream, the passed in pointer can be NULL, and if not, the returned pointer will be NULL.
Returns
SOLCLIENT_OK on success, SOLCLIENT_FAIL on failure. SOLCLIENT_EOS at end of container.
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
solClient_dllExport solClient_returnCode_t solClient_container_getNull ( solClient_opaqueContainer_pt  container_p,
const char *  name 
)

Get a NULL value from the map or stream.

Any data type, including maps and streams, can be read as a NULL type. For a map, the name pointer must not be NULL, and the field corresponding to the name is returned. For a stream, the name pointer must be NULL. The next field in the stream is extracted and the read position in the stream is advanced.

Parameters
container_pAn opaque container pointer.
nameThe name of a field for a map. This parameter must be NULL for a stream.
Returns
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
solClient_dllExport solClient_returnCode_t solClient_container_getSize ( solClient_opaqueContainer_pt  container_p,
size_t *  size_p 
)

Return the size of the map or stream.

Parameters
container_pAn opaque container pointer.
size_pA pointer to a size_t location where the size is returned.
Returns
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
solClient_dllExport solClient_returnCode_t solClient_container_getSmf ( solClient_opaqueContainer_pt  container_p,
solClient_uint8_t smf_p,
solClient_uint32_t *  smfLength_p,
const char *  name 
)

Get contents of a Solace Message Format (SMF) message from the map or stream.

For a map, the name pointer must not be NULL, and the field corresponding to the name is returned. For a stream, the name pointer must be NULL. The next field in the stream is extracted and the read position in the stream is advanced.

Parameters
container_pAn opaque container pointer.
smf_pA pointer to where the byte array is returned
smfLength_pThe IN/OUT maximum length of array.
nameThe name of a field for a map. This parameter must be NULL for a stream.
Returns
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
solClient_dllExport solClient_returnCode_t solClient_container_getSmfPtr ( solClient_opaqueContainer_pt  container_p,
solClient_uint8_t **  smf_p,
solClient_uint32_t *  smfLength_p,
const char *  name 
)

Get a pointer to a Solace Message Format (SMF) message from the map or stream.

For a map, the name pointer must not be NULL, and the field corresponding to the name is returned. For a stream, the name pointer must be NULL. The next field in the stream is extracted, and the read position in the stream is advanced.

Parameters
container_pAn opaque container pointer.
smf_pAn address where a pointer to a byte array is returned
smfLength_pThe returned array length.
nameThe name of a field for a map. This parameter must be NULL for a stream.
Returns
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
solClient_dllExport solClient_returnCode_t solClient_container_getString ( solClient_opaqueContainer_pt  container_p,
char *  string,
size_t  size,
const char *  name 
)

Copy a null terminated string from the map or stream.

For a map, the name pointer must not be NULL, and the field corresponding to the name is returned. For a stream, the name pointer must be NULL. The next field in the stream is extracted, and the read position in the stream is advanced.

Parameters
container_pAn opaque container pointer.
stringA pointer to a string location.
sizeA maximum length of string.
nameThe name of a field for a map. This parameter must be NULL for a stream.
Returns
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
solClient_dllExport solClient_returnCode_t solClient_container_getStringPtr ( solClient_opaqueContainer_pt  container_p,
const char **  string,
const char *  name 
)

Get a null terminated string from the map or stream.

For a map, the name pointer must not be NULL, and the field corresponding to the name is returned. For a stream, the name pointer must be NULL. The next field in the stream is extracted, and the read position in the stream is advanced.

Parameters
container_pAn opaque container pointer.
stringAn address of pointer to a string location.
nameThe name of a field for a map. This parameter must be NULL for a stream.
Returns
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
solClient_dllExport solClient_returnCode_t solClient_container_getSubMap ( solClient_opaqueContainer_pt  container_p,
solClient_opaqueContainer_pt value,
const char *  name 
)

Get a container pointer for the SubMap found in the current container.

For a map, the name pointer must not be NULL, and the field corresponding to the name is returned. For a stream, the name pointer must be NULL. The next field in the stream is extracted, and the read position in the stream is advanced.

The returned map should later be closed by a call to solClient_container_closeMapStream(). However, if it is not, the map is automatically closed when the associated message is freed through a call to solClient_msg_free(). If the map is closed automatically, the application may not continue to use the map. Attempting to use a closed map will return an invalid pointer error (SOLCLIENT_SUBCODE_PARAM_NULL_PTR).

Parameters
container_pAn opaque container pointer.
valueA pointer to a container pointer.
nameThe name of a field for a map. This parameter must be NULL for a stream.
Returns
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
solClient_dllExport solClient_returnCode_t solClient_container_getSubStream ( solClient_opaqueContainer_pt  container_p,
solClient_opaqueContainer_pt value,
const char *  name 
)

Get a container pointer for the SubStream found in the current container.

For a map, the name pointer must not be NULL, and the field corresponding to the name is returned. For a stream, the name pointer must be NULL. The next field in the stream is extracted and the read position in the stream is advanced.

The returned stream should later be closed by a call to solClient_container_closeMapStream(). However, if it is not, the stream is automatically closed when the associated message is freed through a call to solClient_msg_free(). If the stream is closed automatically, the application may not continue to use the stream. Attempting to use a closed stream will return an invalid pointer error (SOLCLIENT_SUBCODE_PARAM_NULL_PTR).

Parameters
container_pAn opaque container pointer.
valueA pointer to a container pointer.
nameThe name of a field for a map. This parameter must be NULL for a stream.
Returns
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
solClient_dllExport solClient_returnCode_t solClient_container_getUint16 ( solClient_opaqueContainer_pt  container_p,
solClient_uint16_t value,
const char *  name 
)

Get an unsigned 16-bit int from the map or stream.

For a map, the name pointer must not be NULL, and the field corresponding to the name is returned. For a stream, the name pointer must be NULL. The next field in the stream is extracted and the read position in the stream is advanced.

Parameters
container_pAn opaque container pointer.
valueA pointer to an unsigned 16-bit int.
nameThe name of a field for a map. This parameter must be NULL for a stream.
Returns
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
solClient_dllExport solClient_returnCode_t solClient_container_getUint32 ( solClient_opaqueContainer_pt  container_p,
solClient_uint32_t *  value,
const char *  name 
)

Get an unsigned 32-bit int from the map or stream.

For a map, the name pointer must not be NULL, and the field corresponding to the name is returned. For a stream, the name pointer must be NULL. The next field in the stream is extracted and the read position in the stream is advanced.

Parameters
container_pAn opaque container pointer.
valueA pointer to an unsigned 32-bit int.
nameThe name of a field for a map. This parameter must be NULL for a stream.
Returns
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
solClient_dllExport solClient_returnCode_t solClient_container_getUint64 ( solClient_opaqueContainer_pt  container_p,
solClient_uint64_t value,
const char *  name 
)

Get an unsigned 64-bit int from the map or stream.

For a map, the name pointer must not be NULL, and the field corresponding to the name is returned. For a stream, the name pointer must be NULL. The next field in the stream is extracted and the read position in the stream is advanced.

Parameters
container_pAn opaque container pointer.
valueA pointer to an unsigned 64-bit int.
nameThe name of a field for a map. This parameter must be NULL for a stream.
Returns
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
solClient_dllExport solClient_returnCode_t solClient_container_getUint8 ( solClient_opaqueContainer_pt  container_p,
solClient_uint8_t value,
const char *  name 
)

Get an unsigned 8-bit int from the map or stream.

For a map, the name pointer must not be NULL, and the field corresponding to the name is returned. For a stream, the name pointer must be NULL. The next field in the stream is extracted and the read position in the stream is advanced.

Parameters
container_pAn opaque container pointer.
valueA pointer to a unsigned 8-bit int.
nameThe name of a field for a map. This parameter must be NULL for a stream.
Returns
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
solClient_dllExport solClient_returnCode_t solClient_container_getWchar ( solClient_opaqueContainer_pt  container_p,
solClient_wchar_t value,
const char *  name 
)

Get a unicode character from the map or stream.

For a map, the name pointer must not be NULL, and the field corresponding to the name is returned. For a stream, the name pointer must be NULL. The next field in the stream is extracted and the read position in the stream is advanced.

Parameters
container_pAn opaque container pointer.
valueA pointer to a unicode character.
nameThe name of a field for a map. This parameter must be NULL for a stream.
Returns
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
solClient_dllExport solClient_bool_t solClient_container_hasNextField ( solClient_opaqueContainer_pt  container_p)

When iterating through a container (a map or stream), this function will return false when the end of the container is reached without advancing the read cursor.

It will return true otherwise.

Parameters
container_pAn opaque container pointer.
Returns
TRUE, if there is a next field in the container; FALSE, otherwise.
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
solClient_dllExport solClient_returnCode_t solClient_container_openSubMap ( solClient_opaqueContainer_pt  container_p,
solClient_opaqueContainer_pt newContainer_p,
const char *  name 
)

Open a nested subMap.

The subMap is a multimap in which more than one value may be associated with a given field name. This is a special add function to create a map in an existing container. It returns a new solClient_opaqueContainer_pt that can be used to build a map using addXXX function. It is possible to add to the original container; however, this can cause extensive data moving operations when the subMap is later closed by a call to solClient_container_closeMapStream. It is more efficient to write the subMap completely and close it before writing again to the original container. The returned map should later be closed by a call to solClient_container_closeMapStream(). However, if it is not, the map is automatically closed when the associated message is freed through a call to solClient_msg_free(), or if the parent container is closed. If the map is closed automatically, the application may not continue to use the map. Attempting to use a closed map returns an invalid pointer error (SOLCLIENT_SUBCODE_PARAM_NULL_PTR).

Parameters
container_pAn opaque container pointer.
newContainer_pA pointer to memory to receive returned opaque container pointer.
nameThe name of the Map if the container_ is Map, must be NULL if container_p references a Stream.
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 all subcodes.
solClient_dllExport solClient_returnCode_t solClient_container_openSubStream ( solClient_opaqueContainer_pt  container_p,
solClient_opaqueContainer_pt newContainer_p,
const char *  name 
)

Open a nested subStream.

This is a special 'add' function to create a stream in an existing container. It returns a new solClient_opaqueContainer_pt that may be used to build a stream using addXXX function. It is possible to add to the original container; however, this can cause extensive data moving operations when the subStream is later closed by a call to solClient_container_closeMapStream. It is more efficient to write the subStream completely and close it before writing again to the original container. The returned stream should later be closed by a call to solClient_container_closeMapStream(). However, if it is not, the stream is automatically closed when the associated message is freed by a call to solClient_msg_free(), or if the parent container is closed. If the stream is closed automatically, the application may not continue to use the stream. Attempting to use a closed stream will return an invalid pointer error (SOLCLIENT_SUBCODE_PARAM_NULL_PTR).

Parameters
container_pAn opaque container pointer.
newContainer_pA pointer to memory to receive returned opaque container pointer.
nameThe name of the stream if the container_p is a map; it must be NULL if container_p references a stream.
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 all subcodes.
solClient_dllExport solClient_returnCode_t solClient_container_rewind ( solClient_opaqueContainer_pt  container_p)

Rewind a container.

Rewind the stream or map so that the getting of fields can be started over from the start of the stream or map.

Parameters
container_pAn opaque container pointer.
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 all subcodes.
solClient_dllExport solClient_returnCode_t solClient_msg_alloc ( solClient_opaqueMsg_pt msg_p)

Allocate a solClient Msg that can be used for storing and sending messages to and from the Solace Messaging Appliance.

Applications are responsible for releasing all message buffers they allocate by solClient_msg_alloc().

Parameters
msg_pA pointer to the memory that will hold the Msg pointer. This is an opaque value. Elements of the msg may only be accessed by the accessors defined in this API.
Returns
SOLCLIENT_OK on success. SOLCLIENT_FAIL on failure. msg_p is only valid after a SOLCLIENT_OK return.
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
Examples:
ex/adPubAck.c, ex/common.c, ex/directPubSub.c, ex/flowControlQueue.c, ex/ios/Example.m, ex/ios/examples/AppReachabilityExample.m, ex/ios/examples/AppTransitionsExample.m, ex/ios/examples/DirectPubSubExample.m, ex/ios/examples/PerfTestExample.m, ex/ios/examples/RedirectLogsExample.m, ex/ios/examples/SdtPubSubMsgDepExample.m, ex/ios/examples/SdtPubSubMsgIndepExample.m, ex/ios/examples/SecureSessionExample.m, ex/ios/examples/SempGetOverMbExample.m, ex/ios/intro/HelloWorldPubExample.m, ex/ios/intro/HelloWorldWebPubExample.m, ex/messageReplay.c, ex/messageSelectorsOnQueue.c, ex/messageTTLAndDeadMessageQueue.c, ex/noLocalPubSub.c, ex/perfADPub.c, ex/perfTest.c, ex/queueProvision.c, ex/redirectLogs.c, ex/replication.c, ex/RRDirectReplier.c, ex/RRDirectRequester.c, ex/RRGuaranteedReplier.c, ex/RRGuaranteedRequester.c, ex/sdtPubSubMsgDep.c, ex/sdtPubSubMsgIndep.c, ex/secureSession.c, ex/sempGetOverMb.c, ex/simpleBrowserFlow.c, ex/simpleFlowToQueue.c, ex/simpleFlowToTopic.c, ex/transactions.c, Intro/HelloWorldPub.c, Intro/HelloWorldQueuePub.c, and Intro/HelloWorldWebPub.c.
solClient_dllExport solClient_returnCode_t solClient_msg_createBinaryAttachmentMap ( solClient_opaqueMsg_pt  msg_p,
solClient_opaqueContainer_pt map_p,
solClient_uint32_t  size 
)

Create a map container in the binary attachment of the message.

The map is a multimap in which more than one value may be associated with a given field name. A call to solClient_container_addXyz() does not overwrite an existing one, but adds a new one instead. To overwrite an existing field, the field has to been deleted and then added with a new value. To get all values associated with a given field name, a linear search is required. Any existing data is overwritten with the map that will be created by subsequent primitive data functions. The returned opaque container reference must be used for subsequent add functions. The returned map should later be closed by a call to solClient_container_closeMapStream(). However, if it is not, the map is automatically closed when the associated message is freed through a call to solClient_msg_free(). If the map is closed automatically, the application may not continue to use the map. Attempting to use a closed map will return an invalid pointer error (SOLCLIENT_SUBCODE_PARAM_NULL_PTR).

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
map_pA pointer location to receive the container pointer.
sizeA hint to the size (in bytes) of the map to be created. This is used to determine what size of data block to allocate. Datablocks are available in fixed sizes from SOLCLIENT_GLOBAL_PROP_DBQUANTASIZE_0 to SOLCLIENT_GLOBAL_PROP_DBQUANTASIZE_4. If the data block is too small for the subsequently created map, a larger data block is allocated when necessary, and existing structured data copied into place. This reallocation can negatively affect performance.
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 all subcodes.
solClient_dllExport solClient_returnCode_t solClient_msg_createBinaryAttachmentStream ( solClient_opaqueMsg_pt  msg_p,
solClient_opaqueContainer_pt stream_p,
solClient_uint32_t  size 
)

Create a stream container in the binary attachment of the message.

Any existing data is overwritten with the stream that is created by subsequent primitive data functions. The returned opaque container reference must be used for subsequent add functions. The returned stream should later be closed by a call to solClient_container_closeMapStream(). However, if it is not, the stream is automatically closed when the associated message is freed through a call to solClient_msg_free(). If the stream is closed automatically, the application may not continue to use the stream. Attempting to use a closed stream returns an invalid pointer error (SOLCLIENT_SUBCODE_PARAM_NULL_PTR).

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
stream_pA pointer location to receive the container pointer.
sizeA hint to the size (in bytes) of the stream to be created. This is used to determine what size of data block to allocate. Datablocks are available in fixed sizes from SOLCLIENT_GLOBAL_PROP_DBQUANTASIZE_0 to SOLCLIENT_GLOBAL_PROP_DBQUANTASIZE_4. If it is too small for the subsequently created stream, a larger data block is allocated when necessary and existing structured data copied into place. This reallocation can negatively affect performance.
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 all subcodes.
Examples:
ex/ios/examples/SdtPubSubMsgDepExample.m, ex/RRDirectReplier.c, ex/RRDirectRequester.c, ex/RRGuaranteedReplier.c, ex/RRGuaranteedRequester.c, and ex/sdtPubSubMsgDep.c.
solClient_dllExport solClient_returnCode_t solClient_msg_createUserPropertyMap ( solClient_opaqueMsg_pt  msg_p,
solClient_opaqueContainer_pt map_p,
solClient_uint32_t  size 
)

Create a User Property map in the binary metadata header.

The map is a multimap in which more than one value may be associated with a given field name. A call to solClient_container_addXyz() does not overwrite an existing one, but adds a new one instead. To overwrite an existing field, the field has to been deleted and then added with a new value. To get all values associated with a given field name, a linear search is required. Any existing data is overwritten with the map that is created by subsequent primitive data functions. It returns an opaque container reference that must be used for subsequent add functions. The returned map should later be closed by a call to solClient_container_closeMapStream(). However, if it is not, the stream is automatically closed when the associated message is freed through a call to solClient_msg_free(). If the stream is closed automatically, the application may not continue to use the stream. Attempting to use a closed stream returns an invalid pointer error (SOLCLIENT_SUBCODE_PARAM_NULL_PTR).

Parameters
msg_psolClient_opaqueMsg_pt returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
map_pA pointer location to receive the container pointer.
sizeA hint to the size (in bytes) of the map to be created. This is used to determine what size of data block to allocate. Datablocks are available in fixed sizes from SOLCLIENT_GLOBAL_PROP_DBQUANTASIZE_0 to SOLCLIENT_GLOBAL_PROP_DBQUANTASIZE_4. If it is too small for the subsequently created map, a larger data block is allocated when necessary, and existing structured data is copied into place. This reallocation can negatively affect performance.
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 all subcodes.
Examples:
ex/ios/examples/SdtPubSubMsgDepExample.m, ex/messageSelectorsOnQueue.c, and ex/sdtPubSubMsgDep.c.
solClient_dllExport solClient_returnCode_t solClient_msg_decodeFromSmf ( solClient_bufInfo_pt  bufinfo_p,
solClient_opaqueMsg_pt msg_p 
)

Create an initialized message block from the passed in serialized (or raw) SMF message.

A solClient message buffer is allocated. Applications are responsible for releasing the message buffer.

Parameters
bufinfo_pA pointer to the bufInfo describing a validly formatted SMF direct message.
msg_pPointer to a reference to a message. This value is set on successful return to a msg_p suitable for subsequent function calls. The message buffer has to be freed by applications on successful return.
Returns
SOLCLIENT_OK or SOLCLIENT_FAIL
solClient_dllExport solClient_returnCode_t solClient_msg_deleteApplicationMessageId ( solClient_opaqueMsg_pt  msg_p)

Given a msg_p, delete the Application MessageId field.

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
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 all subcodes.
solClient_dllExport solClient_returnCode_t solClient_msg_deleteApplicationMsgType ( solClient_opaqueMsg_pt  msg_p)

Given a msg_p, delete the MsgType field.

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
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 all subcodes.
solClient_dllExport solClient_returnCode_t solClient_msg_deleteCorrelationId ( solClient_opaqueMsg_pt  msg_p)

Given a msg_p, delete the Correlation Id field.

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
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 all subcodes.
solClient_dllExport solClient_returnCode_t solClient_msg_deleteHttpContentEncoding ( solClient_opaqueMsg_pt  msg_p)

Given a msg_p, delete the HTTP Content Encoding.

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
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 all subcodes.
solClient_dllExport solClient_returnCode_t solClient_msg_deleteHttpContentType ( solClient_opaqueMsg_pt  msg_p)

Given a msg_p, delete the HTTP Content Type.

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
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 all subcodes.
solClient_dllExport solClient_returnCode_t solClient_msg_deleteReplyTo ( solClient_opaqueMsg_pt  msg_p)

Given a msg_p, delete the ReplyTo destination.

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
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 all subcodes.
solClient_dllExport solClient_returnCode_t solClient_msg_deleteSenderId ( solClient_opaqueMsg_pt  msg_p)

Given a msg_p, delete the SenderId.

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
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 all subcodes.
solClient_dllExport solClient_returnCode_t solClient_msg_deleteSenderTimestamp ( solClient_opaqueMsg_pt  msg_p)

Given a msg_p, delete the SenderTimestamp.

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
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 all subcodes.
solClient_dllExport solClient_returnCode_t solClient_msg_deleteSequenceNumber ( solClient_opaqueMsg_pt  msg_p)

Given a msg_p, delete the Sequence Number field.

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
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 all subcodes.
solClient_dllExport solClient_returnCode_t solClient_msg_dump ( solClient_opaqueMsg_pt  msg_p,
char *  buffer_p,
size_t  bufferSize 
)

Display the contents of a message in human-readable form.

This function creates a string in application-supplied buffer that the application can log or print as it wishes. If the supplied buffer pointer is NULL, this function prints to STDOUT. This function is equivalent to solClient_msg_dumpExt(msg_p, buffer_p, bufferSize, SOLCLIENT_MSGDUMP_FULL).

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
buffer_pA pointer to a buffer to receive the output string. NULL means to dump to STDOUT.
bufferSizeThe size of the memory area referenced by buffer_p. The output is truncated at this size if the buffer is not large enough. The returned string is always NULL-terminated even if truncated.
Returns
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
Examples:
ex/common.c, ex/directPubSub.c, ex/flowControlQueue.c, ex/ios/Example.m, ex/ios/examples/DirectPubSubExample.m, ex/ios/examples/SecureSessionExample.m, ex/ios/intro/HelloWorldSubExample.m, ex/ios/intro/HelloWorldWebSubExample.m, ex/messageReplay.c, ex/secureSession.c, ex/simpleFlowToQueue.c, Intro/HelloWorldQueueSub.c, Intro/HelloWorldSub.c, and Intro/HelloWorldWebSub.c.
solClient_dllExport solClient_returnCode_t solClient_msg_dumpExt ( solClient_opaqueMsg_pt  msg_p,
char *  buffer_p,
size_t  bufferSize,
solClient_uint32_t  flags 
)

Display the contents of a message in human-readable form.

This function creates a string in application-supplied buffer that the application can log or print. If the supplied buffer pointer is NULL, this function prints to STDOUT.

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
buffer_pA pointer to a buffer to receive the output string. NULL means to dump to STDOUT.
bufferSizeThe size of the memory area referenced by buffer_p. The output is truncated at this size if the buffer is not large enough. The returned string is always NULL-terminated even if truncated.
flagsFlags to control the output. Possible values are:
Returns
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
solClient_dllExport solClient_returnCode_t solClient_msg_dup ( solClient_opaqueMsg_pt  msg_p,
solClient_opaqueMsg_pt dupMsg_p 
)

Duplicate a message buffer and allocate a new msg which references all the same data.

For any data blocks, the reference count is incremented to indicate that two message buffers have pointers to the data. Applications are responsible for releasing all message buffers they allocate by solClient_msg_dup().

Parameters
msg_pA pointer to a Msg.
dupMsg_pA pointer to return a pointer to new msg.
Returns
SOLCLIENT_OK or 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 all subcodes.
solClient_dllExport solClient_returnCode_t solClient_msg_encodeToSMF ( solClient_opaqueMsg_pt  msg_p,
solClient_bufInfo_pt  bufinfo_p,
solClient_opaqueDatablock_pt datab_p 
)

Encode a message in Solace Message Format (SMF) and save the SMF encodings in the message bufinfo part.

If both bufinfo_p and datab_p are not NULL pointers, they contain the bufinfo for the SMF encodings and its associated data block as returns. Client applications are responsible for releasing the associated data block.

It returns SOLCLIENT_FAIL if one of bufinfo_p and datab_p is NULL pointer and the other is not a NULL pointer.

Parameters
msg_pA pointer to the message
bufinfo_pA pointer to a bufInfo containing buffer information (ptr, size).as returns.
datab_pA pointer to a data block reference returns data block pointer.The data block has to be released by applications.
Returns
SOLCLIENT_OK or SOLCLIENT_FAIL
solClient_dllExport solClient_returnCode_t solClient_msg_free ( solClient_opaqueMsg_pt msg_p)

Free a solClient Msg previously allocated by solClient_msg_alloc().

Applications are responsible for releasing all message buffers they allocate by solClient_msg_alloc() or solClient_msg_dup(). Message buffers received by callback are owned by the API and must not be released. However the application may take ownership of these message buffers as well by returning SOLCLIENT_CALLBACK_TAKE_MSG on return from the receive message callback function. If the application returns SOLCLIENT_CALLBACK_TAKE_MSG, it must release the message by calling solClient_msg_free() when it is finished with the message buffer.

Parameters
msg_pA pointer to the msg_p previously allocated. On return this reference is NULL and the memory previously referenced by it is no longer valid.
Returns
SOLCLIENT_OK on success. SOLCLIENT_FAIL when msg_p does not point to a valid msg.
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
Examples:
ex/adPubAck.c, ex/common.c, ex/directPubSub.c, ex/flowControlQueue.c, ex/ios/Example.m, ex/ios/examples/AppReachabilityExample.m, ex/ios/examples/AppTransitionsExample.m, ex/ios/examples/DirectPubSubExample.m, ex/ios/examples/PerfTestExample.m, ex/ios/examples/RedirectLogsExample.m, ex/ios/examples/SdtPubSubMsgDepExample.m, ex/ios/examples/SdtPubSubMsgIndepExample.m, ex/ios/examples/SecureSessionExample.m, ex/ios/examples/SempGetOverMbExample.m, ex/ios/intro/HelloWorldPubExample.m, ex/ios/intro/HelloWorldWebPubExample.m, ex/messageReplay.c, ex/messageSelectorsOnQueue.c, ex/messageTTLAndDeadMessageQueue.c, ex/noLocalPubSub.c, ex/perfADPub.c, ex/perfTest.c, ex/queueProvision.c, ex/redirectLogs.c, ex/replication.c, ex/RRDirectReplier.c, ex/RRDirectRequester.c, ex/RRGuaranteedReplier.c, ex/RRGuaranteedRequester.c, ex/sdtPubSubMsgDep.c, ex/sdtPubSubMsgIndep.c, ex/secureSession.c, ex/sempGetOverMb.c, ex/simpleBrowserFlow.c, ex/simpleFlowToQueue.c, ex/simpleFlowToTopic.c, ex/transactions.c, Intro/HelloWorldPub.c, Intro/HelloWorldQueuePub.c, and Intro/HelloWorldWebPub.c.
solClient_dllExport solClient_returnCode_t solClient_msg_getApplicationMessageId ( solClient_opaqueMsg_pt  msg_p,
const char **  messageId_p 
)

Given a msg_p, copy the ApplicationMessageId pointer into the given buffer.

This method allows the application to retrieve a pointer to the string that is the ApplicationMessageId. The ApplicationMessageId is user-defined, carried end-to-end, and can also be matched in a selector, but otherwise is not relevant to the event broker.

In JMS applications, this field is carried as the JMSMessageID Message Header Field.

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
messageId_pA pointer to string pointer to receive MessageId pointer.
Returns
SOLCLIENT_OK on success, SOLCLIENT_FAIL if msg_p is invalid, SOLCLIENT_NOT_FOUND for none found
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
solClient_dllExport solClient_returnCode_t solClient_msg_getApplicationMsgType ( solClient_opaqueMsg_pt  msg_p,
const char **  msgType_p 
)

Given a msg_p, copy the ApplicationMessageType topic pointer into the given pointer.

This method allows the application to retrieve a pointer to the string that is the ApplicationMessageType. The ApplicationMessageType is user-defined, carried end-to-end, and can also be matched in a selector, but otherwise is not relevant to the event broker.

In JMS applications, this field is carried as the JMSType Message Header Field.

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
msgType_pA pointer to string pointer to receive msgType pointer.
Returns
SOLCLIENT_OK on success, SOLCLIENT_FAIL if msg is invalid, SOLCLIENT_NOT_FOUND if it contains no msgType field.
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
solClient_dllExport solClient_returnCode_t solClient_msg_getBinaryAttachmentContainerSize ( solClient_opaqueMsg_pt  msg_p,
size_t *  size_p 
)

Given a msg_p, retrieve the size of the open container in the binary attachment.

If there is no open container in the binary attachment, this function returns SOLCLIENT_NOT_FOUND.

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received data callback.
size_pA pointer to memory that contains the size on return.
Returns
SOLCLIENT_OK or SOLCLIENT_FAIL or SOLCLIENT_NOT_FOUND
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
solClient_dllExport solClient_returnCode_t solClient_msg_getBinaryAttachmentField ( solClient_opaqueMsg_pt  msg_p,
solClient_field_t field_p,
size_t  fieldSize 
)

Check the binary attachment in the message for structured data.

If there is structured data found, either a map or steam, then the opaque container required to access the data is returned.

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
field_pThe address of the solClient_field_t structure where the API will returns the opaque container pointer and type.
fieldSizesizeof(solClient_field_t).
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 all subcodes.
solClient_dllExport solClient_returnCode_t solClient_msg_getBinaryAttachmentMap ( solClient_opaqueMsg_pt  msg_p,
solClient_opaqueContainer_pt map_p 
)

Given a msg_p, retrieve the contents of a binary attachment part as a map.

The returned map is a multimap in which more than one value may be associated with a given field name. A call to solClient_container_addXyz() does not overwrite an existing one, but adds a new one instead. To overwrite an existing field, the field has to been deleted and then added with a new value. To get all values associated with a given field name, a linear search is required. The returned map should later be closed by a call to solClient_container_closeMapStream(). However, if it is not, the map is automatically closed when the associated message is freed through a call to solClient_msg_free(). If the map is closed automatically, the application may not continue to use the map. Attempting to use a closed map will return an invalid pointer error (SOLCLIENT_SUBCODE_PARAM_NULL_PTR)

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
map_pA pointer to memory that contains a map pointer on return;
Returns
SOLCLIENT_OK, SOLCLIENT_FAIL, or SOLCLIENT_NOT_FOUND
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
solClient_dllExport solClient_returnCode_t solClient_msg_getBinaryAttachmentPtr ( solClient_opaqueMsg_pt  msg_p,
solClient_opaquePointer_pt  bufPtr_p,
solClient_uint32_t *  size_p 
)

Given a msg_p, retrieve the contents of a binary attachment part and return the pointer and length.

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received data callback.
bufPtr_pA pointer to the application pointer to fill in with the message data pointer on return. The programmer may cast the returned void pointer to any reference suitable for the application.
size_pA pointer to memory that contains data size on return.
Returns
SOLCLIENT_OK or SOLCLIENT_FAIL or SOLCLIENT_NOT_FOUND
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
Examples:
ex/eventMonitor.c, ex/ios/examples/EventMonitorExample.m, ex/ios/examples/SempGetOverMbExample.m, and ex/sempGetOverMb.c.
solClient_dllExport solClient_returnCode_t solClient_msg_getBinaryAttachmentStream ( solClient_opaqueMsg_pt  msg_p,
solClient_opaqueContainer_pt stream_p 
)

Given a msg_p, retrieve the contents of a binary attachment part as a stream.

The returned stream should later be closed by a call to solClient_container_closeMapStream(). However, if it is not, the stream is automatically closed when the associated message is freed through a call to solClient_msg_free(). If the stream is closed automatically, the application may not continue to use the stream. Attempting to use a closed stream returns an invalid pointer error (SOLCLIENT_SUBCODE_PARAM_NULL_PTR)

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
stream_ppointer to memory that contains a stream pointer on return.
Returns
SOLCLIENT_OK, SOLCLIENT_FAIL, or SOLCLIENT_NOT_FOUND
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
Examples:
ex/RRDirectReplier.c, ex/RRDirectRequester.c, ex/RRGuaranteedReplier.c, and ex/RRGuaranteedRequester.c.
solClient_dllExport solClient_returnCode_t solClient_msg_getBinaryAttachmentString ( solClient_opaqueMsg_pt  msg_p,
const char **  bufPtr_p 
)

Given a msg_p, retrieve the contents of a binary attachment part if it is a JMS string and return a pointer to the string (NULL-terminated string).

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received data callback.
bufPtr_pA pointer to memory that contains the string pointer on return.
Returns
SOLCLIENT_OK or SOLCLIENT_FAIL or SOLCLIENT_NOT_FOUND
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
solClient_dllExport solClient_returnCode_t solClient_msg_getCacheRequestId ( solClient_opaqueMsg_pt  msg_p,
solClient_uint64_t cacheRequestId_p 
)

Given a msg_p containing a cached message, return the cache RequestId that the application set in the call to solClient_csession_sendCacheRequest().

Parameters
msg_psolClient_opaquemsg_pt received in a receive message callback.
cacheRequestId_ppointer to location to receive the cacheRequestId.
Returns
SOLCLIENT_OK, SOLCLIENT_FAIL or SOLCLIENT_NOT_FOUND if msg_p does not contain a received cache message.
solClient_dllExport solClient_returnCode_t solClient_msg_getClassOfService ( solClient_opaqueMsg_pt  msg_p,
solClient_uint32_t *  cos_p 
)

Given a msg_p, get the Class of Service from a message.

The Class of Service has different semantics for direct and guaranteed messages.

For direct messages, the class of service selects the weighted round-robin delivery queue when the message is forwarded to a consumer. {SOLCLIENT_COS_1} are the lowest priority messages and will use the solace message-router D-1 delivery queues.

For messages published as guaranteed messages, * messages published with SOLCLIENT_COS_1 can be rejected by the solace message-router if that message would cause any queue or topic-endpoint to exceed its configured low-priority-max-msg-count.

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
cos_pA place to store the returned class of service, one of
Returns
SOLCLIENT_OK on success, SOLCLIENT_FAIL if msg_p or cos_p is invalid.
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
solClient_dllExport solClient_returnCode_t solClient_msg_getCorrelationId ( solClient_opaqueMsg_pt  msg_p,
const char **  correlation_p 
)

Given a msg_p, copy the CorrelationId pointer into the given buffer.

This method allows the application to retrieve a pointer to the string that is the CorrelationId. The CorrelationId is user-defined, carried end-to-end, and can also be matched in a selector, but otherwise is not relevant to the event broker. The CorrelationId may be used for peer-to-peer message synchronization.

In JMS applications, this field is carried as the JMSCorrelationID Message Header Field.

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
correlation_pA pointer to string pointer to receive correlation Id pointer.
Returns
SOLCLIENT_OK on success, SOLCLIENT_NOT_FOUND if the field is not present and SOLCLIENT_FAIL if msg_p is invalid
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
solClient_dllExport solClient_returnCode_t solClient_msg_getCorrelationTagPtr ( solClient_opaqueMsg_pt  msg_p,
solClient_opaquePointer_pt  bufPtr_p,
solClient_uint32_t *  size_p 
)

Given a msg_p, retrieve the contents of a Correlation Tag part (used by an application when sending Guaranteed messages and receiving Guaranteed message acknowledgments) and return the pointer and length.

Parameters
msg_psolClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
bufPtr_pA pointer to the application pointer to fill in with the message correlation tag pointer on return. The programmer may cast the returned void pointer to any reference suitable for the application.
size_pA pointer to memory that contains data size on return.
See Also
Using Solace Message Buffers for Guaranteed messages
Returns
SOLCLIENT_OK or SOLCLIENT_FAIL or SOLCLIENT_NOT_FOUND
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
solClient_dllExport solClient_returnCode_t solClient_msg_getDeliveryCount ( solClient_opaqueMsg_pt  msg_p,
solClient_int32_t *  count_p 
)

Given a msg_p, return the delivery count.

If delivery is supported returns SOLCLIENT_OK otherwise returns SOLCLIENT_FAIL. Note messages from browser flows will have the delivery of the next consumer delivery not the current message delivery count from the endpoint.

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
count_ppointer to memory to store the returned delivery count.
Returns
SOLCLIENT_OK if delivery count is supported, SOLCLIENT_FAIL if delivery count is not supported, or if msg_p or count_p are invalid.
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
solClient_dllExport solClient_returnCode_t solClient_msg_getDeliveryMode ( solClient_opaqueMsg_pt  msg_p,
solClient_uint32_t *  mode_p 
)

Given a msg_p, return the delivery mode.

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
mode_pA place to store the returned delivery mode, one of
See Also
Using Solace Message Buffers for Guaranteed messages
Returns
SOLCLIENT_OK on success, SOLCLIENT_FAIL if msg_p is invalid.
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
solClient_dllExport solClient_returnCode_t solClient_msg_getDestination ( solClient_opaqueMsg_pt  msg_p,
solClient_destination_t dest_p,
size_t  destSize 
)

Given a msg_p, get the Destination field (queue or topic), which is the destination this message was published to.

On successful return dest_p->dest points to message memory and is only valid as long as msg_p is valid.

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
dest_pA pointer to destination information.
destSizeThe size of destination_t structure.
Returns
SOLCLIENT_OK, SOLCLIENT_FAIL, SOLCLIENT_NOT_FOUND
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
Examples:
ex/eventMonitor.c, and ex/ios/examples/EventMonitorExample.m.
solClient_dllExport solClient_returnCode_t solClient_msg_getDestinationTopicSuffix ( solClient_opaqueMsg_pt  msg_p,
solClient_opaqueSession_pt  opaqueSession_p,
const char **  suffix_p 
)

This utility returns the suffix of the topic string.

If the received message contains a topic destination, and the topic begins with the session topic prefix, this utility returns a pointer to the string following the '/' delimiter that terminates the topic prefix.

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
opaqueSession_pA pointer to the Session the message was received on.
suffix_pA pointer to pointer location that contains pointer to a NULL- terminated suffix string on success.
Returns
SOLCLIENT_OK, SOLCLIENT_FAIL, SOLCLIENT_NOT_FOUND.
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
solClient_dllExport solClient_returnCode_t solClient_msg_getExpiration ( solClient_opaqueMsg_pt  msg_p,
solClient_int64_t timestamp_p 
)

Given a msg_p, copy the Message Expiration timestamp into the given buffer.

If message expiration time is not set in the message and the session property SOLCLIENT_SESSION_PROP_CALCULATE_MESSAGE_EXPIRATION is enabled, the expiration time is calculated based on the message Time To Live. When enabled, the expiration time for sent messages will be the UTC time when the message is sent plus the Time To Live. The expiration time for received messages is the UTC time when the message was received plus the Time To Live in the message at the time it was received.

If the expiration time is not set in the message, and it cannot be calculated, the timestamp is set to zero.

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
timestamp_pA pointer to a 64-bit field to receive the value. The value is in milliseconds.
Returns
SOLCLIENT_OK on success, SOLCLIENT_FAIL if msg_p is invalid.
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
solClient_dllExport solClient_returnCode_t solClient_msg_getHttpContentEncoding ( solClient_opaqueMsg_pt  msg_p,
const char **  encoding_p 
)

Given a msg_p, retrieve the HTTP Content Encoding.

On return type_p points to message memory and is only valid as long as msg_p is valid.

Parameters
msg_psolClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
encoding_pOn return, it points to message memory containing HTTP Content Encoding.
Returns
SOLCLIENT_OK on success, SOLCLIENT_NOT_FOUND if the field is not present and SOLCLIENT_FAIL if msg_p is invalid
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
solClient_dllExport solClient_returnCode_t solClient_msg_getHttpContentType ( solClient_opaqueMsg_pt  msg_p,
const char **  type_p 
)

Given a msg_p, retrieve the HTTP Content Type.

On return type_p points to message memory and is only valid as long as msg_p is valid.

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
type_pOn return, it points to message memory containing HTTP Content Type.
Returns
SOLCLIENT_OK on success, SOLCLIENT_NOT_FOUND if the field is not present and SOLCLIENT_FAIL if msg_p is invalid
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
solClient_dllExport solClient_returnCode_t solClient_msg_getMsgId ( solClient_opaqueMsg_pt  msg_p,
solClient_msgId_t msgId_p 
)

Given a msg_p, return the Guaranteed message Id.

The guaranteed message Id only exists in messages received on a flow. The message Id is only to be used for the purpose of acknowledgements. No other meaning should be inferred from the value of the message Id.

Messages are acknowledged by calling solClient_flow_sendAck()

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
msgId_ppointer to memory to store the returned msgId.
Returns
SOLCLIENT_OK on success, SOLCLIENT_FAIL if msg_p is invalid, SOLCLIENT_NOT_FOUND if msg_p does not contain an assured delivery message.
See Also
Using Solace Message Buffers for Guaranteed messages
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
Examples:
ex/common.c, ex/flowControlQueue.c, ex/messageReplay.c, ex/noLocalPubSub.c, ex/perfADSub.c, ex/queueProvision.c, ex/simpleBrowserFlow.c, ex/simpleFlowToQueue.c, and Intro/HelloWorldQueueSub.c.
solClient_dllExport solClient_returnCode_t solClient_msg_getPriority ( solClient_opaqueMsg_pt  msg_p,
solClient_int32_t *  priority_p 
)

Get message priority.

Parameters
msg_pA pointer to the message
priority_pA pointer to memory that contains priority on return, or -1 if it is not set.
Returns
SOLCLIENT_OK or SOLCLIENT_FAIL
solClient_dllExport solClient_returnCode_t solClient_msg_getRcvTimestamp ( solClient_opaqueMsg_pt  msg_p,
solClient_int64_t timestamp_p 
)

Given a msg_p, copy the Receive Timestamp into the given buffer.

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
timestamp_pA pointer to a 64-bit field to receive the value. The value is in milliseconds.
Returns
SOLCLIENT_OK on success, SOLCLIENT_FAIL if msg_p is invalid, SOLCLIENT_NOT_FOUND if not found.
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
Examples:
ex/directPubSub.c.
solClient_dllExport solClient_returnCode_t solClient_msg_getReplicationGroupMessageId ( solClient_opaqueMsg_pt  msg_p,
solClient_replicationGroupMessageId_pt  rgmid_p,
size_t  size 
)

Retrieve a Replication Group Message Id from a received message.

Parameters
msg_psolClient_opaqueMsg_pt that is received in a receive message callback.
rgmid_pA pointer to solClient_replicationGroupMessageId_t to be filled.
sizeThe return from sizeof(solClient_replicationGroupMessageId_t)
Returns
SOLCLIENT_OK or SOLCLIENT_FAIL or SOLCLIENT_NOT_FOUND
solClient_dllExport solClient_returnCode_t solClient_msg_getReplyTo ( solClient_opaqueMsg_pt  msg_p,
solClient_destination_t dest_p,
size_t  destSize 
)

Given a msg_p, retrieve the replyTo destination and set the information in the passed in destination structure.

On return dest_p->dest points to message memory and is only valid as long as msg_p is valid.

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
dest_pA pointer to destination structure to receive ReplyTo.
destSizeThe size of (solClient_destination_t).
Returns
SOLCLIENT_OK, SOLCLIENT_FAIL, SOLCLIENT_NOT_FOUND
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
Examples:
ex/RRGuaranteedReplier.c, and ex/transactions.c.
solClient_dllExport solClient_returnCode_t solClient_msg_getSenderId ( solClient_opaqueMsg_pt  msg_p,
const char **  buf_p 
)

Given a msg_p, copy the SenderID pointer into the given buffer.

This method allows the application to retrieve a pointer to the string that is the SenderID. The SenderID is user-defined, carried end-to-end, and can also be matched in a selector, but otherwise is not relevant to the event broker.

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
buf_pA pointer to string pointer for senderId.
Returns
SOLCLIENT_OK on success, SOLCLIENT_FAIL if msg is invalid, SOLCLIENT_NOT_FOUND if msg contains no SenderId field.
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
Examples:
ex/common.c, ex/ios/Example.m, and ex/transactions.c.
solClient_dllExport solClient_returnCode_t solClient_msg_getSenderTimestamp ( solClient_opaqueMsg_pt  msg_p,
solClient_int64_t timestamp_p 
)

Given a msg_p, copy the SenderTimestamp into the given buffer.

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
timestamp_pA pointer to a 64-bit field to receive the value. The value is in milliseconds.
Returns
SOLCLIENT_OK on success, SOLCLIENT_FAIL if msg_p is invalid, SOLCLIENT_NOT_FOUND for none found.
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
Examples:
ex/directPubSub.c.
solClient_dllExport solClient_returnCode_t solClient_msg_getSequenceNumber ( solClient_opaqueMsg_pt  msg_p,
solClient_int64_t seqNum_p 
)

Given a msg_p, copy the SequenceNo into the given buffer.

A sequence number is automatically included (if not already present) in the Solace-defined fields for each message sent if the session property SOLCLIENT_SESSION_PROP_GENERATE_SEQUENCE_NUMBER is enabled.

This method allows the application to retrieve the value that is the SequenceNo. The SequenceNo is user-defined, carried end-to-end, and can also be matched in a selector, but otherwise is not relevant to the event broker.

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
seqNum_pA pointer to 64-bit field to receive the value.
Returns
SOLCLIENT_OK on success, SOLCLIENT_FAIL if msg_p is invalid, SOLCLIENT_NOT_FOUND if not found.
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
Examples:
ex/common.c, ex/ios/Example.m, and ex/simpleBrowserFlow.c.
solClient_dllExport solClient_returnCode_t solClient_msg_getSMFPtr ( solClient_opaqueMsg_pt  msg_p,
solClient_uint8_t **  bufPtr_p,
solClient_uint32_t *  size_p 
)

Given a msg_p, retrieve the raw Solace Message Format (SMF) message as originally received.

Parameters
msg_psolClient_opaqueMsg_pt received in a receive message callback.
bufPtr_pA pointer to the application pointer to fill in with the message SMF pointer on return. SMF data is binary 8 byte data and can be stored by copying 'size' bytes from the returned pointer.
size_pA pointer to memory that contains data size on return.
Returns
SOLCLIENT_OK or SOLCLIENT_FAIL or SOLCLIENT_NOT_FOUND
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
solClient_dllExport solClient_returnCode_t solClient_msg_getStat ( solClient_msg_stats_t  msgStatType,
solClient_uint32_t  statIndex,
solClient_uint64_t statValue_p 
)

Returns the value of the specified message statistic.

Parameters
msgStatTypeThe type of statistic to retrieve; one of solClient_msg_stats.
statIndexThe zero-based index of the statistic (for example, which quanta); only used for SOLCLIENT_MSG_STATS_ALLOC_DATA_BLOCKS and SOLCLIENT_MSG_STATS_FREE_DATA_BLOCKS. This must be zero for other statistic types.
statValue_pA pointer to the location to receive the statistic value from.
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 all subcodes.
solClient_dllExport solClient_returnCode_t solClient_msg_getTimeToLive ( solClient_opaqueMsg_pt  msg_p,
solClient_int64_t ttl_p 
)

Given a msg_p, get the Time To Live (TTL) from a message.

If the message does not contain a time to live field, zero is returned.

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
ttl_pA pointer to a 64-bit field to receive the value. The value is in milliseconds.
Returns
SOLCLIENT_OK on success, SOLCLIENT_FAIL if msg_p or timestamp_p is invalid.
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
solClient_dllExport solClient_returnCode_t solClient_msg_getTopicSequenceNumber ( solClient_opaqueMsg_pt  msg_p,
solClient_int64_t seqNum_p 
)

Given a msg_p, return the Topic Sequence Number.

If there is no topic sequence number SOLCLIENT_NOT_FOUND is returned and the sequence number returned is zero.

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
seqNum_ppointer to memory to store the returned topic sequence number.
Returns
SOLCLIENT_OK on success, SOLCLIENT_FAIL if msg_p is invalid, SOLCLIENT_NOT_FOUND if msg_p does not contain a topic sequence number.
See Also
Using Solace Message Buffers for Guaranteed messages
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
solClient_dllExport solClient_returnCode_t solClient_msg_getUserDataPtr ( solClient_opaqueMsg_pt  msg_p,
solClient_opaquePointer_pt  bufPtr_p,
solClient_uint32_t *  size_p 
)

Given a msg_p, retrieve the contents of a User Data part.

The maximum size allowed for the user data part is SOLCLIENT_BUFINFO_MAX_USER_DATA_SIZE.

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
bufPtr_pA pointer to the application pointer to fill in with the message user data pointer on return. The programmer may cast the returned void pointer to any reference suitable for the application.
size_pA pointer to memory that contains data size on return.
Returns
SOLCLIENT_OK or SOLCLIENT_FAIL or SOLCLIENT_NOT_FOUND
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
solClient_dllExport solClient_returnCode_t solClient_msg_getUserPropertyMap ( solClient_opaqueMsg_pt  msg_p,
solClient_opaqueContainer_pt map_p 
)

Given a msg_p, retrieve the user property Map from binary metadata.

Msg mutators.

The solClient Msg accessors provides a safe and managed interface for sending and receiving messages. The accessors allow application developers to set and read any part of the message. The returned map is a multimap, in which more than one value may be associated with a given field name. A call to solClient_container_addXyz() does not overwrite an existing one, instead it adds a new field. To overwrite an existing field, the field has to been deleted and then added with a new value. To get all values associated with a given field name, a linear search is required. The returned map should later be closed by a call to solClient_container_closeMapStream(). However, if it is not, the map is automatically closed when the associated message is freed through a call to solClient_msg_free(). If the map is closed automatically, the application cannot continue to use the map. Attempting to use a closed map returns an invalid pointer error (SOLCLIENT_SUBCODE_PARAM_NULL_PTR).

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
map_pA pointer to memory that contains a map pointer on return.
Returns
SOLCLIENT_OK, SOLCLIENT_FAIL, or SOLCLIENT_NOT_FOUND
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
solClient_dllExport solClient_returnCode_t solClient_msg_getXmlPtr ( solClient_opaqueMsg_pt  msg_p,
solClient_opaquePointer_pt  bufPtr_p,
solClient_uint32_t *  size_p 
)

Given a msg_p, retrieve the contents of a XML part of the message.

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
bufPtr_pA pointer to the application pointer to fill in with the message XML data pointer on return. The programmer may cast the returned void pointer to any reference suitable for the application.
size_pA pointer to memory that contains data size on return.
Returns
SOLCLIENT_OK or SOLCLIENT_FAIL or SOLCLIENT_NOT_FOUND
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
solClient_dllExport solClient_bool_t solClient_msg_isAckImmediately ( solClient_opaqueMsg_pt  msg_p)

Given a msg_p, test if the ACK Immediately message property is set or not.

When the ACK Immediately property is set to true on an outgoing Guaranteed Delivery message, it indicates that the appliance should ACK this message immediately upon receipt.

This property, when set by a publisher, may or may not be removed by the appliance prior to delivery to a consumer, so message consumers must not expect the property value indicates how the message was originally published

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
Returns
True, if the ACK Immediately message property is set to TRUE.
solClient_dllExport solClient_cacheStatus_t solClient_msg_isCacheMsg ( solClient_opaqueMsg_pt  msg_p)

Given a msg_p, return the data source (live or cached message).

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
Returns
cacheStatus, one of:
solClient_dllExport solClient_bool_t solClient_msg_isDiscardIndication ( solClient_opaqueMsg_pt  msg_p)

Given a msg_p, test the discard indication status.

Returns true if one or more messages have been discarded prior to the current message, otherwise it returns false. This indicates congestion discards only, and is not affected by message eliding.

See Also
solClient_msg_isElidingEligible for information about message eliding.
Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
Returns
True, if the message had the discard indication set.
solClient_dllExport solClient_bool_t solClient_msg_isDMQEligible ( solClient_opaqueMsg_pt  msg_p)

Given a msg_p, test the Dead Message Queue (DMQ) eligible property.

Parameters
msg_psolClient_opaqueMsg_pt returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
Returns
True, if the message has "Dead Message Queue eligible" property set.
solClient_dllExport solClient_bool_t solClient_msg_isElidingEligible ( solClient_opaqueMsg_pt  msg_p)

Given a msg_p, test the ElidingEligible attribute.

Does not indicate whether messages were elided or provide information about the subscriber profile eliding configuration.

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
Returns
True, if the message has the Eliding Eligible attribute set.
solClient_dllExport solClient_bool_t solClient_msg_isRedelivered ( solClient_opaqueMsg_pt  msg_p)

Given a msg_p, test the redeliver status.

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
See Also
Using Solace Message Buffers for Guaranteed messages
Returns
True, if the message was redelivered.
solClient_dllExport solClient_bool_t solClient_msg_isReplyMsg ( solClient_opaqueMsg_pt  msg_p)

Given a msg_p, test the response attribute.

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
Returns
True, if the message is a response to a solClient_session_sendRequest().
solClient_dllExport solClient_returnCode_t solClient_msg_reset ( solClient_opaqueMsg_pt  msg_p)

Release all memory associated with a message buffer.

This function returns a message buffer to its original state, as if it has just been allocated by solClient_msg_alloc.

Parameters
msg_pA pointer to a Msg.
Returns
SOLCLIENT_OK or 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 all subcodes.
Examples:
ex/RRDirectRequester.c, and ex/RRGuaranteedRequester.c.
solClient_dllExport solClient_returnCode_t solClient_msg_setAckImmediately ( solClient_opaqueMsg_pt  msg_p,
solClient_bool_t  val 
)

Given a msg_p, set the optional ACK Immediately message property.

When the ACK Immediately property is set to true on an outgoing Guaranteed Delivery message, it indicates that the appliance should ACK this message immediately upon receipt. By default the property is set to false on newly created messages.

This property, when set by a publisher, may or may not be removed by the appliance prior to delivery to a consumer, so message consumers must not expect the property value indicates how the message was originally published. Therefore if a received message is forwarded by the application, the ACK immediately property should be explicitly set to the desired value (true or false).

Setting this property on an outgoing direct message has no effect.

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
valA Boolean that indicates whether to set or clear the ACK Immediately message property.
Returns
SOLCLIENT_OK on success, SOLCLIENT_FAIL if msg is invalid.
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
solClient_dllExport solClient_returnCode_t solClient_msg_setApplicationMessageId ( solClient_opaqueMsg_pt  msg_p,
const char *  messageId_p 
)

Given a msg_p, set the ApplicationMessageId field.

This method allows the application to set the string contents of the ApplicationMessageId. The ApplicationMessageId is user defined, carried end-to-end, and can slso be matched in a selector, but otherwise is not relevant to the event broker.

In JMS applications, this field is carried as the JMSMessageId Message Header Field.

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
messageId_ppointer to string containing messageId.
Returns
SOLCLIENT_OK on success, SOLCLIENT_FAIL if msg_p is invalid.
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
solClient_dllExport solClient_returnCode_t solClient_msg_setApplicationMsgType ( solClient_opaqueMsg_pt  msg_p,
const char *  msgType 
)

Given a msg_p, set the ApplicationMessageType field.

This method allows the application to set the string contents of the ApplicationMessageType. The ApplicationMessageType is user defined, carried end-to-end, and can slso be matched in a selector, but otherwise is not relevant to the event broker.

In JMS applications, this field is carried as the JMSType Message Header Field.

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
msgTypeA pointer to string with msgType.
Returns
SOLCLIENT_OK on success, SOLCLIENT_FAIL if msg or length is invalid.
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
solClient_dllExport solClient_returnCode_t solClient_msg_setAsReplyMsg ( solClient_opaqueMsg_pt  msg_p,
solClient_bool_t  isReply 
)

Set the reply attribute of the message.

When this message is later transmitted it is sent as a reply even if solClient_session_sendMsg() is used instead of solClient_session_reply().

Parameters
msg_psolClient_opaqueMsg_pt returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
isReplyA Boolean that indicates whether to set or reset the reply attribute.
Returns
SOLCLIENT_OK, SOLCLIENT_FAIL.
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
  • SOLCLIENT_SUBCODE_INSUFFICIENT_SPACE - Indicates that the attempt to set the reply attribute was for a message received from an older style API that has insufficient space in the binary meta header.
See Also
solClient_subCode for a description of all subcodes.
solClient_dllExport solClient_returnCode_t solClient_msg_setBinaryAttachment ( solClient_opaqueMsg_pt  msg_p,
const void *  buf_p,
solClient_uint32_t  size 
)

Given a msg_p, set the contents of the binary attachment part by copying in from the given pointer and size.

This causes memory to be allocated from API internal or heap storage. If any binary attachment previously existed it will be first removed before the new data is copied in.

Passing in a buf_p of NULL and a size of zero results in a binary attachment not being present in the message.

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
buf_pA pointer to buffer.
sizeThe maximum number of bytes in buffer.
Returns
SOLCLIENT_OK or SOLCLIENT_FAIL if msg_p is invalid or memory not available.
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
Examples:
ex/adPubAck.c, ex/directPubSub.c, ex/flowControlQueue.c, ex/ios/examples/AppReachabilityExample.m, ex/ios/examples/AppTransitionsExample.m, ex/ios/examples/DirectPubSubExample.m, ex/ios/examples/RedirectLogsExample.m, ex/ios/examples/SecureSessionExample.m, ex/ios/intro/HelloWorldPubExample.m, ex/ios/intro/HelloWorldWebPubExample.m, ex/messageReplay.c, ex/messageSelectorsOnQueue.c, ex/noLocalPubSub.c, ex/perfADPub.c, ex/queueProvision.c, ex/redirectLogs.c, ex/replication.c, ex/secureSession.c, ex/simpleBrowserFlow.c, ex/simpleFlowToQueue.c, ex/simpleFlowToTopic.c, Intro/HelloWorldPub.c, Intro/HelloWorldQueuePub.c, and Intro/HelloWorldWebPub.c.
solClient_dllExport solClient_returnCode_t solClient_msg_setBinaryAttachmentContainer ( solClient_opaqueMsg_pt  msg_p,
solClient_opaqueContainer_pt  cont_p 
)

Given a msg_p, set the contents of the binary attachment part to a Map or Stream, as referenced by the given solClient_opaqueContainer_pt.

This function copies in from the given container. Changes to the container after this function is called will not be propagated to this message. The message will be TLV encoded suitable for reading by any other Solace Messaging API. If any binary attachment previously existed it is first removed before the new data is copied in.

WARNING: This method is intended to be used to add an existing message independent container to a message. That is, a container created by either solClient_container_createMap() or solClient_container_createStream(). Do not call this method with a container that is already in the message, returned from a call to solClient_msg_createBinaryAttachmentMap or solClient_msg_createBinaryAttachmentStream. That is unnecessary as the container is already in the message. Further, the first operation of solClient_msg_setBinaryAttachmentContainer() is to wipe out the existing binary attachment.

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
cont_pAn opaque container pointer for the container to add.
Returns
SOLCLIENT_OK or SOLCLIENT_FAIL if msg_p is invalid or memory is not available.
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
Examples:
ex/ios/examples/SdtPubSubMsgIndepExample.m, and ex/sdtPubSubMsgIndep.c.
solClient_dllExport solClient_returnCode_t solClient_msg_setBinaryAttachmentContainerPtr ( solClient_opaqueMsg_pt  msg_p,
solClient_opaqueContainer_pt  cont_p 
)

Given a msg_p, set the contents of the binary attachment part to a Map or Stream, as referenced by the given solClient_opaqueContainer_pt.

This function takes a reference to the given container. This is a high performance interface function that avoids a memory copy from application memory into the message binary attachment. On a subsequent solClient_session_sendMsg() the binary attachment contents will be copied directly from the application memory to the transmit socket or buffer.

NOTE: When a Guaranteed message is constructed with this API refer to Using Solace Message Buffers for Guaranteed messages

In addition to the above note, the application must not change the container after this function is called until the message is sent, even when the message contains a non-Guaranteed message. Changing the container, or releasing the memory referenced by the container, will cause the message contents to be a corrupt container when transmitted. If the container is added to a Guaranteed Delivery message by reference then the container and container memory must not be modified until the appliance acknowledgment for the message is received. This latter further restriction for Guaranteed Delivery is required in case the C API library needs to retransmit the original message for any reason. In general, for Guaranteed Delivery, it is far safer to use solClient_msg_setBinaryAttachmentContainer. It is unlikely the application will achieve any performance gains by this function with Guaranteed messages.

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
cont_pAn opaque container pointer for the container to add.
Returns
SOLCLIENT_OK or SOLCLIENT_FAIL if msg_p is invalid or memory is not available.
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
solClient_dllExport solClient_returnCode_t solClient_msg_setBinaryAttachmentPtr ( solClient_opaqueMsg_pt  msg_p,
void *  buf_p,
solClient_uint32_t  size 
)

Given a msg_p, set the contents of a Binary Attachment Part to the given pointer and size.

Msg mutators.

The solClient Msg mutators are intended to provide a safe and managed interface to the Solace Message Format (SMF) message used for sending and receiving messages. This memory may contain the pre-built payload the application is sending, or an application may choose to subsequently build a structured message (a map or stream container) in the Binary Attachment part and the buffer set here is used to construct the container up to the size. If the structured message grows to exceed the set size, an internal data block is used to hold the entire container.

NOTE: When a Guaranteed message is constructed with this API refer to Using Solace Message Buffers for Guaranteed messages.

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
buf_pA pointer to buffer.
sizeThe maximum number of bytes in buffer.
Returns
SOLCLIENT_OK or SOLCLIENT_FAIL if msg_p is invalid.
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
Examples:
ex/ios/examples/PerfTestExample.m, ex/ios/examples/SempGetOverMbExample.m, ex/perfTest.c, and ex/sempGetOverMb.c.
solClient_dllExport solClient_returnCode_t solClient_msg_setBinaryAttachmentString ( solClient_opaqueMsg_pt  msg_p,
const char *  buf_p 
)

Given a msg_p, set the contents of the binary attachment part to a UTF-8 or ASCII string by copying in from the given pointer until null-terminated.

The message will be TLV-encoded suitable for reading by any other Solace Corporation Messaging APIs. If any binary attachment previously existed it is first removed before the new data is copied in.

Passing in a buf_p of NULL results in a binary attachment not being present in the message.

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
buf_pA pointer to a buffer containing a UTF-8 or ASCII string.
Returns
SOLCLIENT_OK or SOLCLIENT_FAIL if msg_p is invalid or memory is not available.
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
solClient_dllExport solClient_returnCode_t solClient_msg_setClassOfService ( solClient_opaqueMsg_pt  msg_p,
solClient_uint32_t  cos 
)

Given a msg_p, set the Class of Service to use for transmission.

The Class of Service has different semantics for direct and guaranteed messages.

The Class of Service has different semantics for direct and guaranteed messages. For direct messages, the class of service selects the weighted round-robin delivery queue when the message is forwarded to a consumer. {SOLCLIENT_COS_1} are the lowest priority messages and will use the solace message-router D-1 delivery queues.

For messages published as guaranteed messages, * messages published with SOLCLIENT_COS_1 can be rejected by the solace message-router if that message would cause any queue or topic-endpoint to exceed its configured low-priority-max-msg-count.

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
cosThe class of service, one of SOLCLIENT_COS_1, SOLCLIENT_COS_2, or SOLCLIENT_COS_3.
Returns
SOLCLIENT_OK on success, SOLCLIENT_FAIL if msg_p is invalid.
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
solClient_dllExport solClient_returnCode_t solClient_msg_setCorrelationId ( solClient_opaqueMsg_pt  msg_p,
const char *  correlation_p 
)

Given a msg_p, set the CorrelationId field.

The CorrelationId is user-defined, carried end-to-end, and can also be matched in a selector, but otherwise is not relevant to the event broker. The CorrelationId may be used for peer-to-peer message synchronization.

In JMS applications, this field is carried as the JMSCorrelationID Message Header Field.

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
correlation_pA pointer to string to copy into correlationId.
Returns
SOLCLIENT_OK on success, SOLCLIENT_FAIL if msg_p is invalid.
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
solClient_dllExport solClient_returnCode_t solClient_msg_setCorrelationTag ( solClient_opaqueMsg_pt  msg_p,
const void *  correlation_p,
solClient_uint32_t  size 
)

Given a msg_p, save correlation information Part by copying in from the given pointer and size.

This is not recommended for high performance applications, use solClient_msg_setCorrelationTagPtr instead. The Correlation Tag is a local reference used by applications generating Guaranteed messages. Messages that are sent in either PERSISTENT or non-PERSISTENT mode may set the Correlation Tag. If this method is used, a pointer to the correlation information is returned when the SOLCLIENT_SESSION_EVENT_ACKNOWLEDGEMENT event is later received. The solClient_session_eventCallbackInfo structured returned with the event contains a (void *) correlation_p which points to a copy of the information initialized with this method. The size is not returned. Important: The Correlation Tag is not included in the transmitted message and is only used with the local API.

This causes memory to be allocated from internal or heap storage.

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
correlation_pA pointer to the correlation information.
sizeThe number of bytes in buffer.
See Also
Using Solace Message Buffers for Guaranteed messages
Returns
SOLCLIENT_OK or SOLCLIENT_FAIL if msg_p is invalid or memory not available.
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
solClient_dllExport solClient_returnCode_t solClient_msg_setCorrelationTagPtr ( solClient_opaqueMsg_pt  msg_p,
void *  correlation_p,
solClient_uint32_t  size 
)

Given a msg_p, set the Correlation Tag to the given pointer.

The Correlation Tag is a local reference used by applications generating Guaranteed messages. Messages that are sent in either PERSISTENT or non-PERSISTENT mode can set the Correlation Tag, which is returned when the SOLCLIENT_SESSION_EVENT_ACKNOWLEDGEMENT event is later received. The solClient_session_eventCallbackInfo structured returned with the event contains a (void *) correlation_p which will be the same pointer the application initializes with this method. Important: The Correlation Tag is not included in the transmitted message and is only used with the local API.

This function is provided for high-performance applications that must be aware that the data referenced cannot be modified until the send operation completes.

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
correlation_pA pointer to buffer.
sizeIgnored.
See Also
Using Solace Message Buffers for Guaranteed messages
Returns
SOLCLIENT_OK or SOLCLIENT_FAIL if msg_p is invalid.
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
Examples:
ex/adPubAck.c.
solClient_dllExport solClient_returnCode_t solClient_msg_setDeliveryMode ( solClient_opaqueMsg_pt  msg_p,
solClient_uint32_t  mode 
)

Given a msg_p, set the delivery mode.

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
modeThe delivery mode to use for this message. It can be one of the following:
See Also
Using Solace Message Buffers for Guaranteed messages
Returns
SOLCLIENT_OK on success, SOLCLIENT_FAIL if msg_p is invalid.
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
Examples:
ex/adPubAck.c, ex/common.c, ex/directPubSub.c, ex/flowControlQueue.c, ex/ios/Example.m, ex/ios/examples/AppReachabilityExample.m, ex/ios/examples/AppTransitionsExample.m, ex/ios/examples/DirectPubSubExample.m, ex/ios/examples/RedirectLogsExample.m, ex/ios/examples/SdtPubSubMsgDepExample.m, ex/ios/examples/SdtPubSubMsgIndepExample.m, ex/ios/examples/SecureSessionExample.m, ex/ios/intro/HelloWorldPubExample.m, ex/ios/intro/HelloWorldWebPubExample.m, ex/messageReplay.c, ex/messageSelectorsOnQueue.c, ex/messageTTLAndDeadMessageQueue.c, ex/noLocalPubSub.c, ex/perfADPub.c, ex/perfTest.c, ex/queueProvision.c, ex/redirectLogs.c, ex/replication.c, ex/RRGuaranteedReplier.c, ex/RRGuaranteedRequester.c, ex/sdtPubSubMsgDep.c, ex/sdtPubSubMsgIndep.c, ex/secureSession.c, ex/simpleBrowserFlow.c, ex/simpleFlowToQueue.c, ex/simpleFlowToTopic.c, ex/transactions.c, Intro/HelloWorldPub.c, Intro/HelloWorldQueuePub.c, and Intro/HelloWorldWebPub.c.
solClient_dllExport solClient_returnCode_t solClient_msg_setDestination ( solClient_opaqueMsg_pt  msg_p,
solClient_destination_t dest_p,
size_t  destSize 
)

Given a msg_p, set the Destination field (queue or topic).

A destination can be removed from a message by setting the solClient_destination_t structure to {SOLCLIENT_NULL_DESTINATION, NULL}.

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
dest_pA pointer to destination information.
destSizeThe size of (solClient_destination_t).
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 all subcodes.
Examples:
ex/adPubAck.c, ex/common.c, ex/directPubSub.c, ex/flowControlQueue.c, ex/ios/Example.m, ex/ios/examples/AppReachabilityExample.m, ex/ios/examples/AppTransitionsExample.m, ex/ios/examples/DirectPubSubExample.m, ex/ios/examples/RedirectLogsExample.m, ex/ios/examples/SdtPubSubMsgDepExample.m, ex/ios/examples/SdtPubSubMsgIndepExample.m, ex/ios/examples/SecureSessionExample.m, ex/ios/examples/SempGetOverMbExample.m, ex/ios/intro/HelloWorldPubExample.m, ex/ios/intro/HelloWorldWebPubExample.m, ex/messageReplay.c, ex/messageSelectorsOnQueue.c, ex/messageTTLAndDeadMessageQueue.c, ex/noLocalPubSub.c, ex/perfADPub.c, ex/queueProvision.c, ex/redirectLogs.c, ex/replication.c, ex/RRDirectRequester.c, ex/RRGuaranteedReplier.c, ex/RRGuaranteedRequester.c, ex/sdtPubSubMsgDep.c, ex/sdtPubSubMsgIndep.c, ex/secureSession.c, ex/sempGetOverMb.c, ex/simpleBrowserFlow.c, ex/simpleFlowToQueue.c, ex/simpleFlowToTopic.c, ex/transactions.c, Intro/HelloWorldPub.c, Intro/HelloWorldQueuePub.c, and Intro/HelloWorldWebPub.c.
solClient_dllExport solClient_returnCode_t solClient_msg_setDMQEligible ( solClient_opaqueMsg_pt  msg_p,
solClient_bool_t  val 
)

Given a msg_p, set the Dead Message Queue (DMQ) eligible property on a message.

When this option is set, messages that expire in the network, are saved on a appliance dead message queue. Otherwise expired messages are discarded. By default the property is set to false on newly created messages.

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
val0 - clear, 1 - set.
Returns
SOLCLIENT_OK on success, SOLCLIENT_FAIL if msg_p is invalid.
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
Examples:
ex/messageTTLAndDeadMessageQueue.c.
solClient_dllExport solClient_returnCode_t solClient_msg_setElidingEligible ( solClient_opaqueMsg_pt  msg_p,
solClient_bool_t  elide 
)

Given a msg_p, set the ElidingEligible property on a message.

Setting this property to true indicates that this message should be eligible for eliding. Message eliding enables filtering of data to avoid transmitting every single update to a subscribing client. It can be used to overcome slow consumers or any situation where a slower message rate is desired.

Time-based eliding (supported in SolOS-TR) ensures that subscriber applications always receive only the most current update of a published topic at a rate that they can manage. By limiting the incoming message rate, a subscriber application is able to avoid a message backlog filled with outdated messages.

This property does not indicate whether the message was elided or even provide information about the subscriber's configuration (with regards to Message Eliding).

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
elideA Boolean that indicates whether to set or reset the Eliding Eligible attribute.
Returns
SOLCLIENT_OK on success, SOLCLIENT_FAIL if msg_p is invalid.
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
solClient_dllExport solClient_returnCode_t solClient_msg_setExpiration ( solClient_opaqueMsg_pt  msg_p,
solClient_int64_t  timestamp 
)

Given a msg_p, set the expiration time field.

The expiration time is the UTC time (that is, the number of milliseconds from midnight January 1, 1970 UTC) when the message is to expire. The expiration time is carried in the message when set to a non-zero value. Expiration time is not included when this value is set to zero.

The message expiration time is carried to clients that receive the message unmodified and does not effect the life cycle of the message. Use solClient_msg_setTimeToLive() to enforce message expiry in the network. In fact when solClient_msg_setTimeToLive() is used, setting this property has no effect. When solClient_msg_setTimeToLive() is called, the expiration time is never carried in the message, however it may be calculated and retrieved by the sender if the session property SOLCLIENT_SESSION_PROP_CALCULATE_MESSAGE_EXPIRATION is enabled. Thus if solClient_msg_getExpiration() is called after the message is sent, a calculated expiration time is returned based on the time-to-live.

Note: When solClient_msg_setTimeToLive() is set on a message, the receiving client may also calculate the expiration time if it has enabled the session property SOLCLIENT_SESSION_PROP_CALCULATE_MESSAGE_EXPIRATION.

See solClient_msg_getExpiration() for more details.

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
timestampThe sender timestamp value to set. The value is in milliseconds.
Returns
SOLCLIENT_OK on success, SOLCLIENT_FAIL if msg_p is invalid
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
solClient_dllExport solClient_returnCode_t solClient_msg_setHttpContentEncoding ( solClient_opaqueMsg_pt  msg_p,
const char *  encoding_p 
)

Given a msg_p, set or delete (if encoding_p == NULL) its HTTP Content Encoding.

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
encoding_pA pointer to a null terminated HTTP Content Encoding.
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 all subcodes.
solClient_dllExport solClient_returnCode_t solClient_msg_setHttpContentType ( solClient_opaqueMsg_pt  msg_p,
const char *  type_p 
)

Given a msg_p, set or delete (if type_p == NULL) its HTTP Content Type.

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
type_pA pointer to a null terminated HTTP Content Type .
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 all subcodes.
solClient_dllExport solClient_returnCode_t solClient_msg_setPriority ( solClient_opaqueMsg_pt  msg_p,
solClient_int32_t  priority 
)

Set message priority.

Parameters
msg_pA pointer to the message
priorityPriority value. The valid value range is 0-255 with 0 as the lowest priority and 255 as the highest, or -1 to delete priority.
Returns
SOLCLIENT_OK or SOLCLIENT_FAIL
solClient_dllExport solClient_returnCode_t solClient_msg_setQueueNamePtr ( solClient_opaqueMsg_pt  msg_p,
const char *  queueName_p 
)

Given a msg_p, set the QueueName destination of the message as a pointer to application space.

This function is provided for high-performance applications that must be aware that the pointer data cannot be modified until the send operation completes.

NOTE: When a Guaranteed message is constructed with this API refer to Using Solace Message Buffers for Guaranteed messages.

Only solClient_msg_setQueueNamePtr is provided, for copy-in operations use solClient_msg_setDestination.

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
queueName_pA pointer to topic string.
Returns
SOLCLIENT_OK or SOLCLIENT_FAIL if msg_p is invalid.
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
solClient_dllExport solClient_returnCode_t solClient_msg_setReplyTo ( solClient_opaqueMsg_pt  msg_p,
const solClient_destination_t dest_p,
size_t  destSize 
)

Given a msg_p, set the ReplyTo destination.

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
dest_pA pointer to ReplyTo destination to set.
destSizeThe size of (solClient_destination_t).
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 all subcodes.
Examples:
ex/RRGuaranteedRequester.c, and ex/transactions.c.
solClient_dllExport solClient_returnCode_t solClient_msg_setReplyToSuffix ( solClient_opaqueMsg_pt  msg_p,
solClient_opaqueSession_pt  opaqueSession_p,
const char *  suffix_p 
)

Append an application-specified suffix to the default topic destination for the Session.

When the session is established, a unique topic destination is created for the Session. This topic is generated by the appliance, and the API subscribes to a wildcard extended topic that is derived by appending '/>' to the unique topic destination. By default, solClient_session_sendRequest automatically adds a replyTo destination derived by appending '/#' to the unique topic destination.

When this function is used, a delimiter ('/') and the supplied string are appended instead.

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
opaqueSession_ppointer to the Session the message is later used with.
suffix_pA pointer to a NULL-terminated suffix string.
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 all subcodes.
solClient_dllExport solClient_returnCode_t solClient_msg_setSenderId ( solClient_opaqueMsg_pt  msg_p,
const char *  buf_p 
)

Given a msg_p, set the SenderID.

This overrides SOLCLIENT_SESSION_PROP_GENERATE_SENDER_ID session property and forces the specified SenderID into the binary message header.

This method allows the application to set the contents of the SenderID. The SenderID is user-defined, carried end-to-end, and can also be matched in a selector but otherwise is not relevant to the event broker.

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
buf_pA pointer to string for the data copy.
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 all subcodes.
Examples:
ex/transactions.c.
solClient_dllExport solClient_returnCode_t solClient_msg_setSenderTimestamp ( solClient_opaqueMsg_pt  msg_p,
solClient_int64_t  timestamp 
)

Given a msg_p, set the Sender Timestamp field.

This overrides the SOLCLIENT_SESSION_PROP_GENERATE_SEND_TIMESTAMPS session property and sets the specified Sender Timestamp value in the binary message header.

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
timestampThe sender timestamp value to set. The value is in milliseconds.
Returns
SOLCLIENT_OK on success, SOLCLIENT_FAIL if msg_p is invalid
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
solClient_dllExport solClient_returnCode_t solClient_msg_setSequenceNumber ( solClient_opaqueMsg_pt  msg_p,
solClient_uint64_t  seqNum 
)

Given a msg_p, set the Sequence Number field.

This overrides the SOLCLIENT_SESSION_PROP_GENERATE_SEQUENCE_NUMBER session property and forces the specified Sequence Number into the binary message header. This does not change the internal sequence numbering and the next generated sequence number will still be one more than the last generated sequence number.

A sequence number is automatically included (if not already present) in the Solace-defined fields for each message sent if the session property SOLCLIENT_SESSION_PROP_GENERATE_SEQUENCE_NUMBER is enabled.

This method allows the application to set the value of the SequenceNo. The SequenceNo is user defined, carried end-to-end, and can slso be matched in a selector, but otherwise is not relevant to the event broker.

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
seqNumThe 64-bit Sequence Number.
Returns
SOLCLIENT_OK on success, SOLCLIENT_FAIL if msg_p is invalid.
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
solClient_dllExport solClient_returnCode_t solClient_msg_setTimeToLive ( solClient_opaqueMsg_pt  msg_p,
solClient_int64_t  ttl 
)

Given a msg_p, set the Time To Live (TTL) for a message.

Setting the Time To Live to zero disables TTL for the message.

This property is only valid for Guaranteed messages (Persistent and Non-Persistent). It has no effect when used in conjunction with other message types unless the message is promoted by the appliance to a Guaranteed message.

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
ttl64-bit value in milliseconds to use for message time to live.
Returns
SOLCLIENT_OK on success, SOLCLIENT_FAIL if msg_p is invalid.
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
Examples:
ex/messageTTLAndDeadMessageQueue.c.
solClient_dllExport solClient_returnCode_t solClient_msg_setTopicPtr ( solClient_opaqueMsg_pt  msg_p,
const char *  topic_p 
)

Given a msg_p, set the Topic of the message as a pointer to application space.

This function is provided for high-performance applications that must be aware that the data referenced cannot be modified until the send operation completes.

NOTE: When a Guaranteed message is constructed with this API refer to Using Solace Message Buffers for Guaranteed messages.

Only solClient_msg_setTopicPtr is provided, for copy-in operations use solClient_msg_setDestination.

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
topic_pA pointer to topic string.
Returns
SOLCLIENT_OK or SOLCLIENT_FAIL if msg_p is invalid.
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
Examples:
ex/ios/examples/PerfTestExample.m, and ex/perfTest.c.
solClient_dllExport solClient_returnCode_t solClient_msg_setUserData ( solClient_opaqueMsg_pt  msg_p,
const void *  buf_p,
solClient_uint32_t  size 
)

Given a msg_p, set the contents of User Data Part by copying in from the given pointer and size.

This causes memory to be allocated from internal or heap storage. If any user data previously existed it is first removed before the new data is copied in.

The maximum size allowed for the user data part is SOLCLIENT_BUFINFO_MAX_USER_DATA_SIZE.

Passing in a buf_p of NULL and a size of zero results in user data not being present in the message.

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
buf_pA pointer to buffer.
sizeThe number of bytes in buffer.
Returns
SOLCLIENT_OK or SOLCLIENT_FAIL if msg_p is invalid or memory not available.
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
solClient_dllExport solClient_returnCode_t solClient_msg_setUserDataPtr ( solClient_opaqueMsg_pt  msg_p,
void *  buf_p,
solClient_uint32_t  size 
)

Given a msg_p, set the contents of a user data part to the given pointer and size.

This function is provided for high-performance applications that must be aware that the data referenced cannot be modified until the send operation completes.

The maximum size allowed for the user data part is SOLCLIENT_BUFINFO_MAX_USER_DATA_SIZE.

NOTE: When a Guaranteed message is constructed with this API refer to Using Solace Message Buffers for Guaranteed messages

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
buf_pA pointer to buffer.
sizeThe number of bytes in the buffer.
Returns
SOLCLIENT_OK or SOLCLIENT_FAIL if msg_p is invalid.
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
solClient_dllExport solClient_returnCode_t solClient_msg_setUserPropertyMap ( solClient_opaqueMsg_pt  msg_p,
solClient_opaqueContainer_pt  map_p 
)

Set the User Property map in the binary metadata header.

If there is an existing User Property map, it is overwritten with the map that is passed as a parameter. If the application has any open containers referencing the existing map they are automatically closed. Attempting to use a closed stream returns an invalid pointer error (SOLCLIENT_SUBCODE_PARAM_NULL_PTR). Changes made to the passed in map subsequent to this call do affect the user property map.

Parameters
msg_psolClient_opaqueMsg_pt returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
map_pAn opaque container pointer for the map to set.
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 all subcodes.
Examples:
ex/ios/examples/SdtPubSubMsgIndepExample.m, and ex/sdtPubSubMsgIndep.c.
solClient_dllExport solClient_returnCode_t solClient_msg_setXml ( solClient_opaqueMsg_pt  msg_p,
const void *  buf_p,
solClient_uint32_t  size 
)

Given a msg_p, set the contents of the XML part by copying in from the given pointer and size.

This causes memory to be allocated from internal or heap storage. If any XML part previously existed, it is first removed before the new data is copied in.

Passing in a buf_p of NULL and a size of zero results in the XML part not being present in the message.

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
buf_pA pointer to buffer.
sizeThe number of bytes in buffer.
Returns
SOLCLIENT_OK or SOLCLIENT_FAIL if msg_p is invalid or memory not available.
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
solClient_dllExport solClient_returnCode_t solClient_msg_setXmlPtr ( solClient_opaqueMsg_pt  msg_p,
void *  buf_p,
solClient_uint32_t  size 
)

Given a msg_p, set the contents of the XML part to the given pointer and size.

This function is provided for high-performance applications that must be aware that the data referenced cannot be modified until the send operation completes.

NOTE: When a Guaranteed message is constructed with this API refer to Using Solace Message Buffers for Guaranteed messages.

Parameters
msg_pA solClient_opaqueMsg_pt that is returned from a previous call to solClient_msg_alloc() or received in a receive message callback.
buf_pA pointer to buffer.
sizeThe number of bytes in buffer.
Returns
SOLCLIENT_OK or SOLCLIENT_FAIL if msg_p is invalid.
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
See Also
solClient_subCode for a description of all subcodes.
solClient_dllExport solClient_returnCode_t solClient_replicationGroupMessageId_compare ( solClient_replicationGroupMessageId_pt  rgmid1_p,
solClient_replicationGroupMessageId_pt  rgmid2_p,
int *  compare_p 
)

Compare two Replication Group Message Id.

Not all valid solClient_replicationGroupMessageId_t can be compared. If the messages identified were not published to the same broker or HA pair, then they are not comparable and this method returns SOLCLIENT_FAIL

Parameters
rgmid1_pA pointer to the first solClient_replicationGroupMessageId_t
rgmid2_pA pointer to the second solClient_replicationGroupMessageId_t
compare_pA pointer to an integer for the result which is: *compare_p < 0 if first is less than the second *compare_p == 0 if both are the same. *compare_p >0 if the first is greater than the second.
Returns
SOLCLIENT_OK on success. SOLCLIENT_FAIL if the Replication Group Message Id cannot be compared.
SubCodes (Unless otherwise noted above, subcodes are only relevant when this function returns SOLCLIENT_FAIL):
SOLCLIENT_SUBCODE_MESSAGE_ID_NOT_COMPARABLE
solClient_dllExport solClient_returnCode_t solClient_replicationGroupMessageId_fromString ( solClient_replicationGroupMessageId_pt  rgmid_p,
size_t  size_rgmid,
const char *  rgmid_str 
)

Create a Replication Group Message Id from the string format.

The string may be retrieved by a call to solClient_replicationGroupMessageId_toString, or it can be retrieved from any of the broker admin interfaces.

Parameters
rgmid_pA pointer to solClient_replicationGroupMessageId_t to be filled.
size_rgmidThe return from sizeof(solClient_replicationGroupMessageId_t)
rgmid_strPointer to string representation of the Replication Group MessageId.
Returns
SOLCLIENT_OK or SOLCLIENT_FAIL
solClient_dllExport solClient_bool_t solClient_replicationGroupMessageId_isValid ( solClient_replicationGroupMessageId_pt  rgmid_p)

Validate a Replication Group Message Id.

Parameters
rgmid_pA pointer to a solClient_replicationGroupMessageId_t. The object must have been previously initialized by either solClient_msg_getReplicationGroupMessageId() or solClient_replicationGroupMessageId_fromString()
Returns
SOLCLIENT_OK or SOLCLIENT_FAIL
solClient_dllExport solClient_returnCode_t solClient_replicationGroupMessageId_toString ( solClient_replicationGroupMessageId_pt  rgmid_p,
size_t  size_rgmid,
char *  str,
size_t  size_str 
)

Convert a Replication Group Message Id to a defined string format.

The standard format can be stored for later use in solClient_replicationGroupMessageId_fromString.

Parameters
rgmid_pA pointer to solClient_replicationGroupMessageId_t to serialize.
size_rgmidThe return from sizeof(solClient_replicationGroupMessageId_t)
strPointer to string location to copy the string into.
size_strThe available memory for the string. It should be at least 45 bytes for the standard string: rmid1:xxxxx-xxxxxxxxxxx-xxxxxxxx-xxxxxxxx If there is not enough room the output is truncated.
Returns
SOLCLIENT_OK or SOLCLIENT_FAIL