PahoMqttCpp
MQTT C++ Client for POSIX and Windows
Loading...
Searching...
No Matches
Public Types | Public Member Functions | Static Public Member Functions | Static Public Attributes | Friends
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 ()
 
messageoperator= (const message &rhs)
 
messageoperator= (message &&rhs)
 
void set_topic (string_ref topic)
 
const string_refget_topic_ref () const
 
const stringget_topic () const
 
void clear_payload ()
 
const binary_refget_payload_ref () const
 
const binaryget_payload () const
 
const stringget_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 propertiesget_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
topicThe message topic
payloadthe bytes to use as the message payload
lenthe number of bytes in the payload
qosThe quality of service for the message.
retainedWhether the message should be retained by the broker.
propsThe 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
topicThe message topic
payloadthe bytes to use as the message payload
lenthe 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
topicThe message topic
payloadA byte buffer to use as the message payload.
qosThe quality of service for the message.
retainedWhether the message should be retained by the broker.
propsThe 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
topicThe message topic
payloadA 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
topicThe message topic
cmsgA "C" MQTTAsync_message structure.

◆ message() [7/8]

mqtt::message::message ( const message other)

Constructs a message as a copy of the other message.

Parameters
otherThe message to copy into this one.

◆ message() [8/8]

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

Moves the other message to this one.

Parameters
otherThe 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]

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

Constructs a message with the specified values.

Parameters
topicThe message topic
payloadthe bytes to use as the message payload
lenthe number of bytes in the payload
qosThe quality of service for the message.
retainedWhether the message should be retained by the broker.
propsThe MQTT v5 properties for the message.

◆ create() [2/5]

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

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

Parameters
topicThe message topic
payloadthe bytes to use as the message payload
lenthe number of bytes in the payload

◆ create() [3/5]

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

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

Parameters
topicThe message topic
payloadA byte buffer to use as the message payload.
qosThe quality of service for the message.
retainedWhether the message should be retained by the broker.
propsThe MQTT v5 properties for the message.

◆ create() [4/5]

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

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

Parameters
topicThe message topic
payloadA byte buffer to use as the message payload.

◆ create() [5/5]

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

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

Parameters
topicThe message topic
msgA "C" MQTTAsync_message structure.

◆ operator=() [1/2]

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

Copies another message to this one.

Parameters
rhsThe other message.
Returns
A reference to this message.

◆ operator=() [2/2]

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

Moves another message to this one.

Parameters
rhsThe 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
topicThe 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
payloadA 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
payloadthe bytes to use as the message payload
nthe 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
qosThe integer Quality of Service for the message

◆ validate_qos()

static void mqtt::message::validate_qos ( int  qos)
inlinestatic

Determines if the QOS value is a valid one.

Parameters
qosThe QOS value.
Exceptions
std::invalid_argumentIf 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
retainedtrue 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
propsThe 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
propsThe 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

constexpr int mqtt::message::DFLT_QOS = 0
staticconstexpr

The default QoS for a message

◆ DFLT_RETAINED

constexpr bool mqtt::message::DFLT_RETAINED = false
staticconstexpr

The default retained flag


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