"describeBrokerConnections" (JSON Action)
JSON MQ and Hub "describeBrokerConnections" action returns info about broker connections
The "describeBrokerConnections" action returns all available information about specified broker connections.
Request examples
Minimal
{
"api": "mq",
"action": "describeBrokerConnections",
"params": {
"brokerConnectionNames": [ "MqttBroker1" ]
},
"authToken": "replaceWithAuthTokenFromCreateSession"
}{
"result": {
"brokerConnectionNames": [
{
"brokerHostname": "https://mqtt.faircom.com/",
"brokerPort": 1883,
"brokerUserName": "",
"reconnectFrequencySeconds": 15,
"isConnected": true,
"statusCode": 9026,
"statusMessage": "Not able to connect thread to MQTT broker"
}
]
},
"requestId": "00000056",
"errorCode": 0,
"errorMessage": ""
}The "describeBrokerConnections" JSON action retrieves information about broker connections, including hostname, port, username, reconnect frequency, connection status, status code, and status message.
The "params" property is an object that contains an action's request parameters as defined by a set of properties. Each action defines its own required and optional properties. See System limits for a comprehensive overview of property requirements and limitations.
"params" property summariesProperty | Description | Default | Type | Limits (inclusive) | |||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
(optional) contains a list of |
| array |
|
The "brokerConnectionNames" property is a required array that contains a list of "brokerConnectionName" strings. It defaults to an empty array.
Must contain at least one string.
Each string is the name of a table.
A zero-length string is invalid.
A client should force uniqueness of the items in the array because the server ignores duplicate items.
"result" property summariesProperty | Description | Type | Contents | ||||
|---|---|---|---|---|---|---|---|
lists information about each requested broker connection that matches the values for the | array of objects | 1 object for each broker connection matching the request. | |||||
| indicates the unique broker host name or TCP/IP address. | string | the unique broker host name or TCP/IP address of the specified broker connection. | ||||
| indicates the TCP/IP port. | integer | the TCP/IP port of the specified broker connection. | ||||
| indicates the login name to the external broker. | string | the login name to the external broker. | ||||
| indicates the number of seconds that the broker waits between attempts to reconnect to an external broker. | int32 | the number of seconds the broker will wait between attempts to reconnect to an external broker. | ||||
| indicates whether the specified broker connection is active. | Boolean |
| ||||
| indicates the status code for the broker connection. | integer | See error codes | ||||
| describes the status code with a written explanation. | string | 0 to 1024 bytes |
The "brokerConnectionNames" property is a required array that contains a list of "brokerConnectionName" strings. It defaults to an empty array.
Must contain at least one string.
Each string is the name of a table.
A zero-length string is invalid.
A client should force uniqueness of the items in the array because the server ignores duplicate items.
The "brokerHostname" property is required. It must not be a zero-length string or contain only whitespace. It has a maximum length of 255 characters.
When creating a new broker connection, FairCom's servers log an error stating, "Cannot create the broker connection named xxx because brokerHostname is empty."
When updating an existing broker connection, FairCom's servers log an error stating, "Cannot update the broker connection named xxx because the new "brokerHostname" is empty. The current brokerHostname xxx and brokerPort xxx remain unchanged."
The "brokerPort" property is optional. It defines the TCP/IP port. If it is not present, it defaults to 1883.
If present, it must be a number between
1and65535inclusive.If the port is already in use, FairCom's server will not be able to run.
When it is set to a non-numeric value, or is out of range, FairCom's servers log an error stating, "Cannot create the broker connection named xxx because the brokerPort property is missing or is set to an invalid value. It must be present and set to a number greater than zero and less than 65536."
The "brokerUsername" property is the login name to the external broker. This property is an optional string from 1 to 64 bytes. If omitted, it defaults to an empty string.
Note
Unlike some other properties containing the "name", the "name" in "brokerUsername" is all lowercase.
A zero-length username is invalid.
It is VARCHAR(500).
The "reconnectFrequencySeconds" property is the number of seconds that the broker waits between attempts to reconnect to an external broker. This property is optional. If omitted, it defaults to 15 seconds.
If it is set to
0, the broker does not attempt to reconnect when it loses a connection or fails to connect.FairCom's servers attempt to connect to an external broker when it is configured as a subscriber to topics on an external broker or when it is configured to forward messages to an external broker.
To stop the reconnect process, send the
"configureBrokerConnection"message with the command property set to"disconnect".To restart the reconnect process, send the
"configureBrokerConnection"message with the command property set to"reconnect".
The "isConnected" property indicates whether the specified broker connection is active.
"brokerConnectionNames": [
{
"brokerHostname": "mqtt.faircom.com",
"brokerPort": 1883,
"brokerUserName": "",
"reconnectFrequencySeconds": 15,
"isConnected": true,
"statusCode": 14226,
"statusMessage": "Not able to connect thread to MQTT broker"
}
]The "statusCode" property displays the status code for the specified broker connection.
"brokerConnectionNames": [
{
"brokerHostname": "mqtt.faircom.com",
"brokerPort": 1883,
"brokerUserName": "",
"reconnectFrequencySeconds": 15,
"isConnected": true,
"statusCode": 14226,
"statusMessage": "Not able to connect thread to MQTT broker"
}
]The "statusMessage" property describes the status code with a written explanation.
"brokerConnectionNames": [
{
"brokerHostname": "mqtt.faircom.com",
"brokerPort": 1883,
"brokerUserName": "",
"reconnectFrequencySeconds": 15,
"isConnected": true,
"statusCode": 14226,
"statusMessage": "Not able to connect thread to MQTT broker"
}
]