AMPS C/C++ Client Class Reference
AMPS C/C++ Client Version 5.3.4.3
AMPS::Client Class Reference

Client represents a connection to an AMPS server, but does not provide failover or reconnection behavior by default. More...

#include <ampsplusplus.hpp>

+ Inheritance diagram for AMPS::Client:

Public Member Functions

 Client (const std::string &clientName="")
 Constructs a new client with a given client name. More...
 
void setName (const std::string &name)
 Sets the name of this client, assuming no name was provided previously. More...
 
const std::string & getName () const
 Returns the name of this client passed in the constructor. More...
 
const std::string & getNameHash () const
 Returns the name hash string of this client as generated by the server and returned when the client logged on. More...
 
const amps_uint64_t getNameHashValue () const
 Returns the numeric name hash of this client as generated by the server and returned when the client logged on. More...
 
void setLogonCorrelationData (const std::string &logonCorrelationData_)
 Sets the logon correlation data for the client. More...
 
const std::string & getLogonCorrelationData () const
 Returns the currently set logon correlation data for the client. More...
 
size_t getServerVersion () const
 Returns the server version retrieved during logon. More...
 
VersionInfo getServerVersionInfo () const
 Returns the server version retrieved during logon. More...
 
const std::string & getURI () const
 Returns the last URI this client is connected to. More...
 
void connect (const std::string &uri)
 Connect to an AMPS server. More...
 
void disconnect ()
 Disconnect from an AMPS server. More...
 
void send (const Message &message)
 Sends a Message to the connected AMPS server, performing only minimal validation and bypassing client services such as the publish store. More...
 
void addMessageHandler (const Field &commandId_, const AMPS::MessageHandler &messageHandler_, unsigned requestedAcks_, bool isSubscribe_)
 Adds a MessageHandler to be invoked for Messages with the given CommandId as their command id, sub id, or query id. More...
 
void addMessageHandler (const Field &commandId_, const AMPS::MessageHandler &messageHandler_, unsigned requestedAcks_, Message::Command::Type commandType_)
 Adds a MessageHandler to be invoked for Messages with the given CommandId as their command id, sub id, or query id. More...
 
bool removeMessageHandler (const Field &commandId_)
 Removes a MessageHandler for a given ComandId from self. More...
 
std::string send (const MessageHandler &messageHandler, Message &message, int timeout=0)
 Sends a Message to the connected AMPS server, performing only minimal validation and bypassing client services such as the publish store. More...
 
void setDisconnectHandler (const DisconnectHandler &disconnectHandler)
 Sets the function to be called when the client is unintentionally disconnected. More...
 
DisconnectHandler getDisconnectHandler (void) const
 Returns the callback function that is invoked when a disconnect occurs. More...
 
virtual ConnectionInfo getConnectionInfo () const
 Get the connection information for the current connection. More...
 
void setBookmarkStore (const BookmarkStore &bookmarkStore_)
 Set the bookmark store to be used by the client. More...
 
BookmarkStore getBookmarkStore ()
 Get the bookmark store being used by the client. More...
 
SubscriptionManagergetSubscriptionManager ()
 Get the subscription manager being used by the client. More...
 
void setSubscriptionManager (SubscriptionManager *subscriptionManager_)
 Set the subscription manager to be used by the client. More...
 
void setPublishStore (const Store &publishStore_)
 Set the publish store to be used by the client. More...
 
Store getPublishStore ()
 Get the publish store used by the client. More...
 
void setDuplicateMessageHandler (const MessageHandler &duplicateMessageHandler_)
 Sets a callback function that is invoked when a duplicate message is detected. More...
 
MessageHandler getDuplicateMessageHandler (void)
 Returns the callback function that is invoked when a duplicate message is detected. More...
 
void setFailedWriteHandler (FailedWriteHandler *handler_)
 Set the handler that is invoked to report when a publish fails, for example if the publisher is not entitled, if AMPS attempts to parse the message and the parse fails, and so on. More...
 
FailedWriteHandlergetFailedWriteHandler ()
 Get the handler that is invoked to report on failed writes. More...
 
amps_uint64_t publish (const std::string &topic_, const std::string &data_)
 Publish a message to an AMPS topic, returning the sequence number assigned by the publish store if one is present on the client. More...
 
amps_uint64_t publish (const char *topic_, size_t topicLength_, const char *data_, size_t dataLength_)
 Publish a message to an AMPS topic, returning the sequence number assigned by the publish store if one is present on the client. More...
 
amps_uint64_t publish (const std::string &topic_, const std::string &data_, unsigned long expiration_)
 Publish a message to an AMPS topic, returning the sequence number assigned by the publish store (if a publish store is present on the client). More...
 
amps_uint64_t publish (const char *topic_, size_t topicLength_, const char *data_, size_t dataLength_, unsigned long expiration_)
 Publish a message to an AMPS topic, returning the sequence number assigned by the publish store if one is present on the client. More...
 
void publishFlush (long timeout_=0, unsigned ackType_=Message::AckType::Processed)
 Ensure that AMPS messages are sent and have been processed by the AMPS server. More...
 
amps_uint64_t deltaPublish (const std::string &topic_, const std::string &data_)
 Publish the changed fields of a message to an AMPS topic. More...
 
amps_uint64_t deltaPublish (const char *topic_, size_t topicLength_, const char *data_, size_t dataLength_)
 Publish the changed fields of a message to an AMPS topic. More...
 
amps_uint64_t deltaPublish (const std::string &topic_, const std::string &data_, unsigned long expiration_)
 Publish the changed fields of a message to an AMPS topic. More...
 
amps_uint64_t deltaPublish (const char *topic_, size_t topicLength_, const char *data_, size_t dataLength_, unsigned long expiration_)
 Publish the changed fields of a message to an AMPS topic. More...
 
std::string logon (int timeout_=0, Authenticator &authenticator_=DefaultAuthenticator::instance(), const char *options_=NULL)
 Logon to the server, providing the client name, credentials (if available), and client information (such as client version and connection message type). More...
 
std::string logon (const char *options_, int timeout_=0)
 Logon to the server, providing the client name, credentials (if available) client information (such as client version and connection message type), and the specified options. More...
 
std::string logon (const std::string &options_, int timeout_=0)
 Logon to the server, providing the client name, credentials (if available) client information (such as client version and connection message type), and the specified options. More...
 
std::string subscribe (const MessageHandler &messageHandler_, const std::string &topic_, long timeout_=0, const std::string &filter_="", const std::string &options_="", const std::string &subId_="")
 Subscribe to a topic. More...
 
MessageStream subscribe (const std::string &topic_, long timeout_=0, const std::string &filter_="", const std::string &options_="", const std::string &subId_="")
 Subscribe to a topic. More...
 
MessageStream subscribe (const char *topic_, long timeout_=0, const std::string &filter_="", const std::string &options_="", const std::string &subId_="")
 Subscribe to a topic. More...
 
std::string deltaSubscribe (const MessageHandler &messageHandler_, const std::string &topic_, long timeout_, const std::string &filter_="", const std::string &options_="", const std::string &subId_="")
 Delta Subscribe to a topic. More...
 
MessageStream deltaSubscribe (const std::string &topic_, long timeout_, const std::string &filter_="", const std::string &options_="", const std::string &subId_="")
 Delta Subscribe to a topic. More...
 
MessageStream deltaSubscribe (const char *topic_, long timeout_, const std::string &filter_="", const std::string &options_="", const std::string &subId_="")
 Delta Subscribe to a topic. More...
 
std::string bookmarkSubscribe (const MessageHandler &messageHandler_, const std::string &topic_, long timeout_, const std::string &bookmark_, const std::string &filter_="", const std::string &options_="", const std::string &subId_="")
 Subscribe to a topic using a bookmark. More...
 
MessageStream bookmarkSubscribe (const std::string &topic_, long timeout_, const std::string &bookmark_, const std::string &filter_="", const std::string &options_="", const std::string &subId_="")
 Subscribe to a topic using a bookmark. More...
 
MessageStream bookmarkSubscribe (const char *topic_, long timeout_, const std::string &bookmark_, const std::string &filter_="", const std::string &options_="", const std::string &subId_="")
 Subscribe to a topic using a bookmark. More...
 
void unsubscribe (const std::string &commandId)
 Unsubscribe from a topic. More...
 
void unsubscribe ()
 Unsubscribe from all topics. More...
 
std::string sow (const MessageHandler &messageHandler_, const std::string &topic_, const std::string &filter_="", const std::string &orderBy_="", const std::string &bookmark_="", int batchSize_=DEFAULT_BATCH_SIZE, int topN_=DEFAULT_TOP_N, const std::string &options_="", long timeout_=DEFAULT_COMMAND_TIMEOUT)
 Query a State-of-the-World topic. More...
 
MessageStream sow (const std::string &topic_, const std::string &filter_="", const std::string &orderBy_="", const std::string &bookmark_="", int batchSize_=DEFAULT_BATCH_SIZE, int topN_=DEFAULT_TOP_N, const std::string &options_="", long timeout_=DEFAULT_COMMAND_TIMEOUT)
 Query the SOW cache of a topic. More...
 
MessageStream sow (const char *topic_, const std::string &filter_="", const std::string &orderBy_="", const std::string &bookmark_="", int batchSize_=DEFAULT_BATCH_SIZE, int topN_=DEFAULT_TOP_N, const std::string &options_="", long timeout_=DEFAULT_COMMAND_TIMEOUT)
 Query the SOW cache of a topic. More...
 
std::string sow (const MessageHandler &messageHandler_, const std::string &topic_, long timeout_, const std::string &filter_="", int batchSize_=DEFAULT_BATCH_SIZE, int topN_=DEFAULT_TOP_N)
 Query the SOW cache of a topic. More...
 
std::string sowAndSubscribe (const MessageHandler &messageHandler_, const std::string &topic_, long timeout_, const std::string &filter_="", int batchSize_=DEFAULT_BATCH_SIZE, bool oofEnabled_=false, int topN_=DEFAULT_TOP_N)
 Query the SOW cache of a topic and initiates a new subscription on it. More...
 
MessageStream sowAndSubscribe (const std::string &topic_, long timeout_, const std::string &filter_="", int batchSize_=DEFAULT_BATCH_SIZE, bool oofEnabled_=false, int topN_=DEFAULT_TOP_N)
 Query the SOW cache of a topic and initiates a new subscription on it. More...
 
MessageStream sowAndSubscribe (const char *topic_, long timeout_, const std::string &filter_="", int batchSize_=DEFAULT_BATCH_SIZE, bool oofEnabled_=false, int topN_=DEFAULT_TOP_N)
 Query the SOW cache of a topic and initiates a new subscription on it. More...
 
std::string sowAndSubscribe (const MessageHandler &messageHandler_, const std::string &topic_, const std::string &filter_="", const std::string &orderBy_="", const std::string &bookmark_="", int batchSize_=DEFAULT_BATCH_SIZE, int topN_=DEFAULT_TOP_N, const std::string &options_="", long timeout_=DEFAULT_COMMAND_TIMEOUT)
 Query the SOW cache of a topic and initiates a new subscription on it. More...
 
MessageStream sowAndSubscribe (const std::string &topic_, const std::string &filter_="", const std::string &orderBy_="", const std::string &bookmark_="", int batchSize_=DEFAULT_BATCH_SIZE, int topN_=DEFAULT_TOP_N, const std::string &options_="", long timeout_=DEFAULT_COMMAND_TIMEOUT)
 Query the SOW cache of a topic and initiates a new subscription on it. More...
 
MessageStream sowAndSubscribe (const char *topic_, const std::string &filter_="", const std::string &orderBy_="", const std::string &bookmark_="", int batchSize_=DEFAULT_BATCH_SIZE, int topN_=DEFAULT_TOP_N, const std::string &options_="", long timeout_=DEFAULT_COMMAND_TIMEOUT)
 Query the SOW cache of a topic and initiates a new subscription on it. More...
 
std::string sowAndDeltaSubscribe (const MessageHandler &messageHandler_, const std::string &topic_, const std::string &filter_="", const std::string &orderBy_="", int batchSize_=DEFAULT_BATCH_SIZE, int topN_=DEFAULT_TOP_N, const std::string &options_="", long timeout_=DEFAULT_COMMAND_TIMEOUT)
 Query the SOW cache of a topic and initiates a new delta subscription on it. More...
 
MessageStream sowAndDeltaSubscribe (const std::string &topic_, const std::string &filter_="", const std::string &orderBy_="", int batchSize_=DEFAULT_BATCH_SIZE, int topN_=DEFAULT_TOP_N, const std::string &options_="", long timeout_=DEFAULT_COMMAND_TIMEOUT)
 Query the SOW cache of a topic and initiates a new delta subscription on it. More...
 
MessageStream sowAndDeltaSubscribe (const char *topic_, const std::string &filter_="", const std::string &orderBy_="", int batchSize_=DEFAULT_BATCH_SIZE, int topN_=DEFAULT_TOP_N, const std::string &options_="", long timeout_=DEFAULT_COMMAND_TIMEOUT)
 Query the SOW cache of a topic and initiates a new delta subscription on it. More...
 
std::string sowAndDeltaSubscribe (const MessageHandler &messageHandler_, const std::string &topic_, long timeout_, const std::string &filter_="", int batchSize_=DEFAULT_BATCH_SIZE, bool oofEnabled_=false, bool sendEmpties_=false, int topN_=DEFAULT_TOP_N)
 Query the SOW cache of a topic and initiates a new delta subscription on it. More...
 
MessageStream sowAndDeltaSubscribe (const std::string &topic_, long timeout_, const std::string &filter_="", int batchSize_=DEFAULT_BATCH_SIZE, bool oofEnabled_=false, bool sendEmpties_=false, int topN_=DEFAULT_TOP_N)
 Query the SOW cache of a topic and initiates a new delta subscription on it. More...
 
MessageStream sowAndDeltaSubscribe (const char *topic_, long timeout_, const std::string &filter_="", int batchSize_=DEFAULT_BATCH_SIZE, bool oofEnabled_=false, bool sendEmpties_=false, int topN_=DEFAULT_TOP_N)
 Query the SOW cache of a topic and initiates a new delta subscription on it. More...
 
std::string sowDelete (const MessageHandler &messageHandler, const std::string &topic, const std::string &filter, long timeout)
 Deletes one or more messages from a topic's SOW cache. More...
 
Message sowDelete (const std::string &topic, const std::string &filter, long timeout=0)
 Deletes one or more messages from a topic's SOW cache. More...
 
void startTimer ()
 
std::string stopTimer (const MessageHandler &messageHandler)
 
std::string sowDeleteByKeys (const MessageHandler &messageHandler_, const std::string &topic_, const std::string &keys_, long timeout_=0)
 Deletes messages that match SOW keys from a topic's SOW cache. More...
 
Message sowDeleteByKeys (const std::string &topic_, const std::string &keys_, long timeout_=0)
 Deletes messages that match SOW keys from a topic's SOW cache. More...
 
std::string sowDeleteByData (const MessageHandler &messageHandler_, const std::string &topic_, const std::string &data_, long timeout_=0)
 Deletes the message whose keys match the message data provided. More...
 
Message sowDeleteByData (const std::string &topic_, const std::string &data_, long timeout_=0)
 Deletes the message whose keys match the message data provided. More...
 
amps_handle getHandle ()
 Returns the underlying amps_handle for this client, to be used with amps_client_* functions from the C api. More...
 
void setExceptionListener (const std::shared_ptr< const ExceptionListener > &pListener_)
 Sets the exception listener for exceptions that are not thrown back to the user (for example, exceptions that are thrown from a MessageHandler running on the client receive thread.) 60East strongly recommends setting this callback if an application uses asynchronous message processing (that is, provides message handler callbacks). More...
 
void setExceptionListener (const ExceptionListener &listener_)
 
const ExceptionListenergetExceptionListener (void) const
 Returns the exception listener set on this Client. More...
 
void setHeartbeat (unsigned heartbeatTime_, unsigned readTimeout_)
 Requests heartbeating with the AMPS server. More...
 
void setHeartbeat (unsigned heartbeatTime_)
 Requests heartbeating with the AMPS server. More...
 
void setUnhandledMessageHandler (const AMPS::MessageHandler &messageHandler)
 
void setLastChanceMessageHandler (const AMPS::MessageHandler &messageHandler)
 Sets the message handler called when no other handler matches. More...
 
void setGlobalCommandTypeMessageHandler (const std::string &command_, const MessageHandler &handler_)
 Sets a handler for all messages of a particular type, or for messages that would be delivered to a particular special handler: currently supported types are "heartbeat", "ack", "duplicate", and "lastchance". More...
 
void setGlobalCommandTypeMessageHandler (const Message::Command::Type command_, const MessageHandler &handler_)
 Sets a handler for all messages of a particular type: currently supported types are heartbeat messages and ack messages. More...
 
void addConnectionStateListener (ConnectionStateListener *listener)
 Adds a ConnectionStateListener to self's set of listeners. More...
 
void removeConnectionStateListener (ConnectionStateListener *listener)
 Attempts to remove listener from self's set of ConnectionStateListeners. More...
 
void clearConnectionStateListeners ()
 Clear all listeners from self's set of ConnectionStateListeners.
 
std::string executeAsync (Command &command_, MessageHandler handler_)
 Execute the provided command and, once AMPS acknowledges the command, process messages in response to the command on the client receive thread by invoking the provided handler. More...
 
std::string executeAsyncNoResubscribe (Command &command_, MessageHandler handler_)
 Execute the provided command and, once AMPS acknowledges the command, process messages in response to the command on the client receive thread by invoking the provided handler. More...
 
MessageStream execute (Command &command_)
 Execute the provided command and return messages received in response in a MessageStream. More...
 
void ack (Field &topic_, Field &bookmark_, const char *options_=NULL)
 Acknowledge a message queue message by supplying a topic and bookmark: this adds the ack to the current batch (or sends the ack immediately if the batch size is 1 or less). More...
 
void ack (Message &message_, const char *options_=NULL)
 Acknowledge a message queue message by supplying the message directly: this adds the ack to the current batch (or sends the ack immediately if the batch size is 1 or less). More...
 
void ack (const std::string &topic_, const std::string &bookmark_, const char *options_=NULL)
 Acknowledge a message queue message by supplying a topic and bookmark string: this adds the ack to the current batch (or sends the ack immediately if the batch size is 1 or less). More...
 
void flushAcks (void)
 Sends any queued message queue ack messages to the server immediately. More...
 
bool getAutoAck (void) const
 Returns the value of the queue auto-ack setting. More...
 
void setAutoAck (bool isAutoAckEnabled_)
 Sets the queue auto-ack setting on this client. More...
 
unsigned getAckBatchSize (void) const
 Returns the value of the queue ack batch size setting. More...
 
void setAckBatchSize (const unsigned ackBatchSize_)
 Sets the queue ack batch size setting. More...
 
int getAckTimeout (void) const
 Returns the current value of the message queue ack timeout setting – that is, the amount of time after which queue messages will be acknowledged even if the ack batch is not full. More...
 
void setAckTimeout (const int ackTimeout_)
 Sets the message queue ack timeout value. More...
 
void setRetryOnDisconnect (bool isRetryOnDisconnect_)
 Enables or disables automatic retry of a command to AMPS after a reconnect. More...
 
bool getRetryOnDisconnect (void) const
 Returns true if automatic retry of a command to AMPS after a reconnect is enabled.
 
void setDefaultMaxDepth (unsigned maxDepth_)
 Sets a default max depth on all subsequently created MessageStream objects. More...
 
unsigned getDefaultMaxDepth (void) const
 Returns the default max depth for returned MessageStream objects. More...
 
void setTransportFilterFunction (amps_transport_filter_function filter_, void *userData_)
 Sets a filter function on the transport that is called with all raw data sent or received. More...
 
void setThreadCreatedCallback (amps_thread_created_callback callback_, void *userData_)
 Sets a callback function on the transport that is called when a new thread is created to receive data from the server. More...
 

Static Public Member Functions

static size_t convertVersionToNumber (const std::string &version_)
 Converts a string version, such as "3.8.1.5" into the same numeric form used internally and returned by getServerVersion. More...
 
static size_t convertVersionToNumber (const char *data_, size_t len_)
 Converts a string version, such as "3.8.1.5" into the same numeric form used internally and returned by getServerVersion. More...
 
static const char * BOOKMARK_NOW ()
 Convenience method for returning the special value to start a subscription at the end of the transaction log. More...
 
static const char * NOW ()
 Convenience method for returning the special value to start a subscription at the end of the transaction log. More...
 
static const char * BOOKMARK_EPOCH ()
 Convenience method for returning the special value to start a subscription at the beginning of the transaction log. More...
 
static const char * EPOCH ()
 Convenience method for returning the special value to start a subscription at the beginning of the transaction log. More...
 
static const char * BOOKMARK_MOST_RECENT ()
 Convenience method for returning the special value to start a subscription at a recovery point based on the information that the configured BookmarkStore (if one is set) has for the subscription. More...
 
static const char * MOST_RECENT ()
 Convenience method for returning the special value to start a subscription at a recovery point based on the information that the configured BookmarkStore (if one is set) has for the subscription. More...
 
static const char * BOOKMARK_RECENT ()
 Convenience method for returning the special value to start a subscription at a recovery point based on the information that the configured BookmarkStore (if one is set) has for the subscription. More...
 

Detailed Description

Client represents a connection to an AMPS server, but does not provide failover or reconnection behavior by default.

The class provides methods for executing commands against the server, (for example, publishing messages, subscribing, and so on.)

A Client object has a single connection to an AMPS server at a time. That connection is serviced by a background thread created by the Client. When using the Asynchronous Message Processing interface, messages are delivered to the MessageHandler callback on the background thread.

A Client object is implemented as a reference-counted handle to an underlying object. This means that a Client can be safely and efficiently passed by value.

For applications that require automatic failover and reconnection to AMPS, 60East recommends using the HAClient subclass instead of the Client.

Constructor & Destructor Documentation

AMPS::Client::Client ( const std::string &  clientName = "")
inline

Constructs a new client with a given client name.

Parameters
clientNameName for the client. This name is used for duplicate message detection and should be unique. AMPS does not enforce specific restrictions on the character set used, however some protocols (for example, XML) may not allow specific characters. 60East recommends that the client name be meaningful, short, human readable, and avoids using control characters, newline characters, or square brackets.

Member Function Documentation

void AMPS::Client::ack ( Field topic_,
Field bookmark_,
const char *  options_ = NULL 
)
inline

Acknowledge a message queue message by supplying a topic and bookmark: this adds the ack to the current batch (or sends the ack immediately if the batch size is 1 or less).

Parameters
topic_The topic to acknowledge
bookmark_The bookmark of the message to acknowledge
options_The options string for the ack, such as cancel
void AMPS::Client::ack ( Message message_,
const char *  options_ = NULL 
)
inline

Acknowledge a message queue message by supplying the message directly: this adds the ack to the current batch (or sends the ack immediately if the batch size is 1 or less).

Parameters
message_The message to acknowledge
options_The options string for the ack, such as cancel
void AMPS::Client::ack ( const std::string &  topic_,
const std::string &  bookmark_,
const char *  options_ = NULL 
)
inline

Acknowledge a message queue message by supplying a topic and bookmark string: this adds the ack to the current batch (or sends the ack immediately if the batch size is 1 or less).

Parameters
topic_The message queue topic to acknowledge
bookmark_The bookmark to acknowledge
options_The options string for the ack, such as cancel
void AMPS::Client::addConnectionStateListener ( ConnectionStateListener listener)
inline

Adds a ConnectionStateListener to self's set of listeners.

These listeners are invoked whenever the connection state of this client changes (either becomes connected or disconnected.)

Parameters
listenerThe ConnectionStateListener to invoke.
void AMPS::Client::addMessageHandler ( const Field commandId_,
const AMPS::MessageHandler messageHandler_,
unsigned  requestedAcks_,
bool  isSubscribe_ 
)
inline

Adds a MessageHandler to be invoked for Messages with the given CommandId as their command id, sub id, or query id.

Parameters
commandId_The command, query, or subid used to invoke the handler.
messageHandler_The message handler to route to
requestedAcks_The actual acks requested from amps for this command
isSubscribe_True is the handler is for an ongoing subscription.
void AMPS::Client::addMessageHandler ( const Field commandId_,
const AMPS::MessageHandler messageHandler_,
unsigned  requestedAcks_,
Message::Command::Type  commandType_ 
)
inline

Adds a MessageHandler to be invoked for Messages with the given CommandId as their command id, sub id, or query id.

Parameters
commandId_The command, query, or subid used to invoke the handler.
messageHandler_The message handler to route to
requestedAcks_The actual acks requested from amps for this command
commandType_The command type of the message.
static const char* AMPS::Client::BOOKMARK_EPOCH ( )
inlinestatic

Convenience method for returning the special value to start a subscription at the beginning of the transaction log.

Returns
Always returns AMPS_BOOKMARK_EPOCH
static const char* AMPS::Client::BOOKMARK_MOST_RECENT ( )
inlinestatic

Convenience method for returning the special value to start a subscription at a recovery point based on the information that the configured BookmarkStore (if one is set) has for the subscription.

Returns
Always returns AMPS_BOOKMARK_RECENT
static const char* AMPS::Client::BOOKMARK_NOW ( )
inlinestatic

Convenience method for returning the special value to start a subscription at the end of the transaction log.

/returns Always returns AMPS_BOOKMARK_NOW

static const char* AMPS::Client::BOOKMARK_RECENT ( )
inlinestatic

Convenience method for returning the special value to start a subscription at a recovery point based on the information that the configured BookmarkStore (if one is set) has for the subscription.

Returns
Always returns AMPS_BOOKMARK_RECENT
std::string AMPS::Client::bookmarkSubscribe ( const MessageHandler messageHandler_,
const std::string &  topic_,
long  timeout_,
const std::string &  bookmark_,
const std::string &  filter_ = "",
const std::string &  options_ = "",
const std::string &  subId_ = "" 
)
inline

Subscribe to a topic using a bookmark.

Initiates a bookmark subscription (a transaction log replay) to a topic on the server. using the provided messageHandler_ to receive messages for the subscription. The messageHandler_ is called on the client receive thread: see the Developer Guide for details on the threading considerations.

Parameters
messageHandler_The function to be invoked when messages for this topic arrive.
topic_The topic, or regular expression topic, to subscribe to.
timeout_The time to wait, in milliseconds, for the receive thread to consume a processed ack for this command. 0 indicates no timeout.
bookmark_Bookmark to supply with this subscription. This can be a bookmark within the journal file, or one of the Special Bookmark Values.
filter_Optional filter expression for this subscription.
options_Optional options to supply with this subscription.
subId_Optional subscription Id to use for this subscription. When used with the 'replace' option, this is the subscription to be replaced. With a bookmark store, this is the subscription Id used for recovery. so, when using a persistent bookmark store, provide an explicit subscription Id that is consistent across application restarts.
Returns
A std::string with a unique identifier for this subscription.
Exceptions
DisconnectedExceptionThe Client is no longer connected to a server.
ConnectionExceptionAn error occurred while sending the message.
TimedOutExceptionA timeout occurred while waiting for a response from the server.
AuthenticationExceptionAn authentication failure was received from the server.
UnknownExceptionAn unknown failure was received from the server.
BadFilterExceptionThe specified filter is not valid or has a syntax error.
BadRegexTopicExceptionThe specified topic contains an invalid regex.
MessageStream AMPS::Client::bookmarkSubscribe ( const std::string &  topic_,
long  timeout_,
const std::string &  bookmark_,
const std::string &  filter_ = "",
const std::string &  options_ = "",
const std::string &  subId_ = "" 
)
inline

Subscribe to a topic using a bookmark.

Initiates a bookmark subscription (transaction log replay) to a topic on the server, returning a MessageStream to iterate over.

Parameters
topic_The topic, or regular expression topic, to subscribe to.
timeout_The time to wait, in milliseconds, for the receive thread to consume a processed ack for this command. 0 indicates no timeout.
bookmark_Bookmark to supply with this subscription. This can be a bookmark within the journal file, or one of the Special Bookmark Values.
filter_Optional filter expression for this subscription.
options_Optional options to supply with this subscription.
subId_Optional subscription Id to use for this subscription.
Returns
A MessageStream to iterate over.
Exceptions
DisconnectedExceptionThe Client is no longer connected to a server.
ConnectionExceptionAn error occurred while sending the message.
TimedOutExceptionA timeout occurred while waiting for a response from the server.
AuthenticationExceptionAn authentication failure was received from the server.
UnknownExceptionAn unknown failure was received from the server.
BadFilterExceptionThe specified filter is not valid or has a syntax error.
BadRegexTopicExceptionThe specified topic contains an invalid regex.
MessageStream AMPS::Client::bookmarkSubscribe ( const char *  topic_,
long  timeout_,
const std::string &  bookmark_,
const std::string &  filter_ = "",
const std::string &  options_ = "",
const std::string &  subId_ = "" 
)
inline

Subscribe to a topic using a bookmark.

Initiates a bookmark subscription (transaction log replay) to a topic on the server, returning a MessageStream to iterate over.

Parameters
topic_The topic, or regular expression topic, to subscribe to.
timeout_The time to wait, in milliseconds, for the receive thread to consume a processed ack for this command. 0 indicates no timeout.
bookmark_Bookmark to supply with this subscription. This can be a bookmark within the journal file, or one of the Special Bookmark Values.
filter_Optional filter expression for this subscription.
options_Optional options to supply with this subscription.
subId_Optional subscription Id to use for this subscription.
Returns
A MessageStream to iterate over.
Exceptions
DisconnectedExceptionThe Client is no longer connected to a server.
ConnectionExceptionAn error occurred while sending the message.
TimedOutExceptionA timeout occurred while waiting for a response from the server.
AuthenticationExceptionAn authentication failure was received from the server.
UnknownExceptionAn unknown failure was received from the server.
BadFilterExceptionThe specified filter is not valid or has a syntax error.
BadRegexTopicExceptionThe specified topic contains an invalid regex.
void AMPS::Client::connect ( const std::string &  uri)
inline

Connect to an AMPS server.

Connects to the AMPS server specified by the uri parameter.

Parameters
uriThe URI of the desired AMPS server, with the format transport://user:password@host:port/protocol, for example, tcp://localhost:9007/amps.

The elements in the URI string are as follows:

  • transport – the network transport used for the connection
  • user(optional) the userId used to authenticate the connection
  • password(optional) the password used to authenticate the connection
  • host – the hostname or IP address of the host where AMPS is running
  • port – the port to connect to
  • protocol – the protocol used for the connection
Exceptions
InvalidURIExceptionThe URI passed in is invalid.
ConnectionRefusedExceptionThe connection could not be established.
static size_t AMPS::Client::convertVersionToNumber ( const std::string &  version_)
inlinestatic

Converts a string version, such as "3.8.1.5" into the same numeric form used internally and returned by getServerVersion.

This can be used to do comparisons such as client.getServerVersion() >= "3.8" Conversion works with any string that starts with a number, and will assume 0 for any portions of the version not present. So "4" will return 4000000, equivalent to "4.0.0.0"

Parameters
version_The version string to convert.
Returns
The size_t equivalent of the version.
static size_t AMPS::Client::convertVersionToNumber ( const char *  data_,
size_t  len_ 
)
inlinestatic

Converts a string version, such as "3.8.1.5" into the same numeric form used internally and returned by getServerVersion.

This can be used to do comparisons such as client.getServerVersion() >= "3.8" Conversion works with any string that starts with a number, and will assume 0 for any portions of the version not present. So "4" will return 4000000, equivalent to "4.0.0.0"

Parameters
data_The pointer the start of the character data to convert.
len_The length of the character data to convert.
Returns
The size_t equivalent of the version.
amps_uint64_t AMPS::Client::deltaPublish ( const std::string &  topic_,
const std::string &  data_ 
)
inline

Publish the changed fields of a message to an AMPS topic.

Send a delta_publish to the server, indicating that only changed fields are included in the data portion of this message. If the client has a publish store set, then the client will store the message before forwarding the message to AMPS. This method does not wait for a response from the AMPS server. To detect failure, install a failed write handler. If a DisconnectException occurs, the message is still stored in the publish store. See the AMPS User Guide and the Developer Guide for details on how delta messaging works.

Parameters
topic_The topic to publish on.
data_The data corresponding to the fields you'd like to change.
Exceptions
DisconnectedExceptionThe Client is no longer connected to a server.
ConnectionExceptionAn error occurred while sending the message.
Returns
The sequence number of the message when this client uses a publish store, 0 otherwise.
amps_uint64_t AMPS::Client::deltaPublish ( const char *  topic_,
size_t  topicLength_,
const char *  data_,
size_t  dataLength_ 
)
inline

Publish the changed fields of a message to an AMPS topic.

Send a delta_publish to the server, indicating that only changed fields are included in the data portion of this message. If the client has a publish store set, then the client will store the message before forwarding the message to AMPS. This method does not wait for a response from the AMPS server. To detect failure, install a failed write handler. If a DisconnectException occurs, the message is still stored in the publish store. See the AMPS User Guide and the Developer Guide for details on how delta messaging works.

Parameters
topic_The topic to publish on.
topicLength_The length, in bytes, of the topic string.
data_The data corresponding to the fields you'd like to change.
dataLength_The length, in bytes, of the data.
Exceptions
DisconnectedExceptionThe Client is no longer connected to a server.
ConnectionExceptionAn error occurred while sending the message.
Returns
The sequence number of the message when this client uses a publish store, 0 otherwise.
amps_uint64_t AMPS::Client::deltaPublish ( const std::string &  topic_,
const std::string &  data_,
unsigned long  expiration_ 
)
inline

Publish the changed fields of a message to an AMPS topic.

Send a delta_publish to the server, indicating that only changed fields are included in the data portion of this message. If the client has a publish store set, then the client will store the message before forwarding the message to AMPS. This method does not wait for a response from the AMPS server. To detect failure, install a failed write handler. If a DisconnectException occurs, the message is still stored in the publish store. See the AMPS User Guide and the Developer Guide for details on how delta messaging works.

Parameters
topic_The topic to publish on.
data_The data corresponding to the fields you'd like to change.
expiration_The number of seconds until the message expires.
Exceptions
DisconnectedExceptionThe Client is no longer connected to a server.
ConnectionExceptionAn error occurred while sending the message.
Returns
The sequence number of the message when this client uses a publish store, 0 otherwise.
amps_uint64_t AMPS::Client::deltaPublish ( const char *  topic_,
size_t  topicLength_,
const char *  data_,
size_t  dataLength_,
unsigned long  expiration_ 
)
inline

Publish the changed fields of a message to an AMPS topic.

Send a delta_publish to the server, indicating that only changed fields are included in the data portion of this message. If the client has a publish store set, then the client will store the message before forwarding the message to AMPS. This method does not wait for a response from the AMPS server. To detect failure, install a failed write handler. If a DisconnectException occurs, the message is still stored in the publish store. See the AMPS User Guide and the Developer Guide for details on how delta messaging works.

Parameters
topic_The topic to publish on.
topicLength_The length, in bytes, of the topic string.
data_The data corresponding to the fields you'd like to change.
dataLength_The length, in bytes, of the data.
expiration_The number of seconds until the message expires.
Exceptions
DisconnectedExceptionThe Client is no longer connected to a server.
ConnectionExceptionAn error occurred while sending the message.
Returns
The sequence number of the message when this client uses a publish store, 0 otherwise.
std::string AMPS::Client::deltaSubscribe ( const MessageHandler messageHandler_,
const std::string &  topic_,
long  timeout_,
const std::string &  filter_ = "",
const std::string &  options_ = "",
const std::string &  subId_ = "" 
)
inline

Delta Subscribe to a topic.

Initiates a delta subscription to a topic on the server, using the provided messageHandler_ to receive messages for the subscription. The messageHandler_ is called on the client receive thread: see the Developer Guide for details on the threading considerations.

Parameters
messageHandler_The function to be invoked when messages for this topic arrive.
topic_The topic, or regular expression topic, to subscribe to.
timeout_The time to wait, in milliseconds, for the receive thread to consume a processed ack for this command. 0 indicates no timeout.
filter_Optional filter expression for this subscription.
options_Optional options to supply with this subscription.
subId_Optional subscription id to use with this subscription.
Returns
A std::string with a unique identifier for this subscription.
MessageStream AMPS::Client::deltaSubscribe ( const std::string &  topic_,
long  timeout_,
const std::string &  filter_ = "",
const std::string &  options_ = "",
const std::string &  subId_ = "" 
)
inline

Delta Subscribe to a topic.

Initiates a delta subscription to a topic on the server, returning a MessageStream.

Parameters
topic_The topic, or regular expression topic, to subscribe to.
timeout_The time to wait, in milliseconds, for the receive thread to consume a processed ack for this command. 0 indicates no timeout.
filter_Optional filter expression for this subscription.
options_Optional options to supply with this subscription.
subId_Optional subscription id to use with this subscription.
Returns
A MessageStream to iterate over.
MessageStream AMPS::Client::deltaSubscribe ( const char *  topic_,
long  timeout_,
const std::string &  filter_ = "",
const std::string &  options_ = "",
const std::string &  subId_ = "" 
)
inline

Delta Subscribe to a topic.

Initiates a delta subscription to a topic on the server, returning a MessageStream.

Parameters
topic_The topic, or regular expression topic, to subscribe to.
timeout_The time to wait, in milliseconds, for the receive thread to consume a processed ack for this command. 0 indicates no timeout.
filter_Optional filter expression for this subscription.
options_Optional options to supply with this subscription.
subId_Optional subscription id to use with this subscription.
Returns
A MessageStream to iterate over.
void AMPS::Client::disconnect ( )
inline

Disconnect from an AMPS server.

Disconnects from the currently-connected AMPS server.

static const char* AMPS::Client::EPOCH ( )
inlinestatic

Convenience method for returning the special value to start a subscription at the beginning of the transaction log.

Returns
Always returns AMPS_BOOKMARK_EPOCH
MessageStream AMPS::Client::execute ( Command command_)
inline

Execute the provided command and return messages received in response in a MessageStream.

This method creates a message based on the provided Command, sends the message to AMPS, and receives the results. AMPS sends the message and receives the results on a background thread. That thread populates the MessageStream returned by this method.

Parameters
command_The Command object containing the command to send to AMPS
Returns
A MessageStream that provides messages received in response to the command
std::string AMPS::Client::executeAsync ( Command command_,
MessageHandler  handler_ 
)
inline

Execute the provided command and, once AMPS acknowledges the command, process messages in response to the command on the client receive thread by invoking the provided handler.

This method creates a message based on the provided Command, sends the message to AMPS, and invokes the provided MessageHandler to process messages returned in response to the command. Rather than providing messages on the calling thread, the Client runs the MessageHandler directly on the client receive thread.

When the provided MessageHandler is valid (that is, the object contains a function to be called), this method blocks until AMPS acknowledges that the command has been processed. The results of the command after that acknowledgement are provided to the MessageHandler.

This method adds the subscription to any SubscriptionManager present on the Client, to allow the subscription to be re-entered after failover (the HAClient disconnect handler does this automatically).

Parameters
command_The Command object containing the command to send to AMPS
handler_The MessageHandler to invoke to process messages received
Returns
the command ID for the command
std::string AMPS::Client::executeAsyncNoResubscribe ( Command command_,
MessageHandler  handler_ 
)
inline

Execute the provided command and, once AMPS acknowledges the command, process messages in response to the command on the client receive thread by invoking the provided handler.

This method creates a message based on the provided Command, sends the message to AMPS, and invokes the provided MessageHandler to process messages returned in response to the command. Rather than providing messages on the calling thread, the Client runs the MessageHandler directly on the client receive thread.

When the provided MessageHandler is valid (that is, the object contains a function to be called), this method blocks until AMPS acknowledges that the command has been processed. The results of the command after that acknowledgement are provided to the MessageHandler.

When the provided Command is a form of subscribe, the subscription will not be placed into any SubscriptionMananger which may be in place. If a disconnect occurs, the subscription will need to be placed again.

While the provided Command doesn't have to be a form of subscribe, the main purpose of this function is to place a subscription that doesn't restart after a disconnect.

Parameters
command_The Command object containing the command to send to AMPS
handler_The MessageHandler to invoke to process messages received
Returns
the command ID for the command
void AMPS::Client::flushAcks ( void  )
inline

Sends any queued message queue ack messages to the server immediately.

If your application uses a message queue and has set an ack batch size, it can be helpful to call this method before the application exits.

unsigned AMPS::Client::getAckBatchSize ( void  ) const
inline

Returns the value of the queue ack batch size setting.

Returns
The current ack batch size (default: 0)
int AMPS::Client::getAckTimeout ( void  ) const
inline

Returns the current value of the message queue ack timeout setting – that is, the amount of time after which queue messages will be acknowledged even if the ack batch is not full.

Returns
the current ack timeout, in milliseconds.
bool AMPS::Client::getAutoAck ( void  ) const
inline

Returns the value of the queue auto-ack setting.

Returns
true if auto-ack is enabled, false otherwise.
BookmarkStore AMPS::Client::getBookmarkStore ( )
inline

Get the bookmark store being used by the client.

Returns
The bookmark store being used.
virtual ConnectionInfo AMPS::Client::getConnectionInfo ( ) const
inlinevirtual

Get the connection information for the current connection.

Returns
A ConnectionInfo object with the information describing the the current connection.

Reimplemented in AMPS::HAClient.

unsigned AMPS::Client::getDefaultMaxDepth ( void  ) const
inline

Returns the default max depth for returned MessageStream objects.

Returns
The max depth in use, where 0 is unlimited.
DisconnectHandler AMPS::Client::getDisconnectHandler ( void  ) const
inline

Returns the callback function that is invoked when a disconnect occurs.

Returns
The current DisconnectHandler callback to be invoked for a disconnect.
MessageHandler AMPS::Client::getDuplicateMessageHandler ( void  )
inline

Returns the callback function that is invoked when a duplicate message is detected.

Notice that in a failover scenario, a duplicate message does not generally indicate an error. Instead, during failover, a duplicate message most often indicates that the publisher established a connection to a failover server before the original server had finished replicating messages to the failover server, but that the replicated messages arrived before the publisher republished the messages.

Returns
The current MessageHandler callback to be invoked for duplicate messages.
const ExceptionListener& AMPS::Client::getExceptionListener ( void  ) const
inline

Returns the exception listener set on this Client.

Returns
The ExceptionListener associated with self.
FailedWriteHandler* AMPS::Client::getFailedWriteHandler ( )
inline

Get the handler that is invoked to report on failed writes.

Returns
The handler that is invoked for failed writes.
amps_handle AMPS::Client::getHandle ( void  )
inline

Returns the underlying amps_handle for this client, to be used with amps_client_* functions from the C api.

Returns
The amps_handle associated with self.
const std::string& AMPS::Client::getLogonCorrelationData ( ) const
inline

Returns the currently set logon correlation data for the client.

Returns
The data that will be sent with the logon.
const std::string& AMPS::Client::getName ( ) const
inline

Returns the name of this client passed in the constructor.

Returns
The client name passed via the constructor.
const std::string& AMPS::Client::getNameHash ( ) const
inline

Returns the name hash string of this client as generated by the server and returned when the client logged on.

Returns
The client name hash from the server after logon.
const amps_uint64_t AMPS::Client::getNameHashValue ( ) const
inline

Returns the numeric name hash of this client as generated by the server and returned when the client logged on.

Returns
The client name hash from the server after logon.
Store AMPS::Client::getPublishStore ( )
inline

Get the publish store used by the client.

Returns
The publish store being used.
size_t AMPS::Client::getServerVersion ( ) const
inline

Returns the server version retrieved during logon.

If the client has not logged on or is connected to a server whose version is less than 3.8.0.0 this function will return 0. The version uses 2 digits each for major, minor, maintenance & hotfix i.e., 3.8.1.4 will return 3080104 Versions of AMPS prior to 3.8.0.0 do not return the server version to the client.

Returns
The version of the server as a size_t.
VersionInfo AMPS::Client::getServerVersionInfo ( ) const
inline

Returns the server version retrieved during logon.

If the client has not logged on or is connected to a server whose version is less than 3.8.0.0 this function will return a default version. Versions of AMPS prior to 3.8.0.0 do not return the server version to the client.

Returns
The version of the server in a VersionInfo.
SubscriptionManager* AMPS::Client::getSubscriptionManager ( )
inline

Get the subscription manager being used by the client.

Returns
The subscription manager being used.
const std::string& AMPS::Client::getURI ( ) const
inline

Returns the last URI this client is connected to.

Returns
The URI passed in to connect.
std::string AMPS::Client::logon ( int  timeout_ = 0,
Authenticator authenticator_ = DefaultAuthenticator::instance(),
const char *  options_ = NULL 
)
inline

Logon to the server, providing the client name, credentials (if available), and client information (such as client version and connection message type).

Authentication is supplied using the provided authenticator (by default, the DefaultAuthenticator, which simply provides the password in the connection string if one is present).

Parameters
timeout_The time to wait, in milliseconds, for an acknowledgement. (Default: 0 – wait forever.)
authenticator_The custom authenticator to use in the logon process.
options_The options to pass in with the logon command such as "conflation_interval=10ms".
Exceptions
DisconnectedExceptionThe Client is no longer connected to a server.
ConnectionExceptionAn error occurred while sending the message.
TimedOutExceptionA timeout occurred while waiting for a response from the server.
AuthenticationExceptionAn authentication failure was received from the server.
PublishStoreGapExceptionThe server is not up to date on all messages previously published by this Client and a gap of missing messages would be created by publishing new messages here.
UnknownExceptionAn unknown failure was received from the server.
NameInUseExceptionThe specified client name is already in use on the server, and will not allow this connection to replace that connection (for example, if the two connections use different credentials)
std::string AMPS::Client::logon ( const char *  options_,
int  timeout_ = 0 
)
inline

Logon to the server, providing the client name, credentials (if available) client information (such as client version and connection message type), and the specified options.

Authentication is supplied using the DefaultAuthenticator (which simply provides the password in the connection string if one is present).

Parameters
options_The options to pass in with the logon command such as "conflation_interval=10ms".
timeout_The time to wait, in milliseconds, for an acknowledgement. (Default: 0 – wait forever.)
Exceptions
DisconnectedExceptionThe Client is no longer connected to a server.
ConnectionExceptionAn error occurred while sending the message.
TimedOutExceptionA timeout occurred while waiting for a response from the server.
AuthenticationExceptionAn authentication failure was received from the server.
PublishStoreGapExceptionThe server is not up to date on all messages previously published by this Client and a gap of missing messages would be created by publishing new messages here.
UnknownExceptionAn unknown failure was received from the server.
NameInUseExceptionThe specified client name is already in use on the server, and will not allow this connection to replace that connection (for example, if the two connections use different credentials)
std::string AMPS::Client::logon ( const std::string &  options_,
int  timeout_ = 0 
)
inline

Logon to the server, providing the client name, credentials (if available) client information (such as client version and connection message type), and the specified options.

Authentication is supplied using the DefaultAuthenticator (which simply provides the password in the connection string if one is present).

Parameters
options_The options to pass in with the logon command such as "conflation_interval=10ms".
timeout_The time to wait, in milliseconds, for an acknowledgement. (Default: 0 – wait forever.)
Exceptions
DisconnectedExceptionThe Client is no longer connected to a server.
ConnectionExceptionAn error occurred while sending the message.
TimedOutExceptionA timeout occurred while waiting for a response from the server.
AuthenticationExceptionAn authentication failure was received from the server.
PublishStoreGapExceptionThe server is not up to date on all messages previously published by this Client and a gap of missing messages would be created by publishing new messages here.
UnknownExceptionAn unknown failure was received from the server.
NameInUseExceptionThe specified client name is already in use on the server, and will not allow this connection to replace that connection (for example, if the two connections use different credentials)
static const char* AMPS::Client::MOST_RECENT ( )
inlinestatic

Convenience method for returning the special value to start a subscription at a recovery point based on the information that the configured BookmarkStore (if one is set) has for the subscription.

Returns
Always returns AMPS_BOOKMARK_RECENT
static const char* AMPS::Client::NOW ( )
inlinestatic

Convenience method for returning the special value to start a subscription at the end of the transaction log.

/returns Always returns AMPS_BOOKMARK_NOW

amps_uint64_t AMPS::Client::publish ( const std::string &  topic_,
const std::string &  data_ 
)
inline

Publish a message to an AMPS topic, returning the sequence number assigned by the publish store if one is present on the client.

Notice that this function does not wait for acknowledgement from the AMPS server. To detect failure, set a failed write handler on the client. If the client has a publish store set, then the client will automatically store the message before forwarding the message to AMPS. If a DisconnectException occurs, the message is still stored in the publish store and can be forwarded when the connection is re-established.

Parameters
topic_The topic to publish on.
data_The data to include in the message.
Exceptions
DisconnectedExceptionThe Client is not connected to a server; the program needs to call connect().
ConnectionExceptionAn error occurred while sending the message.
Returns
The sequence number of the message when this client uses a publish store, 0 otherwise.
amps_uint64_t AMPS::Client::publish ( const char *  topic_,
size_t  topicLength_,
const char *  data_,
size_t  dataLength_ 
)
inline

Publish a message to an AMPS topic, returning the sequence number assigned by the publish store if one is present on the client.

Notice that this function does not wait for acknowledgement from the AMPS server. To detect failure, set a failed write handler on the client. If the client has a publish store set, then the client will automatically store the message before forwarding the message to AMPS. If a DisconnectException occurs, the message is still stored in the publish store and can be forwarded when the connection is re-established.

Parameters
topic_The topic to publish on.
topicLength_The length, in bytes, of the topic string.
data_The data to include in the message.
dataLength_The length, in bytes, of the data.
Exceptions
DisconnectedExceptionThe Client is not connected to a server; the program needs to call connect().
ConnectionExceptionAn error occurred while sending the message.
Returns
The sequence number of the message when this client uses a publish store, 0 otherwise.
amps_uint64_t AMPS::Client::publish ( const std::string &  topic_,
const std::string &  data_,
unsigned long  expiration_ 
)
inline

Publish a message to an AMPS topic, returning the sequence number assigned by the publish store (if a publish store is present on the client).

Notice that this function does not wait for acknowledgement from the AMPS server. To detect failure, set a failed write handler on the client. If the client has a publish store set, then the client will automatically store the message before forwarding the message to AMPS. If a DisconnectException occurs, the message is still stored in the publish store and can be forwarded when the connection is re-established.

Parameters
topic_The topic to publish on.
data_The data to include in the message.
expiration_The number of seconds after which the message should expire
Exceptions
DisconnectedExceptionThe Client is not connected to a server; the program needs to call connect().
ConnectionExceptionAn error occurred while sending the message.
Returns
The sequence number of the message when this client uses a publish store, 0 otherwise.
amps_uint64_t AMPS::Client::publish ( const char *  topic_,
size_t  topicLength_,
const char *  data_,
size_t  dataLength_,
unsigned long  expiration_ 
)
inline

Publish a message to an AMPS topic, returning the sequence number assigned by the publish store if one is present on the client.

Notice that this function does not wait for acknowledgement from the AMPS server. To detect failure, set a failed write handler on the client. If the client has a publish store set, then the client will automatically store the message before forwarding the message to AMPS. If a DisconnectException occurs, the message is still stored in the publish store and can be forwarded when the connection is re-established.

Parameters
topic_The topic to publish on.
topicLength_The length, in bytes, of the topic string.
data_The data to include in the message.
dataLength_The length, in bytes, of the data.
expiration_The number of seconds after which the message should expire
Exceptions
DisconnectedExceptionThe Client is not connected to a server; the program needs to call connect().
ConnectionExceptionAn error occurred while sending the message.
Returns
The sequence number of the message when this client uses a publish store, 0 otherwise.
void AMPS::Client::publishFlush ( long  timeout_ = 0,
unsigned  ackType_ = Message::AckType::Processed 
)
inline

Ensure that AMPS messages are sent and have been processed by the AMPS server.

When a client is configured with a publish store, this function call blocks until all messages that are in the publish store at the point of the call have been acknowledged by AMPS. Otherwise, the client sends a message to AMPS and waits for that message to be processed. The mechanism that the client uses to do this depends on the version of AMPS that the client is connected to. When the client is connected to a server that implements the flush command, the client issues that command and waits for an acknowledgement. For older versions of AMPS, the client sends a publish to a dummy topic.

This function blocks until one of the following is true:

  • The client has a publish store, and no messages that were in the publish store at the time the function was called are unacknowledged by AMPS.
  • The client does not have a publish store, and the results of the command to the server have been received (indicating that the server has processed all previous commands).
  • The specified timeout expires (in this case, the function throws an exception). This function is most useful when the application reaches a point at which it is acceptable to block to ensure that messages are delivered to the AMPS server. For example, an application might call publishFlush before exiting.

One thing to note is that if AMPS is unavailable (HA Client), publishFlush needs to wait for a connection to come back up which may look like it's hanging.

Parameters
timeout_The maximum milliseconds to wait for flush to complete. Default is 0, which is no maximum (wait until the command completes).
ackType_Wait for Message::AckType::Processed or Message::AckType::Persisted ack. Default is Message::AckType::Processed, but Message::AckType::Persisted ensures all previous messages were persisted.
Exceptions
DisconnectedExceptionThe Client is no longer connected to a server.
CommandExceptionAn ack type other than Processed or Persisted was requested.
ConnectionExceptionAn error occurred while sending the message.
TimedOutExceptionThe command did not complete in the specified time.
void AMPS::Client::removeConnectionStateListener ( ConnectionStateListener listener)
inline

Attempts to remove listener from self's set of ConnectionStateListeners.

Parameters
listenerThe ConnectionStateListener to remove.
bool AMPS::Client::removeMessageHandler ( const Field commandId_)
inline

Removes a MessageHandler for a given ComandId from self.

Parameters
commandId_The CommandId for which to remove the handler.
Returns
True if the handler was removed.
void AMPS::Client::send ( const Message message)
inline

Sends a Message to the connected AMPS server, performing only minimal validation and bypassing client services such as the publish store.

This method is provided for special cases. The Message must be formatted properly with the appropriate fields set for the command you wish to issue. No adjustments are made to the message before sending. Notice that this function bypasses validation of the Message contents, does not record the contents of the Message in the publish store(if one is present) and so on. In general, applications use a Command object with the execute or executeAsync functions rather than using this function.

Parameters
messageThe Message to send to the AMPS server.
Exceptions
DisconnectedExceptionThe Client is no longer connected to a server.
ConnectionExceptionAn error occurred while sending the message.
std::string AMPS::Client::send ( const MessageHandler messageHandler,
Message message,
int  timeout = 0 
)
inline

Sends a Message to the connected AMPS server, performing only minimal validation and bypassing client services such as the publish store.

This method is provided for special cases. The Message must be formatted properly with the appropriate fields set for the command you wish to issue. No adjustments are made to the message before sending. Notice that this function bypasses validation of the Message contents, does not record the contents of the Message in the publish store(if one is present) and so on. In general, applications use a Command object with the execute or executeAsync functions rather than using this function.

Parameters
messageHandlerThe MessageHandler to associate with this message.
messageThe message to send to the AMPS server.
timeoutWhen submitting a command, the time to wait for the receive thread to consume a processed ack, in milliseconds. 0 indicates no timeout.
Exceptions
DisconnectedExceptionThe Client is no longer connected to a server.
ConnectionExceptionAn error occurred while sending the message.
TimedOutExceptionA timeout occurred while waiting for a response from the server.
AuthenticationExceptionAn authentication failure was received from the server.
UnknownExceptionAn unknown failure was received from the server.
NameInUseExceptionFor a logon command, the specified client name is already in use on the server, and will not allow this connection to replace that connection (for example, if the two connections use different credentials)
BadFilterExceptionThe specified filter is not valid or has a syntax error.
BadRegexTopicExceptionThe specified topic contains an invalid regex.
InvalidTopicExceptionThe specified topic may not be used with this command.
SubscriptionAlreadyExistsExceptionThis ID already exists as a subscription.
void AMPS::Client::setAckBatchSize ( const unsigned  ackBatchSize_)
inline

Sets the queue ack batch size setting.

When set to a value greater than 1, message queue success ack messages are not sent immediately, but are batched together for increased performance.

Parameters
ackBatchSize_The batch size to use.
void AMPS::Client::setAckTimeout ( const int  ackTimeout_)
inline

Sets the message queue ack timeout value.

When set, queued message queue ack messages are sent when the oldest pending ack for a message queue has exceeded this timeout.

Parameters
ackTimeout_The ack timeout value, in milliseconds. Throws a UsageException if setting to 0 and the ack batch size > 1.
Exceptions
UsageExceptionIf ackTimeout_ is 0 but the ack batch size > 1.
void AMPS::Client::setAutoAck ( bool  isAutoAckEnabled_)
inline

Sets the queue auto-ack setting on this client.

If true, message queue messages are automatically acknowledged upon successful return from your message handler. If your message handler throws an exception, the message is returned to the queue.

Parameters
isAutoAckEnabled_The new value of the auto-ack setting.
void AMPS::Client::setBookmarkStore ( const BookmarkStore bookmarkStore_)
inline

Set the bookmark store to be used by the client.

The bookmark store is used for recovery when an AMPS client requests a replay from the transaction log. The guarantees provided by the bookmark store depend on the implementation chosen. See the Developer Guide for details.

Parameters
bookmarkStore_The bookmark store to use.
Exceptions
AlreadyConnectedExceptionIf called while the client is already connected
void AMPS::Client::setDefaultMaxDepth ( unsigned  maxDepth_)
inline

Sets a default max depth on all subsequently created MessageStream objects.

Parameters
maxDepth_The new max depth to use.
void AMPS::Client::setDisconnectHandler ( const DisconnectHandler disconnectHandler)
inline

Sets the function to be called when the client is unintentionally disconnected.

Sets a callback function that is invoked when a disconnect is detected. For automatically reconnecting a client, 60East recommends using the HAClient rather than creating a disconnect handler. Notice that the reconnect, republish, and resubscribe behavior for the HAClient class is provided through the disconnect handler, so setting a disconnect handler for the HAClient will completely replace the high-availability behavior of that client.

Parameters
disconnectHandlerThe callback to be invoked on disconnect.
void AMPS::Client::setDuplicateMessageHandler ( const MessageHandler duplicateMessageHandler_)
inline

Sets a callback function that is invoked when a duplicate message is detected.

Parameters
duplicateMessageHandler_The callback to be invoked.
void AMPS::Client::setExceptionListener ( const std::shared_ptr< const ExceptionListener > &  pListener_)
inline

Sets the exception listener for exceptions that are not thrown back to the user (for example, exceptions that are thrown from a MessageHandler running on the client receive thread.) 60East strongly recommends setting this callback if an application uses asynchronous message processing (that is, provides message handler callbacks).

Parameters
pListener_A shared pointer to the ExceptionListener that should be notified.
void AMPS::Client::setExceptionListener ( const ExceptionListener listener_)
inline
Deprecated:
Use setExceptionListener(std::shared_ptr<const ExceptionListener>&) Sets the exception listener for exceptions that are not thrown back to the user (for example, exceptions that are thrown from a MessageHandler running on the client receive thread.) 60East strongly recommends setting this callback if an application uses asynchronous message processing (that is, provides message handler callbacks).
Parameters
listener_The exception listener to be used
void AMPS::Client::setFailedWriteHandler ( FailedWriteHandler handler_)
inline

Set the handler that is invoked to report when a publish fails, for example if the publisher is not entitled, if AMPS attempts to parse the message and the parse fails, and so on.

The Client takes ownership of the pointer provided. In order to receive failure acknowledgements, the publish commands must request an acknowledgement from AMPS. The AMPS client automatically requests these acknowledgements when a publish store is present.

Parameters
handler_The handler to invoke for failed writes.
void AMPS::Client::setGlobalCommandTypeMessageHandler ( const std::string &  command_,
const MessageHandler handler_ 
)
inline

Sets a handler for all messages of a particular type, or for messages that would be delivered to a particular special handler: currently supported types are "heartbeat", "ack", "duplicate", and "lastchance".

When a handler for a specific message type is set, the AMPS client calls that handler for all messages of that type in addition to any other handlers called. Use this function in cases where an application needs to precisely monitor messages that would otherwise be handled by the AMPS Client infrastructure or the last chance message handler. A global command type message handler is rarely needed, but can sometimes be helpful for test harnesses, advanced troubleshooting, or similar situations where it is important to monitor messages that are normally handled by the client.

The handler_ provided is called on the client receive thread. See the Developer Guide for threading considerations.

Parameters
command_A string specifying the type of command to handle.
handler_The message handler to call.
Exceptions
CommandExceptionAn unknown or unsupported message type was provided.
void AMPS::Client::setGlobalCommandTypeMessageHandler ( const Message::Command::Type  command_,
const MessageHandler handler_ 
)
inline

Sets a handler for all messages of a particular type: currently supported types are heartbeat messages and ack messages.

When a handler for a specific message type is set, the AMPS client calls that handler for all messages of that type in addition to any other handlers called.

Use this function in cases where an application needs to precisely monitor messages that would otherwise be handled by the AMPS Client infrastructure or the last chance message handler. A global command type message handler is rarely needed, but can sometimes be helpful for test harnesses, advanced troubleshooting, or similar situations where it is important to monitor messages that are normally handled by the client.

The handler_ provided is called on the client receive thread. See the Developer Guide for threading considerations.

Parameters
command_The type of command to handle.
handler_The message handler to call.
Exceptions
CommandExceptionAn unknown or unsupported message type was provided.
void AMPS::Client::setHeartbeat ( unsigned  heartbeatTime_,
unsigned  readTimeout_ 
)
inline

Requests heartbeating with the AMPS server.

The client will provide a heartbeat to the server on the specified interval, and requests that the server provide a heartbeat to the client the specified interval.

If the client does not receive a message (either a heartbeat or another the client will consider the connection to have failed and close the connection. Likewise, if the server does not receive a message from the client for the specified interval (plus a grace period), the server will consider the connection or client to have failed and close the connection. Notice that operations that block the client receive thread (that is, blocking in a Handler or Listener) will prevent the client from sending or responding to heartbeats while the thread is blocked. Any invocation of a Handler or Listener that takes longer than the heartbeat interval set may cause the server to consider the client to have failed, and disconnect the client.

Parameters
heartbeatTime_The time (seconds) to request the server heartbeat.
readTimeout_The time (seconds) to block waiting for a read from the socket before timing out the read and checking the heartbeat interval.
void AMPS::Client::setHeartbeat ( unsigned  heartbeatTime_)
inline

Requests heartbeating with the AMPS server.

The client will provide a heartbeat to the server on the specified interval, and requests that the server provide a heartbeat to the client the specified interval.

If the client does not receive a message (either a heartbeat or another the client will consider the connection to have failed and close the connection. Likewise, if the server does not receive a message from the client for the specified interval (plus a grace period), the server will consider the connection or client to have failed and close the connection. Notice that operations that block the client receive thread (that is, blocking in a Handler or Listener) will prevent the client from sending or responding to heartbeats while the thread is blocked. Any invocation of a Handler or Listener that takes longer than the heartbeat interval set may cause the server to consider the client to have failed, and disconnect the client.

Parameters
heartbeatTime_The time (seconds) to request the server heartbeat.
void AMPS::Client::setLastChanceMessageHandler ( const AMPS::MessageHandler messageHandler)
inline

Sets the message handler called when no other handler matches.

Parameters
messageHandlerThe message handler to invoke when no other handler matches.
void AMPS::Client::setLogonCorrelationData ( const std::string &  logonCorrelationData_)
inline

Sets the logon correlation data for the client.

The data should be in base64 characters. It is not escaped when sent to the server and the server does not interpret the data. The data can provide some extra information about the client that is logging into the server that may not be available from just the client name and user id.

Parameters
logonCorrelationData_The data to be sent with the logon.
void AMPS::Client::setName ( const std::string &  name)
inline

Sets the name of this client, assuming no name was provided previously.

This may only be called on client objects with no name.

Parameters
nameName for the client. This name is used for duplicate message detection and should be unique. AMPS does not enforce specific restrictions on the character set used, however some protocols (for example, XML) may not allow specific characters. 60East recommends that the client name be meaningful, short, human readable, and avoids using control characters, newline characters, or square brackets.
Exceptions
UsageExceptionAn attempt was made to set a name on a client, but the client already has a name.
void AMPS::Client::setPublishStore ( const Store publishStore_)
inline

Set the publish store to be used by the client.

A publish store is used to help ensure that messages reach AMPS, even in cases of connection failure or application failure. The client automatically stores appropriate messages in the publish store when using the named commands (such as publish) or the execute or executeAsync functions. With the HAClient, that class's default disconnect handler automatically republishes messages from the publish store as needed when a connection is made.

The precise guarantees provided by a publish store depend on the publish store implementation. See the Developer Guide for details on choosing a publish store.

When a publish store is set on a client, 60East strongly recommends providing a FailedWriteHandler so that the application is notified of any failures in publishing messages.

Parameters
publishStore_The publish store to use.
Exceptions
AlreadyConnectedExceptionIf called while the client is already connected
void AMPS::Client::setRetryOnDisconnect ( bool  isRetryOnDisconnect_)
inline

Enables or disables automatic retry of a command to AMPS after a reconnect.

This behavior is enabled by default. NOTE: Clients using a publish store will have all publish messages sent, regardless of this setting. Also, Clients with a subscription manager, including all HAClients, will have all subscribe calls placed.

Parameters
isRetryOnDisconnect_false will disable this behavior.
void AMPS::Client::setSubscriptionManager ( SubscriptionManager subscriptionManager_)
inline

Set the subscription manager to be used by the client.

It is the disconnect handler's responsibility to use this subscription manager to re-establish subscriptions. By default, an HAClient will set a MemorySubscriptionManager and use this subscription manager during reconnection.

Parameters
subscriptionManager_The subscription manager to use.
void AMPS::Client::setThreadCreatedCallback ( amps_thread_created_callback  callback_,
void *  userData_ 
)
inline

Sets a callback function on the transport that is called when a new thread is created to receive data from the server.

The callback should only be used if setting specific thread attributes, such as the thread name.

Parameters
callback_The function to call first in the new thread.
userData_Any data that should be passed to the function.
void AMPS::Client::setTransportFilterFunction ( amps_transport_filter_function  filter_,
void *  userData_ 
)
inline

Sets a filter function on the transport that is called with all raw data sent or received.

Parameters
filter_The amps_transport_filter_function to call.
userData_Any data that should be passed to the function.
void AMPS::Client::setUnhandledMessageHandler ( const AMPS::MessageHandler messageHandler)
inline
Deprecated:
. Use setLastChanceMessageHandler
MessageStream AMPS::Client::sow ( const char *  topic_,
const std::string &  filter_ = "",
const std::string &  orderBy_ = "",
const std::string &  bookmark_ = "",
int  batchSize_ = DEFAULT_BATCH_SIZE,
int  topN_ = DEFAULT_TOP_N,
const std::string &  options_ = "",
long  timeout_ = DEFAULT_COMMAND_TIMEOUT 
)
inline

Query the SOW cache of a topic.

Queries the SOW cache of a topic on the AMPS server, returning a MessageStream to iterate over.

Parameters
topic_The topic, or regular expression topic, to subscribe to.
filter_Optional filter expression for this subscription.
orderBy_Optional orderBy to have records ordered by server.
bookmark_Optional bookmark for historical query. Bookmarks can be one of the Special Bookmark Values, the bookmark assigned to a specific message, or a timestamp of the format YYYYmmddTHHMMSS, as described in the AMPS User's Guide.
batchSize_The number of records the server should pack into each message: typically applications use DEFAULT_BATCH_SIZE unless the messages are much smaller than the MTU for the network or are very large
topN_The maximum number of records the server will return (default is all that match).
options_An 'or'ing of options for the command.
timeout_The time to wait, in milliseconds, for the receive thread to consume a processed ack for this command. 0 indicates no timeout.
Returns
A MessageStream to iterate over.
Exceptions
DisconnectedExceptionThe Client is no longer connected to a server.
ConnectionExceptionAn error occurred while sending the message.
TimedOutExceptionA timeout occurred while waiting for a response from the server.
AuthenticationExceptionAn authentication failure was received from the server.
UnknownExceptionAn unknown failure was received from the server.
BadFilterExceptionThe specified filter is not valid or has a syntax error.
BadRegexTopicExceptionThe specified topic contains an invalid regex.
InvalidTopicExceptionThe specified topic may not be used with this command.
SubscriptionAlreadyExistsExceptionThis ID already exists as a subscription.
MessageStream AMPS::Client::sowAndDeltaSubscribe ( const char *  topic_,
const std::string &  filter_ = "",
const std::string &  orderBy_ = "",
int  batchSize_ = DEFAULT_BATCH_SIZE,
int  topN_ = DEFAULT_TOP_N,
const std::string &  options_ = "",
long  timeout_ = DEFAULT_COMMAND_TIMEOUT 
)
inline

Query the SOW cache of a topic and initiates a new delta subscription on it.

Queries the SOW cache of a topic on the AMPS server, and simultaneously begins a new delta subscription on it. Returns a MessageStream to iterate over.

Parameters
topic_The topic, or regular expression topic, to subscribe to.
filter_Optional filter expression for this subscription.
orderBy_Optional orderBy to have records ordered by server.
batchSize_The number of records the server should pack into each message.
topN_The maximum number of records the server will return (default is all that match).
options_An 'or'ing of options for the command.
timeout_The time to wait, in milliseconds, for the receive thread to consume a processed ack for this command. 0 indicates no timeout.
Returns
A MessageStream to iterate over.
Exceptions
DisconnectedExceptionThe Client is no longer connected to a server.
ConnectionExceptionAn error occurred while sending the message.
TimedOutExceptionA timeout occurred while waiting for a response from the server.
AuthenticationExceptionAn authentication failure was received from the server.
UnknownExceptionAn unknown failure was received from the server.
BadFilterExceptionThe specified filter is not valid or has a syntax error.
BadRegexTopicExceptionThe specified topic contains an invalid regex.
InvalidTopicExceptionThe specified topic may not be used with this command.
SubscriptionAlreadyExistsExceptionThis ID already exists as a subscription.
MessageStream AMPS::Client::sowAndSubscribe ( const char *  topic_,
const std::string &  filter_ = "",
const std::string &  orderBy_ = "",
const std::string &  bookmark_ = "",
int  batchSize_ = DEFAULT_BATCH_SIZE,
int  topN_ = DEFAULT_TOP_N,
const std::string &  options_ = "",
long  timeout_ = DEFAULT_COMMAND_TIMEOUT 
)
inline

Query the SOW cache of a topic and initiates a new subscription on it.

Queries the SOW cache of a topic on the AMPS server, and simultaneously begins a new subscription, returning a MessageStream to iterate over.

Parameters
topic_The topic, or regular expression topic, to subscribe to.
filter_Optional filter expression for this subscription.
orderBy_Optional orderBy to have records ordered by server.
bookmark_Optional bookmark for historical query. Bookmarks can be one of the Special Bookmark Values, the bookmark assigned to a specific message, or a timestamp of the format YYYYmmddTHHMMSS, as described in the AMPS User's Guide.
batchSize_The number of records the server should pack into each message.
topN_The maximum number of records the server will return (default is all that match).
options_An 'or'ing of options for the command.
timeout_The time to wait, in milliseconds, for the receive thread to consume a processed ack for this command. 0 indicates no timeout.
Returns
A MessageStream to iterate over.
Exceptions
DisconnectedExceptionThe Client is no longer connected to a server.
ConnectionExceptionAn error occurred while sending the message.
TimedOutExceptionA timeout occurred while waiting for a response from the server.
AuthenticationExceptionAn authentication failure was received from the server.
UnknownExceptionAn unknown failure was received from the server.
BadFilterExceptionThe specified filter is not valid or has a syntax error.
BadRegexTopicExceptionThe specified topic contains an invalid regex.
InvalidTopicExceptionThe specified topic may not be used with this command.
SubscriptionAlreadyExistsExceptionThis ID already exists as a subscription.
void AMPS::Client::startTimer ( void  )
inline
Deprecated:
As of AMPS server 5.3.2.0 start_timer is not valid.

Sends a message to AMPS requesting that AMPS start a server-side timer. The application can later call stopTimer() to stop the timer and request a message with the results.

std::string AMPS::Client::stopTimer ( const MessageHandler messageHandler)
inline
Deprecated:
As of AMPS server 5.3.2.0 stop_timer is not valid.

Sends a message to AMPS requesting that AMPS stop the previously started timer. The provided MessageHandler will receive an acknowledgement with information about the timer.

Parameters
messageHandlerThe function to be invoked when the acknowledgement message arrives
See also
startTimer()
std::string AMPS::Client::subscribe ( const MessageHandler messageHandler_,
const std::string &  topic_,
long  timeout_ = 0,
const std::string &  filter_ = "",
const std::string &  options_ = "",
const std::string &  subId_ = "" 
)
inline

Subscribe to a topic.

Initiates a subscription to a topic on the server, using the provided messageHandler_ to receive messages for the subscription. The messageHandler_ is called on the client receive thread: see the Developer Guide for details on the threading considerations.

Parameters
messageHandler_The function to be invoked when messages for this topic arrive.
topic_The topic, or regular expression topic, to subscribe to.
timeout_The time to wait, in milliseconds, for the receive thread to consume a processed ack for this command. 0 indicates no timeout.
filter_Optional filter expression for this subscription.
options_Optional options to supply with this subscription.
subId_Optional subscription id to use with this subscription.
Returns
A std::string with a unique identifier for this subscription.
Exceptions
DisconnectedExceptionThe Client is no longer connected to a server.
ConnectionExceptionAn error occurred while sending the message.
TimedOutExceptionA timeout occurred while waiting for a response from the server.
AuthenticationExceptionAn authentication failure was received from the server.
UnknownExceptionAn unknown failure was received from the server.
BadFilterExceptionThe specified filter is not valid or has a syntax error.
BadRegexTopicExceptionThe specified topic contains an invalid regex.
MessageStream AMPS::Client::subscribe ( const std::string &  topic_,
long  timeout_ = 0,
const std::string &  filter_ = "",
const std::string &  options_ = "",
const std::string &  subId_ = "" 
)
inline

Subscribe to a topic.

Initiates a subscription to a topic on the server, returning a MessageStream to iterate over.

Parameters
topic_The topic, or regular expression topic, to subscribe to.
timeout_The time to wait, in milliseconds, for the receive thread to consume a processed ack for this command. 0 indicates no timeout.
filter_Optional filter expression for this subscription.
options_Optional options to supply with this subscription.
subId_Optional subscription id to use with this subscription.
Returns
A MessageStream to iterate over.
Exceptions
DisconnectedExceptionThe Client is no longer connected to a server.
ConnectionExceptionAn error occurred while sending the message.
TimedOutExceptionA timeout occurred while waiting for a response from the server.
AuthenticationExceptionAn authentication failure was received from the server.
UnknownExceptionAn unknown failure was received from the server.
BadFilterExceptionThe specified filter is not valid or has a syntax error.
BadRegexTopicExceptionThe specified topic contains an invalid regex.
MessageStream AMPS::Client::subscribe ( const char *  topic_,
long  timeout_ = 0,
const std::string &  filter_ = "",
const std::string &  options_ = "",
const std::string &  subId_ = "" 
)
inline

Subscribe to a topic.

Initiates a subscription to a topic on the server, returning a MessageStream to iterate over.

Parameters
topic_The topic, or regular expression topic, to subscribe to.
timeout_The time to wait, in milliseconds, for the receive thread to consume a processed ack for this command. 0 indicates no timeout.
filter_Optional filter expression for this subscription.
options_Optional options to supply with this subscription.
subId_Optional subscription id to use with this subscription.
Returns
A MessageStream to iterate over.
Exceptions
DisconnectedExceptionThe Client is no longer connected to a server.
ConnectionExceptionAn error occurred while sending the message.
TimedOutExceptionA timeout occurred while waiting for a response from the server.
AuthenticationExceptionAn authentication failure was received from the server.
UnknownExceptionAn unknown failure was received from the server.
BadFilterExceptionThe specified filter is not valid or has a syntax error.
BadRegexTopicExceptionThe specified topic contains an invalid regex.
void AMPS::Client::unsubscribe ( const std::string &  commandId)
inline

Unsubscribe from a topic.

Stops a subscription already placed on this Client.

Parameters
commandIdThe unique identifier for this subscription.
Exceptions
DisconnectedExceptionThe Client is no longer connected to a server.
ConnectionExceptionAn error occurred while sending the message.
TimedOutExceptionA timeout occurred while waiting for a response from the server.
AuthenticationExceptionAn authentication failure was received from the server.
UnknownExceptionAn unknown failure was received from the server.
void AMPS::Client::unsubscribe ( void  )
inline

Unsubscribe from all topics.

Stops all active subscriptions on this client.

Exceptions
DisconnectedExceptionThe Client is no longer connected to a server.
ConnectionExceptionAn error occurred while sending the message.
TimedOutExceptionA timeout occurred while waiting for a response from the server.
AuthenticationExceptionAn authentication failure was received from the server.
UnknownExceptionAn unknown failure was received from the server.

The documentation for this class was generated from the following file: