"deleteMqSession" (jsonAction)
Use the "deleteMqSession" action to disconnect a client's MQ session
The "deleteMqSession" action selects an MQ session by the "clientName" property and either sets its "sessionStatus" to "inactive" or permanently removes it.
To permanently delete a session, you must set the
"permanentlyDeleteSession"property totrue.To deactivate a session, set the
"permanentlyDeleteSession"property tofalseornullor omit the property.
Permanently deleting a session is useful for removing temporary client connections create during testing and troubleshooting and for resetting client sessions so that a device or software can reconnect in the future to recreate the session from scratch.
Deactivating a session is useful for labelling a session as inactive without preventing a device or software form connecting to that session in the future. The server preserves the data for an inactive session so it can continue to associate the session with the messages it previously sent and received.
The action returns an error when a session with the specified "clientName" does not exist or the action fails.
If an MQTT session with the specified "clientName" is connected, this action disconnects it. An MQTT client will typically reconnect after it is disconnected, which automatically recreates the session using the client's session parameters. Thus, you can permanently delete a session to force it to be recreated by the client from scratch. You can also inactivate a session to temporarily disconnect an MQTT client. If the client reconnects, the server sets the "sessionStatus" to "normal". If the client does not reconnect, the "sessionStatus" remains "inactive", which signals that no device or software is using the session.
If you want to prevent any device or software from connecting to an MQ session, use the "alterMqSession" action to set the "sessionStatus" to "banned". The server returns an error for each connection attempt to that session.
Request examples
Minimum
{
"api": "mq",
"action": "deleteMqSession",
"params":
{
"clientName": "a unique MQTT or MQ API client identifier",
"permanentlyDeleteSession": true
},
"authToken": "replaceWithAuthTokenFromCreateSession"
}{
"api": "mq",
"action": "deleteMqSession",
"params":
{
"clientName": "a unique MQTT or MQ API client identifier",
},
"apiVersion": "1.0",
"debug": "max",
"requestId": "optionalUniqueRequestIdFromTheClient",
"authToken": "replaceWithAuthTokenFromCreateSession"
}Use the "deleteMqSession" action to disconnect a client's MQ session
"params" property summariesProperty | Description | Default | Type | Limits (inclusive) | ||
|---|---|---|---|---|---|---|
(optional) specifies the unique name that identifies the client to the FairCom MQ engine |
| string | 0 to 65,550 bytes | |||
(optional) specifies whether or not to delete the session permanently |
| Boolean |
|
The "clientName" property is an optional string of up to 65,550 characters. It is the client identifier (or clientId) in the MQTT protocol. It uniquely identifies an MQ session, which contains information about a client's subscriptions, settings, and queue position of each topic to which the client is subscribed. The FairCom MQ engine stores this information and retrieves it when an MQTT or MQ API client connects.
Connection authorization is done using an account name with a password or a client certificate.
The "clientName" property does not authorize an MQTT or MQ API session. Another authentication technique authorizes the connection, such as an account name and password or a client certificate. Thus, any account may be used to authorize an MQ connection. Each account is assigned to roles that authorize access to specific topics, client names, actions, etc.
The MQ API allows multiple processes to simultaneously use the same client name to manage sessions, subscribe to topics, send messages to topics, and retrieve messages from topics.
The MQTT protocol allows only one connection per client identifier because each connection is stateful. If another client with the same "clientName" is already connected, the FairCom server disconnects the other client and vice-versa.
The "permanentlyDeleteSession" property is a Boolean that specifies whether or not you want to permanently delete the specified session.
When set to true, it permanently deletes a session and removes its data from the server.
When set to false, it marks a session as deleted without removing the session's data.