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

Functions
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

## ◆ sow() [1/2]

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

## ◆ sow() [2/2]

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

## ◆ sowAndDeltaSubscribe() [1/2]

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

## ◆ sowAndDeltaSubscribe() [2/2]

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

## ◆ sowAndSubscribe() [1/2]

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

## ◆ sowAndSubscribe() [2/2]

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

## ◆ sowDelete()

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 occurred while sending the message.
  TimedOutException | A timeout occurred while waiting for a response from the server.
  AuthenticationException | An authentication failure was received from the server.
  UnknownException | An unknown failure was received from the server.
  BadFilterException | The specified filter is not valid or has a syntax error.
  BadRegexTopicException | The specified topic contains an invalid regex.
  InvalidTopicException | The specified topic may not be used with this command.

## ◆ sowDeleteByData() [1/2]

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 occurred while sending the message.
  TimedOutException | A timeout occurred while waiting for a response from the server.
  AuthenticationException | An authentication failure was received from the server.
  UnknownException | An unknown failure was received from the server.
  BadRegexTopicException | The specified topic contains an invalid regex.
  InvalidTopicException | The specified topic may not be used with this command.

## ◆ sowDeleteByData() [2/2]

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 occurred while sending the message.
  TimedOutException | A timeout occurred while waiting for a response from the server.
  AuthenticationException | An authentication failure was received from the server.
  UnknownException | An unknown failure was received from the server.
  BadRegexTopicException | The specified topic contains an invalid regex.
  InvalidTopicException | The specified topic may not be used with this command.

## ◆ sowDeleteByKeys()

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 occurred while sending the message.
  TimedOutException | A timeout occurred while waiting for a response from the server.
  AuthenticationException | An authentication failure was received from the server.
  UnknownException | An unknown failure was received from the server.
  BadRegexTopicException | The specified topic contains an invalid regex.
  InvalidTopicException | The specified topic may not be used with this command.