AMPS C/C++ Client Class Reference
AMPS C/C++ Client Version 5.3.4.3
Asynchronous Message Processing

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
DisconnectedExceptionThe Client is no longer connected to a server.
ConnectionExceptionAn error occurred while sending the message.
TimedOutExceptionA timeout occurred while waiting for a response from the server.
AuthenticationExceptionAn authentication failure was received from the server.
UnknownExceptionAn unknown failure was received from the server.
BadFilterExceptionThe specified filter is not valid or has a syntax error.
BadRegexTopicExceptionThe specified topic contains an invalid regex.
InvalidTopicExceptionThe specified topic may not be used with this command.
SubscriptionAlreadyExistsExceptionThis ID already exists as a subscription.
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
DisconnectedExceptionThe Client is no longer connected to a server.
ConnectionExceptionAn error occurred while sending the message.
TimedOutExceptionA timeout occurred while waiting for a response from the server.
AuthenticationExceptionAn authentication failure was received from the server.
UnknownExceptionAn unknown failure was received from the server.
BadFilterExceptionThe specified filter is not valid or has a syntax error.
BadRegexTopicExceptionThe specified topic contains an invalid regex.
InvalidTopicExceptionThe specified topic may not be used with this command.
SubscriptionAlreadyExistsExceptionThis ID already exists as a subscription.
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
DisconnectedExceptionThe Client is no longer connected to a server.
ConnectionExceptionAn error occurred while sending the message.
TimedOutExceptionA timeout occurred while waiting for a response from the server.
AuthenticationExceptionAn authentication failure was received from the server.
UnknownExceptionAn unknown failure was received from the server.
BadFilterExceptionThe specified filter is not valid or has a syntax error.
BadRegexTopicExceptionThe specified topic contains an invalid regex.
InvalidTopicExceptionThe specified topic may not be used with this command.
SubscriptionAlreadyExistsExceptionThis ID already exists as a subscription.
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
DisconnectedExceptionThe Client is no longer connected to a server.
ConnectionExceptionAn error occurred while sending the message.
TimedOutExceptionA timeout occurred while waiting for a response from the server.
AuthenticationExceptionAn authentication failure was received from the server.
UnknownExceptionAn unknown failure was received from the server.
BadFilterExceptionThe specified filter is not valid or has a syntax error.
BadRegexTopicExceptionThe specified topic contains an invalid regex.
InvalidTopicExceptionThe specified topic may not be used with this command.
SubscriptionAlreadyExistsExceptionThis ID already exists as a subscription.
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
DisconnectedExceptionThe Client is no longer connected to a server.
ConnectionExceptionAn error occurred while sending the message.
TimedOutExceptionA timeout occurred while waiting for a response from the server.
AuthenticationExceptionAn authentication failure was received from the server.
UnknownExceptionAn unknown failure was received from the server.
BadFilterExceptionThe specified filter is not valid or has a syntax error.
BadRegexTopicExceptionThe specified topic contains an invalid regex.
InvalidTopicExceptionThe specified topic may not be used with this command.
SubscriptionAlreadyExistsExceptionThis ID already exists as a subscription.
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
DisconnectedExceptionThe Client is no longer connected to a server.
ConnectionExceptionAn error occurred while sending the message.
TimedOutExceptionA timeout occurred while waiting for a response from the server.
AuthenticationExceptionAn authentication failure was received from the server.
UnknownExceptionAn unknown failure was received from the server.
BadFilterExceptionThe specified filter is not valid or has a syntax error.
BadRegexTopicExceptionThe specified topic contains an invalid regex.
InvalidTopicExceptionThe specified topic may not be used with this command.
SubscriptionAlreadyExistsExceptionThis ID already exists as a subscription.
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
messageHandlerThe function to be invoked when messages for this topic arrive.
topicThe topic, or regular expression topic, to delete from.
filterOptional filter expression for this subscription. To delete all records, set a filter that is always true ('1=1').
timeoutThe 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
DisconnectedExceptionThe Client is no longer connected to a server.
ConnectionExceptionAn error occurred while sending the message.
TimedOutExceptionA timeout occurred while waiting for a response from the server.
AuthenticationExceptionAn authentication failure was received from the server.
UnknownExceptionAn unknown failure was received from the server.
BadFilterExceptionThe specified filter is not valid or has a syntax error.
BadRegexTopicExceptionThe specified topic contains an invalid regex.
InvalidTopicExceptionThe specified topic may not be used with this command.
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
DisconnectedExceptionThe Client is no longer connected to a server.
ConnectionExceptionAn error occurred while sending the message.
TimedOutExceptionA timeout occurred while waiting for a response from the server.
AuthenticationExceptionAn authentication failure was received from the server.
UnknownExceptionAn unknown failure was received from the server.
BadRegexTopicExceptionThe specified topic contains an invalid regex.
InvalidTopicExceptionThe 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
DisconnectedExceptionThe Client is no longer connected to a server.
ConnectionExceptionAn error occurred while sending the message.
TimedOutExceptionA timeout occurred while waiting for a response from the server.
AuthenticationExceptionAn authentication failure was received from the server.
UnknownExceptionAn unknown failure was received from the server.
BadRegexTopicExceptionThe specified topic contains an invalid regex.
InvalidTopicExceptionThe 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
DisconnectedExceptionThe Client is no longer connected to a server.
ConnectionExceptionAn error occurred while sending the message.
TimedOutExceptionA timeout occurred while waiting for a response from the server.
AuthenticationExceptionAn authentication failure was received from the server.
UnknownExceptionAn unknown failure was received from the server.
BadRegexTopicExceptionThe specified topic contains an invalid regex.
InvalidTopicExceptionThe specified topic may not be used with this command.