AMQPClassic Class
Properties Methods Events Configuration Settings Errors
An easy-to-use AMQP 0.9.1 client implementation, with support for RabbitMQ extensions.
Syntax
ipworksiot.amqpclassic()
Remarks
The AMQPClassic class provides an easy-to-use AMQP 0.9.1 client implementation, and it also supports certain RabbitMQ extensions to the AMQP 0.9.1 specification. The class supports both plaintext and TLS-enabled connections over TCP.
Connecting
The AMQP 0.9.1 transport protocol has two layers: an overall connection between the client and server, and one or more channels running over that connection.
The class implements both layers, so the first step is to initiate the overall connection. Set the AuthScheme, User, Password, SSLEnabled, and VirtualHost properties if necessary, then call the Connect method, passing it the server's hostname and port number. (If the server in question is not running RabbitMQ, disabling the RabbitMQCompatible configuration setting before connecting is also recommended.)
The next step is to create at least one channel, which can be accomplished by using the CreateChannel method. The class allows creating any number of channels, up to the limit specified by the MaxChannelCount configuration setting.
Connecting and Creating a Channel
// The examples in this documentation use a RabbitMQ server, which requires SASL Plain auth.
amqpc1.AuthScheme = AmqpclassicAuthSchemes.smSASLPlain;
amqpc1.User = "guest";
amqpc1.Password = "guest";
amqpc1.SSLEnabled = true;
amqpc1.Connect("amqpclassic.test-server.com", 5671);
amqpc1.CreateChannel("channel");
Once the class has connected to the server, and one or more channels have been opened, the class can begin manipulating exchanges and queues, publishing messages, and creating consumers.
Note that most AMQP 0.9.1 operations can themselves vary in their complexity. The examples below are intentionally simple for the sake of clarity and brevity, but links are provided for many other parts of the class's API where more detail can be found.
Declaring Exchanges
The DeclareExchange method is used to declare (i.e., create, or verify the existence of) exchanges on the server. While all AMQP servers provide a default, direct-type exchange that all queues are bound to automatically (using their name as the routing key), more complex use-cases will often require creating additional exchanges of varying types.
Declaring an Exchange
// Declare a direct-type exchange.
amqpc1.DeclareExchange("channel", "MyExchange", "direct", false, false, false, false);
Exchanges can also be deleted using the DeleteExchange method.
Declaring Queues
The DeclareQueue method is used to declare (i.e., create, or verify the existence of) queues on the server. Unlike with exchanges, the server does not provide any queues by default, so declaring a queue is always necessary (unless one has already been created by another client, or configured ahead-of-time on the server itself).
Declaring a Queue
// Declare a queue.
amqpc1.DeclareQueue("channel", "MyQueue", false, false, false, false, false);
Queues may also be deleted or purged using the DeleteQueue and PurgeQueue methods.
Binding Queues to Exchanges
The BindQueue method is used to bind a queue to an exchange. Exchanges use the information held by their queue bindings to determine which messages to forward to which queues.
Note that all AMQP 0.9.1 servers automatically bind all queues to their default exchange (which is always a direct exchange with no name) using each queue's name as the binding's routing key. This makes it easy to send a message to a specific queue without having to declare bindings; just call PublishMessage, pass empty string for ExchangeName, and the name of the desired queue for RoutingKey.
Binding a Queue to an Exchange
// Bind a queue to an exchange. Messages will only be delivered to the queue if their routing key is "MyRoutingKey".
amqpc1.BindQueue("channel", "MyQueue", "MyExchange", "MyRoutingKey", false);
Queues can also be unbound from exchanges using the UnbindQueue method.
Publishing Messages
To publish a message, populate the Message* properties, and then call the PublishMessage method.
Publishing a Message
amqpc1.Message.Body = "Hello, world!";
// Publish a message to the server's default (no-name) exchange, using the name of a specific queue as the routing key.
amqpc1.PublishMessage("channel", "", "MyQueue", false, false);
// Publish a message to the "MyExchange" exchange, using the routing key "MyRoutingKey".
amqpc1.PublishMessage("channel", "MyExchange", "MyRoutingKey", false, false);
Note that outgoing messages may be handled differently by the server if the channel they are sent over is in transaction or (for RabbitMQ only) "publish confirmations" mode. Refer to the EnableTransactionMode and EnablePublishConfirms methods for more information.
Receiving Messages
There are two possible ways for the class to receive a message:
- Messages can be asynchronously pushed to the class from the server. At any point in time, the server may push a message to the class from a queue that the Consume method has been used to attach a consumer to.
- Messages can be synchronously pulled from the server by the class. The FetchMessage method is used to attempt to pull (or "fetch") messages from a specific queue.
Regardless of how they are received, all incoming messages cause the ReceivedMessage* properties to be populated and the MessageIn event to fire.
Receiving a Message
// MessageIn event handler.
amqpc1.OnMessageIn += (s, e) => {
if (e.MessageCount == -1) {
// The server pushed a message to us asynchronously due to a consumer we created.
Console.WriteLine("The server pushed this message to us via consumer '" + e.ConsumerTag + "':");
Console.WriteLine(amqpc1.ReceivedMessage.Body);
} else if (e.DeliveryTag > 0) {
// We pulled a message from a queue with the FetchMessage() method.
Console.WriteLine("Message successfully pulled:");
Console.WriteLine(amqpc1.ReceivedMessage.Body);
Console.WriteLine(e.MessageCount + " messages are still available to pull.");
} else {
// We tried to pull a message, but there were none available to pull.
Console.WriteLine("No messages available to pull.");
}
};
// Attach a consumer to "MyQueue".
amqpc1.Consume("channel", "MyQueue", "consumerTag", false, true, false, false);
// Or, try to fetch a message from "MyQueue".
amqpc1.FetchMessage("channel", "MyQueue", true);
Note that the MessageIn event always fires if FetchMessage is called successfully, even if there were no messages available to fetch; refer to MessageIn for more information.
Property List
The following is the full list of the properties of the class with short descriptions. Click on the links for further details.
ArgumentCount | The number of records in the Argument arrays. |
ArgumentName | The table property's name. |
ArgumentValue | The table property's value. |
ArgumentValueType | The table property's value type. |
AuthScheme | The authentication scheme to use when connecting. |
ChannelCount | The number of records in the Channel arrays. |
ChannelAccept | Whether the channel is currently accepting new messages from the server. |
ChannelMode | What mode the channel is operating in. |
ChannelName | The name of the channel. |
ChannelReadyToSend | Whether the channel is ready to send a message. |
ClientPropertyCount | The number of records in the ClientProperty arrays. |
ClientPropertyName | The table property's name. |
ClientPropertyValue | The table property's value. |
ClientPropertyValueType | The table property's value type. |
Connected | Triggers a connection or disconnection. |
FirewallAutoDetect | This property tells the class whether or not to automatically detect and use firewall system settings, if available. |
FirewallType | This property determines the type of firewall to connect through. |
FirewallHost | This property contains the name or IP address of firewall (optional). |
FirewallPassword | This property contains a password if authentication is to be used when connecting through the firewall. |
FirewallPort | This property contains the TCP port for the firewall Host . |
FirewallUser | This property contains a user name if authentication is to be used connecting through a firewall. |
Heartbeat | The heartbeat timeout value. |
IncomingMessageCount | The number of records in the IncomingMessage arrays. |
IncomingMessageAppId | The Id of the application that created the message. |
IncomingMessageBody | The message body. |
IncomingMessageChannelName | The name of the channel the message is associated with. |
IncomingMessageContentEncoding | The content encoding of the message's body. |
IncomingMessageContentType | The content type (MIME type) of the message's body. |
IncomingMessageCorrelationId | The correlation Id of the message. |
IncomingMessageDeliveryMode | The delivery mode of the message. |
IncomingMessageExpiration | The time-to-live value for this message. |
IncomingMessageHeaders | Headers associated with the message. |
IncomingMessageId | The unique Id of the message. |
IncomingMessagePriority | The priority of the message. |
IncomingMessageReplyTo | The address to send replies to for the message. |
IncomingMessageTimestamp | The message's timestamp. |
IncomingMessageType | The message's type. |
IncomingMessageUserId | The identity of the user responsible for producing the message. |
LocalHost | The name of the local host or user-assigned IP interface through which connections are initiated or accepted. |
LocalPort | The TCP port in the local host where the class binds. |
MessageAppId | The Id of the application that created the message. |
MessageBody | The message body. |
MessageChannelName | The name of the channel the message is associated with. |
MessageContentEncoding | The content encoding of the message's body. |
MessageContentType | The content type (MIME type) of the message's body. |
MessageCorrelationId | The correlation Id of the message. |
MessageDeliveryMode | The delivery mode of the message. |
MessageExpiration | The time-to-live value for this message. |
MessageHeaders | Headers associated with the message. |
MessageId | The unique Id of the message. |
MessagePriority | The priority of the message. |
MessageReplyTo | The address to send replies to for the message. |
MessageTimestamp | The message's timestamp. |
MessageType | The message's type. |
MessageUserId | The identity of the user responsible for producing the message. |
OutgoingMessageCount | The number of records in the OutgoingMessage arrays. |
OutgoingMessageAppId | The Id of the application that created the message. |
OutgoingMessageBody | The message body. |
OutgoingMessageChannelName | The name of the channel the message is associated with. |
OutgoingMessageContentEncoding | The content encoding of the message's body. |
OutgoingMessageContentType | The content type (MIME type) of the message's body. |
OutgoingMessageCorrelationId | The correlation Id of the message. |
OutgoingMessageDeliveryMode | The delivery mode of the message. |
OutgoingMessageExpiration | The time-to-live value for this message. |
OutgoingMessageHeaders | Headers associated with the message. |
OutgoingMessageId | The unique Id of the message. |
OutgoingMessagePriority | The priority of the message. |
OutgoingMessageReplyTo | The address to send replies to for the message. |
OutgoingMessageTimestamp | The message's timestamp. |
OutgoingMessageType | The message's type. |
OutgoingMessageUserId | The identity of the user responsible for producing the message. |
Password | A password to use for SASL authentication. |
QueueMessageCount | The message count returned by various queue operations. |
ReceivedMessageAppId | The Id of the application that created the message. |
ReceivedMessageBody | The message body. |
ReceivedMessageChannelName | The name of the channel the message is associated with. |
ReceivedMessageContentEncoding | The content encoding of the message's body. |
ReceivedMessageContentType | The content type (MIME type) of the message's body. |
ReceivedMessageCorrelationId | The correlation Id of the message. |
ReceivedMessageDeliveryMode | The delivery mode of the message. |
ReceivedMessageExpiration | The time-to-live value for this message. |
ReceivedMessageHeaders | Headers associated with the message. |
ReceivedMessageId | The unique Id of the message. |
ReceivedMessagePriority | The priority of the message. |
ReceivedMessageReplyTo | The address to send replies to for the message. |
ReceivedMessageTimestamp | The message's timestamp. |
ReceivedMessageType | The message's type. |
ReceivedMessageUserId | The identity of the user responsible for producing the message. |
RemoteHost | The address of the remote host. Domain names are resolved to IP addresses. |
RemotePort | The port of the AQMP server (default is 5672). The default port for SSL is 5671. |
ServerPropertyCount | The number of records in the ServerProperty arrays. |
ServerPropertyName | The table property's name. |
ServerPropertyValue | The table property's value. |
ServerPropertyValueType | The table property's value type. |
SSLAcceptServerCertEncoded | The certificate (PEM/base64 encoded). |
SSLCertEncoded | The certificate (PEM/base64 encoded). |
SSLCertStore | The name of the certificate store for the client certificate. |
SSLCertStorePassword | If the certificate store is of a type that requires a password, this property is used to specify that password in order to open the certificate store. |
SSLCertStoreType | The type of certificate store for this certificate. |
SSLCertSubject | The subject of the certificate used for client authentication. |
SSLEnabled | Whether TLS/SSL is enabled. |
SSLServerCertEncoded | The certificate (PEM/base64 encoded). |
Timeout | A timeout for the class. |
User | A username to use for SASL authentication. |
VirtualHost | The virtual host to connect to. |
Method List
The following is the full list of the methods of the class with short descriptions. Click on the links for further details.
BindQueue | Binds a queue to an exchange. |
CancelConsume | Cancels an existing consumer. |
CloseChannel | Closes a channel. |
CommitTransaction | Commits the current transaction for a channel. |
Config | Sets or retrieves a configuration setting. |
Connect | Connects to a remote host. |
Consume | Starts a new consumer for a given queue. |
CreateChannel | Creates a new channel. |
DeclareExchange | Verifies that an exchange exists, potentially creating it if necessary. |
DeclareQueue | Verifies that a queue exists, potentially creating it if necessary. |
DeleteExchange | Deletes an exchange. |
DeleteQueue | Deletes a queue. |
Disconnect | Disconnects from the remote host. |
DoEvents | Processes events from the internal message queue. |
EnablePublishConfirms | Enables publish confirmations mode for a channel. |
EnableTransactionMode | Enables transaction mode for a channel. |
FetchMessage | Attempts to fetch a message from a given queue. |
Interrupt | Interrupt the current action and disconnects from the remote host. |
PublishMessage | Publishes a message. |
PurgeQueue | Purges all messages from a queue. |
Recover | Request that the server redeliver all messages on a given channel that have not been acknowledged. |
Reset | Reset the class. |
ResetMessage | Resets the Message properties. |
RollbackTransaction | Rolls back the current transaction for a channel. |
SetChannelAccept | Disables or enables message acceptance for a given channel. |
SetQoS | Requests a specific quality of service (QoS). |
UnbindQueue | Removes a previously-created queue binding. |
Event List
The following is the full list of the events fired by the class with short descriptions. Click on the links for further details.
ChannelReadyToSend | Fires when a channel is ready to send messages. |
Connected | Fired immediately after a connection completes (or fails). |
ConnectionStatus | Fired to indicate changes in connection state. |
Disconnected | Fired when a connection is closed. |
Error | Information about errors during data delivery. |
Log | Fires once for each log message. |
MessageIn | Fires when a message is received; as well as when an attempt is made to fetch a message from a currently empty queue. |
MessageOut | Fires when a message is published. |
MessageReturned | Fires if a previously published message is returned by the server due to it being undeliverable. |
SSLServerAuthentication | Fired after the server presents its certificate to the client. |
SSLStatus | Shows the progress of the secure connection. |
Configuration Settings
The following is a list of configuration settings for the class with short descriptions. Click on the links for further details.
AuthorizationIdentity | The value to use as the authorization identity when SASL authentication is used. |
ConsumerTag | The consumer tag associated with the most recently created consumer. |
Locale | The desired message locale to use. |
Locales | The message locales supported by the server. |
LogLevel | The level of detail that is logged. |
MaxChannelCount | The maximum number of channels. |
MaxFrameSize | The maximum frame size. |
Mechanisms | The authentication mechanisms supported by the server. |
NackMultiple | Whether negative acknowledgments should be cumulative or not. |
ProtocolVersion | The AMQP protocol version to conform to. |
QueueConsumerCount | The consumer count associated with the most recently created (or verified) queue. |
QueueName | The queue name associated with the most recently created (or verified) queue. |
RabbitMQCompatible | Whether to operate in a mode compatible with RabbitMQ. |
ConnectionTimeout | Sets a separate timeout value for establishing a connection. |
FirewallAutoDetect | Tells the class whether or not to automatically detect and use firewall system settings, if available. |
FirewallHost | Name or IP address of firewall (optional). |
FirewallPassword | Password to be used if authentication is to be used when connecting through the firewall. |
FirewallPort | The TCP port for the FirewallHost;. |
FirewallType | Determines the type of firewall to connect through. |
FirewallUser | A user name if authentication is to be used connecting through a firewall. |
KeepAliveInterval | The retry interval, in milliseconds, to be used when a TCP keep-alive packet is sent and no response is received. |
KeepAliveTime | The inactivity time in milliseconds before a TCP keep-alive packet is sent. |
Linger | When set to True, connections are terminated gracefully. |
LingerTime | Time in seconds to have the connection linger. |
LocalHost | The name of the local host through which connections are initiated or accepted. |
LocalPort | The port in the local host where the class binds. |
MaxLineLength | The maximum amount of data to accumulate when no EOL is found. |
MaxTransferRate | The transfer rate limit in bytes per second. |
ProxyExceptionsList | A semicolon separated list of hosts and IPs to bypass when using a proxy. |
TCPKeepAlive | Determines whether or not the keep alive socket option is enabled. |
TcpNoDelay | Whether or not to delay when sending packets. |
UseIPv6 | Whether to use IPv6. |
LogSSLPackets | Controls whether SSL packets are logged when using the internal security API. |
OpenSSLCADir | The path to a directory containing CA certificates. |
OpenSSLCAFile | Name of the file containing the list of CA's trusted by your application. |
OpenSSLCipherList | A string that controls the ciphers to be used by SSL. |
OpenSSLPrngSeedData | The data to seed the pseudo random number generator (PRNG). |
ReuseSSLSession | Determines if the SSL session is reused. |
SSLCACertFilePaths | The paths to CA certificate files on Unix/Linux. |
SSLCACerts | A newline separated list of CA certificate to use during SSL client authentication. |
SSLCheckCRL | Whether to check the Certificate Revocation List for the server certificate. |
SSLCipherStrength | The minimum cipher strength used for bulk encryption. |
SSLEnabledCipherSuites | The cipher suite to be used in an SSL negotiation. |
SSLEnabledProtocols | Used to enable/disable the supported security protocols. |
SSLEnableRenegotiation | Whether the renegotiation_info SSL extension is supported. |
SSLIncludeCertChain | Whether the entire certificate chain is included in the SSLServerAuthentication event. |
SSLNegotiatedCipher | Returns the negotiated ciphersuite. |
SSLNegotiatedCipherStrength | Returns the negotiated ciphersuite strength. |
SSLNegotiatedCipherSuite | Returns the negotiated ciphersuite. |
SSLNegotiatedKeyExchange | Returns the negotiated key exchange algorithm. |
SSLNegotiatedKeyExchangeStrength | Returns the negotiated key exchange algorithm strength. |
SSLNegotiatedVersion | Returns the negotiated protocol version. |
SSLProvider | The name of the security provider to use. |
SSLSecurityFlags | Flags that control certificate verification. |
SSLServerCACerts | A newline separated list of CA certificate to use during SSL server certificate validation. |
TLS12SignatureAlgorithms | Defines the allowed TLS 1.2 signature algorithms when UseInternalSecurityAPI is True. |
TLS12SupportedGroups | The supported groups for ECC. |
TLS13KeyShareGroups | The groups for which to pregenerate key shares. |
TLS13SignatureAlgorithms | The allowed certificate signature algorithms. |
TLS13SupportedGroups | The supported groups for (EC)DHE key exchange. |
AbsoluteTimeout | Determines whether timeouts are inactivity timeouts or absolute timeouts. |
FirewallData | Used to send extra data to the firewall. |
InBufferSize | The size in bytes of the incoming queue of the socket. |
OutBufferSize | The size in bytes of the outgoing queue of the socket. |
BuildInfo | Information about the product's build. |
CodePage | The system code page used for Unicode to Multibyte translations. |
LicenseInfo | Information about the current license. |
ProcessIdleEvents | Whether the class uses its internal event loop to process events when the main thread is idle. |
SelectWaitMillis | The length of time in milliseconds the class will wait when DoEvents is called if there are no events to process. |
UseInternalSecurityAPI | Tells the class whether or not to use the system security libraries or an internal implementation. |