Ending Subscriptions

The AMPS server continues a subscription until the client explicitly ends the subscription (that is, unsubscribes) or until the connection to the client is closed.

With the synchronous interface, AMPS automatically unsubscribes to the topic when the destructor for the MessageStream runs. You can also explicitly call the close() method on the MessageStream object to remove the subscription.

In the asynchronous interface, when a subscription is successfully made, messages will begin flowing to the message handler, and the subscribe() or executeAsync() call will return a string for the subscription id that serves as the identifier for this subscription. A Client can have any number of active subscriptions, and this subscription id is how AMPS designates messages intended for this particular subscription. To unsubscribe, we simply call unsubscribe with the subscription identifier:

Client client = ...;

// Register asynchronous subscription
std::string subId = client.executeAsync(
                         Command("subscribe").setTopic("messages"),
                         MessageHandler(myHandlerFunction, NULL));

... other work here ...

client.unsubscribe(subId);

In this example, as in the previous section, we use the client.executeAsync() method to create a subscription to the messages topic. When our application is done listening to this topic, it unsubscribes by passing in the subId returned by subscribe(). After the subscription is removed, no more messages will flow into our myHandlerFunction().

When an application calls unsubscribe(), the client sends an explicit unsubscribe command to AMPS. The AMPS server removes that subscription from the set of subscriptions for the client, and stops sending messages for that subscription. On the client side, the client unregisters the subscription so that the MessageStream or MessageHandler for that subscription will no longer receive messages for that subscription.

Notice that calling unsubscribe does not destroy messages that the server has already sent to the client. If there are messages on the way to the client for this subscription, the AMPS client must consume those messages. If a LastChanceMessageHandler is registered, the handler will receive the messages. Otherwise, they will be discarded since no message handler matches the subscription ID on the message.