The main class for interacting with AMPS. 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...

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

const std::string &	getLogonCorrelationData () const
	Returns the currently set logoon 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. 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...

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

std::string	send (MessageHandler messageHandler, Message &message, int timeout=0)
	Sends a Message to the connected AMPS server. More...

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

DisconnectHandler	getDisconnectHandler (void)
	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 on duplicate or not entitled messages that have been published. 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. More...

amps_uint64_t	publish (const char topic_, size_t topicLength_, const char data_, size_t dataLength_)
	Publish a message to an AMPS topic. More...

amps_uint64_t	publish (const std::string &topic_, const std::string &data_, unsigned long expiration_)
	Publish a message to an AMPS topic. 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. More...

void	publishFlush (long timeout_=0)
	Ensures 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. More...

std::string	logon (const char *options_, int timeout_=0)
	Logon to the server. More...

std::string	logon (const std::string &options_, int timeout_=0)
	Logon to the server. More...

std::string	subscribe (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 (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 (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 (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 (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 (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 (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 (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 (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 (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 ()
	Sends a message to AMPS requesting that AMPS start a server-side timer. More...

std::string	stopTimer (MessageHandler messageHandler)
	Sends a message to AMPS requesting that AMPS stop the previously started timer. More...

std::string	sowDeleteByKeys (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 (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 ExceptionListener &listener_)
	Sets the exception listener for exceptions that are not thrown back to the user. More...

const ExceptionListener &	getExceptionListener (void) const
	Returns the exception listener for exceptions that are not thrown back to the user. More...

void	setHeartbeat (unsigned heartbeatTime_, unsigned readTimeout_)
	Sets the heartbeat time on this Client, Server and Transport. More...

void	setHeartbeat (unsigned heartbeatTime_)
	Sets the heartbeat time on this Client, Server and Transport. More...

void	setUnhandledMessageHandler (const AMPS::MessageHandler &messageHandler)
	Deprecated. Use setLastChanceMessageHandler instead.

void	setLastChanceMessageHandler (const AMPS::MessageHandler &messageHandler)
	Sets the message handler called when no other handler matches. 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...

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)
	ACK a message queue message by supplying a topic and bookmark. More...

void	ack (Message &message_, const char *options_=NULL)
	ACK a message queue message by supplying the message directly. More...

void	ack (const std::string &topic_, const std::string &bookmark_, const char *options_=NULL)
	ACK a message queue message by supplying a topic and bookmark string. More...

void	flushAcks (void)
	Sends any queued message queue ACK messages to the server immediately.

bool	getAutoAck (void) const
	Returns the value of the auto-ack setting. More...

void	setAutoAck (bool isAutoAckEnabled_)
	Sets the auto-ack setting on this client. More...

unsigned	getAckBatchSize (void) const
	Returns the value of the ack batch size setting. More...

void	setAckBatchSize (const unsigned ackBatchSize_)
	Sets the ack batch size setting. More...

int	getAckTimeout (void) const
	Returns the current value of the ack timeout setting. 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 defualt 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...

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

Detailed Description

The main class for interacting with AMPS.

Client represents a single connection to an AMPS server, and provides methods for subscribing, publishing, and disconnecting.

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

ACK a message queue message by supplying a topic and bookmark.

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

ACK a message queue message by supplying the message directly.

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

ACK a message queue message by supplying a topic and bookmark string.

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.

std::string AMPS::Client::bookmarkSubscribe	(	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 subscription to a topic on the server.

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 a response from the server. 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 occured while sending the message.
TimedOutException	A timeout occured 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 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 a response from the server. 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 occured while sending the message.
TimedOutException	A timeout occured 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 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 a response from the server. 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 occured while sending the message.
TimedOutException	A timeout occured 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.

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 occured while sending the message.

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.

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 occured while sending the message.

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.

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 occured while sending the message.

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.

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 occured while sending the message.

std::string AMPS::Client::deltaSubscribe	(	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.

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 a response from the server. 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 a response from the server. 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 a response from the server. 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.

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.

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

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

inline

Returns the value of the 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 ack timeout setting.

Returns: the current ack timeout, in milliseconds.

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

inline

Returns the value of the 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 )

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.

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

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

inline

Returns the exception listener for exceptions that are not thrown back to the user.

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 ( )

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

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.

Sends a logon request to the server, using a custom authenticator

Parameters

timeout_	The time to wait, in milliseconds, for a response. (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 occured while sending the message.
TimedOutException	A timeout occured 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	The specified client name is already in use on the server.

std::string AMPS::Client::logon	(	const char *	options_,
		int	timeout_ = `0`
	)

inline

Logon to the server.

Sends a logon request to the server using the DefaultAuthenticator and given options

Parameters

options_	The options to pass in with the logon command such as "conflation_interval=10ms".
timeout_	The time to wait, in milliseconds, for a response. (Default: 0 – wait forever.)

Exceptions

DisconnectedException	The Client is no longer connected to a server.
ConnectionException	An error occured while sending the message.
TimedOutException	A timeout occured 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	The specified client name is already in use on the server.

std::string AMPS::Client::logon	(	const std::string &	options_,
		int	timeout_ = `0`
	)

inline

Logon to the server.

Sends a logon request to the server using the DefaultAuthenticator and given options

Parameters

options_	The options to pass in with the logon command such as "conflation_interval=10ms".
timeout_	The time to wait, in milliseconds, for a response. (Default: 0 – wait forever.)

Exceptions

DisconnectedException	The Client is no longer connected to a server.
ConnectionException	An error occured while sending the message.
TimedOutException	A timeout occured 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	The specified client name is already in use on the server.

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

inline

Publish a message to an AMPS topic.

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.

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

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.

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

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.

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

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.

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 occured 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 )

inline

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

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 method blocks until messages have been processed or until the timeout expires, and 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 amount of time to wait for flush to complete. Default is 0, which is no maximum.

Exceptions

DisconnectedException	The Client is no longer connected to a server.
ConnectionException	An error occured while sending the message.
TimedOutException	The publish command was not acked in the allowed 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 hanlder.

Returns: True if the handler was removed.

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

inline

Sends a Message to the connected AMPS server.

Sends the given Message to the connected AMPS server. 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.

Parameters

message The Message to send to the AMPS server.

Exceptions

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

std::string AMPS::Client::send	(	MessageHandler	messageHandler,
		Message &	message,
		int	timeout = `0`
	)

inline

Sends a Message to the connected AMPS server.

Sends the given Message to the connected AMPS server. 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.

Parameters

messageHandler	The MessageHandler to associate with this message.
message	The message to send to the AMPS server.
timeout	For synchronous messages, the time to wait for a response, in milliseconds. 0 indicates no timeout.

Exceptions

DisconnectedException	The Client is no longer connected to a server.
ConnectionException	An error occured while sending the message.
TimedOutException	A timeout occured 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	The specified client name is already in use on 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::setAckBatchSize ( const unsigned ackBatchSize_ )

inline

Sets the 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 the timeout.

Parameters

ackTimeout_ The ACK timeout value, in milliseconds.

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

inline

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

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 defualt max depth on all subsequently created MessageStream objects.

Parameters

maxDepth_ The new max depth to use.

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

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 ExceptionListener & listener_ )

inline

Sets the exception listener for exceptions that are not thrown back to the user.

Parameters

listener_ The exception listener to be used

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

inline

Set the handler that is invoked to report on duplicate or not entitled messages that have been published.

The Client takes ownership of the pointer.

Parameters

handler_ The handler to invoke for failed writes.

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

inline

Sets the heartbeat time on this Client, Server and Transport.

Parameters

heartbeatTime_	The time (seconds) to request the server heartbeat.
readTimeout_	The time (seconds) to allow a read before timing out.

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

inline

Sets the heartbeat time on this Client, Server and Transport.

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.

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.

Parameters

subscriptionManager_ The subscription manager to use.

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.

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.
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 a response from the server. 0 indicates no timeout.

Returns: A MessageStream to iterate over.

Exceptions

DisconnectedException	The Client is no longer connected to a server.
ConnectionException	An error occured while sending the message.
TimedOutException	A timeout occured 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 a response from the server. 0 indicates no timeout.

Returns: A MessageStream to iterate over.

Exceptions

DisconnectedException	The Client is no longer connected to a server.
ConnectionException	An error occured while sending the message.
TimedOutException	A timeout occured 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 a response from the server. 0 indicates no timeout.

Returns: A MessageStream to iterate over.

Exceptions

DisconnectedException	The Client is no longer connected to a server.
ConnectionException	An error occured while sending the message.
TimedOutException	A timeout occured 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 ( )

inline

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 ( MessageHandler messageHandler )

inline

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

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 a response from the server. 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 occured while sending the message.
TimedOutException	A timeout occured 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 a response from the server. 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 occured while sending the message.
TimedOutException	A timeout occured 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 a response from the server. 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 occured while sending the message.
TimedOutException	A timeout occured 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 occured while sending the message.
TimedOutException	A timeout occured 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 ( )

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 occured while sending the message.
TimedOutException	A timeout occured 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/ampsplusplus.hpp

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation