AMPS C/C++ Client Class Reference AMPS C/C++ Client Version 5.3.5.1

Public Member Functions | Static Public Member Functions | List of all members
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...
void | addHttpPreflightHeader (const std::string &header_)
| Adds a given HTTP header line to the end of the headers that will be sent for the HTTP GET Upgrade request. More...
void | addHttpPreflightHeader (const std::string &key_, const std::string &value_)
| Adds a given key/value pair as an HTTP header line as "key: value" to the end of the headers that will be sent for the HTTP GET Upgrade request. More...
void | clearHttpPreflightHeaders ()
| Clears all previously set HTTP header lines.
template<class T >
void | setHttpPreflightHeaders (const T &headers_)
| Sets the given HTTP header lines to be sent for the HTTP GET Upgrade request. 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...
virtual void | setDisconnectHandler (const DisconnectHandler &disconnectHandler)
DisconnectHandler | getDisconnectHandler (void) const
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...
SubscriptionManager * | getSubscriptionManager ()
| 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...
FailedWriteHandler * | getFailedWriteHandler ()
| 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 ExceptionListener & | getExceptionListener (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...
void | setPublishBatching (size_t batchSize_, amps_uint64_t batchTimeoutMillis_)
| Sets the max bytes to cache and max timeout in millis for caching delta_publish and publish commands. 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

## ◆ Client()

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

Constructs a new client with a given client name.

Parameters

  clientName | Name 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

## ◆ ack() [1/3]

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

## ◆ ack() [2/3]

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

## ◆ ack() [3/3]

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

## ◆ addConnectionStateListener()

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

  listener | The ConnectionStateListener to invoke.

## ◆ addHttpPreflightHeader() [1/2]

void AMPS::Client::addHttpPreflightHeader | ( | const std::string & | header_ | ) |
| inline

Adds a given HTTP header line to the end of the headers that will be sent for the HTTP GET Upgrade request.

Parameters

  header_ | The full header line.

## ◆ addHttpPreflightHeader() [2/2]

void AMPS::Client::addHttpPreflightHeader | ( | const std::string & | key_,
|  | const std::string & | value_
| ) |  |
| inline

Adds a given key/value pair as an HTTP header line as "key: value" to the end of the headers that will be sent for the HTTP GET Upgrade request.

Parameters

  key_ | The key.
  value_ | The value.

## ◆ addMessageHandler() [1/2]

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.

## ◆ addMessageHandler() [2/2]

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.

## ◆ BOOKMARK_EPOCH()

static const char* AMPS::Client::BOOKMARK_EPOCH | ( |  | ) |
| inline static

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

Returns
  Always returns AMPS_BOOKMARK_EPOCH

## ◆ BOOKMARK_MOST_RECENT()

static const char* AMPS::Client::BOOKMARK_MOST_RECENT | ( |  | ) |
| inline static

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

## ◆ BOOKMARK_NOW()

static const char* AMPS::Client::BOOKMARK_NOW | ( |  | ) |
| inline static

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

/returns Always returns AMPS_BOOKMARK_NOW

## ◆ BOOKMARK_RECENT()

static const char* AMPS::Client::BOOKMARK_RECENT | ( |  | ) |
| inline static

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

## ◆ bookmarkSubscribe() [1/3]

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

  DisconnectedException | The Client is no longer connected to a server.
  ConnectionException | An error occurred while sending the message.
  TimedOutException | A timeout occurred while waiting for a response from the server.
  AuthenticationException | An authentication failure was received from the server.
  UnknownException | An unknown failure was received from the server.
  BadFilterException | The specified filter is not valid or has a syntax error.
  BadRegexTopicException | The specified topic contains an invalid regex.

## ◆ bookmarkSubscribe() [2/3]

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

  DisconnectedException | The Client is no longer connected to a server.
  ConnectionException | An error occurred while sending the message.
  TimedOutException | A timeout occurred while waiting for a response from the server.
  AuthenticationException | An authentication failure was received from the server.
  UnknownException | An unknown failure was received from the server.
  BadFilterException | The specified filter is not valid or has a syntax error.
  BadRegexTopicException | The specified topic contains an invalid regex.

## ◆ bookmarkSubscribe() [3/3]

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

  DisconnectedException | The Client is no longer connected to a server.
  ConnectionException | An error occurred while sending the message.
  TimedOutException | A timeout occurred while waiting for a response from the server.
  AuthenticationException | An authentication failure was received from the server.
  UnknownException | An unknown failure was received from the server.
  BadFilterException | The specified filter is not valid or has a syntax error.
  BadRegexTopicException | The specified topic contains an invalid regex.

## ◆ connect()

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

  uri | The 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

  InvalidURIException | The URI passed in is invalid.
  ConnectionRefusedException | The connection could not be established.

## ◆ convertVersionToNumber() [1/2]

static size_t AMPS::Client::convertVersionToNumber | ( | const char * | data_,
|  | size_t | len_
| ) |  |
| inline static

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.

## ◆ convertVersionToNumber() [2/2]

static size_t AMPS::Client::convertVersionToNumber | ( | const std::string & | version_ | ) |
| inline static

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.

## ◆ deltaPublish() [1/4]

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

  DisconnectedException | The Client is no longer connected to a server.
  ConnectionException | An error occurred while sending the message.

Returns
  The sequence number of the message when this client uses a publish store, 0 otherwise.

## ◆ deltaPublish() [2/4]

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

  DisconnectedException | The Client is no longer connected to a server.
  ConnectionException | An error occurred while sending the message.

Returns
  The sequence number of the message when this client uses a publish store, 0 otherwise.

## ◆ deltaPublish() [3/4]

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

  DisconnectedException | The Client is no longer connected to a server.
  ConnectionException | An error occurred while sending the message.

Returns
  The sequence number of the message when this client uses a publish store, 0 otherwise.

## ◆ deltaPublish() [4/4]

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

  DisconnectedException | The Client is no longer connected to a server.
  ConnectionException | An error occurred while sending the message.

Returns
  The sequence number of the message when this client uses a publish store, 0 otherwise.

## ◆ deltaSubscribe() [1/3]

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.

## ◆ deltaSubscribe() [2/3]

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.

## ◆ deltaSubscribe() [3/3]

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.

## ◆ disconnect()

void AMPS::Client::disconnect | ( |  | ) |
| inline

Disconnect from an AMPS server.

Disconnects from the currently-connected AMPS server.

## ◆ EPOCH()

static const char* AMPS::Client::EPOCH | ( |  | ) |
| inline static

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

Returns
  Always returns AMPS_BOOKMARK_EPOCH

## ◆ execute()

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

## ◆ executeAsync()

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

## ◆ executeAsyncNoResubscribe()

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

## ◆ flushAcks()

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.

## ◆ getAckBatchSize()

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)

## ◆ getAckTimeout()

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.

## ◆ getAutoAck()

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.

## ◆ getBookmarkStore()

BookmarkStore AMPS::Client::getBookmarkStore | ( |  | ) |
| inline

Get the bookmark store being used by the client.

Returns
  The bookmark store being used.

## ◆ getConnectionInfo()

virtual ConnectionInfo AMPS::Client::getConnectionInfo | ( |  | ) | const
| inline virtual

Get the connection information for the current connection.

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

Reimplemented in AMPS::HAClient.

## ◆ getDefaultMaxDepth()

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.

## ◆ getDisconnectHandler()

DisconnectHandler AMPS::Client::getDisconnectHandler | ( | void |  | ) | const
| inline

Deprecated:
  This function will be removed in future version.

Use an HAClient for automatic reconnection. Use a ConnectionStateListener to monitor the state of your connection. Returns the callback function that is invoked when a disconnect occurs.

Returns
  The current DisconnectHandler callback to be invoked for a disconnect.

## ◆ getDuplicateMessageHandler()

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.

## ◆ getExceptionListener()

const ExceptionListener& AMPS::Client::getExceptionListener | ( | void |  | ) | const
| inline

Returns the exception listener set on this Client.

Returns
  The ExceptionListener associated with self.

## ◆ getFailedWriteHandler()

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.

## ◆ getHandle()

amps_handle AMPS::Client::getHandle | ( |  | ) |
| 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.

## ◆ getLogonCorrelationData()

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.

## ◆ getName()

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.

## ◆ getNameHash()

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.

## ◆ getNameHashValue()

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.

## ◆ getPublishStore()

Store AMPS::Client::getPublishStore | ( |  | ) |
| inline

Get the publish store used by the client.

Returns
  The publish store being used.

## ◆ getServerVersion()

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.

## ◆ getServerVersionInfo()

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.

## ◆ getSubscriptionManager()

SubscriptionManager* AMPS::Client::getSubscriptionManager | ( |  | ) |
| inline

Get the subscription manager being used by the client.

Returns
  The subscription manager being used.

## ◆ getURI()

const std::string& AMPS::Client::getURI | ( |  | ) | const
| inline

Returns the last URI this client is connected to.

Returns
  The URI passed in to connect.

## ◆ logon() [1/3]

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

  DisconnectedException | The Client is no longer connected to a server.
  ConnectionException | An error occurred while sending the message.
  TimedOutException | A timeout occurred while waiting for a response from the server.
  AuthenticationException | An authentication failure was received from the server.
  PublishStoreGapException | The 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.
  UnknownException | An unknown failure was received from the server.
  NameInUseException | 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)

## ◆ logon() [2/3]

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

  DisconnectedException | The Client is no longer connected to a server.
  ConnectionException | An error occurred while sending the message.
  TimedOutException | A timeout occurred while waiting for a response from the server.
  AuthenticationException | An authentication failure was received from the server.
  PublishStoreGapException | The 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.
  UnknownException | An unknown failure was received from the server.
  NameInUseException | 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)

## ◆ logon() [3/3]

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

  DisconnectedException | The Client is no longer connected to a server.
  ConnectionException | An error occurred while sending the message.
  TimedOutException | A timeout occurred while waiting for a response from the server.
  AuthenticationException | An authentication failure was received from the server.
  PublishStoreGapException | The 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.
  UnknownException | An unknown failure was received from the server.
  NameInUseException | 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)

## ◆ MOST_RECENT()

static const char* AMPS::Client::MOST_RECENT | ( |  | ) |
| inline static

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

## ◆ NOW()

static const char* AMPS::Client::NOW | ( |  | ) |
| inline static

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

/returns Always returns AMPS_BOOKMARK_NOW

## ◆ publish() [1/4]

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

  DisconnectedException | The Client is not connected to a server; the program needs to call connect().
  ConnectionException | An error occurred while sending the message.

Returns
  The sequence number of the message when this client uses a publish store, 0 otherwise.

## ◆ publish() [2/4]

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

  DisconnectedException | The Client is not connected to a server; the program needs to call connect().
  ConnectionException | An error occurred while sending the message.

Returns
  The sequence number of the message when this client uses a publish store, 0 otherwise.

## ◆ publish() [3/4]

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

  DisconnectedException | The Client is not connected to a server; the program needs to call connect().
  ConnectionException | An error occurred while sending the message.

Returns
  The sequence number of the message when this client uses a publish store, 0 otherwise.

## ◆ publish() [4/4]

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

  DisconnectedException | The Client is not connected to a server; the program needs to call connect().
  ConnectionException | An error occurred while sending the message.

Returns
  The sequence number of the message when this client uses a publish store, 0 otherwise.

## ◆ publishFlush()

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

  DisconnectedException | The Client is no longer connected to a server.
  CommandException | An ack type other than Processed or Persisted was requested.
  ConnectionException | An error occurred while sending the message.
  TimedOutException | The command did not complete in the specified time.

## ◆ removeConnectionStateListener()

void AMPS::Client::removeConnectionStateListener | ( | ConnectionStateListener * | listener | ) |
| inline

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

Parameters

  listener | The ConnectionStateListener to remove.

## ◆ removeMessageHandler()

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.

## ◆ send() [1/2]

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

  message | The Message to send to the AMPS server.

Exceptions

  DisconnectedException | The Client is no longer connected to a server.
  ConnectionException | An error occurred while sending the message.

## ◆ send() [2/2]

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

  messageHandler | The MessageHandler to associate with this message.
  message | The message to send to the AMPS server.
  timeout | When submitting a command, the time to wait for the receive thread to consume a processed ack, in milliseconds. 0 indicates no timeout.

Exceptions

  DisconnectedException | The Client is no longer connected to a server.
  ConnectionException | An error occurred while sending the message.
  TimedOutException | A timeout occurred while waiting for a response from the server.
  AuthenticationException | An authentication failure was received from the server.
  UnknownException | An unknown failure was received from the server.
  NameInUseException | For 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)
  BadFilterException | The specified filter is not valid or has a syntax error.
  BadRegexTopicException | The specified topic contains an invalid regex.
  InvalidTopicException | The specified topic may not be used with this command.
  SubscriptionAlreadyExistsException | This ID already exists as a subscription.

## ◆ setAckBatchSize()

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.

## ◆ setAckTimeout()

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

  UsageException | If ackTimeout_ is 0 but the ack batch size > 1.

## ◆ setAutoAck()

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.

## ◆ setBookmarkStore()

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

  AlreadyConnectedException | If called while the client is already connected

## ◆ setDefaultMaxDepth()

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.

## ◆ setDisconnectHandler()

virtual void AMPS::Client::setDisconnectHandler | ( | const DisconnectHandler & | disconnectHandler | ) |
| inline virtual

Deprecated:
  This function will be removed in future version.

Use an HAClient for automatic reconnection. Use a ConnectionStateListener to monitor the state of your connection. 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

  disconnectHandler | The callback to be invoked on disconnect.

Reimplemented in AMPS::HAClient.

## ◆ setDuplicateMessageHandler()

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.

## ◆ setExceptionListener() [1/2]

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

## ◆ setExceptionListener() [2/2]

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.

## ◆ setFailedWriteHandler()

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.

## ◆ setGlobalCommandTypeMessageHandler() [1/2]

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

  CommandException | An unknown or unsupported message type was provided.

## ◆ setGlobalCommandTypeMessageHandler() [2/2]

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

  CommandException | An unknown or unsupported message type was provided.

## ◆ setHeartbeat() [1/2]

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.

## ◆ setHeartbeat() [2/2]

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.

## ◆ setHttpPreflightHeaders()

template<class T >

void AMPS::Client::setHttpPreflightHeaders | ( | const T & | headers_ | ) |
| inline

Sets the given HTTP header lines to be sent for the HTTP GET Upgrade request.

Clears any previously set headers.

Parameters

  headers_ | The full list header lines.

## ◆ setLastChanceMessageHandler()

void AMPS::Client::setLastChanceMessageHandler | ( | const AMPS::MessageHandler & | messageHandler | ) |
| inline

Sets the message handler called when no other handler matches.

Parameters

  messageHandler | The message handler to invoke when no other handler matches.

## ◆ setLogonCorrelationData()

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.

## ◆ setName()

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

  name | Name 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

  UsageException | An attempt was made to set a name on a client, but the client already has a name.

## ◆ setPublishBatching()

void AMPS::Client::setPublishBatching | ( | size_t | batchSize_,
|  | amps_uint64_t | batchTimeoutMillis_
| ) |  |
| inline

Sets the max bytes to cache and max timeout in millis for caching delta_publish and publish commands.

Parameters

  batchSize_ | The max number of bytes to cache before sending.
  batchTimeoutMillis_ | The max ms between sending batches.

## ◆ setPublishStore()

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

  AlreadyConnectedException | If called while the client is already connected

## ◆ setRetryOnDisconnect()

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.

## ◆ setSubscriptionManager()

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.

## ◆ setThreadCreatedCallback()

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.

## ◆ setTransportFilterFunction()

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.

## ◆ setUnhandledMessageHandler()

void AMPS::Client::setUnhandledMessageHandler | ( | const AMPS::MessageHandler & | messageHandler | ) |
| inline

Deprecated:
  . Use setLastChanceMessageHandler

## ◆ sow()

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

  DisconnectedException | The Client is no longer connected to a server.
  ConnectionException | An error occurred while sending the message.
  TimedOutException | A timeout occurred while waiting for a response from the server.
  AuthenticationException | An authentication failure was received from the server.
  UnknownException | An unknown failure was received from the server.
  BadFilterException | The specified filter is not valid or has a syntax error.
  BadRegexTopicException | The specified topic contains an invalid regex.
  InvalidTopicException | The specified topic may not be used with this command.
  SubscriptionAlreadyExistsException | This ID already exists as a subscription.

## ◆ sowAndDeltaSubscribe()

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

  DisconnectedException | The Client is no longer connected to a server.
  ConnectionException | An error occurred while sending the message.
  TimedOutException | A timeout occurred while waiting for a response from the server.
  AuthenticationException | An authentication failure was received from the server.
  UnknownException | An unknown failure was received from the server.
  BadFilterException | The specified filter is not valid or has a syntax error.
  BadRegexTopicException | The specified topic contains an invalid regex.
  InvalidTopicException | The specified topic may not be used with this command.
  SubscriptionAlreadyExistsException | This ID already exists as a subscription.

## ◆ sowAndSubscribe()

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

  DisconnectedException | The Client is no longer connected to a server.
  ConnectionException | An error occurred while sending the message.
  TimedOutException | A timeout occurred while waiting for a response from the server.
  AuthenticationException | An authentication failure was received from the server.
  UnknownException | An unknown failure was received from the server.
  BadFilterException | The specified filter is not valid or has a syntax error.
  BadRegexTopicException | The specified topic contains an invalid regex.
  InvalidTopicException | The specified topic may not be used with this command.
  SubscriptionAlreadyExistsException | This ID already exists as a subscription.

## ◆ startTimer()

void AMPS::Client::startTimer | ( |  | ) |
| 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.

## ◆ stopTimer()

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

  messageHandler | The function to be invoked when the acknowledgement message arrives

See also
  startTimer()

## ◆ subscribe() [1/3]

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

  DisconnectedException | The Client is no longer connected to a server.
  ConnectionException | An error occurred while sending the message.
  TimedOutException | A timeout occurred while waiting for a response from the server.
  AuthenticationException | An authentication failure was received from the server.
  UnknownException | An unknown failure was received from the server.
  BadFilterException | The specified filter is not valid or has a syntax error.
  BadRegexTopicException | The specified topic contains an invalid regex.

## ◆ subscribe() [2/3]

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

  DisconnectedException | The Client is no longer connected to a server.
  ConnectionException | An error occurred while sending the message.
  TimedOutException | A timeout occurred while waiting for a response from the server.
  AuthenticationException | An authentication failure was received from the server.
  UnknownException | An unknown failure was received from the server.
  BadFilterException | The specified filter is not valid or has a syntax error.
  BadRegexTopicException | The specified topic contains an invalid regex.

## ◆ subscribe() [3/3]

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

  DisconnectedException | The Client is no longer connected to a server.
  ConnectionException | An error occurred while sending the message.
  TimedOutException | A timeout occurred while waiting for a response from the server.
  AuthenticationException | An authentication failure was received from the server.
  UnknownException | An unknown failure was received from the server.
  BadFilterException | The specified filter is not valid or has a syntax error.
  BadRegexTopicException | The specified topic contains an invalid regex.

## ◆ unsubscribe() [1/2]

void AMPS::Client::unsubscribe | ( |  | ) |
| inline

Unsubscribe from all topics.

Stops all active subscriptions on this client.

Exceptions

  DisconnectedException | The Client is no longer connected to a server.
  ConnectionException | An error occurred while sending the message.
  TimedOutException | A timeout occurred while waiting for a response from the server.
  AuthenticationException | An authentication failure was received from the server.
  UnknownException | An unknown failure was received from the server.

## ◆ unsubscribe() [2/2]

void AMPS::Client::unsubscribe | ( | const std::string & | commandId | ) |
| inline

Unsubscribe from a topic.

Stops a subscription already placed on this Client.

Parameters

  commandId | The unique identifier for this subscription.

Exceptions

  DisconnectedException | The Client is no longer connected to a server.
  ConnectionException | An error occurred while sending the message.
  TimedOutException | A timeout occurred while waiting for a response from the server.
  AuthenticationException | An authentication failure was received from the server.
  UnknownException | An unknown failure was received from the server.

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

- include/amps/ampsplusplus.hpp