These functions process messages on a background thread by calling the provided message handler. More...

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

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

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

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

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

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

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

std::string	AMPS::Client::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	AMPS::Client::sowDeleteByData (const std::string &topic_, const std::string &data_, long timeout_=0)
	Deletes the message whose keys match the message data provided. More...

Detailed Description

These functions process messages on a background thread by calling the provided message handler.

Warning: Notice that the AMPS client reuses the Message object provided to the handler, so the contents of the object are reset between calls to the handler. If you need to use the data outside of the call to the message handler, you must make a copy of the data.

Function Documentation

std::string AMPS::Client::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`
	)

inline

Query a State-of-the-World topic.

Queries a SOW topic on the AMPS server. When you call this function, AMPS returns the command ID assigned to this command immediately. The query runs on a background thread, and the provided message handler is called on that thread. See the Developer Guide for considerations on the threading model.

Parameters

messageHandler_	The function to be invoked when messages for this topic arrive.
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.
batchSize_	The number of records the server should pack into each message: typically applications use the DEFAULT_BATCH_SIZE unless the records 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 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.
InvalidTopicException	The specified topic may not be used with this command.
SubscriptionAlreadyExistsException	This ID already exists as a subscription.

std::string AMPS::Client::sow	(	const MessageHandler &	messageHandler_,
		const std::string &	topic_,
		long	timeout_,
		const std::string &	filter_ = `""`,
		int	batchSize_ = `DEFAULT_BATCH_SIZE`,
		int	topN_ = `DEFAULT_TOP_N`
	)

inline

Query the SOW cache of a topic.

Queries the SOW cache of a topic on the AMPS server. The query runs on a background thread, and the provided messageHandler_ is invoked on that thread. See the Developer Guide for details on 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.
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).

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.
InvalidTopicException	The specified topic may not be used with this command.
SubscriptionAlreadyExistsException	This ID already exists as a subscription.

std::string AMPS::Client::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`
	)

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. The messageHandler_ is invoked 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.
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 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.
InvalidTopicException	The specified topic may not be used with this command.
SubscriptionAlreadyExistsException	This ID already exists as a subscription.

std::string AMPS::Client::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`
	)

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. The messageHandler_ is invoked on the client receive thread. See the Developer Guide for 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.
batchSize_	The number of records the server should pack into each message.
oofEnabled_	`true` indicates Out-Of-Focus messages are desired for this topic.
sendEmpties_	`true` indicates empty messages should be sent by the server.
topN_	The maximum number of records the server will return (default is all that match).

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.
InvalidTopicException	The specified topic may not be used with this command.
SubscriptionAlreadyExistsException	This ID already exists as a subscription.

std::string AMPS::Client::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`
	)

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. The messageHandler_ provided is invoked 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.
batchSize_	The number of records the server should pack into each message.
oofEnabled_	`true` indicates Out-Of-Focus messages are desired for this topic.
topN_	The maximum number of records the server will return (default is all that match).

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.
InvalidTopicException	The specified topic may not be used with this command.
SubscriptionAlreadyExistsException	This ID already exists as a subscription.

std::string AMPS::Client::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`
	)

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. The messageHandler_ provided is invoked 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.
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 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.
InvalidTopicException	The specified topic may not be used with this command.
SubscriptionAlreadyExistsException	This ID already exists as a subscription.

std::string AMPS::Client::sowDelete	(	const MessageHandler &	messageHandler,
		const std::string &	topic,
		const std::string &	filter,
		long	timeout
	)

inline

Deletes one or more messages from a topic's SOW cache.

Sends a request to the server to delete one or more messages in the SOW cache. The messageHandler is called on the client receive thread. See the Developer Guide for threading considerations.

Parameters

messageHandler	The function to be invoked when messages for this topic arrive.
topic	The topic, or regular expression topic, to delete from.
filter	Optional filter expression for this subscription. To delete all records, set a filter that is always true ('1=1').
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 std::string with a unique identifier for this request.

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.

std::string AMPS::Client::sowDeleteByData	(	const MessageHandler &	messageHandler_,
		const std::string &	topic_,
		const std::string &	data_,
		long	timeout_ = `0`
	)

inline

Deletes the message whose keys match the message data provided.

Parameters

messageHandler_	The function to be invoked when statistics about the delete arrive.
topic_	The topic, or regular expression topic, to delete from.
data_	The message whose keys are matched against the server's SOW cache.
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 std::string with a unique identifier for this request.

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.
BadRegexTopicException	The specified topic contains an invalid regex.
InvalidTopicException	The specified topic may not be used with this command.

Message AMPS::Client::sowDeleteByData	(	const std::string &	topic_,
		const std::string &	data_,
		long	timeout_ = `0`
	)

inline

Deletes the message whose keys match the message data provided.

Sends a request to the server to delete the message whose keys match the data provided. This method returns once the operation is complete.

Parameters

topic_	The topic, or regular expression topic, to delete from.
data_	The message whose keys are matched against the server's SOW cache.
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 Message containing information about the completed operation.

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.
BadRegexTopicException	The specified topic contains an invalid regex.
InvalidTopicException	The specified topic may not be used with this command.

std::string AMPS::Client::sowDeleteByKeys	(	const MessageHandler &	messageHandler_,
		const std::string &	topic_,
		const std::string &	keys_,
		long	timeout_ = `0`
	)

inline

Deletes messages that match SOW keys from a topic's SOW cache.

Sends a request to the server to delete messages that match SOW keys from a topic's SOW cache. The SOW keys provided are a comma-delimited list. When the topic is configured such that AMPS generates the SOW key based on the message contents, these are the key values that AMPS generates (as returned in the SowKey field of the message header). When the topic is configured such that a publisher must provide the SOW key, the key that the publisher provided can be used to delete a message.

Parameters

messageHandler_	The function to be invoked when messages for this topic arrive.
topic_	The topic, or regular expression topic, to delete from.
keys_	The sow keys to delete as a comma-separated list
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 std::string with a unique identifier for this request.

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.
BadRegexTopicException	The specified topic contains an invalid regex.
InvalidTopicException	The specified topic may not be used with this command.

Functions

Detailed Description

Function Documentation