public class Subscription

Summary

Manages a subscription to a queue or exchange.

Remarks

This convenience class abstracts away from much of the detail involved in receiving messages from a queue or an exchange.

Once created, the Subscription consumes from a queue (using a QueueingBasicConsumer). Received deliveries can be retrieved by calling Next(), or by using the Subscription as an IEnumerator in, for example, a foreach loop.

Note that if the "noAck" option is enabled (which it is by default), then received deliveries are automatically acked within the server before they are even transmitted across the network to us. Calling Ack() on received events will always do the right thing: if "noAck" is enabled, nothing is done on an Ack() call, and if "noAck" is disabled, IModel.BasicAck() is called with the correct parameters.

Property Summary

Flags Type Name Summary
public IBasicConsumer Consumer (r)

Retrieve the IBasicConsumer that is receiving the messages from the server for us. Normally, you will not need to access this property - use Next() and friends instead.

public string ConsumerTag (r)

Retrieve the consumer-tag that this subscription is using. Will usually be a server-generated name.

public BasicDeliverEventArgs LatestEvent (r)

Returns the most recent value returned by Next(), or null when either no values have been retrieved yet, the end of the subscription has been reached, or the most recent value has already been Ack()ed. See also the documentation for Ack().

public IModel Model (r)

Retrieve the IModel our subscription is carried by.

public bool NoAck (r)

Returns true if we are in "noAck" mode, where calls to Ack() will be no-ops, and where the server acks messages before they are delivered to us. Returns false if we are in a mode where calls to Ack() are required, and where such calls will actually send an acknowledgement message across the network to the server.

public string QueueName (r)

Retrieve the queue name we have subscribed to.

Constructor Summary

Flags Name Summary
public Subscription(IModel model, string queueName, bool noAck)

Creates a new Subscription, with full control over both "noAck" mode and the name of the queue.

public Subscription(IModel model, string queueName)

Creates a new Subscription in "noAck" mode, consuming from a named queue.

Method Summary

Flags Name Summary
public void Ack()

If LatestEvent is non-null, passes it to Ack(BasicDeliverEventArgs). Causes LatestEvent to become null.

public void Ack(BasicDeliverEventArgs evt)

If we are not in "noAck" mode, calls IModel.BasicAck with the delivery-tag from the passed in event; otherwise, sends nothing to the server. In both cases, if the passed-in event is the same as LatestEvent (by pointer comparison), sets LatestEvent to null.

public void Close()

Closes this Subscription, cancelling the consumer record in the server.

public bool Next(int millisecondsTimeout, out BasicDeliverEventArgs result)

Retrieves the next incoming delivery in our subscription queue, or times out after a specified number of milliseconds.

public BasicDeliverEventArgs Next()

Retrieves the next incoming delivery in our subscription queue.

Property Detail

public IBasicConsumer Consumer (r)

Summary

Retrieve the IBasicConsumer that is receiving the messages from the server for us. Normally, you will not need to access this property - use Next() and friends instead.

public string ConsumerTag (r)

Summary

Retrieve the consumer-tag that this subscription is using. Will usually be a server-generated name.

public BasicDeliverEventArgs LatestEvent (r)

Summary

Returns the most recent value returned by Next(), or null when either no values have been retrieved yet, the end of the subscription has been reached, or the most recent value has already been Ack()ed. See also the documentation for Ack().

public IModel Model (r)

Summary

Retrieve the IModel our subscription is carried by.

public bool NoAck (r)

Summary

Returns true if we are in "noAck" mode, where calls to Ack() will be no-ops, and where the server acks messages before they are delivered to us. Returns false if we are in a mode where calls to Ack() are required, and where such calls will actually send an acknowledgement message across the network to the server.

public string QueueName (r)

Summary

Retrieve the queue name we have subscribed to.

Constructor Detail

Subscription

public Subscription(IModel model, string queueName, bool noAck)

Parameters
Name Type
model IModel
queueName string
noAck bool

Summary

Creates a new Subscription, with full control over both "noAck" mode and the name of the queue.

Subscription

public Subscription(IModel model, string queueName)

Parameters
Name Type
model IModel
queueName string

Summary

Creates a new Subscription in "noAck" mode, consuming from a named queue.

Method Detail

Ack

public void Ack()

Flags public
Return type void

Summary

If LatestEvent is non-null, passes it to Ack(BasicDeliverEventArgs). Causes LatestEvent to become null.

Ack

public void Ack(BasicDeliverEventArgs evt)

Flags public
Return type void
Parameters
Name Type
evt BasicDeliverEventArgs

Summary

If we are not in "noAck" mode, calls IModel.BasicAck with the delivery-tag from the passed in event; otherwise, sends nothing to the server. In both cases, if the passed-in event is the same as LatestEvent (by pointer comparison), sets LatestEvent to null.

Remarks

Make sure that this method is only called with events that originated from this Subscription - other usage will have unpredictable results.

Close

public void Close()

Flags public
Return type void

Summary

Closes this Subscription, cancelling the consumer record in the server.

Next

public bool Next(int millisecondsTimeout, out BasicDeliverEventArgs result)

Flags public
Return type bool
Parameters
Name Type
millisecondsTimeout int
result out BasicDeliverEventArgs

Summary

Retrieves the next incoming delivery in our subscription queue, or times out after a specified number of milliseconds.

Remarks

Returns false only if the timeout expires before either a delivery appears or the end-of-stream is reached. If false is returned, the out parameter "result" is set to null, but LatestEvent is not updated.

Returns true to indicate a delivery or the end-of-stream.

If a delivery is already waiting in the queue, or one arrives before the timeout expires, it is removed from the queue and placed in the "result" out parameter. If the end-of-stream is detected before the timeout expires, "result" is set to null.

Whenever this method returns true, it updates LatestEvent to the value placed in "result" before returning.

End-of-stream can arise through the action of the Subscription.Close() method, or through the closure of the IModel or its underlying IConnection.

This method does not acknowledge any deliveries at all (but in "noAck" mode, the server will have auto-acknowledged each event before it is even sent across the wire to us).

A timeout of -1 (i.e. System.Threading.Timeout.Infinite) will be interpreted as a command to wait for an indefinitely long period of time for an item or the end of the stream to become available. Usage of such a timeout is equivalent to calling Next() with no arguments (modulo predictable method signature differences).

Next

public BasicDeliverEventArgs Next()

Flags public
Return type BasicDeliverEventArgs

Summary

Retrieves the next incoming delivery in our subscription queue.

Remarks

Returns null when the end of the stream is reached and on every subsequent call. End-of-stream can arise through the action of the Subscription.Close() method, or through the closure of the IModel or its underlying IConnection.

Updates LatestEvent to the value returned.

Does not acknowledge any deliveries at all (but in "noAck" mode, the server will have auto-acknowledged each event before it is even sent across the wire to us).