DeclareExchange Method

Verifies that an exchange exists, potentially creating it if necessary.

Syntax

ANSI (Cross Platform)
int DeclareExchange(const char* lpszChannelName, const char* lpszExchangeName, const char* lpszExchangeType, int bPassive, int bDurable, int bAutoDelete, int bNoWait);

Unicode (Windows)
INT DeclareExchange(LPCWSTR lpszChannelName, LPCWSTR lpszExchangeName, LPCWSTR lpszExchangeType, BOOL bPassive, BOOL bDurable, BOOL bAutoDelete, BOOL bNoWait);
- (void)declareExchange:(NSString*)channelName :(NSString*)exchangeName :(NSString*)exchangeType :(BOOL)passive :(BOOL)durable :(BOOL)autoDelete :(BOOL)noWait;
#define MID_AMQPCLASSIC_DECLAREEXCHANGE 10

IPWORKSMQ_EXTERNAL int IPWORKSMQ_CALL IPWorksMQ_AMQPClassic_Do(void *lpObj, int methid, int cparam, void *param[], int cbparam[], int64 *lpllVal);

Remarks

This method is used to verify that an exchange named ExchangeName exists; and potentially creates it if no such exchange exists.

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.

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

ExchangeType specifies the exchange type. All servers support the direct and fanout exchange types, and most should also support the topic and header exchange types. Some servers may support additional, custom exchange types as well. Refer to your server's documentation for more information about each exchange type, and to determine what exchange types it supports other than direct and fanout.

If Passive is True, the server will only verify that an exchange with the given ExchangeName actually exists (regardless of how it is configured).

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

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

Durable specifies what happens to the exchange in the event of a server restart. Durable exchanges will be recreated, while non-durable (transient) exchanges will not.

AutoDelete specifies whether the server should automatically delete the exchange when all queues have been unbound from it. Note that this parameter is only sent if the RabbitMQCompatible configuration setting is enabled; it is ignored otherwise.

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, 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.
  • The value passed for ExchangeType did not correspond to an exchange type supported by the server.

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 an Exchange

// Declare a direct-type exchange.
amqpc1.DeclareExchange("channel", "MyExchange", "direct", false, false, false, false);

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

Copyright (c) 2022 /n software inc. - All rights reserved.
IPWorks MQ 2020 C++ Edition - Version 20.0 [Build 8155]