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

#include <ampsplusplus.hpp>

Inheritance diagram for AMPS::Client:

Public Member Functions
	Client (const std::string &clientName="")
	Constructs a new client with a given client name. More...

void	setName (const std::string &name)
	Sets the name of this client, assuming no name was provided previously. More...

const std::string &	getName () const
	Returns the name of this client passed in the constructor. More...

const std::string &	getNameHash () const
	Returns the name hash string of this client as generated by the server and returned when the client logged on. More...

const amps_uint64_t	getNameHashValue () const
	Returns the numeric name hash of this client as generated by the server and returned when the client logged on. More...

void	setLogonCorrelationData (const std::string &logonCorrelationData_)
	Sets the logon correlation data for the client. More...

const std::string &	getLogonCorrelationData () const
	Returns the currently set logon correlation data for the client. More...

size_t	getServerVersion () const
	Returns the server version retrieved during logon. More...

VersionInfo	getServerVersionInfo () const
	Returns the server version retrieved during logon. More...

const std::string &	getURI () const
	Returns the last URI this client is connected to. More...

void	connect (const std::string &uri)
	Connect to an AMPS server. More...

void	disconnect ()
	Disconnect from an AMPS server. More...

void	send (const Message &message)
	Sends a Message to the connected AMPS server, performing only minimal validation and bypassing client services such as the publish store. More...

void	addMessageHandler (const Field &commandId_, const AMPS::MessageHandler &messageHandler_, unsigned requestedAcks_, bool isSubscribe_)
	Adds a MessageHandler to be invoked for Messages with the given CommandId as their command id, sub id, or query id. More...

void	addMessageHandler (const Field &commandId_, const AMPS::MessageHandler &messageHandler_, unsigned requestedAcks_, Message::Command::Type commandType_)
	Adds a MessageHandler to be invoked for Messages with the given CommandId as their command id, sub id, or query id. More...

bool	removeMessageHandler (const Field &commandId_)
	Removes a MessageHandler for a given ComandId from self. More...

std::string	send (const MessageHandler &messageHandler, Message &message, int timeout=0)
	Sends a Message to the connected AMPS server, performing only minimal validation and bypassing client services such as the publish store. More...

void	setDisconnectHandler (const DisconnectHandler &disconnectHandler)
	Sets the function to be called when the client is unintentionally disconnected. More...

DisconnectHandler	getDisconnectHandler (void) const
	Returns the callback function that is invoked when a disconnect occurs. More...

virtual ConnectionInfo	getConnectionInfo () const
	Get the connection information for the current connection. More...

void	setBookmarkStore (const BookmarkStore &bookmarkStore_)
	Set the bookmark store to be used by the client. More...

BookmarkStore	getBookmarkStore ()
	Get the bookmark store being used by the client. More...

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...

Static Public Member Functions
static size_t	convertVersionToNumber (const std::string &version_)
	Converts a string version, such as "3.8.1.5" into the same numeric form used internally and returned by getServerVersion. More...

static size_t	convertVersionToNumber (const char *data_, size_t len_)
	Converts a string version, such as "3.8.1.5" into the same numeric form used internally and returned by getServerVersion. More...

static const char *	BOOKMARK_NOW ()
	Convenience method for returning the special value to start a subscription at the end of the transaction log. More...

static const char *	NOW ()
	Convenience method for returning the special value to start a subscription at the end of the transaction log. More...

static const char *	BOOKMARK_EPOCH ()
	Convenience method for returning the special value to start a subscription at the beginning of the transaction log. More...

static const char *	EPOCH ()
	Convenience method for returning the special value to start a subscription at the beginning of the transaction log. More...

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

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

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

Detailed Description

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

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

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

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

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

Constructor & Destructor Documentation

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

inline

Constructs a new client with a given client name.

Parameters

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

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

inline

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

Parameters

topic_	The topic to acknowledge
bookmark_	The bookmark of the message to acknowledge
options_	The options string for the ack, such as cancel

void AMPS::Client::ack	(	Message &	message_,
		const char *	options_ = `NULL`
	)

inline

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

Parameters

message_	The message to acknowledge
options_	The options string for the ack, such as cancel

void AMPS::Client::ack	(	const std::string &	topic_,
		const std::string &	bookmark_,
		const char *	options_ = `NULL`
	)

inline

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

Parameters

topic_	The message queue topic to acknowledge
bookmark_	The bookmark to acknowledge
options_	The options string for the ack, such as cancel

void AMPS::Client::addConnectionStateListener ( ConnectionStateListener * listener )

inline

Adds a ConnectionStateListener to self's set of listeners.

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

Parameters

listener The ConnectionStateListener to invoke.

void AMPS::Client::addMessageHandler	(	const Field &	commandId_,
		const AMPS::MessageHandler &	messageHandler_,
		unsigned	requestedAcks_,
		bool	isSubscribe_
	)

inline

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

Parameters

commandId_	The command, query, or subid used to invoke the handler.
messageHandler_	The message handler to route to
requestedAcks_	The actual acks requested from amps for this command
isSubscribe_	True is the handler is for an ongoing subscription.

void AMPS::Client::addMessageHandler	(	const Field &	commandId_,
		const AMPS::MessageHandler &	messageHandler_,
		unsigned	requestedAcks_,
		Message::Command::Type	commandType_
	)

inline

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

Parameters

commandId_	The command, query, or subid used to invoke the handler.
messageHandler_	The message handler to route to
requestedAcks_	The actual acks requested from amps for this command
commandType_	The command type of the message.

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

inlinestatic

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

Returns: Always returns AMPS_BOOKMARK_EPOCH

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

inlinestatic

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

Returns: Always returns AMPS_BOOKMARK_RECENT

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

inlinestatic

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

/returns Always returns AMPS_BOOKMARK_NOW

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

inlinestatic

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

Returns: Always returns AMPS_BOOKMARK_RECENT

std::string AMPS::Client::bookmarkSubscribe	(	const MessageHandler &	messageHandler_,
		const std::string &	topic_,
		long	timeout_,
		const std::string &	bookmark_,
		const std::string &	filter_ = `""`,
		const std::string &	options_ = `""`,
		const std::string &	subId_ = `""`
	)

inline

Subscribe to a topic using a bookmark.

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

Parameters

messageHandler_	The function to be invoked when messages for this topic arrive.
topic_	The topic, or regular expression topic, to subscribe to.
timeout_	The time to wait, in milliseconds, for the receive thread to consume a processed ack for this command. 0 indicates no timeout.
bookmark_	Bookmark to supply with this subscription. This can be a bookmark within the journal file, or one of the Special Bookmark Values.
filter_	Optional filter expression for this subscription.
options_	Optional options to supply with this subscription.
subId_	Optional subscription Id to use for this subscription. When used with the 'replace' option, this is the subscription to be replaced. With a bookmark store, this is the subscription Id used for recovery. so, when using a persistent bookmark store, provide an explicit subscription Id that is consistent across application restarts.

Returns: A std::string with a unique identifier for this subscription.

Exceptions

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.

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.

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.

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.

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

inlinestatic

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

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

Parameters

version_ The version string to convert.

Returns: The size_t equivalent of the version.

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

inlinestatic

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

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

Parameters

data_	The pointer the start of the character data to convert.
len_	The length of the character data to convert.

Returns: The size_t equivalent of the version.

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

inline

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

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

Parameters

topic_	The topic to publish on.
data_	The data corresponding to the fields you'd like to change.

Exceptions

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.

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.

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.

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.

std::string AMPS::Client::deltaSubscribe	(	const MessageHandler &	messageHandler_,
		const std::string &	topic_,
		long	timeout_,
		const std::string &	filter_ = `""`,
		const std::string &	options_ = `""`,
		const std::string &	subId_ = `""`
	)

inline

Delta Subscribe to a topic.

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

Parameters

messageHandler_	The function to be invoked when messages for this topic arrive.
topic_	The topic, or regular expression topic, to subscribe to.
timeout_	The time to wait, in milliseconds, for the receive thread to consume a processed ack for this command. 0 indicates no timeout.
filter_	Optional filter expression for this subscription.
options_	Optional options to supply with this subscription.
subId_	Optional subscription id to use with this subscription.

Returns: A std::string with a unique identifier for this subscription.

MessageStream AMPS::Client::deltaSubscribe	(	const std::string &	topic_,
		long	timeout_,
		const std::string &	filter_ = `""`,
		const std::string &	options_ = `""`,
		const std::string &	subId_ = `""`
	)

inline

Delta Subscribe to a topic.

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

Parameters

topic_	The topic, or regular expression topic, to subscribe to.
timeout_	The time to wait, in milliseconds, for the receive thread to consume a processed ack for this command. 0 indicates no timeout.
filter_	Optional filter expression for this subscription.
options_	Optional options to supply with this subscription.
subId_	Optional subscription id to use with this subscription.

Returns: A MessageStream to iterate over.

MessageStream AMPS::Client::deltaSubscribe	(	const char *	topic_,
		long	timeout_,
		const std::string &	filter_ = `""`,
		const std::string &	options_ = `""`,
		const std::string &	subId_ = `""`
	)

inline

Delta Subscribe to a topic.

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

Parameters

topic_	The topic, or regular expression topic, to subscribe to.
timeout_	The time to wait, in milliseconds, for the receive thread to consume a processed ack for this command. 0 indicates no timeout.
filter_	Optional filter expression for this subscription.
options_	Optional options to supply with this subscription.
subId_	Optional subscription id to use with this subscription.

Returns: A MessageStream to iterate over.

void AMPS::Client::disconnect ( )

inline

Disconnect from an AMPS server.

Disconnects from the currently-connected AMPS server.

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

inlinestatic

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

Returns: Always returns AMPS_BOOKMARK_EPOCH

MessageStream AMPS::Client::execute ( Command & command_ )

inline

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

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

Parameters

command_ The Command object containing the command to send to AMPS

Returns: A MessageStream that provides messages received in response to the command

std::string AMPS::Client::executeAsync	(	Command &	command_,
		MessageHandler	handler_
	)

inline

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

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

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

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

Parameters

command_	The Command object containing the command to send to AMPS
handler_	The MessageHandler to invoke to process messages received

Returns: the command ID for the command

std::string AMPS::Client::executeAsyncNoResubscribe	(	Command &	command_,
		MessageHandler	handler_
	)

inline

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

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

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

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

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

Parameters

command_	The Command object containing the command to send to AMPS
handler_	The MessageHandler to invoke to process messages received

Returns: the command ID for the command

void AMPS::Client::flushAcks ( void )

inline

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

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

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

inline

Returns the value of the queue ack batch size setting.

Returns: The current ack batch size (default: 0)

int AMPS::Client::getAckTimeout ( void ) const

inline

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

Returns: the current ack timeout, in milliseconds.

bool AMPS::Client::getAutoAck ( void ) const

inline

Returns the value of the queue auto-ack setting.

Returns: true if auto-ack is enabled, false otherwise.

BookmarkStore AMPS::Client::getBookmarkStore ( )

inline

Get the bookmark store being used by the client.

Returns: The bookmark store being used.

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

inlinevirtual

Get the connection information for the current connection.

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

Reimplemented in AMPS::HAClient.

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

inline

Returns the default max depth for returned MessageStream objects.

Returns: The max depth in use, where 0 is unlimited.

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

inline

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

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

MessageHandler AMPS::Client::getDuplicateMessageHandler ( void )

inline

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

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

Returns: The current MessageHandler callback to be invoked for duplicate messages.

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

inline

Returns the exception listener set on this Client.

Returns: The ExceptionListener associated with self.

FailedWriteHandler* AMPS::Client::getFailedWriteHandler ( )

inline

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

Returns: The handler that is invoked for failed writes.

amps_handle AMPS::Client::getHandle ( void )

inline

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

Returns: The amps_handle associated with self.

const std::string& AMPS::Client::getLogonCorrelationData ( ) const

inline

Returns the currently set logon correlation data for the client.

Returns: The data that will be sent with the logon.

const std::string& AMPS::Client::getName ( ) const

inline

Returns the name of this client passed in the constructor.

Returns: The client name passed via the constructor.

const std::string& AMPS::Client::getNameHash ( ) const

inline

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

Returns: The client name hash from the server after logon.

const amps_uint64_t AMPS::Client::getNameHashValue ( ) const

inline

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

Returns: The client name hash from the server after logon.

Store AMPS::Client::getPublishStore ( )

inline

Get the publish store used by the client.

Returns: The publish store being used.

size_t AMPS::Client::getServerVersion ( ) const

inline

Returns the server version retrieved during logon.

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

Returns: The version of the server as a size_t.

VersionInfo AMPS::Client::getServerVersionInfo ( ) const

inline

Returns the server version retrieved during logon.

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

Returns: The version of the server in a VersionInfo.

SubscriptionManager* AMPS::Client::getSubscriptionManager ( )

inline

Get the subscription manager being used by the client.

Returns: The subscription manager being used.

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

inline

Returns the last URI this client is connected to.

Returns: The URI passed in to connect.

std::string AMPS::Client::logon	(	int	timeout_ = `0`,
		Authenticator &	authenticator_ = `DefaultAuthenticator::instance()`,
		const char *	options_ = `NULL`
	)

inline

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

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

Parameters

timeout_	The time to wait, in milliseconds, for an acknowledgement. (Default: 0 – wait forever.)
authenticator_	The custom authenticator to use in the logon process.
options_	The options to pass in with the logon command such as "conflation_interval=10ms".

Exceptions

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)

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)

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)

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

inlinestatic

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

Returns: Always returns AMPS_BOOKMARK_RECENT

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

inlinestatic

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

/returns Always returns AMPS_BOOKMARK_NOW

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

inline

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

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

Parameters

topic_	The topic to publish on.
data_	The data to include in the message.

Exceptions

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.

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.

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.

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.

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.

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

inline

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

Parameters

listener The ConnectionStateListener to remove.

bool AMPS::Client::removeMessageHandler ( const Field & commandId_ )

inline

Removes a MessageHandler for a given ComandId from self.

Parameters

commandId_ The CommandId for which to remove the handler.

Returns: True if the handler was removed.

void AMPS::Client::send ( const Message & message )

inline

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

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

Parameters

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.

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.

void AMPS::Client::setAckBatchSize ( const unsigned ackBatchSize_ )

inline

Sets the queue ack batch size setting.

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

Parameters

ackBatchSize_ The batch size to use.

void AMPS::Client::setAckTimeout ( const int ackTimeout_ )

inline

Sets the message queue ack timeout value.

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

Parameters

ackTimeout_ The ack timeout value, in milliseconds. Throws a UsageException if setting to 0 and the ack batch size > 1.

Exceptions

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

void AMPS::Client::setAutoAck ( bool isAutoAckEnabled_ )

inline

Sets the queue auto-ack setting on this client.

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

Parameters

isAutoAckEnabled_ The new value of the auto-ack setting.

void AMPS::Client::setBookmarkStore ( const BookmarkStore & bookmarkStore_ )

inline

Set the bookmark store to be used by the client.

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

Parameters

bookmarkStore_ The bookmark store to use.

Exceptions

AlreadyConnectedException If called while the client is already connected

void AMPS::Client::setDefaultMaxDepth ( unsigned maxDepth_ )

inline

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

Parameters

maxDepth_ The new max depth to use.

void AMPS::Client::setDisconnectHandler ( const DisconnectHandler & disconnectHandler )

inline

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

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

Parameters

disconnectHandler The callback to be invoked on disconnect.

void AMPS::Client::setDuplicateMessageHandler ( const MessageHandler & duplicateMessageHandler_ )

inline

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

Parameters

duplicateMessageHandler_ The callback to be invoked.

void AMPS::Client::setExceptionListener ( const std::shared_ptr< const ExceptionListener > & pListener_ )

inline

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

Parameters

pListener_ A shared pointer to the ExceptionListener that should be notified.

void AMPS::Client::setExceptionListener ( const ExceptionListener & listener_ )

inline

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

Parameters

listener_ The exception listener to be used

void AMPS::Client::setFailedWriteHandler ( FailedWriteHandler * handler_ )

inline

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

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

Parameters

handler_ The handler to invoke for failed writes.

void AMPS::Client::setGlobalCommandTypeMessageHandler	(	const std::string &	command_,
		const MessageHandler &	handler_
	)

inline

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

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

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

Parameters

command_	A string specifying the type of command to handle.
handler_	The message handler to call.

Exceptions

CommandException An unknown or unsupported message type was provided.

void AMPS::Client::setGlobalCommandTypeMessageHandler	(	const Message::Command::Type	command_,
		const MessageHandler &	handler_
	)

inline

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

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

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

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

Parameters

command_	The type of command to handle.
handler_	The message handler to call.

Exceptions

CommandException An unknown or unsupported message type was provided.

void AMPS::Client::setHeartbeat	(	unsigned	heartbeatTime_,
		unsigned	readTimeout_
	)

inline

Requests heartbeating with the AMPS server.

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

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

Parameters

heartbeatTime_	The time (seconds) to request the server heartbeat.
readTimeout_	The time (seconds) to block waiting for a read from the socket before timing out the read and checking the heartbeat interval.

void AMPS::Client::setHeartbeat ( unsigned heartbeatTime_ )

inline

Requests heartbeating with the AMPS server.

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

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

Parameters

heartbeatTime_ The time (seconds) to request the server heartbeat.

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

inline

Sets the message handler called when no other handler matches.

Parameters

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

void AMPS::Client::setLogonCorrelationData ( const std::string & logonCorrelationData_ )

inline

Sets the logon correlation data for the client.

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

Parameters

logonCorrelationData_ The data to be sent with the logon.

void AMPS::Client::setName ( const std::string & name )

inline

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

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

Parameters

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.

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

void AMPS::Client::setRetryOnDisconnect ( bool isRetryOnDisconnect_ )

inline

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

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

Parameters

isRetryOnDisconnect_ false will disable this behavior.

void AMPS::Client::setSubscriptionManager ( SubscriptionManager * subscriptionManager_ )

inline

Set the subscription manager to be used by the client.

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

Parameters

subscriptionManager_ The subscription manager to use.

void AMPS::Client::setThreadCreatedCallback	(	amps_thread_created_callback	callback_,
		void *	userData_
	)

inline

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

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

Parameters

callback_	The function to call first in the new thread.
userData_	Any data that should be passed to the function.

void AMPS::Client::setTransportFilterFunction	(	amps_transport_filter_function	filter_,
		void *	userData_
	)

inline

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

Parameters

filter_	The amps_transport_filter_function to call.
userData_	Any data that should be passed to the function.

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

inline

Deprecated:: . Use setLastChanceMessageHandler

MessageStream AMPS::Client::sow	(	const char *	topic_,
		const std::string &	filter_ = `""`,
		const std::string &	orderBy_ = `""`,
		const std::string &	bookmark_ = `""`,
		int	batchSize_ = `DEFAULT_BATCH_SIZE`,
		int	topN_ = `DEFAULT_TOP_N`,
		const std::string &	options_ = `""`,
		long	timeout_ = `DEFAULT_COMMAND_TIMEOUT`
	)

inline

Query the SOW cache of a topic.

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

Parameters

topic_	The topic, or regular expression topic, to subscribe to.
filter_	Optional filter expression for this subscription.
orderBy_	Optional orderBy to have records ordered by server.
bookmark_	Optional bookmark for historical query. Bookmarks can be one of the Special Bookmark Values, the bookmark assigned to a specific message, or a timestamp of the format YYYYmmddTHHMMSS, as described in the AMPS User's Guide.
batchSize_	The number of records the server should pack into each message: typically applications use DEFAULT_BATCH_SIZE unless the messages are much smaller than the MTU for the network or are very large
topN_	The maximum number of records the server will return (default is all that match).
options_	An 'or'ing of options for the command.
timeout_	The time to wait, in milliseconds, for the receive thread to consume a processed ack for this command. 0 indicates no timeout.

Returns: A MessageStream to iterate over.

Exceptions

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.

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.

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.

void AMPS::Client::startTimer ( void )

inline

Deprecated:: As of AMPS server 5.3.2.0 start_timer is not valid.

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

std::string AMPS::Client::stopTimer ( const MessageHandler & messageHandler )

inline

Deprecated:: As of AMPS server 5.3.2.0 stop_timer is not valid.

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

Parameters

messageHandler The function to be invoked when the acknowledgement message arrives

See also: startTimer()

std::string AMPS::Client::subscribe	(	const MessageHandler &	messageHandler_,
		const std::string &	topic_,
		long	timeout_ = `0`,
		const std::string &	filter_ = `""`,
		const std::string &	options_ = `""`,
		const std::string &	subId_ = `""`
	)

inline

Subscribe to a topic.

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

Parameters

messageHandler_	The function to be invoked when messages for this topic arrive.
topic_	The topic, or regular expression topic, to subscribe to.
timeout_	The time to wait, in milliseconds, for the receive thread to consume a processed ack for this command. 0 indicates no timeout.
filter_	Optional filter expression for this subscription.
options_	Optional options to supply with this subscription.
subId_	Optional subscription id to use with this subscription.

Returns: A std::string with a unique identifier for this subscription.

Exceptions

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.

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.

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.

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.

void AMPS::Client::unsubscribe ( void )

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.

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

include/amps/ampsplusplus.hpp

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation