Home - News ( United States | United Kingdom | Italy | Germany ) - Football scores

Showing content from https://freertos.github.io/coreMQTT-Agent/main/coreMQTT/core__mqtt_8h.html below:

coreMQTT: core_mqtt.h File Reference

Loading...

Searching...

No Matches

User-facing functions of the MQTT 3.1.1 library. More...

Go to the source code of this file.

User-facing functions of the MQTT 3.1.1 library.

Initialize an MQTT context.

This function must be called on an MQTTContext_t before any other function.

Note

The MQTTGetCurrentTimeFunc_t function for querying time must be defined. If there is no time implementation, it is the responsibility of the application to provide a dummy function to always return 0, provide 0 timeouts for all calls to MQTT_Connect, MQTT_ProcessLoop, and MQTT_ReceiveLoop and configure the MQTT_RECV_POLLING_TIMEOUT_MS and MQTT_SEND_TIMEOUT_MS configurations to be 0. This will result in loop functions running for a single iteration, and MQTT_Connect relying on MQTT_MAX_CONNACK_RECEIVE_RETRY_COUNT to receive the CONNACK packet.

Parameters

[in] pContext The context to initialize. [in] pTransportInterface The transport interface to use with the context. [in] getTimeFunction The time utility function which can return the amount of time (in milliseconds) elapsed since a given epoch. This function will be used to ensure that timeouts in the API calls are met and keep-alive messages are sent on time. [in] userCallback The user callback to use with the context to notify about incoming packet events. [in] pNetworkBuffer Network buffer provided for the context. This buffer will be used to receive incoming messages from the broker. This buffer must remain valid and in scope for the entire lifetime of the pContext and must not be used by another context and/or application.

Returns

MQTTBadParameter if invalid parameters are passed; MQTTSuccess otherwise.

Example

uint32_t getTimeStampMs();

void eventCallback(

);

int32_t networkSend(

* pContext,

* pBuffer,

bytes );

int32_t networkRecv(

* pContext,

* pBuffer,

bytes );

uint8_t buffer[ 1024 ];

memset( (

* ) &mqttContext, 0x00,

(

) );

transport.

= networkSend;

transport.

= networkRecv;

fixedBuffer.

= 1024;

status =

( &mqttContext, &transport, getTimeStampMs, eventCallback, &fixedBuffer );

{

}

MQTTStatus_t MQTT_Init(MQTTContext_t *pContext, const TransportInterface_t *pTransportInterface, MQTTGetCurrentTimeFunc_t getTimeFunction, MQTTEventCallback_t userCallback, const MQTTFixedBuffer_t *pNetworkBuffer)

Initialize an MQTT context.

Definition: core_mqtt.c:2531

@ MQTTSuccess

Definition: core_mqtt_serializer.h:88

struct NetworkContext NetworkContext_t

The NetworkContext is an incomplete type. An implementation of this interface must define struct Netw...

Definition: transport_interface.h:191

A struct representing an MQTT connection.

Definition: core_mqtt.h:173

Struct to hold deserialized packet information for an MQTTEventCallback_t callback.

Definition: core_mqtt.h:257

Buffer passed to MQTT library.

Definition: core_mqtt_serializer.h:123

size_t size

Size of buffer.

Definition: core_mqtt_serializer.h:125

uint8_t * pBuffer

Pointer to buffer.

Definition: core_mqtt_serializer.h:124

MQTT incoming packet parameters.

Definition: core_mqtt_serializer.h:244

The transport layer interface.

Definition: transport_interface.h:299

TransportSend_t send

Definition: transport_interface.h:301

TransportRecv_t recv

Definition: transport_interface.h:300

NetworkContext_t * pNetworkContext

Definition: transport_interface.h:303

Initialize an MQTT context for QoS > 0.

This function must be called on an MQTTContext_t after MQTT_Init and before any other function.

Parameters

[in] pContext The context to initialize. [in] pOutgoingPublishRecords Pointer to memory which will be used to store state of outgoing publishes. [in] outgoingPublishCount Maximum number of records which can be kept in the memory pointed to by pOutgoingPublishRecords. [in] pIncomingPublishRecords Pointer to memory which will be used to store state of incoming publishes. [in] incomingPublishCount Maximum number of records which can be kept in the memory pointed to by pIncomingPublishRecords.

Returns

MQTTBadParameter if invalid parameters are passed; MQTTSuccess otherwise.

Example

uint32_t getTimeStampMs();

void eventCallback(

);

int32_t networkSend(

* pContext,

* pBuffer,

bytes );

int32_t networkRecv(

* pContext,

* pBuffer,

bytes );

uint8_t buffer[ 1024 ];

const size_t outgoingPublishCount = 30;

memset( (

* ) &mqttContext, 0x00,

(

) );

transport.

= networkSend;

transport.

= networkRecv;

fixedBuffer.

= 1024;

status =

( &mqttContext, &transport, getTimeStampMs, eventCallback, &fixedBuffer );

{

}

MQTTStatus_t MQTT_InitStatefulQoS(MQTTContext_t *pContext, MQTTPubAckInfo_t *pOutgoingPublishRecords, size_t outgoingPublishCount, MQTTPubAckInfo_t *pIncomingPublishRecords, size_t incomingPublishCount)

Initialize an MQTT context for QoS > 0.

Definition: core_mqtt.c:2590

An element of the state engine records for QoS 1 or Qos 2 publishes.

Definition: core_mqtt.h:162

Establish an MQTT session.

This function will send MQTT CONNECT packet and receive a CONNACK packet. The send and receive from the network is done through the transport interface.

The maximum time this function waits for a CONNACK is decided in one of the following ways:

1. If timeoutMs is greater than 0: MQTTContext_t.getTime is used to ensure that the function does not wait more than timeoutMs for CONNACK.
2. If timeoutMs is 0: The network receive for CONNACK is retried up to the number of times configured by MQTT_MAX_CONNACK_RECEIVE_RETRY_COUNT.

Note

If a dummy MQTTGetCurrentTimeFunc_t was passed to MQTT_Init, then a timeout value of 0 MUST be passed to the API, and the MQTT_RECV_POLLING_TIMEOUT_MS and MQTT_SEND_TIMEOUT_MS timeout configurations MUST be set to 0.

Parameters

[in] pContext Initialized MQTT context. [in] pConnectInfo MQTT CONNECT packet information. [in] pWillInfo Last Will and Testament. Pass NULL if Last Will and Testament is not used. [in] timeoutMs Maximum time in milliseconds to wait for a CONNACK packet. A zero timeout makes use of the retries for receiving CONNACK as configured with MQTT_MAX_CONNACK_RECEIVE_RETRY_COUNT. [out] pSessionPresent This value will be set to true if a previous session was present; otherwise it will be set to false. It is only relevant if not establishing a clean session.

Returns

MQTTNoMemory if the MQTTContext_t.networkBuffer is too small to hold the MQTT packet; MQTTBadParameter if invalid parameters are passed; MQTTSendFailed if transport send failed; MQTTRecvFailed if transport receive failed for CONNACK; MQTTNoDataAvailable if no data available to receive in transport until the timeoutMs for CONNACK; MQTTSuccess otherwise.

Note

This API may spend more time than provided in the timeoutMS parameters in certain conditions as listed below:

1. Timeouts are incorrectly configured - If the timeoutMS is less than the transport receive timeout and if a CONNACK packet is not received within the transport receive timeout, the API will spend the transport receive timeout (which is more time than the timeoutMs). It is the case of incorrect timeout configuration as the timeoutMs parameter passed to this API must be greater than the transport receive timeout. Please refer to the transport interface documentation for more details about timeout configurations.
2. Partial CONNACK packet is received right before the expiry of the timeout - It is possible that first two bytes of CONNACK packet (packet type and remaining length) are received right before the expiry of the timeoutMS. In that case, the API makes one more network receive call in an attempt to receive the remaining 2 bytes. In the worst case, it can happen that the remaining 2 bytes are never received and this API will end up spending timeoutMs + transport receive timeout.

Example

bool sessionPresent;

status =

( pContext, &connectInfo, &willInfo, 100, &sessionPresent );

{

assert( sessionPresent == false );

}

MQTTStatus_t MQTT_Connect(MQTTContext_t *pContext, const MQTTConnectInfo_t *pConnectInfo, const MQTTPublishInfo_t *pWillInfo, uint32_t timeoutMs, bool *pSessionPresent)

Establish an MQTT session.

Definition: core_mqtt.c:2679

MQTTStatus_t

Return codes from MQTT functions.

Definition: core_mqtt_serializer.h:87

@ MQTTQoS0

Definition: core_mqtt_serializer.h:110

MQTT CONNECT packet parameters.

Definition: core_mqtt_serializer.h:133

const char * pClientIdentifier

MQTT client identifier. Must be unique per client.

Definition: core_mqtt_serializer.h:147

const char * pUserName

MQTT user name. Set to NULL if not used.

Definition: core_mqtt_serializer.h:157

bool cleanSession

Whether to establish a new, clean session or resume a previous session.

Definition: core_mqtt_serializer.h:137

uint16_t userNameLength

Length of MQTT user name. Set to 0 if not used.

Definition: core_mqtt_serializer.h:162

uint16_t keepAliveSeconds

MQTT keep alive period.

Definition: core_mqtt_serializer.h:142

uint16_t clientIdentifierLength

Length of the client identifier.

Definition: core_mqtt_serializer.h:152

uint16_t passwordLength

Length of MQTT password. Set to 0 if not used.

Definition: core_mqtt_serializer.h:172

const char * pPassword

MQTT password. Set to NULL if not used.

Definition: core_mqtt_serializer.h:167

MQTT PUBLISH packet parameters.

Definition: core_mqtt_serializer.h:202

MQTTQoS_t qos

Quality of Service for message.

Definition: core_mqtt_serializer.h:206

uint16_t topicNameLength

Length of topic name.

Definition: core_mqtt_serializer.h:226

size_t payloadLength

Message payload length.

Definition: core_mqtt_serializer.h:236

const char * pTopicName

Topic name on which the message is published.

Definition: core_mqtt_serializer.h:221

const void * pPayload

Message payload.

Definition: core_mqtt_serializer.h:231

Sends MQTT SUBSCRIBE for the given list of topic filters to the broker.

Parameters

[in] pContext Initialized MQTT context. [in] pSubscriptionList Array of MQTT subscription info. [in] subscriptionCount The number of elements in @ pSubscriptionList array. [in] packetId Packet ID generated by MQTT_GetPacketId.

Returns

MQTTNoMemory if the MQTTContext_t.networkBuffer is too small to hold the MQTT packet; MQTTBadParameter if invalid parameters are passed; MQTTSendFailed if transport write failed; MQTTSuccess otherwise.

Example

uint16_t packetId;

const char * filters[ NUMBER_OF_SUBSCRIPTIONS ];

for( int i = 0; i < NUMBER_OF_SUBSCRIPTIONS; i++ )

{

}

status =

( pContext, &subscriptionList[ 0 ], NUMBER_OF_SUBSCRIPTIONS, packetId );

{

}

uint16_t MQTT_GetPacketId(MQTTContext_t *pContext)

Get a packet ID that is valid according to the MQTT 3.1.1 spec.

Definition: core_mqtt.c:3172

MQTTStatus_t MQTT_Subscribe(MQTTContext_t *pContext, const MQTTSubscribeInfo_t *pSubscriptionList, size_t subscriptionCount, uint16_t packetId)

Sends MQTT SUBSCRIBE for the given list of topic filters to the broker.

Definition: core_mqtt.c:2761

MQTT SUBSCRIBE packet parameters.

Definition: core_mqtt_serializer.h:180

MQTTQoS_t qos

Quality of Service for subscription.

Definition: core_mqtt_serializer.h:184

uint16_t topicFilterLength

Length of subscription topic filter.

Definition: core_mqtt_serializer.h:194

const char * pTopicFilter

Topic filter to subscribe to.

Definition: core_mqtt_serializer.h:189

Publishes a message to the given topic name.

Parameters

[in] pContext Initialized MQTT context. [in] pPublishInfo MQTT PUBLISH packet parameters. [in] packetId packet ID generated by MQTT_GetPacketId.

Returns

MQTTNoMemory if pBuffer is too small to hold the MQTT packet; MQTTBadParameter if invalid parameters are passed; MQTTSendFailed if transport write failed; MQTTSuccess otherwise.

Example

uint16_t packetId;

publishInfo.

=

;

{

}

MQTTStatus_t MQTT_Publish(MQTTContext_t *pContext, const MQTTPublishInfo_t *pPublishInfo, uint16_t packetId)

Publishes a message to the given topic name.

Definition: core_mqtt.c:2805

@ MQTTQoS1

Definition: core_mqtt_serializer.h:111

Cancels an outgoing publish callback (only for QoS > QoS0) by removing it from the pending ACK list.

Note

This cannot cancel the actual publish as that might have already been sent to the broker. This only removes the details of the given packet ID from the list of unACKed packet. That allows the caller to free any memory associated with the publish payload, topic string etc. Also, after this API call, the user provided callback will not be invoked when the ACK packet is received.

Parameters

[in] pContext Initialized MQTT context. [in] packetId packet ID corresponding to the outstanding publish.

Returns

MQTTBadParameter if invalid parameters are passed; MQTTSuccess otherwise.

Sends an MQTT PINGREQ to broker.

Parameters

[in] pContext Initialized and connected MQTT context.

Returns

MQTTNoMemory if pBuffer is too small to hold the MQTT packet; MQTTBadParameter if invalid parameters are passed; MQTTSendFailed if transport write failed; MQTTSuccess otherwise.

Sends MQTT UNSUBSCRIBE for the given list of topic filters to the broker.

Parameters

[in] pContext Initialized MQTT context. [in] pSubscriptionList List of MQTT subscription info. [in] subscriptionCount The number of elements in pSubscriptionList. [in] packetId packet ID generated by MQTT_GetPacketId.

Returns

MQTTNoMemory if the MQTTContext_t.networkBuffer is too small to hold the MQTT packet; MQTTBadParameter if invalid parameters are passed; MQTTSendFailed if transport write failed; MQTTSuccess otherwise.

Example

uint16_t packetId;

const char * filters[ NUMBER_OF_SUBSCRIPTIONS ];

for( int i = 0; i < NUMBER_OF_SUBSCRIPTIONS; i++ )

{

}

status =

( pContext, &unsubscribeList[ 0 ], NUMBER_OF_SUBSCRIPTIONS, packetId );

{

}

MQTTStatus_t MQTT_Unsubscribe(MQTTContext_t *pContext, const MQTTSubscribeInfo_t *pSubscriptionList, size_t subscriptionCount, uint16_t packetId)

Sends MQTT UNSUBSCRIBE for the given list of topic filters to the broker.

Definition: core_mqtt.c:3000

Loop to receive packets from the transport interface. Handles keep alive.

Note

If a dummy timer function, MQTTGetCurrentTimeFunc_t, is passed to the library, then the keep-alive mechanism is not supported by the MQTT_ProcessLoop API. In that case, the MQTT_ReceiveLoop API function should be used instead.

Parameters

[in] pContext Initialized and connected MQTT context.

Note

Calling this function blocks the calling context for a time period that depends on the passed the configuration macros, MQTT_RECV_POLLING_TIMEOUT_MS and MQTT_SEND_TIMEOUT_MS, and the underlying transport interface implementation timeouts, unless an error occurs. The blocking period also depends on the execution time of the MQTTEventCallback_t callback supplied to the library. It is recommended that the supplied MQTTEventCallback_t callback does not contain blocking operations to prevent potential non-deterministic blocking period of the MQTT_ProcessLoop API call.

Returns

MQTTBadParameter if context is NULL; MQTTRecvFailed if a network error occurs during reception; MQTTSendFailed if a network error occurs while sending an ACK or PINGREQ; MQTTBadResponse if an invalid packet is received; MQTTKeepAliveTimeout if the server has not sent a PINGRESP before MQTT_PINGRESP_TIMEOUT_MS milliseconds; MQTTIllegalState if an incoming QoS 1/2 publish or ack causes an invalid transition for the internal state machine; MQTTNeedMoreBytes if MQTT_ProcessLoop has received incomplete data; it should be called again (probably after a delay); MQTTSuccess on success.

Example

while( true )

{

{

}

else

{

}

}

MQTTStatus_t MQTT_ProcessLoop(MQTTContext_t *pContext)

Loop to receive packets from the transport interface. Handles keep alive.

Definition: core_mqtt.c:3119

@ MQTTNeedMoreBytes

Definition: core_mqtt_serializer.h:99

Loop to receive packets from the transport interface. Does not handle keep alive.

Note

If a dummy MQTTGetCurrentTimeFunc_t was passed to MQTT_Init, then the MQTT_RECV_POLLING_TIMEOUT_MS and MQTT_SEND_TIMEOUT_MS timeout configurations MUST be set to 0.

Parameters

[in] pContext Initialized and connected MQTT context.

Note

Calling this function blocks the calling context for a time period that depends on the the configuration macros, MQTT_RECV_POLLING_TIMEOUT_MS and MQTT_SEND_TIMEOUT_MS, and the underlying transport interface implementation timeouts, unless an error occurs. The blocking period also depends on the execution time of the MQTTEventCallback_t callback supplied to the library. It is recommended that the supplied MQTTEventCallback_t callback does not contain blocking operations to prevent potential non-deterministic blocking period of the MQTT_ReceiveLoop API call.

Returns

MQTTBadParameter if context is NULL; MQTTRecvFailed if a network error occurs during reception; MQTTSendFailed if a network error occurs while sending an ACK or PINGREQ; MQTTBadResponse if an invalid packet is received; MQTTIllegalState if an incoming QoS 1/2 publish or ack causes an invalid transition for the internal state machine; MQTTNeedMoreBytes if MQTT_ReceiveLoop has received incomplete data; it should be called again (probably after a delay); MQTTSuccess on success.

Example

uint32_t keepAliveMs = 60 * 1000;

while( true )

{

{

}

else

{

{

}

}

}

MQTTStatus_t MQTT_Ping(MQTTContext_t *pContext)

Sends an MQTT PINGREQ to broker.

Definition: core_mqtt.c:2922

MQTTStatus_t MQTT_ReceiveLoop(MQTTContext_t *pContext)

Loop to receive packets from the transport interface. Does not handle keep alive.

Definition: core_mqtt.c:3146

uint32_t lastPacketTxTime

Timestamp of the last packet sent by the library.

Definition: core_mqtt.h:227

MQTTGetCurrentTimeFunc_t getTime

Function used to get millisecond timestamps.

Definition: core_mqtt.h:217

Get a packet ID that is valid according to the MQTT 3.1.1 spec.

Parameters

[in] pContext Initialized MQTT context.

Returns

A non-zero number.

A utility function that determines whether the passed topic filter and topic name match according to the MQTT 3.1.1 protocol specification.

Parameters

[in] pTopicName The topic name to check. [in] topicNameLength Length of the topic name. [in] pTopicFilter The topic filter to check. [in] topicFilterLength Length of topic filter. [out] pIsMatch If the match is performed without any error, that is if the return value is MQTTSuccess, then and only then the value in this parameter is valid and updated. In such a case, if the topic filter and the topic name match, then this value is set to true; otherwise if there is no match then it is set to false.

Note

The API assumes that the passed topic name is valid to meet the requirements of the MQTT 3.1.1 specification. Invalid topic names (for example, containing wildcard characters) should not be passed to the function. Also, the API checks validity of topic filter for wildcard characters ONLY if the passed topic name and topic filter do not have an exact string match.

Returns

Returns one of the following:

• MQTTBadParameter, if any of the input parameters is invalid.
• MQTTSuccess, if the matching operation was performed.

Example

const char * pTopic = "topic/match/1";

const char * pFilter = "topic/#";

bool match = false;

status =

( pTopic, strlen( pTopic ), pFilter, strlen( pFilter ), &match );

if( match )

{

}

MQTTStatus_t MQTT_MatchTopic(const char *pTopicName, const uint16_t topicNameLength, const char *pTopicFilter, const uint16_t topicFilterLength, bool *pIsMatch)

A utility function that determines whether the passed topic filter and topic name match according to ...

Definition: core_mqtt.c:3201

Parses the payload of an MQTT SUBACK packet that contains status codes corresponding to topic filter subscription requests from the original subscribe packet.

Each return code in the SUBACK packet corresponds to a topic filter in the SUBSCRIBE Packet being acknowledged. The status codes can be one of the following:

• 0x00 - Success - Maximum QoS 0
• 0x01 - Success - Maximum QoS 1
• 0x02 - Success - Maximum QoS 2
• 0x80 - Failure Refer to MQTTSubAckStatus_t for the status codes.

Parameters

[in] pSubackPacket The SUBACK packet whose payload is to be parsed. [out] pPayloadStart This is populated with the starting address of the payload (or return codes for topic filters) in the SUBACK packet. [out] pPayloadSize This is populated with the size of the payload in the SUBACK packet. It represents the number of topic filters whose SUBACK status is present in the packet.

Returns

Returns one of the following:

• MQTTBadParameter if the input SUBACK packet is invalid.
• MQTTSuccess if parsing the payload was successful.

Example

void eventCallback(

)

{

uint8_t * pCodes;

size_t numCodes;

{

assert( numCodes == NUMBER_OF_SUBSCRIPTIONS );

for( int i = 0; i < numCodes; i++ )

{

{

}

else

{

if( pSubscribes[ i ].qos != pCodes[ i ] )

{

"Requested QoS %u, but granted QoS %u for %s",

pSubscribes[ i ].qos, pCodes[ i ], pSubscribes[ i ].pTopicFilter

) );

}

}

}

}

}

MQTTStatus_t MQTT_GetSubAckStatusCodes(const MQTTPacketInfo_t *pSubackPacket, uint8_t **pPayloadStart, size_t *pPayloadSize)

Parses the payload of an MQTT SUBACK packet that contains status codes corresponding to topic filter ...

Definition: core_mqtt.c:3270

#define LogWarn(message)

Macro that is called in the MQTT library for logging "Warning" level messages.

Definition: core_mqtt_config_defaults.h:235

#define MQTT_PACKET_TYPE_SUBACK

SUBACK (server-to-client).

Definition: core_mqtt_serializer.h:61

@ MQTTSubAckFailure

Failure.

Definition: core_mqtt.h:154

uint8_t type

Type of incoming MQTT packet.

Definition: core_mqtt_serializer.h:248

Error code to string conversion for MQTT statuses.

Parameters

[in] status The status to convert to a string.

Returns

The string representation of the status.

RetroSearch is an open source project built by @garambo | Open a GitHub Issue

Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo

HTML: 3.2 | Encoding: UTF-8 | Version: 0.7.4