publishMessage (method)

Publishes a message with a string payload.

Syntax

- (void)publishMessage:(NSString*)topic :(int)QOS :(NSString*)message;
public func publishMessage(_ topic: String, _ QOS: Int32, _ message: String) throws -> Void

Remarks

This method publishes an MQTT message with a string payload to the specified Topic at a given QOS level.

Publish Examples

// Publish a simple string-based message.
mqtt1.PublishMessage("/home/floor1/security/camera2", 1, "Cat detected!");

// Publish a raw data message.
byte[] catPicture = ...;
mqtt1.PublishData("/home/floor1/security/camera2", 1, catPicture);

The Retain configuration setting may be set before calling this method in order to publish a retained message (see Retain for more information).

Topic Names

Topic names are case-sensitive, must be 1-65535 characters long, and may include any characters except wildcard characters (# and +) and the null character. The / character separates levels within a topic name, which is important in the context of subscribing (see Subscribe for more information).

Keep in mind that using topic names with leading or trailing / characters will cause topic levels with zero-length names to be created. That is, a topic name like /a/b/ consists of the levels '', 'a', 'b', and ''. Depending on the server, multiple successive /s may also cause zero-length levels to be created, or may be treated as a single /.

Topic names that begin with a $ are "system topics", and servers will typically prevent clients from publishing to them.

For example, topic names that begin with $share are reserved for Shared Subscriptions (see Subscribe).

QoS Values

QoS values set the service level for delivery of a message. Values range from 0 to 2 and have the following meanings:

QoS LevelDescription
0 At most once - The published message is sent once, and if it does not arrive it is lost.
1 At least once - Guarantees that the published message arrives, but there may be duplicates.
2 Exactly once - Guarantees that the publish message arrives and that there are no duplicates.

For outgoing messages with a QoS of 0, the class sends a PUBLISH packet, but does not add the message to OutgoingMessage* (since QoS 0 messages do not get acknowledged).

QoS is not guaranteed to be end-to-end in MQTT. The server must downgrade a message's QoS level when delivering it to clients who specified a lower "maximum acceptable" QoS when they subscribed. For example, if Client X subscribes to a topic at QoS 1, and Client Y publishes a message to that topic at QoS 2, the server will downgrade the message to QoS 1 when attempting to deliver it to Client X.

Outbound Message Processing

Outgoing messages with a QoS of 1 follow these steps:

  1. The class sends the PUBLISH packet, then adds the message to OutgoingMessage*.
  2. The class waits to receive a PUBACK (publish acknowledgment) packet.
  3. The MessageAck event is fired.
  4. The message is removed from OutgoingMessage*.
  5. The MessageOut event is fired.

Outgoing messages with a QoS of 2 follow these steps:

  1. The class sends the PUBLISH packet, then adds the message to OutgoingMessage*.
  2. The class waits to receive a PUBREC (publish received) packet.
  3. The class sends a PUBREL (publish release) packet in response.
  4. The class waits to receive a PUBCOMP (publish complete) packet.
  5. The MessageAck event is fired.
  6. The message is removed from OutgoingMessage*.
  7. The MessageOut event is fired.

In MQTT 3.1.1, the RepublishInterval configuration setting, if set to a non-zero value (default), controls how long the class will wait to receive a PUBACK (for QoS 1) or PUBREC (for QoS 2) before automatically republishing an outgoing message. In MQTT 5, messages are only republished if the client is disconnected before receiving a PUBACK or PUBREC.

MQTT 5 Notes

MQTT 5 makes a number of new features available when publishing messages, including:

  • TopicAlias - Set an integer alias along with the topic name when first publishing a message. When publishing additional messages to the same topic if TopicAlias is set the Topic parameter does not need to be set. This reduces the size of the message sent to the server.
  • Request / Response - Set a ResponseTopic which identifies the topic to which a receiver should respond.

Some of these features require configuration settings to be set prior to publishing. In these cases, note that these configuration settings will continue to be applicable to any future PUBLISH packets sent with the method unless they are updated or reset. To prevent clear a previously set configuration setting, set it to "", or -1 (for integers).

See the OutgoingMessageProperties configuration setting for additional details.

Copyright (c) 2022 /n software inc. - All rights reserved.
IPWorks IoT 2020 iOS Edition - Version 20.0 [Build 8265]