amqp.openconnection(url, callback)

Description

Important Note Agent AMQP functionality is now deprecated and will shortly become unsupported. Any attempt to interact with imp API amqp objects and methods on unregistered development devices or on production devices will generate a runtime error.

If you are using or intend to use Azure IoTHub, we recommend you make use of MQTT instead of AMQP. Please see our Azure IoT Hub integration for more information.

---

This method opens a new AMQP connection to the specified URL. It returns an amqpconnection object which is used to manage individual AMQP sessions.

The callback parameter takes a reference to a function which may be called many times throughout the lifetime of the connection in response to specific events. The function passed into callback has the following parameters of its own:

Parameter	Type	Description
event	String	A constant representing the type of event that triggered the callback
errorDetail	String or null	In the event of an error, an error description, otherwise null

In the initial implementation, errorDetail is only populated in the event of an error.

event Value	errorDetail Value
CONNECTION_OPEN	null
CONNECTION_CLOSED	null
CONNECTION_ERROR	An error message string
SESSION_OPEN	null
SESSION_CLOSED	null
SESSION_ERROR	An error message string
SENDER_OPEN	null
SENDER_CLOSED	null
SENDER_ERROR	An error message string
RECEIVER_OPEN	null
RECEIVER_CLOSED	null
RECEIVER_ERROR	An error message string

amqpconnection objects are automatically closed when they are deallocated, which occurs (also automatically) when they go out of scope. To manually close an amqpconnection, it must be deallocated by setting it to null.

Example

What follows is a typical implementation of openconnection(), here used to access Microsoft Azure’s IoT Hub. The callback function, amqpConnectionManager(), examines the passed in value of event and takes the appropriate action: when the connection opens, a session is created; when the session opens, a sender is established; when the sender is ready, the code can begin sending messages to the broker.

const HUB_NAME = "<YOUR_HUB_NAME>";

conn <- null;
session <- null;
sender <- null;
transfer <- null;

function amqpConnectionManager(event, errorDetail) {
  // Received an event from the AMQP connection
  if (errorDetail) {
    server.error(errorDetail);
  } else {
    switch(event) {
      case "CONNECTION_OPEN":
        session = conn.opensession(amqpConnectionManager);
        break;

      case "SESSION_OPEN":
        if (session) sender = session.opensender("$cbs", amqpConnectionManager);
        break;

      case "SENDER_OPEN":
        if (sender) {
          transfer = sender.createtransfer(amqp.createmessage("Hello!"));
          transfer.sendasync(function() {
            server.log("Message transferred");
          });
        }
    }
  }
}

// Initiate the connection
local url = "amqps://" + HUB_NAME + ".azure-devices.net:5671";
conn = amqp.openconnection(url, amqpConnectionManager);