LogoLogo
AMPS C++ Client 5.3.4
AMPS C++ Client 5.3.4
  • Welcome to the AMPS C / C++ Client
    • Before You Start
    • Introduction
    • Obtaining and Installing the AMPS C / C++ Client
    • Your First AMPS Program
      • Client Identification
      • Connection Strings for AMPS
      • Connection Parameters for AMPS
      • Providing Credentials to AMPS
    • Subscriptions
      • Content Filtering
        • Changing the Filter on a Subscription
      • Understanding Message Objects
      • Synchronous Message Processing
      • Asynchronous Message Processing
        • Understanding Threading
      • Regular Expression Subscriptions
      • Ending Subscriptions
    • Error Handling
      • Exceptions
      • Exception Types
      • Exception Handling and Asynchronous Message Processing
      • Controlling Blocking with Command Timeout
      • Disconnect Handling
        • Using a Heartbeat to Detect Disconnection
        • Managing Disconnection
        • Replacing Disconnect Handling
      • Unexpected Messages
      • Unhandled Exceptions
      • Detecting Write Failures
      • Monitoring Connection State
    • State of the World
      • Performing SOW Queries
        • Samples of Querying a Topic in the SOW
      • SOW and Subscribe
        • Samples of SOW and Subscribe
      • Setting Batch Size
      • Managing SOW Contents
      • Client Side Conflation
    • Using Queues
      • Backlog and Smart Pipelining
      • Returning a Message to the Queue
      • Acknowledgement Batching
      • Manual Acknowledgement
      • Samples of Working With a Queue
    • Delta Publish and Subscribe
      • Delta Subscribe
      • Delta Publish
    • High Availability
    • AMPS Programming: Working with Commands
    • Utility Classes
    • Advanced Topics
    • Exceptions Reference
    • AMPS Server Documentation
    • API Documentation
Powered by GitBook

Get Help

  • FAQ
  • Legacy Documentation
  • Support / Contact Us

Get AMPS

  • Evaluate
  • Develop

60East Resources

  • Website
  • Privacy Policy

Copyright 2013-2024 60East Technologies, Inc.

On this page
Export as PDF
  1. Welcome to the AMPS C / C++ Client

Subscriptions

Messages published to a topic on an AMPS server are available to other clients via a subscription. Before messages can be received, a client must subscribe to one or more topics on the AMPS server so that the server will begin sending messages to the client. The server will continue sending messages to the client until the client unsubscribes, or the client disconnects. With content filtering, the AMPS server will limit the messages sent only to those messages that match a client-supplied filter. In this chapter, you will learn how to subscribe, unsubscribe, and supply filters for messages using the AMPS C/C++ client.

Subscribing

Subscribing to an AMPS topic takes place by calling Client.subscribe(). Here is a short example showing the simplest way to subscribe to a topic (error handling and connection details are omitted for brevity):

Client client(...);
client.connect(...);

/* Here we have created or received a Client that is properly connected
to an AMPS server. */
client.logon();


/* Here we subscribe to the topic messages. We do not provide a filter, so AMPS
 * does not content-filter the subscription. Although we don't use the object
 * explicitly here, the subscribe function returns a MessageStream object that we
 * iterate over. If, at any time, we no longer need to subscribe, we can break out
 * of the loop. When we break out of the loop, the MessageStream goes out of scope,
 * the MessageStream destructor runs, and the AMPS client sends an unsubscribe
 * command to AMPS.
 */
for (auto message : client.subscribe("messages"))
{
    /* Within the body of the loop, we can process the message as we need to. In this
     * case, we simply print the contents of the message.
     */
    std :: cout << "Received message: " << message.getData () << std :: endl ;
}

AMPS creates a background thread that receives messages and copies them into a MessageStream that you iterate over. This means that the client application as a whole can continue to receive messages while you are doing processing work.

The simple method described above is provided for convenience. The AMPS C++ client provides convenience methods for the most common form of the AMPS commands. The client also provides an interface that allows you to have precise control over the command. Using that interface, the example above becomes:

Client client(...);
client.connect(...);

/* Here we have created or received a Client that is properly connected to an AMPS server. */
client.logon();


/* Here we subscribe to the topic messages. We do not provide a filter, so AMPS
 * does not content-filter the subscription. Although we don't use the object
 * explicitly here, the execute function returns a MessageStream object that we
 * iterate over. If, at any time, we no longer need to subscribe, we can break out
 * of the loop. When we break out of the loop, the MessageStream goes out of scope,
 * the MessageStream destructor runs, and the AMPS client sends an unsubscribe
 * command to AMPS.
 *
 * Here we create a command object for the subscribe command, specifying the topic
 * messages.
 */
for (auto message : ampsClient.execute(Command("subscribe").setTopic("messages")))
{
    std :: cout << "Received message: "<< message.getData () << std :: endl;
}

The Command interface allows you to precisely customize the commands you send to AMPS. For flexibility and ease of maintenance, 60East recommends using the Command interface (rather than a named method) for any command that will receive messages from AMPS. For publishing messages, there can be a slight performance advantage to using the named commands where possible.

PreviousProviding Credentials to AMPSNextContent Filtering

Last updated 4 months ago