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

Classes | Functions
Synchronous Message Processing

These functions provide messages to the calling thread by using the AMPS::MessageStream class to return messages. More...

## Classes
class | AMPS::MessageStream
| An iterable object representing the results of an AMPS subscription and/or query. More...

## Functions
MessageStream | AMPS::Client::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 | AMPS::Client::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 | AMPS::Client::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...
MessageStream | AMPS::Client::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 | AMPS::Client::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 | AMPS::Client::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 | AMPS::Client::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...
Message | AMPS::Client::sowDelete (const std::string &topic_, const std::string &filter_, long timeout_=0)
| Deletes one or more messages from a topic's SOW cache. More...
Message | AMPS::Client::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...

## Detailed Description

These functions provide messages to the calling thread by using the AMPS::MessageStream class to return messages.

## Function Documentation

## ◆ sow()

MessageStream AMPS::Client::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`
| ) |  |
| inline

Query the SOW cache of a topic.

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

Parameters

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

Returns
  A MessageStream to iterate over.

Exceptions

  DisconnectedException | The Client is no longer connected to a server.
  ConnectionException | An error occurred while sending the message.
  TimedOutException | A timeout occurred while waiting for a response from the server.
  AuthenticationException | An authentication failure was received from the server.
  UnknownException | An unknown failure was received from the server.
  BadFilterException | The specified filter is not valid or has a syntax error.
  BadRegexTopicException | The specified topic contains an invalid regex.
  InvalidTopicException | The specified topic may not be used with this command.
  SubscriptionAlreadyExistsException | This ID already exists as a subscription.

## ◆ sowAndDeltaSubscribe() [1/3]

MessageStream AMPS::Client::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`
| ) |  |
| 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.

Parameters

  topic_ | The topic, or regular expression topic, to subscribe to.
  timeout_ | The time to wait, in milliseconds, for the receive thread to consume an acknowledgment 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 MessageStream to iterate over.

Exceptions

  DisconnectedException | The Client is no longer connected to a server.
  ConnectionException | An error occurred while sending the message.
  TimedOutException | A timeout occurred while waiting for a response from the server.
  AuthenticationException | An authentication failure was received from the server.
  UnknownException | An unknown failure was received from the server.
  BadFilterException | The specified filter is not valid or has a syntax error.
  BadRegexTopicException | The specified topic contains an invalid regex.
  InvalidTopicException | The specified topic may not be used with this command.
  SubscriptionAlreadyExistsException | This ID already exists as a subscription.

## ◆ sowAndDeltaSubscribe() [2/3]

MessageStream AMPS::Client::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`
| ) |  |
| inline

Query the SOW cache of a topic and initiates a new delta subscription on it.

Queries the SOW cache of a topic on the AMPS server, and simultaneously begins a new delta subscription on it. Returns a MessageStream to iterate over.

Parameters

  topic_ | The topic, or regular expression topic, to subscribe to.
  filter_ | Optional filter expression for this subscription.
  orderBy_ | Optional orderBy to have records ordered by server.
  batchSize_ | The number of records the server should pack into each message.
  topN_ | The maximum number of records the server will return (default is all that match).
  options_ | An 'or'ing of options for the command.
  timeout_ | The time to wait, in milliseconds, for the receive thread to consume a processed ack for this command. 0 indicates no timeout.

Returns
  A MessageStream to iterate over.

Exceptions

  DisconnectedException | The Client is no longer connected to a server.
  ConnectionException | An error occurred while sending the message.
  TimedOutException | A timeout occurred while waiting for a response from the server.
  AuthenticationException | An authentication failure was received from the server.
  UnknownException | An unknown failure was received from the server.
  BadFilterException | The specified filter is not valid or has a syntax error.
  BadRegexTopicException | The specified topic contains an invalid regex.
  InvalidTopicException | The specified topic may not be used with this command.
  SubscriptionAlreadyExistsException | This ID already exists as a subscription.

## ◆ sowAndDeltaSubscribe() [3/3]

MessageStream AMPS::Client::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`
| ) |  |
| 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.

Parameters

  topic_ | The topic, or regular expression topic, to subscribe to.
  timeout_ | The time to wait, in milliseconds, for the receive thread to consume a processed ack for this command. 0 indicates no timeout.
  filter_ | Optional filter expression for this subscription.
  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 MessageStream to iterate over.

Exceptions

  DisconnectedException | The Client is no longer connected to a server.
  ConnectionException | An error occurred while sending the message.
  TimedOutException | A timeout occurred while waiting for a response from the server.
  AuthenticationException | An authentication failure was received from the server.
  UnknownException | An unknown failure was received from the server.
  BadFilterException | The specified filter is not valid or has a syntax error.
  BadRegexTopicException | The specified topic contains an invalid regex.
  InvalidTopicException | The specified topic may not be used with this command.
  SubscriptionAlreadyExistsException | This ID already exists as a subscription.

## ◆ sowAndSubscribe() [1/3]

MessageStream AMPS::Client::sowAndSubscribe | ( | const char * | 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.

Parameters

  topic_ | The topic, or regular expression topic, to subscribe to.
  timeout_ | The time to wait, in milliseconds, for the receive thread to consume a processed ack for this command. 0 indicates no timeout.
  filter_ | Optional filter expression for this subscription.
  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 MessageStream to iterate over.

Exceptions

  DisconnectedException | The Client is no longer connected to a server.
  ConnectionException | An error occurred while sending the message.
  TimedOutException | A timeout occurred while waiting for a response from the server.
  AuthenticationException | An authentication failure was received from the server.
  UnknownException | An unknown failure was received from the server.
  BadFilterException | The specified filter is not valid or has a syntax error.
  BadRegexTopicException | The specified topic contains an invalid regex.
  InvalidTopicException | The specified topic may not be used with this command.
  SubscriptionAlreadyExistsException | This ID already exists as a subscription.

## ◆ sowAndSubscribe() [2/3]

MessageStream AMPS::Client::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`
| ) |  |
| inline

Query the SOW cache of a topic and initiates a new subscription on it.

Queries the SOW cache of a topic on the AMPS server, and simultaneously begins a new subscription, returning a MessageStream to iterate over.

Parameters

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

Returns
  A MessageStream to iterate over.

Exceptions

  DisconnectedException | The Client is no longer connected to a server.
  ConnectionException | An error occurred while sending the message.
  TimedOutException | A timeout occurred while waiting for a response from the server.
  AuthenticationException | An authentication failure was received from the server.
  UnknownException | An unknown failure was received from the server.
  BadFilterException | The specified filter is not valid or has a syntax error.
  BadRegexTopicException | The specified topic contains an invalid regex.
  InvalidTopicException | The specified topic may not be used with this command.
  SubscriptionAlreadyExistsException | This ID already exists as a subscription.

## ◆ sowAndSubscribe() [3/3]

MessageStream AMPS::Client::sowAndSubscribe | ( | 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.

Parameters

  topic_ | The topic, or regular expression topic, to subscribe to.
  timeout_ | The time to wait, in milliseconds, for the receive thread to consume a processed ack for this command. 0 indicates no timeout.
  filter_ | Optional filter expression for this subscription.
  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 MessageStream to iterate over.

Exceptions

  DisconnectedException | The Client is no longer connected to a server.
  ConnectionException | An error occurred while sending the message.
  TimedOutException | A timeout occurred while waiting for a response from the server.
  AuthenticationException | An authentication failure was received from the server.
  UnknownException | An unknown failure was received from the server.
  BadFilterException | The specified filter is not valid or has a syntax error.
  BadRegexTopicException | The specified topic contains an invalid regex.
  InvalidTopicException | The specified topic may not be used with this command.
  SubscriptionAlreadyExistsException | This ID already exists as a subscription.

## ◆ sowDelete()

Message AMPS::Client::sowDelete | ( | const std::string & | topic_,
|  | const std::string & | filter_,
|  | long | timeout_ = `0`
| ) |  |
| 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, returning once the operation is complete.

Parameters

  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 Message containing information about the completed delete 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.
  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.

## ◆ sowDeleteByKeys()

Message AMPS::Client::sowDeleteByKeys | ( | 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, returning once the operation is complete. 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

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