Loading...
Searching...
No Matches
mqtt::message Class Reference

`#include <message.h>`

## Public Types

using | ptr_t = std::shared_ptr<message>
using | const_ptr_t = std::shared_ptr<const message>

## Public Member Functions

| message ()
| message (string_ref topic, const void *payload, size_t len, int qos, bool retained, const properties &props=properties())
| message (string_ref topic, const void *payload, size_t len)
| message (string_ref topic, binary_ref payload, int qos, bool retained, const properties &props=properties())
| message (string_ref topic, binary_ref payload)
| message (string_ref topic, const MQTTAsync_message &cmsg)
| message (const message &other)
| message (message &&other)
| ~message ()
message & | operator= (const message &rhs)
message & | operator= (message &&rhs)
void | set_topic (string_ref topic)
const string_ref & | get_topic_ref () const
const string & | get_topic () const
void | clear_payload ()
const binary_ref & | get_payload_ref () const
const binary & | get_payload () const
const string & | get_payload_str () const
int | get_qos () const
bool | is_duplicate () const
bool | is_retained () const
void | set_payload (binary_ref payload)
void | set_payload (const void *payload, size_t n)
void | set_qos (int qos)
void | set_retained (bool retained)
const properties & | get_properties () const
void | set_properties (const properties &props)
void | set_properties (properties &&props)
string | to_string () const

## Static Public Member Functions

static ptr_t | create (string_ref topic, const void *payload, size_t len, int qos, bool retained, const properties &props=properties())
static ptr_t | create (string_ref topic, const void *payload, size_t len)
static ptr_t | create (string_ref topic, binary_ref payload, int qos, bool retained, const properties &props=properties())
static ptr_t | create (string_ref topic, binary_ref payload)
static ptr_t | create (string_ref topic, const MQTTAsync_message &msg)
static void | validate_qos (int qos)

## Static Public Attributes

static constexpr int | DFLT_QOS = 0
static constexpr bool | DFLT_RETAINED = false

## Friends

class | async_client

## Detailed Description

An MQTT message holds everything required for an MQTT PUBLISH message. This holds the binary message payload, topic string, and all the additional meta-data for an MQTT message.

The topic and payload buffers are kept as references to const data, so they can be reassigned as needed, but the buffers can not be updated in-place. Normally they would be created externally then copied or moved into the message. The library to transport the messages never touches the payloads or topics.

This also means that message objects are fairly cheap to copy, since they don't copy the payloads. They simply copy the reference to the buffers. It is safe to pass these buffer references across threads since all references promise not to update the contents of the buffer.

## Member Typedef Documentation

## ptr_t

using mqtt::message::ptr_t = std::shared_ptr<message>

Smart/shared pointer to this class.

## const_ptr_t

using mqtt::message::const_ptr_t = std::shared_ptr<const message>

Smart/shared pointer to this class.

## Constructor & Destructor Documentation

## message() [1/8]

mqtt::message::message | ( |  | ) |

inline

Constructs a message with an empty payload, and all other values set to defaults.

## message() [2/8]

mqtt::message::message | ( | string_ref | topic,
|  | const void * | payload,
|  | size_t | len,
|  | int | qos,
|  | bool | retained,
|  | const properties & | props = properties() )

Constructs a message with the specified array as a payload, and all other values set to defaults.

Parameters

  topic | The message topic
  payload | the bytes to use as the message payload
  len | the number of bytes in the payload
  qos | The quality of service for the message.
  retained | Whether the message should be retained by the broker.
  props | The MQTT v5 properties for the message.

## message() [3/8]

mqtt::message::message | ( | string_ref | topic,
|  | const void * | payload,
|  | size_t | len )

inline

Constructs a message with the specified array as a payload, and all other values set to defaults.

Parameters

  topic | The message topic
  payload | the bytes to use as the message payload
  len | the number of bytes in the payload

## message() [4/8]

mqtt::message::message | ( | string_ref | topic,
|  | binary_ref | payload,
|  | int | qos,
|  | bool | retained,
|  | const properties & | props = properties() )

Constructs a message from a byte buffer. Note that the payload accepts copy or move semantics.

Parameters

  topic | The message topic
  payload | A byte buffer to use as the message payload.
  qos | The quality of service for the message.
  retained | Whether the message should be retained by the broker.
  props | The MQTT v5 properties for the message.

## message() [5/8]

mqtt::message::message | ( | string_ref | topic,
|  | binary_ref | payload )

inline

Constructs a message from a byte buffer. Note that the payload accepts copy or move semantics.

Parameters

  topic | The message topic
  payload | A byte buffer to use as the message payload.

## message() [6/8]

mqtt::message::message | ( | string_ref | topic,
|  | const MQTTAsync_message & | cmsg )

Constructs a message as a copy of the message structure.

Parameters

  topic | The message topic
  cmsg | A "C" MQTTAsync_message structure.

## message() [7/8]

mqtt::message::message | ( | const message & | other | ) |

Constructs a message as a copy of the other message.

Parameters

  other | The message to copy into this one.

## message() [8/8]

mqtt::message::message | ( | message && | other | ) |

Moves the other message to this one.

Parameters

  other | The message to move into this one.

## ~message()

mqtt::message::~message | ( |  | ) |

inline

Destroys a message and frees all associated resources.

## Member Function Documentation

## create() [1/5]

ptr_t mqtt::message::create | ( | string_ref | topic,
|  | const void * | payload,
|  | size_t | len,
|  | int | qos,
|  | bool | retained,
|  | const properties & | props = properties() )

inline static

Constructs a message with the specified values.

Parameters

  topic | The message topic
  payload | the bytes to use as the message payload
  len | the number of bytes in the payload
  qos | The quality of service for the message.
  retained | Whether the message should be retained by the broker.
  props | The MQTT v5 properties for the message.

## create() [2/5]

ptr_t mqtt::message::create | ( | string_ref | topic,
|  | const void * | payload,
|  | size_t | len )

inline static

Constructs a message with the specified array as a payload, and all other values set to defaults.

Parameters

  topic | The message topic
  payload | the bytes to use as the message payload
  len | the number of bytes in the payload

## create() [3/5]

ptr_t mqtt::message::create | ( | string_ref | topic,
|  | binary_ref | payload,
|  | int | qos,
|  | bool | retained,
|  | const properties & | props = properties() )

inline static

Constructs a message from a byte buffer. Note that the payload accepts copy or move semantics.

Parameters

  topic | The message topic
  payload | A byte buffer to use as the message payload.
  qos | The quality of service for the message.
  retained | Whether the message should be retained by the broker.
  props | The MQTT v5 properties for the message.

## create() [4/5]

ptr_t mqtt::message::create | ( | string_ref | topic,
|  | binary_ref | payload )

inline static

Constructs a message from a byte buffer. Note that the payload accepts copy or move semantics.

Parameters

  topic | The message topic
  payload | A byte buffer to use as the message payload.

## create() [5/5]

ptr_t mqtt::message::create | ( | string_ref | topic,
|  | const MQTTAsync_message & | msg )

inline static

Constructs a message as a copy of the C message struct.

Parameters

  topic | The message topic
  msg | A "C" MQTTAsync_message structure.

## operator=() [1/2]

message & mqtt::message::operator= | ( | const message & | rhs | ) |

Copies another message to this one.

Parameters

  rhs | The other message.

Returns
  A reference to this message.

## operator=() [2/2]

message & mqtt::message::operator= | ( | message && | rhs | ) |

Moves another message to this one.

Parameters

  rhs | The other message.

Returns
  A reference to this message.

## set_topic()

void mqtt::message::set_topic | ( | string_ref | topic | ) |

inline

Expose the underlying C struct for the unit tests. Sets the topic string.

Parameters

  topic | The topic on which the message is published.

## get_topic_ref()

const string_ref & mqtt::message::get_topic_ref | ( |  | ) | const

inline

Gets the topic reference for the message.

Returns
  The topic reference for the message.

## get_topic()

const string & mqtt::message::get_topic | ( |  | ) | const

inline

Gets the topic for the message.

Returns
  The topic string for the message.

## clear_payload()

void mqtt::message::clear_payload | ( |  | ) |

Clears the payload, resetting it to be empty.

## get_payload_ref()

const binary_ref & mqtt::message::get_payload_ref | ( |  | ) | const

inline

Gets the payload reference.

## get_payload()

const binary & mqtt::message::get_payload | ( |  | ) | const

inline

Gets the payload

## get_payload_str()

const string & mqtt::message::get_payload_str | ( |  | ) | const

inline

Gets the payload as a string

## get_qos()

int mqtt::message::get_qos | ( |  | ) | const

inline

Returns the quality of service for this message.

Returns
  The quality of service for this message.

## is_duplicate()

bool mqtt::message::is_duplicate | ( |  | ) | const

inline

Returns whether or not this message might be a duplicate of one which has already been received.

Returns
  true this message might be a duplicate of one which has already been received, false otherwise

## is_retained()

bool mqtt::message::is_retained | ( |  | ) | const

inline

Returns whether or not this message should be/was retained by the server.

Returns
  true if this message should be/was retained by the server, false otherwise.

## set_payload() [1/2]

void mqtt::message::set_payload | ( | binary_ref | payload | ) |

Sets the payload of this message to be the specified buffer. Note that this accepts copy or move operations: set_payload(buf); set_payload(std::move(buf));

Parameters

  payload | A buffer to use as the message payload.

## set_payload() [2/2]

void mqtt::message::set_payload | ( | const void * | payload,
|  | size_t | n )

inline

Sets the payload of this message to be the specified byte array.

Parameters

  payload | the bytes to use as the message payload
  n | the number of bytes in the payload

## set_qos()

void mqtt::message::set_qos | ( | int | qos | ) |

inline

Sets the quality of service for this message.

Parameters

  qos | The integer Quality of Service for the message

## validate_qos()

void mqtt::message::validate_qos | ( | int | qos | ) |

inline static

Determines if the QOS value is a valid one.

Parameters

  qos | The QOS value.

Exceptions

  std::invalid_argument | If the qos value is invalid.

## set_retained()

void mqtt::message::set_retained | ( | bool | retained | ) |

inline

Whether or not the publish message should be retained by the broker.

Parameters

  retained | true if the message should be retained by the broker, false if not.

## get_properties()

const properties & mqtt::message::get_properties | ( |  | ) | const

inline

Gets the properties in the message.

Returns
  A const reference to the properties in the message.

## set_properties() [1/2]

void mqtt::message::set_properties | ( | const properties & | props | ) |

inline

Sets the properties in the message.

Parameters

  props | The properties to place into the message.

## set_properties() [2/2]

void mqtt::message::set_properties | ( | properties && | props | ) |

inline

Moves the properties into the message.

Parameters

  props | The properties to move into the message.

## to_string()

string mqtt::message::to_string | ( |  | ) | const

inline

Returns a string representation of this messages payload.

Returns
  A string representation of this messages payload.

## Friends And Related Symbol Documentation

## async_client

friend class async_client

friend

The client has special access.

## Field Documentation

## DFLT_QOS

int mqtt::message::DFLT_QOS = 0

static constexpr

The default QoS for a message

## DFLT_RETAINED

bool mqtt::message::DFLT_RETAINED = false

static constexpr

The default retained flag

The documentation for this class was generated from the following file:

- message.h