declareQueue (method)

Verifies that a queue exists, potentially creating it if necessary.

Syntax

- (void)declareQueue:(NSString*)channelName :(NSString*)queueName :(BOOL)passive :(BOOL)durable :(BOOL)exclusive :(BOOL)autoDelete :(BOOL)noWait;
public func declareQueue(_ channelName: String, _ queueName: String, _ passive: Bool, _ durable: Bool, _ exclusive: Bool, _ autoDelete: Bool, _ noWait: Bool) throws -> Void

Remarks

This method is used to verify that a queue named QueueName exists; and potentially creates it if no such queue exists.

After each successful call to this method, the class populates the QueueMessageCount property, as well as the QueueConsumerCount and QueueName configuration settings. Refer to each one for more information.

ChannelName controls what channel the class will send the request over. While any channel can technically be used, keep in mind that the server will close it if a channel error occurs. For this reason, it is good practice to make requests such as this one using a channel that is not involved in message publishing or consumption.

If creating a new queue, empty string can be passed for QueueName to have the server automatically generate a name for the new queue (which can then be retrieved using the QueueName configuration setting). In all other cases, QueueName must be a non-empty string consisting only of letters, digits, hyphens, underscores, periods, and colons. It must be no longer than 255 characters, and must not begin with amq. unless the Passive parameter is True.

If Passive is True, the server will only verify that a queue with the given QueueName actually exists (regardless of how it is configured).

If Passive is False, and no queue named QueueName currently exists, the server will create one.

If Passive is False, and there is a preexisting queue named QueueName, the server will verify that its current configuration matches the given parameters and arguments.

Durable specifies what happens to the queue in the event of a server restart. Durable queue will be recreated, while non-durable (transient) queue will not. (Note that the messages in durable queues will still be lost unless they are marked as persistent.)

Exclusive, if True, indicates that the queue may only be accessed by the current connection. Exclusive queues are deleted when the current connection closes.

AutoDelete specifies whether the server should automatically delete the queue when all consumers have finished using it. (Note that auto-delete queues aren't eligible for deletion until after a consumer attaches to them for the first time.)

The NoWait parameter, if True, will cause the server to execute the request asynchronously. For asynchronous request handling, the server only sends back a response in case of an error.

Additional arguments may be sent with this request by adding them to the Argument* properties. Arguments are server-dependent; refer to your server's documentation to determine if any additional arguments apply for this request.

An exception is thrown if no channel with the given ChannelName exists, if QueueName empty string and NoWait is True, or if the server returns an error because:

  • One of the parameter constraints described above was violated.
  • One of the verification cases described above fails.
  • An attempt was made to verify (i.e., the Passive parameter was True) another connection's exclusive queue.

Note that in AMQP, server errors are grouped into "connection errors" and "channel errors", and both are fatal. That is, if the server returns a channel error, it will then close the channel which caused the error; and if it returns a connection error, it will then close the connection. The AMQPClassic class's Error Codes page includes AMQP's various connection and channel errors.

Declaring a Queue

// Declare a queue.
amqpc1.DeclareQueue("channel", "MyQueue", false, false, false, false, false);

Copyright (c) 2022 /n software inc. - All rights reserved.
IPWorks IoT 2020 iOS Edition - Version 20.0 [Build 8265]