Skip to main content

amqp.openconnection(url, callback)

Initiates and manages a connection between the agent and a remote AMQP message broker

Availability

Agent

Parameters

Name Type Description
url String The URL of the AMQP broker with which the connection will be established
callback Function A function that will be called at key moments during the life of the object

Returns

An amqpconnection object

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);