mirror of
https://github.com/FreeRTOS/coreMQTT
synced 2025-05-12 13:24:58 +08:00
1282 lines
135 KiB
HTML
1282 lines
135 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml" lang="en-US">
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
|
|
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
|
|
<meta name="generator" content="Doxygen 1.9.6"/>
|
|
<meta name="viewport" content="width=device-width, initial-scale=1"/>
|
|
<title>coreMQTT: core_mqtt.h File Reference</title>
|
|
<link href="tabs.css" rel="stylesheet" type="text/css"/>
|
|
<script type="text/javascript" src="jquery.js"></script>
|
|
<script type="text/javascript" src="dynsections.js"></script>
|
|
<link href="navtree.css" rel="stylesheet" type="text/css"/>
|
|
<script type="text/javascript" src="resize.js"></script>
|
|
<script type="text/javascript" src="navtreedata.js"></script>
|
|
<script type="text/javascript" src="navtree.js"></script>
|
|
<link href="search/search.css" rel="stylesheet" type="text/css"/>
|
|
<script type="text/javascript" src="search/searchdata.js"></script>
|
|
<script type="text/javascript" src="search/search.js"></script>
|
|
<script type="text/javascript">
|
|
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
|
|
$(document).ready(function() { init_search(); });
|
|
/* @license-end */
|
|
</script>
|
|
<link href="doxygen.css" rel="stylesheet" type="text/css" />
|
|
<link href="style.css" rel="stylesheet" type="text/css"/>
|
|
</head>
|
|
<body>
|
|
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
|
|
<div id="titlearea">
|
|
<table cellspacing="0" cellpadding="0">
|
|
<tbody>
|
|
<tr id="projectrow">
|
|
<td id="projectalign">
|
|
<div id="projectname">coreMQTT<span id="projectnumber"> v2.3.1</span>
|
|
</div>
|
|
<div id="projectbrief">MQTT 3.1.1 Client Library</div>
|
|
</td>
|
|
<td> <div id="MSearchBox" class="MSearchBoxInactive">
|
|
<span class="left">
|
|
<span id="MSearchSelect" onmouseover="return searchBox.OnSearchSelectShow()" onmouseout="return searchBox.OnSearchSelectHide()"> </span>
|
|
<input type="text" id="MSearchField" value="" placeholder="Search" accesskey="S"
|
|
onfocus="searchBox.OnSearchFieldFocus(true)"
|
|
onblur="searchBox.OnSearchFieldFocus(false)"
|
|
onkeyup="searchBox.OnSearchFieldChange(event)"/>
|
|
</span><span class="right">
|
|
<a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.svg" alt=""/></a>
|
|
</span>
|
|
</div>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
<!-- end header part -->
|
|
<!-- Generated by Doxygen 1.9.6 -->
|
|
<script type="text/javascript">
|
|
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
|
|
var searchBox = new SearchBox("searchBox", "search/",'.html');
|
|
/* @license-end */
|
|
</script>
|
|
</div><!-- top -->
|
|
<div id="side-nav" class="ui-resizable side-nav-resizable">
|
|
<div id="nav-tree">
|
|
<div id="nav-tree-contents">
|
|
<div id="nav-sync" class="sync"></div>
|
|
</div>
|
|
</div>
|
|
<div id="splitbar" style="-moz-user-select:none;"
|
|
class="ui-resizable-handle">
|
|
</div>
|
|
</div>
|
|
<script type="text/javascript">
|
|
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
|
|
$(document).ready(function(){initNavTree('core__mqtt_8h.html',''); initResizable(); });
|
|
/* @license-end */
|
|
</script>
|
|
<div id="doc-content">
|
|
<!-- window showing the filter options -->
|
|
<div id="MSearchSelectWindow"
|
|
onmouseover="return searchBox.OnSearchSelectShow()"
|
|
onmouseout="return searchBox.OnSearchSelectHide()"
|
|
onkeydown="return searchBox.OnSearchSelectKey(event)">
|
|
</div>
|
|
|
|
<!-- iframe showing the search results (closed by default) -->
|
|
<div id="MSearchResultsWindow">
|
|
<div id="MSearchResults">
|
|
<div class="SRPage">
|
|
<div id="SRIndex">
|
|
<div id="SRResults"></div>
|
|
<div class="SRStatus" id="Loading">Loading...</div>
|
|
<div class="SRStatus" id="Searching">Searching...</div>
|
|
<div class="SRStatus" id="NoMatches">No Matches</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="header">
|
|
<div class="summary">
|
|
<a href="#nested-classes">Data Structures</a> |
|
|
<a href="#define-members">Macros</a> |
|
|
<a href="#typedef-members">Typedefs</a> |
|
|
<a href="#enum-members">Enumerations</a> |
|
|
<a href="#func-members">Functions</a> </div>
|
|
<div class="headertitle"><div class="title">core_mqtt.h File Reference</div></div>
|
|
</div><!--header-->
|
|
<div class="contents">
|
|
|
|
<p>User-facing functions of the MQTT 3.1.1 library.
|
|
<a href="#details">More...</a></p>
|
|
<div class="textblock"><code>#include "<a class="el" href="core__mqtt__serializer_8h_source.html">core_mqtt_serializer.h</a>"</code><br />
|
|
<code>#include "<a class="el" href="transport__interface_8h_source.html">transport_interface.h</a>"</code><br />
|
|
</div>
|
|
<p><a href="core__mqtt_8h_source.html">Go to the source code of this file.</a></p>
|
|
<table class="memberdecls">
|
|
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a id="nested-classes" name="nested-classes"></a>
|
|
Data Structures</h2></td></tr>
|
|
<tr class="memitem:"><td class="memItemLeft" align="right" valign="top">struct  </td><td class="memItemRight" valign="bottom"><a class="el" href="struct_m_q_t_t_pub_ack_info__t.html">MQTTPubAckInfo_t</a></td></tr>
|
|
<tr class="memdesc:"><td class="mdescLeft"> </td><td class="mdescRight">An element of the state engine records for QoS 1 or Qos 2 publishes. <a href="struct_m_q_t_t_pub_ack_info__t.html#details">More...</a><br /></td></tr>
|
|
<tr class="separator:"><td class="memSeparator" colspan="2"> </td></tr>
|
|
<tr class="memitem:"><td class="memItemLeft" align="right" valign="top">struct  </td><td class="memItemRight" valign="bottom"><a class="el" href="struct_m_q_t_t_context__t.html">MQTTContext_t</a></td></tr>
|
|
<tr class="memdesc:"><td class="mdescLeft"> </td><td class="mdescRight">A struct representing an MQTT connection. <a href="struct_m_q_t_t_context__t.html#details">More...</a><br /></td></tr>
|
|
<tr class="separator:"><td class="memSeparator" colspan="2"> </td></tr>
|
|
<tr class="memitem:"><td class="memItemLeft" align="right" valign="top">struct  </td><td class="memItemRight" valign="bottom"><a class="el" href="struct_m_q_t_t_deserialized_info__t.html">MQTTDeserializedInfo_t</a></td></tr>
|
|
<tr class="memdesc:"><td class="mdescLeft"> </td><td class="mdescRight">Struct to hold deserialized packet information for an <a class="el" href="group__mqtt__callback__types.html#ga00d348277ed4fde23c95bfc749ae954a" title="Application callback for receiving incoming publishes and incoming acks.">MQTTEventCallback_t</a> callback. <a href="struct_m_q_t_t_deserialized_info__t.html#details">More...</a><br /></td></tr>
|
|
<tr class="separator:"><td class="memSeparator" colspan="2"> </td></tr>
|
|
</table><table class="memberdecls">
|
|
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a id="define-members" name="define-members"></a>
|
|
Macros</h2></td></tr>
|
|
<tr class="memitem:ga9fde6503edb9eaad50ecd3392ab9992a"><td class="memItemLeft" align="right" valign="top">#define </td><td class="memItemRight" valign="bottom"><a class="el" href="group__mqtt__constants.html#ga9fde6503edb9eaad50ecd3392ab9992a">MQTT_PACKET_ID_INVALID</a>   ( ( uint16_t ) 0U )</td></tr>
|
|
<tr class="memdesc:ga9fde6503edb9eaad50ecd3392ab9992a"><td class="mdescLeft"> </td><td class="mdescRight">Invalid packet identifier. <br /></td></tr>
|
|
<tr class="separator:ga9fde6503edb9eaad50ecd3392ab9992a"><td class="memSeparator" colspan="2"> </td></tr>
|
|
</table><table class="memberdecls">
|
|
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a id="typedef-members" name="typedef-members"></a>
|
|
Typedefs</h2></td></tr>
|
|
<tr class="memitem:gae3bea55b0e49e5208b8c5709a5ea23aa"><td class="memItemLeft" align="right" valign="top">typedef uint32_t(* </td><td class="memItemRight" valign="bottom"><a class="el" href="group__mqtt__callback__types.html#gae3bea55b0e49e5208b8c5709a5ea23aa">MQTTGetCurrentTimeFunc_t</a>) (void)</td></tr>
|
|
<tr class="memdesc:gae3bea55b0e49e5208b8c5709a5ea23aa"><td class="mdescLeft"> </td><td class="mdescRight">Application provided function to query the time elapsed since a given epoch in milliseconds. <br /></td></tr>
|
|
<tr class="separator:gae3bea55b0e49e5208b8c5709a5ea23aa"><td class="memSeparator" colspan="2"> </td></tr>
|
|
<tr class="memitem:ga00d348277ed4fde23c95bfc749ae954a"><td class="memItemLeft" align="right" valign="top">typedef void(* </td><td class="memItemRight" valign="bottom"><a class="el" href="group__mqtt__callback__types.html#ga00d348277ed4fde23c95bfc749ae954a">MQTTEventCallback_t</a>) (struct MQTTContext *pContext, struct MQTTPacketInfo *pPacketInfo, struct MQTTDeserializedInfo *pDeserializedInfo)</td></tr>
|
|
<tr class="memdesc:ga00d348277ed4fde23c95bfc749ae954a"><td class="mdescLeft"> </td><td class="mdescRight">Application callback for receiving incoming publishes and incoming acks. <br /></td></tr>
|
|
<tr class="separator:ga00d348277ed4fde23c95bfc749ae954a"><td class="memSeparator" colspan="2"> </td></tr>
|
|
</table><table class="memberdecls">
|
|
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a id="enum-members" name="enum-members"></a>
|
|
Enumerations</h2></td></tr>
|
|
<tr class="memitem:ga9f84d003695205cf10a7bd0bafb3dbf6"><td class="memItemLeft" align="right" valign="top">enum  </td><td class="memItemRight" valign="bottom"><a class="el" href="group__mqtt__enum__types.html#ga9f84d003695205cf10a7bd0bafb3dbf6">MQTTConnectionStatus_t</a> { <a class="el" href="group__mqtt__enum__types.html#gga9f84d003695205cf10a7bd0bafb3dbf6a0320177ebf1f1b2e24646b44702cec69">MQTTNotConnected</a>
|
|
, <a class="el" href="group__mqtt__enum__types.html#gga9f84d003695205cf10a7bd0bafb3dbf6a82c8f64d976734e5632e5257bc429ef5">MQTTConnected</a>
|
|
}</td></tr>
|
|
<tr class="memdesc:ga9f84d003695205cf10a7bd0bafb3dbf6"><td class="mdescLeft"> </td><td class="mdescRight">Values indicating if an MQTT connection exists. <a href="group__mqtt__enum__types.html#ga9f84d003695205cf10a7bd0bafb3dbf6">More...</a><br /></td></tr>
|
|
<tr class="separator:ga9f84d003695205cf10a7bd0bafb3dbf6"><td class="memSeparator" colspan="2"> </td></tr>
|
|
<tr class="memitem:ga0480de7552eedd739a26a23fa8e6fd94"><td class="memItemLeft" align="right" valign="top">enum  </td><td class="memItemRight" valign="bottom"><a class="el" href="group__mqtt__enum__types.html#ga0480de7552eedd739a26a23fa8e6fd94">MQTTPublishState_t</a> { <br />
|
|
  <a class="el" href="group__mqtt__enum__types.html#gga0480de7552eedd739a26a23fa8e6fd94a8349567b7a9efb3913a64a8f4f6fe5c9">MQTTStateNull</a> = 0
|
|
, <a class="el" href="group__mqtt__enum__types.html#gga0480de7552eedd739a26a23fa8e6fd94a896b1507647b504c9208580e4cde26ad">MQTTPublishSend</a>
|
|
, <a class="el" href="group__mqtt__enum__types.html#gga0480de7552eedd739a26a23fa8e6fd94a65f6f7b343a30fc0558e3aeeb8c97f35">MQTTPubAckSend</a>
|
|
, <a class="el" href="group__mqtt__enum__types.html#gga0480de7552eedd739a26a23fa8e6fd94a11e2319a2b25b82121471743d39761e1">MQTTPubRecSend</a>
|
|
, <br />
|
|
  <a class="el" href="group__mqtt__enum__types.html#gga0480de7552eedd739a26a23fa8e6fd94a5d2ee2709c6dc7a1eb8b9c40f318909b">MQTTPubRelSend</a>
|
|
, <a class="el" href="group__mqtt__enum__types.html#gga0480de7552eedd739a26a23fa8e6fd94a7d88904d550b502b4424a41aa4205e56">MQTTPubCompSend</a>
|
|
, <a class="el" href="group__mqtt__enum__types.html#gga0480de7552eedd739a26a23fa8e6fd94ab086c55acf106cdc8d420f90899b6803">MQTTPubAckPending</a>
|
|
, <a class="el" href="group__mqtt__enum__types.html#gga0480de7552eedd739a26a23fa8e6fd94a1bea59454700be9b683b7eb8aaf6bb4f">MQTTPubRecPending</a>
|
|
, <br />
|
|
  <a class="el" href="group__mqtt__enum__types.html#gga0480de7552eedd739a26a23fa8e6fd94a695431cde1dc9dc5a2dcbd10eba49df2">MQTTPubRelPending</a>
|
|
, <a class="el" href="group__mqtt__enum__types.html#gga0480de7552eedd739a26a23fa8e6fd94a3281a28d1829d954b596f091b547b627">MQTTPubCompPending</a>
|
|
, <a class="el" href="group__mqtt__enum__types.html#gga0480de7552eedd739a26a23fa8e6fd94ad07733793a235ef9a6a04d16637cd7dc">MQTTPublishDone</a>
|
|
<br />
|
|
}</td></tr>
|
|
<tr class="memdesc:ga0480de7552eedd739a26a23fa8e6fd94"><td class="mdescLeft"> </td><td class="mdescRight">The state of QoS 1 or QoS 2 MQTT publishes, used in the state engine. <a href="group__mqtt__enum__types.html#ga0480de7552eedd739a26a23fa8e6fd94">More...</a><br /></td></tr>
|
|
<tr class="separator:ga0480de7552eedd739a26a23fa8e6fd94"><td class="memSeparator" colspan="2"> </td></tr>
|
|
<tr class="memitem:ga8c1bee959b3ed5fab2a2688dd72bf237"><td class="memItemLeft" align="right" valign="top">enum  </td><td class="memItemRight" valign="bottom"><a class="el" href="group__mqtt__enum__types.html#ga8c1bee959b3ed5fab2a2688dd72bf237">MQTTPubAckType_t</a> { <a class="el" href="group__mqtt__enum__types.html#gga8c1bee959b3ed5fab2a2688dd72bf237a53d5939c680962f37c15ee87ffd63d0f">MQTTPuback</a>
|
|
, <a class="el" href="group__mqtt__enum__types.html#gga8c1bee959b3ed5fab2a2688dd72bf237a8c98d5d1a68dda33d9039009ab4ef053">MQTTPubrec</a>
|
|
, <a class="el" href="group__mqtt__enum__types.html#gga8c1bee959b3ed5fab2a2688dd72bf237af2d737088a231c88e7603acfdbc4fc8c">MQTTPubrel</a>
|
|
, <a class="el" href="group__mqtt__enum__types.html#gga8c1bee959b3ed5fab2a2688dd72bf237a910c34311ad6a2341afc04839e1c13bd">MQTTPubcomp</a>
|
|
}</td></tr>
|
|
<tr class="memdesc:ga8c1bee959b3ed5fab2a2688dd72bf237"><td class="mdescLeft"> </td><td class="mdescRight">Packet types used in acknowledging QoS 1 or QoS 2 publishes. <a href="group__mqtt__enum__types.html#ga8c1bee959b3ed5fab2a2688dd72bf237">More...</a><br /></td></tr>
|
|
<tr class="separator:ga8c1bee959b3ed5fab2a2688dd72bf237"><td class="memSeparator" colspan="2"> </td></tr>
|
|
<tr class="memitem:ga48dabc1579e3c0ac6058ce9068054611"><td class="memItemLeft" align="right" valign="top">enum  </td><td class="memItemRight" valign="bottom"><a class="el" href="group__mqtt__enum__types.html#ga48dabc1579e3c0ac6058ce9068054611">MQTTSubAckStatus_t</a> { <a class="el" href="group__mqtt__enum__types.html#gga48dabc1579e3c0ac6058ce9068054611abcc3040d7d53025baee3542c40758abb">MQTTSubAckSuccessQos0</a> = 0x00
|
|
, <a class="el" href="group__mqtt__enum__types.html#gga48dabc1579e3c0ac6058ce9068054611ab180361a6da712c8144d8c499537787d">MQTTSubAckSuccessQos1</a> = 0x01
|
|
, <a class="el" href="group__mqtt__enum__types.html#gga48dabc1579e3c0ac6058ce9068054611a877b2afbc6ec7d9ab57d4862caadf4f1">MQTTSubAckSuccessQos2</a> = 0x02
|
|
, <a class="el" href="group__mqtt__enum__types.html#gga48dabc1579e3c0ac6058ce9068054611aeb83b20da8eda934cde6b92db225a808">MQTTSubAckFailure</a> = 0x80
|
|
}</td></tr>
|
|
<tr class="memdesc:ga48dabc1579e3c0ac6058ce9068054611"><td class="mdescLeft"> </td><td class="mdescRight">The status codes in the SUBACK response to a subscription request. <a href="group__mqtt__enum__types.html#ga48dabc1579e3c0ac6058ce9068054611">More...</a><br /></td></tr>
|
|
<tr class="separator:ga48dabc1579e3c0ac6058ce9068054611"><td class="memSeparator" colspan="2"> </td></tr>
|
|
</table><table class="memberdecls">
|
|
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a id="func-members" name="func-members"></a>
|
|
Functions</h2></td></tr>
|
|
<tr class="memitem:ae8444f3a85535e62cdb1ae9c192677d6"><td class="memItemLeft" align="right" valign="top"><a class="el" href="group__mqtt__enum__types.html#gaba7ec045874a1c3432f99173367f735c">MQTTStatus_t</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="core__mqtt_8h.html#ae8444f3a85535e62cdb1ae9c192677d6">MQTT_Init</a> (<a class="el" href="struct_m_q_t_t_context__t.html">MQTTContext_t</a> *pContext, const <a class="el" href="struct_transport_interface__t.html">TransportInterface_t</a> *pTransportInterface, <a class="el" href="group__mqtt__callback__types.html#gae3bea55b0e49e5208b8c5709a5ea23aa">MQTTGetCurrentTimeFunc_t</a> getTimeFunction, <a class="el" href="group__mqtt__callback__types.html#ga00d348277ed4fde23c95bfc749ae954a">MQTTEventCallback_t</a> userCallback, const <a class="el" href="struct_m_q_t_t_fixed_buffer__t.html">MQTTFixedBuffer_t</a> *pNetworkBuffer)</td></tr>
|
|
<tr class="memdesc:ae8444f3a85535e62cdb1ae9c192677d6"><td class="mdescLeft"> </td><td class="mdescRight">Initialize an MQTT context. <br /></td></tr>
|
|
<tr class="separator:ae8444f3a85535e62cdb1ae9c192677d6"><td class="memSeparator" colspan="2"> </td></tr>
|
|
<tr class="memitem:afe4c020749e3b9ca044e0e9ad96025c5"><td class="memItemLeft" align="right" valign="top"><a class="el" href="group__mqtt__enum__types.html#gaba7ec045874a1c3432f99173367f735c">MQTTStatus_t</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="core__mqtt_8h.html#afe4c020749e3b9ca044e0e9ad96025c5">MQTT_InitStatefulQoS</a> (<a class="el" href="struct_m_q_t_t_context__t.html">MQTTContext_t</a> *pContext, <a class="el" href="struct_m_q_t_t_pub_ack_info__t.html">MQTTPubAckInfo_t</a> *pOutgoingPublishRecords, size_t outgoingPublishCount, <a class="el" href="struct_m_q_t_t_pub_ack_info__t.html">MQTTPubAckInfo_t</a> *pIncomingPublishRecords, size_t incomingPublishCount)</td></tr>
|
|
<tr class="memdesc:afe4c020749e3b9ca044e0e9ad96025c5"><td class="mdescLeft"> </td><td class="mdescRight">Initialize an MQTT context for QoS > 0. <br /></td></tr>
|
|
<tr class="separator:afe4c020749e3b9ca044e0e9ad96025c5"><td class="memSeparator" colspan="2"> </td></tr>
|
|
<tr class="memitem:aed1e4dc123a8ba79ac569cb17c69bfa0"><td class="memItemLeft" align="right" valign="top"><a class="el" href="group__mqtt__enum__types.html#gaba7ec045874a1c3432f99173367f735c">MQTTStatus_t</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="core__mqtt_8h.html#aed1e4dc123a8ba79ac569cb17c69bfa0">MQTT_Connect</a> (<a class="el" href="struct_m_q_t_t_context__t.html">MQTTContext_t</a> *pContext, const <a class="el" href="struct_m_q_t_t_connect_info__t.html">MQTTConnectInfo_t</a> *pConnectInfo, const <a class="el" href="struct_m_q_t_t_publish_info__t.html">MQTTPublishInfo_t</a> *pWillInfo, uint32_t timeoutMs, bool *pSessionPresent)</td></tr>
|
|
<tr class="memdesc:aed1e4dc123a8ba79ac569cb17c69bfa0"><td class="mdescLeft"> </td><td class="mdescRight">Establish an MQTT session. <br /></td></tr>
|
|
<tr class="separator:aed1e4dc123a8ba79ac569cb17c69bfa0"><td class="memSeparator" colspan="2"> </td></tr>
|
|
<tr class="memitem:a567aa9c38726a7879f9cbf943e813e8f"><td class="memItemLeft" align="right" valign="top"><a class="el" href="group__mqtt__enum__types.html#gaba7ec045874a1c3432f99173367f735c">MQTTStatus_t</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="core__mqtt_8h.html#a567aa9c38726a7879f9cbf943e813e8f">MQTT_Subscribe</a> (<a class="el" href="struct_m_q_t_t_context__t.html">MQTTContext_t</a> *pContext, const <a class="el" href="struct_m_q_t_t_subscribe_info__t.html">MQTTSubscribeInfo_t</a> *pSubscriptionList, size_t subscriptionCount, uint16_t packetId)</td></tr>
|
|
<tr class="memdesc:a567aa9c38726a7879f9cbf943e813e8f"><td class="mdescLeft"> </td><td class="mdescRight">Sends MQTT SUBSCRIBE for the given list of topic filters to the broker. <br /></td></tr>
|
|
<tr class="separator:a567aa9c38726a7879f9cbf943e813e8f"><td class="memSeparator" colspan="2"> </td></tr>
|
|
<tr class="memitem:a1d8217e9d30fb2aed002060a8c97c63e"><td class="memItemLeft" align="right" valign="top"><a class="el" href="group__mqtt__enum__types.html#gaba7ec045874a1c3432f99173367f735c">MQTTStatus_t</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="core__mqtt_8h.html#a1d8217e9d30fb2aed002060a8c97c63e">MQTT_Publish</a> (<a class="el" href="struct_m_q_t_t_context__t.html">MQTTContext_t</a> *pContext, const <a class="el" href="struct_m_q_t_t_publish_info__t.html">MQTTPublishInfo_t</a> *pPublishInfo, uint16_t packetId)</td></tr>
|
|
<tr class="memdesc:a1d8217e9d30fb2aed002060a8c97c63e"><td class="mdescLeft"> </td><td class="mdescRight">Publishes a message to the given topic name. <br /></td></tr>
|
|
<tr class="separator:a1d8217e9d30fb2aed002060a8c97c63e"><td class="memSeparator" colspan="2"> </td></tr>
|
|
<tr class="memitem:a31b74c34cd295b98ed5f5b4c15ed4a8b"><td class="memItemLeft" align="right" valign="top"><a class="el" href="group__mqtt__enum__types.html#gaba7ec045874a1c3432f99173367f735c">MQTTStatus_t</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="core__mqtt_8h.html#a31b74c34cd295b98ed5f5b4c15ed4a8b">MQTT_CancelCallback</a> (const <a class="el" href="struct_m_q_t_t_context__t.html">MQTTContext_t</a> *pContext, uint16_t packetId)</td></tr>
|
|
<tr class="memdesc:a31b74c34cd295b98ed5f5b4c15ed4a8b"><td class="mdescLeft"> </td><td class="mdescRight">Cancels an outgoing publish callback (only for QoS > QoS0) by removing it from the pending ACK list. <br /></td></tr>
|
|
<tr class="separator:a31b74c34cd295b98ed5f5b4c15ed4a8b"><td class="memSeparator" colspan="2"> </td></tr>
|
|
<tr class="memitem:a66eced0c62ace790354ae3de40fc0959"><td class="memItemLeft" align="right" valign="top"><a class="el" href="group__mqtt__enum__types.html#gaba7ec045874a1c3432f99173367f735c">MQTTStatus_t</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="core__mqtt_8h.html#a66eced0c62ace790354ae3de40fc0959">MQTT_Ping</a> (<a class="el" href="struct_m_q_t_t_context__t.html">MQTTContext_t</a> *pContext)</td></tr>
|
|
<tr class="memdesc:a66eced0c62ace790354ae3de40fc0959"><td class="mdescLeft"> </td><td class="mdescRight">Sends an MQTT PINGREQ to broker. <br /></td></tr>
|
|
<tr class="separator:a66eced0c62ace790354ae3de40fc0959"><td class="memSeparator" colspan="2"> </td></tr>
|
|
<tr class="memitem:a77c911dbe24c5a51aaea88250895dba4"><td class="memItemLeft" align="right" valign="top"><a class="el" href="group__mqtt__enum__types.html#gaba7ec045874a1c3432f99173367f735c">MQTTStatus_t</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="core__mqtt_8h.html#a77c911dbe24c5a51aaea88250895dba4">MQTT_Unsubscribe</a> (<a class="el" href="struct_m_q_t_t_context__t.html">MQTTContext_t</a> *pContext, const <a class="el" href="struct_m_q_t_t_subscribe_info__t.html">MQTTSubscribeInfo_t</a> *pSubscriptionList, size_t subscriptionCount, uint16_t packetId)</td></tr>
|
|
<tr class="memdesc:a77c911dbe24c5a51aaea88250895dba4"><td class="mdescLeft"> </td><td class="mdescRight">Sends MQTT UNSUBSCRIBE for the given list of topic filters to the broker. <br /></td></tr>
|
|
<tr class="separator:a77c911dbe24c5a51aaea88250895dba4"><td class="memSeparator" colspan="2"> </td></tr>
|
|
<tr class="memitem:ac79c366acbc3dddd88072d99ccb9140c"><td class="memItemLeft" align="right" valign="top"><a class="el" href="group__mqtt__enum__types.html#gaba7ec045874a1c3432f99173367f735c">MQTTStatus_t</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="core__mqtt_8h.html#ac79c366acbc3dddd88072d99ccb9140c">MQTT_Disconnect</a> (<a class="el" href="struct_m_q_t_t_context__t.html">MQTTContext_t</a> *pContext)</td></tr>
|
|
<tr class="memdesc:ac79c366acbc3dddd88072d99ccb9140c"><td class="mdescLeft"> </td><td class="mdescRight">Disconnect an MQTT session. <br /></td></tr>
|
|
<tr class="separator:ac79c366acbc3dddd88072d99ccb9140c"><td class="memSeparator" colspan="2"> </td></tr>
|
|
<tr class="memitem:ab95d3d6b3eed98a6184fb2018c5b55d7"><td class="memItemLeft" align="right" valign="top"><a class="el" href="group__mqtt__enum__types.html#gaba7ec045874a1c3432f99173367f735c">MQTTStatus_t</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="core__mqtt_8h.html#ab95d3d6b3eed98a6184fb2018c5b55d7">MQTT_ProcessLoop</a> (<a class="el" href="struct_m_q_t_t_context__t.html">MQTTContext_t</a> *pContext)</td></tr>
|
|
<tr class="memdesc:ab95d3d6b3eed98a6184fb2018c5b55d7"><td class="mdescLeft"> </td><td class="mdescRight">Loop to receive packets from the transport interface. Handles keep alive. <br /></td></tr>
|
|
<tr class="separator:ab95d3d6b3eed98a6184fb2018c5b55d7"><td class="memSeparator" colspan="2"> </td></tr>
|
|
<tr class="memitem:aeb7c37284fcf6f68eb577427a6763fc6"><td class="memItemLeft" align="right" valign="top"><a class="el" href="group__mqtt__enum__types.html#gaba7ec045874a1c3432f99173367f735c">MQTTStatus_t</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="core__mqtt_8h.html#aeb7c37284fcf6f68eb577427a6763fc6">MQTT_ReceiveLoop</a> (<a class="el" href="struct_m_q_t_t_context__t.html">MQTTContext_t</a> *pContext)</td></tr>
|
|
<tr class="memdesc:aeb7c37284fcf6f68eb577427a6763fc6"><td class="mdescLeft"> </td><td class="mdescRight">Loop to receive packets from the transport interface. Does not handle keep alive. <br /></td></tr>
|
|
<tr class="separator:aeb7c37284fcf6f68eb577427a6763fc6"><td class="memSeparator" colspan="2"> </td></tr>
|
|
<tr class="memitem:a00e1a3eba2c21899a6b4312c7d65d090"><td class="memItemLeft" align="right" valign="top">uint16_t </td><td class="memItemRight" valign="bottom"><a class="el" href="core__mqtt_8h.html#a00e1a3eba2c21899a6b4312c7d65d090">MQTT_GetPacketId</a> (<a class="el" href="struct_m_q_t_t_context__t.html">MQTTContext_t</a> *pContext)</td></tr>
|
|
<tr class="memdesc:a00e1a3eba2c21899a6b4312c7d65d090"><td class="mdescLeft"> </td><td class="mdescRight">Get a packet ID that is valid according to the MQTT 3.1.1 spec. <br /></td></tr>
|
|
<tr class="separator:a00e1a3eba2c21899a6b4312c7d65d090"><td class="memSeparator" colspan="2"> </td></tr>
|
|
<tr class="memitem:a633409812b18547365ec9b853069021b"><td class="memItemLeft" align="right" valign="top"><a class="el" href="group__mqtt__enum__types.html#gaba7ec045874a1c3432f99173367f735c">MQTTStatus_t</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="core__mqtt_8h.html#a633409812b18547365ec9b853069021b">MQTT_MatchTopic</a> (const char *pTopicName, const uint16_t topicNameLength, const char *pTopicFilter, const uint16_t topicFilterLength, bool *pIsMatch)</td></tr>
|
|
<tr class="memdesc:a633409812b18547365ec9b853069021b"><td class="mdescLeft"> </td><td class="mdescRight">A utility function that determines whether the passed topic filter and topic name match according to the MQTT 3.1.1 protocol specification. <br /></td></tr>
|
|
<tr class="separator:a633409812b18547365ec9b853069021b"><td class="memSeparator" colspan="2"> </td></tr>
|
|
<tr class="memitem:ac43449e06856c6703cda73359c222bd2"><td class="memItemLeft" align="right" valign="top"><a class="el" href="group__mqtt__enum__types.html#gaba7ec045874a1c3432f99173367f735c">MQTTStatus_t</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="core__mqtt_8h.html#ac43449e06856c6703cda73359c222bd2">MQTT_GetSubAckStatusCodes</a> (const <a class="el" href="struct_m_q_t_t_packet_info__t.html">MQTTPacketInfo_t</a> *pSubackPacket, uint8_t **pPayloadStart, size_t *pPayloadSize)</td></tr>
|
|
<tr class="memdesc:ac43449e06856c6703cda73359c222bd2"><td class="mdescLeft"> </td><td class="mdescRight">Parses the payload of an MQTT SUBACK packet that contains status codes corresponding to topic filter subscription requests from the original subscribe packet. <br /></td></tr>
|
|
<tr class="separator:ac43449e06856c6703cda73359c222bd2"><td class="memSeparator" colspan="2"> </td></tr>
|
|
<tr class="memitem:a05d9facfce89c5f9edef09ca13717f50"><td class="memItemLeft" align="right" valign="top">const char * </td><td class="memItemRight" valign="bottom"><a class="el" href="core__mqtt_8h.html#a05d9facfce89c5f9edef09ca13717f50">MQTT_Status_strerror</a> (<a class="el" href="group__mqtt__enum__types.html#gaba7ec045874a1c3432f99173367f735c">MQTTStatus_t</a> status)</td></tr>
|
|
<tr class="memdesc:a05d9facfce89c5f9edef09ca13717f50"><td class="mdescLeft"> </td><td class="mdescRight">Error code to string conversion for MQTT statuses. <br /></td></tr>
|
|
<tr class="separator:a05d9facfce89c5f9edef09ca13717f50"><td class="memSeparator" colspan="2"> </td></tr>
|
|
</table>
|
|
<a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
|
|
<div class="textblock"><p>User-facing functions of the MQTT 3.1.1 library. </p>
|
|
</div><h2 class="groupheader">Function Documentation</h2>
|
|
<a id="ae8444f3a85535e62cdb1ae9c192677d6" name="ae8444f3a85535e62cdb1ae9c192677d6"></a>
|
|
<h2 class="memtitle"><span class="permalink"><a href="#ae8444f3a85535e62cdb1ae9c192677d6">◆ </a></span>MQTT_Init()</h2>
|
|
|
|
<div class="memitem">
|
|
<div class="memproto">
|
|
<table class="memname">
|
|
<tr>
|
|
<td class="memname"><a class="el" href="group__mqtt__enum__types.html#gaba7ec045874a1c3432f99173367f735c">MQTTStatus_t</a> MQTT_Init </td>
|
|
<td>(</td>
|
|
<td class="paramtype"><a class="el" href="struct_m_q_t_t_context__t.html">MQTTContext_t</a> * </td>
|
|
<td class="paramname"><em>pContext</em>, </td>
|
|
</tr>
|
|
<tr>
|
|
<td class="paramkey"></td>
|
|
<td></td>
|
|
<td class="paramtype">const <a class="el" href="struct_transport_interface__t.html">TransportInterface_t</a> * </td>
|
|
<td class="paramname"><em>pTransportInterface</em>, </td>
|
|
</tr>
|
|
<tr>
|
|
<td class="paramkey"></td>
|
|
<td></td>
|
|
<td class="paramtype"><a class="el" href="group__mqtt__callback__types.html#gae3bea55b0e49e5208b8c5709a5ea23aa">MQTTGetCurrentTimeFunc_t</a> </td>
|
|
<td class="paramname"><em>getTimeFunction</em>, </td>
|
|
</tr>
|
|
<tr>
|
|
<td class="paramkey"></td>
|
|
<td></td>
|
|
<td class="paramtype"><a class="el" href="group__mqtt__callback__types.html#ga00d348277ed4fde23c95bfc749ae954a">MQTTEventCallback_t</a> </td>
|
|
<td class="paramname"><em>userCallback</em>, </td>
|
|
</tr>
|
|
<tr>
|
|
<td class="paramkey"></td>
|
|
<td></td>
|
|
<td class="paramtype">const <a class="el" href="struct_m_q_t_t_fixed_buffer__t.html">MQTTFixedBuffer_t</a> * </td>
|
|
<td class="paramname"><em>pNetworkBuffer</em> </td>
|
|
</tr>
|
|
<tr>
|
|
<td></td>
|
|
<td>)</td>
|
|
<td></td><td></td>
|
|
</tr>
|
|
</table>
|
|
</div><div class="memdoc">
|
|
|
|
<p>Initialize an MQTT context. </p>
|
|
<p>This function must be called on an <a class="el" href="struct_m_q_t_t_context__t.html" title="A struct representing an MQTT connection.">MQTTContext_t</a> before any other function.</p>
|
|
<dl class="section note"><dt>Note</dt><dd>The <a class="el" href="group__mqtt__callback__types.html#gae3bea55b0e49e5208b8c5709a5ea23aa" title="Application provided function to query the time elapsed since a given epoch in milliseconds.">MQTTGetCurrentTimeFunc_t</a> 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 <a class="el" href="core__mqtt_8h.html#aed1e4dc123a8ba79ac569cb17c69bfa0" title="Establish an MQTT session.">MQTT_Connect</a>, <a class="el" href="core__mqtt_8h.html#ab95d3d6b3eed98a6184fb2018c5b55d7" title="Loop to receive packets from the transport interface. Handles keep alive.">MQTT_ProcessLoop</a>, and <a class="el" href="core__mqtt_8h.html#aeb7c37284fcf6f68eb577427a6763fc6" title="Loop to receive packets from the transport interface. Does not handle keep alive.">MQTT_ReceiveLoop</a> and configure the <a class="el" href="core__mqtt__config__defaults_8h.html#a43dc9a67427d9e420a65955eea0e2671" title="The maximum duration between non-empty network reads while receiving an MQTT packet via the MQTT_Proc...">MQTT_RECV_POLLING_TIMEOUT_MS</a> and <a class="el" href="core__mqtt__config__defaults_8h.html#ac262cab68c4c713ebc2b91a2e4ab8b19" title="The maximum duration allowed to send an MQTT packet over the transport interface.">MQTT_SEND_TIMEOUT_MS</a> configurations to be 0. This will result in loop functions running for a single iteration, and <a class="el" href="core__mqtt_8h.html#aed1e4dc123a8ba79ac569cb17c69bfa0" title="Establish an MQTT session.">MQTT_Connect</a> relying on <a class="el" href="core__mqtt__config__defaults_8h.html#a8ca6c96436d5e7c2c8a7933fb28a5c87" title="The number of retries for receiving CONNACK.">MQTT_MAX_CONNACK_RECEIVE_RETRY_COUNT</a> to receive the CONNACK packet.</dd></dl>
|
|
<dl class="params"><dt>Parameters</dt><dd>
|
|
<table class="params">
|
|
<tr><td class="paramdir">[in]</td><td class="paramname">pContext</td><td>The context to initialize. </td></tr>
|
|
<tr><td class="paramdir">[in]</td><td class="paramname">pTransportInterface</td><td>The transport interface to use with the context. </td></tr>
|
|
<tr><td class="paramdir">[in]</td><td class="paramname">getTimeFunction</td><td>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. </td></tr>
|
|
<tr><td class="paramdir">[in]</td><td class="paramname">userCallback</td><td>The user callback to use with the context to notify about incoming packet events. </td></tr>
|
|
<tr><td class="paramdir">[in]</td><td class="paramname">pNetworkBuffer</td><td>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 <code>pContext</code> and must not be used by another context and/or application.</td></tr>
|
|
</table>
|
|
</dd>
|
|
</dl>
|
|
<dl class="section return"><dt>Returns</dt><dd><a class="el" href="group__mqtt__enum__types.html#ggaba7ec045874a1c3432f99173367f735caa39030c93b0263b2699502a074f003b5">MQTTBadParameter</a> if invalid parameters are passed; <a class="el" href="group__mqtt__enum__types.html#ggaba7ec045874a1c3432f99173367f735ca484e062cb4f3fccc1858dd25cfeee056">MQTTSuccess</a> otherwise.</dd></dl>
|
|
<p><b>Example</b> </p><div class="fragment"><div class="line"><span class="comment">// Function for obtaining a timestamp.</span></div>
|
|
<div class="line">uint32_t getTimeStampMs();</div>
|
|
<div class="line"><span class="comment">// Callback function for receiving packets.</span></div>
|
|
<div class="line"><span class="keywordtype">void</span> eventCallback(</div>
|
|
<div class="line"> <a class="code hl_struct" href="struct_m_q_t_t_context__t.html">MQTTContext_t</a> * pContext,</div>
|
|
<div class="line"> <a class="code hl_struct" href="struct_m_q_t_t_packet_info__t.html">MQTTPacketInfo_t</a> * pPacketInfo,</div>
|
|
<div class="line"> <a class="code hl_struct" href="struct_m_q_t_t_deserialized_info__t.html">MQTTDeserializedInfo_t</a> * pDeserializedInfo</div>
|
|
<div class="line">);</div>
|
|
<div class="line"><span class="comment">// Network send.</span></div>
|
|
<div class="line">int32_t networkSend( <a class="code hl_typedef" href="group__mqtt__struct__types.html#ga7769e434e7811caed8cd6fd7f9ec26ec">NetworkContext_t</a> * pContext, <span class="keyword">const</span> <span class="keywordtype">void</span> * pBuffer, <span class="keywordtype">size_t</span> bytes );</div>
|
|
<div class="line"><span class="comment">// Network receive.</span></div>
|
|
<div class="line">int32_t networkRecv( <a class="code hl_typedef" href="group__mqtt__struct__types.html#ga7769e434e7811caed8cd6fd7f9ec26ec">NetworkContext_t</a> * pContext, <span class="keywordtype">void</span> * pBuffer, <span class="keywordtype">size_t</span> bytes );</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><a class="code hl_struct" href="struct_m_q_t_t_context__t.html">MQTTContext_t</a> mqttContext;</div>
|
|
<div class="line"><a class="code hl_struct" href="struct_transport_interface__t.html">TransportInterface_t</a> transport;</div>
|
|
<div class="line"><a class="code hl_struct" href="struct_m_q_t_t_fixed_buffer__t.html">MQTTFixedBuffer_t</a> fixedBuffer;</div>
|
|
<div class="line"><span class="comment">// Create a globally accessible buffer which remains in scope for the entire duration</span></div>
|
|
<div class="line"><span class="comment">// of the MQTT context.</span></div>
|
|
<div class="line">uint8_t buffer[ 1024 ];</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// Clear context.</span></div>
|
|
<div class="line">memset( ( <span class="keywordtype">void</span> * ) &mqttContext, 0x00, <span class="keyword">sizeof</span>( <a class="code hl_struct" href="struct_m_q_t_t_context__t.html">MQTTContext_t</a> ) );</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// Set transport interface members.</span></div>
|
|
<div class="line">transport.<a class="code hl_variable" href="struct_transport_interface__t.html#aaf4702050bef8d62714a4d3900e95087">pNetworkContext</a> = &someTransportContext;</div>
|
|
<div class="line">transport.<a class="code hl_variable" href="struct_transport_interface__t.html#a01cd9935e9a5266ca196243a0054d489">send</a> = networkSend;</div>
|
|
<div class="line">transport.<a class="code hl_variable" href="struct_transport_interface__t.html#a7c34e9b865e2a509306f09c7dfa3699e">recv</a> = networkRecv;</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// Set buffer members.</span></div>
|
|
<div class="line">fixedBuffer.<a class="code hl_variable" href="struct_m_q_t_t_fixed_buffer__t.html#acea147448e044870fb36b7fa2347dbd6">pBuffer</a> = buffer;</div>
|
|
<div class="line">fixedBuffer.<a class="code hl_variable" href="struct_m_q_t_t_fixed_buffer__t.html#a0b0b6a93cc62751ebeb03095d5431636">size</a> = 1024;</div>
|
|
<div class="line"> </div>
|
|
<div class="line">status = <a class="code hl_function" href="core__mqtt_8h.html#ae8444f3a85535e62cdb1ae9c192677d6">MQTT_Init</a>( &mqttContext, &transport, getTimeStampMs, eventCallback, &fixedBuffer );</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="keywordflow">if</span>( status == <a class="code hl_enumvalue" href="group__mqtt__enum__types.html#ggaba7ec045874a1c3432f99173367f735ca484e062cb4f3fccc1858dd25cfeee056">MQTTSuccess</a> )</div>
|
|
<div class="line">{</div>
|
|
<div class="line"> <span class="comment">// Do something with mqttContext. The transport and fixedBuffer structs were</span></div>
|
|
<div class="line"> <span class="comment">// copied into the context, so the original structs do not need to stay in scope.</span></div>
|
|
<div class="line"> <span class="comment">// However, the memory pointed to by the fixedBuffer.pBuffer must remain in scope.</span></div>
|
|
<div class="line">}</div>
|
|
<div class="ttc" id="acore__mqtt_8h_html_ae8444f3a85535e62cdb1ae9c192677d6"><div class="ttname"><a href="core__mqtt_8h.html#ae8444f3a85535e62cdb1ae9c192677d6">MQTT_Init</a></div><div class="ttdeci">MQTTStatus_t MQTT_Init(MQTTContext_t *pContext, const TransportInterface_t *pTransportInterface, MQTTGetCurrentTimeFunc_t getTimeFunction, MQTTEventCallback_t userCallback, const MQTTFixedBuffer_t *pNetworkBuffer)</div><div class="ttdoc">Initialize an MQTT context.</div><div class="ttdef"><b>Definition:</b> core_mqtt.c:2531</div></div>
|
|
<div class="ttc" id="agroup__mqtt__enum__types_html_ggaba7ec045874a1c3432f99173367f735ca484e062cb4f3fccc1858dd25cfeee056"><div class="ttname"><a href="group__mqtt__enum__types.html#ggaba7ec045874a1c3432f99173367f735ca484e062cb4f3fccc1858dd25cfeee056">MQTTSuccess</a></div><div class="ttdeci">@ MQTTSuccess</div><div class="ttdef"><b>Definition:</b> core_mqtt_serializer.h:88</div></div>
|
|
<div class="ttc" id="agroup__mqtt__struct__types_html_ga7769e434e7811caed8cd6fd7f9ec26ec"><div class="ttname"><a href="group__mqtt__struct__types.html#ga7769e434e7811caed8cd6fd7f9ec26ec">NetworkContext_t</a></div><div class="ttdeci">struct NetworkContext NetworkContext_t</div><div class="ttdoc">The NetworkContext is an incomplete type. An implementation of this interface must define struct Netw...</div><div class="ttdef"><b>Definition:</b> transport_interface.h:191</div></div>
|
|
<div class="ttc" id="astruct_m_q_t_t_context__t_html"><div class="ttname"><a href="struct_m_q_t_t_context__t.html">MQTTContext_t</a></div><div class="ttdoc">A struct representing an MQTT connection.</div><div class="ttdef"><b>Definition:</b> core_mqtt.h:173</div></div>
|
|
<div class="ttc" id="astruct_m_q_t_t_deserialized_info__t_html"><div class="ttname"><a href="struct_m_q_t_t_deserialized_info__t.html">MQTTDeserializedInfo_t</a></div><div class="ttdoc">Struct to hold deserialized packet information for an MQTTEventCallback_t callback.</div><div class="ttdef"><b>Definition:</b> core_mqtt.h:257</div></div>
|
|
<div class="ttc" id="astruct_m_q_t_t_fixed_buffer__t_html"><div class="ttname"><a href="struct_m_q_t_t_fixed_buffer__t.html">MQTTFixedBuffer_t</a></div><div class="ttdoc">Buffer passed to MQTT library.</div><div class="ttdef"><b>Definition:</b> core_mqtt_serializer.h:123</div></div>
|
|
<div class="ttc" id="astruct_m_q_t_t_fixed_buffer__t_html_a0b0b6a93cc62751ebeb03095d5431636"><div class="ttname"><a href="struct_m_q_t_t_fixed_buffer__t.html#a0b0b6a93cc62751ebeb03095d5431636">MQTTFixedBuffer_t::size</a></div><div class="ttdeci">size_t size</div><div class="ttdoc">Size of buffer.</div><div class="ttdef"><b>Definition:</b> core_mqtt_serializer.h:125</div></div>
|
|
<div class="ttc" id="astruct_m_q_t_t_fixed_buffer__t_html_acea147448e044870fb36b7fa2347dbd6"><div class="ttname"><a href="struct_m_q_t_t_fixed_buffer__t.html#acea147448e044870fb36b7fa2347dbd6">MQTTFixedBuffer_t::pBuffer</a></div><div class="ttdeci">uint8_t * pBuffer</div><div class="ttdoc">Pointer to buffer.</div><div class="ttdef"><b>Definition:</b> core_mqtt_serializer.h:124</div></div>
|
|
<div class="ttc" id="astruct_m_q_t_t_packet_info__t_html"><div class="ttname"><a href="struct_m_q_t_t_packet_info__t.html">MQTTPacketInfo_t</a></div><div class="ttdoc">MQTT incoming packet parameters.</div><div class="ttdef"><b>Definition:</b> core_mqtt_serializer.h:244</div></div>
|
|
<div class="ttc" id="astruct_transport_interface__t_html"><div class="ttname"><a href="struct_transport_interface__t.html">TransportInterface_t</a></div><div class="ttdoc">The transport layer interface.</div><div class="ttdef"><b>Definition:</b> transport_interface.h:299</div></div>
|
|
<div class="ttc" id="astruct_transport_interface__t_html_a01cd9935e9a5266ca196243a0054d489"><div class="ttname"><a href="struct_transport_interface__t.html#a01cd9935e9a5266ca196243a0054d489">TransportInterface_t::send</a></div><div class="ttdeci">TransportSend_t send</div><div class="ttdef"><b>Definition:</b> transport_interface.h:301</div></div>
|
|
<div class="ttc" id="astruct_transport_interface__t_html_a7c34e9b865e2a509306f09c7dfa3699e"><div class="ttname"><a href="struct_transport_interface__t.html#a7c34e9b865e2a509306f09c7dfa3699e">TransportInterface_t::recv</a></div><div class="ttdeci">TransportRecv_t recv</div><div class="ttdef"><b>Definition:</b> transport_interface.h:300</div></div>
|
|
<div class="ttc" id="astruct_transport_interface__t_html_aaf4702050bef8d62714a4d3900e95087"><div class="ttname"><a href="struct_transport_interface__t.html#aaf4702050bef8d62714a4d3900e95087">TransportInterface_t::pNetworkContext</a></div><div class="ttdeci">NetworkContext_t * pNetworkContext</div><div class="ttdef"><b>Definition:</b> transport_interface.h:303</div></div>
|
|
</div><!-- fragment -->
|
|
</div>
|
|
</div>
|
|
<a id="afe4c020749e3b9ca044e0e9ad96025c5" name="afe4c020749e3b9ca044e0e9ad96025c5"></a>
|
|
<h2 class="memtitle"><span class="permalink"><a href="#afe4c020749e3b9ca044e0e9ad96025c5">◆ </a></span>MQTT_InitStatefulQoS()</h2>
|
|
|
|
<div class="memitem">
|
|
<div class="memproto">
|
|
<table class="memname">
|
|
<tr>
|
|
<td class="memname"><a class="el" href="group__mqtt__enum__types.html#gaba7ec045874a1c3432f99173367f735c">MQTTStatus_t</a> MQTT_InitStatefulQoS </td>
|
|
<td>(</td>
|
|
<td class="paramtype"><a class="el" href="struct_m_q_t_t_context__t.html">MQTTContext_t</a> * </td>
|
|
<td class="paramname"><em>pContext</em>, </td>
|
|
</tr>
|
|
<tr>
|
|
<td class="paramkey"></td>
|
|
<td></td>
|
|
<td class="paramtype"><a class="el" href="struct_m_q_t_t_pub_ack_info__t.html">MQTTPubAckInfo_t</a> * </td>
|
|
<td class="paramname"><em>pOutgoingPublishRecords</em>, </td>
|
|
</tr>
|
|
<tr>
|
|
<td class="paramkey"></td>
|
|
<td></td>
|
|
<td class="paramtype">size_t </td>
|
|
<td class="paramname"><em>outgoingPublishCount</em>, </td>
|
|
</tr>
|
|
<tr>
|
|
<td class="paramkey"></td>
|
|
<td></td>
|
|
<td class="paramtype"><a class="el" href="struct_m_q_t_t_pub_ack_info__t.html">MQTTPubAckInfo_t</a> * </td>
|
|
<td class="paramname"><em>pIncomingPublishRecords</em>, </td>
|
|
</tr>
|
|
<tr>
|
|
<td class="paramkey"></td>
|
|
<td></td>
|
|
<td class="paramtype">size_t </td>
|
|
<td class="paramname"><em>incomingPublishCount</em> </td>
|
|
</tr>
|
|
<tr>
|
|
<td></td>
|
|
<td>)</td>
|
|
<td></td><td></td>
|
|
</tr>
|
|
</table>
|
|
</div><div class="memdoc">
|
|
|
|
<p>Initialize an MQTT context for QoS > 0. </p>
|
|
<p>This function must be called on an <a class="el" href="struct_m_q_t_t_context__t.html" title="A struct representing an MQTT connection.">MQTTContext_t</a> after MQTT_Init and before any other function.</p>
|
|
<dl class="params"><dt>Parameters</dt><dd>
|
|
<table class="params">
|
|
<tr><td class="paramdir">[in]</td><td class="paramname">pContext</td><td>The context to initialize. </td></tr>
|
|
<tr><td class="paramdir">[in]</td><td class="paramname">pOutgoingPublishRecords</td><td>Pointer to memory which will be used to store state of outgoing publishes. </td></tr>
|
|
<tr><td class="paramdir">[in]</td><td class="paramname">outgoingPublishCount</td><td>Maximum number of records which can be kept in the memory pointed to by <code>pOutgoingPublishRecords</code>. </td></tr>
|
|
<tr><td class="paramdir">[in]</td><td class="paramname">pIncomingPublishRecords</td><td>Pointer to memory which will be used to store state of incoming publishes. </td></tr>
|
|
<tr><td class="paramdir">[in]</td><td class="paramname">incomingPublishCount</td><td>Maximum number of records which can be kept in the memory pointed to by <code>pIncomingPublishRecords</code>.</td></tr>
|
|
</table>
|
|
</dd>
|
|
</dl>
|
|
<dl class="section return"><dt>Returns</dt><dd><a class="el" href="group__mqtt__enum__types.html#ggaba7ec045874a1c3432f99173367f735caa39030c93b0263b2699502a074f003b5">MQTTBadParameter</a> if invalid parameters are passed; <a class="el" href="group__mqtt__enum__types.html#ggaba7ec045874a1c3432f99173367f735ca484e062cb4f3fccc1858dd25cfeee056">MQTTSuccess</a> otherwise.</dd></dl>
|
|
<p><b>Example</b> </p><div class="fragment"><div class="line"><span class="comment">// Function for obtaining a timestamp.</span></div>
|
|
<div class="line">uint32_t getTimeStampMs();</div>
|
|
<div class="line"><span class="comment">// Callback function for receiving packets.</span></div>
|
|
<div class="line"><span class="keywordtype">void</span> eventCallback(</div>
|
|
<div class="line"> <a class="code hl_struct" href="struct_m_q_t_t_context__t.html">MQTTContext_t</a> * pContext,</div>
|
|
<div class="line"> <a class="code hl_struct" href="struct_m_q_t_t_packet_info__t.html">MQTTPacketInfo_t</a> * pPacketInfo,</div>
|
|
<div class="line"> <a class="code hl_struct" href="struct_m_q_t_t_deserialized_info__t.html">MQTTDeserializedInfo_t</a> * pDeserializedInfo</div>
|
|
<div class="line">);</div>
|
|
<div class="line"><span class="comment">// Network send.</span></div>
|
|
<div class="line">int32_t networkSend( <a class="code hl_typedef" href="group__mqtt__struct__types.html#ga7769e434e7811caed8cd6fd7f9ec26ec">NetworkContext_t</a> * pContext, <span class="keyword">const</span> <span class="keywordtype">void</span> * pBuffer, <span class="keywordtype">size_t</span> bytes );</div>
|
|
<div class="line"><span class="comment">// Network receive.</span></div>
|
|
<div class="line">int32_t networkRecv( <a class="code hl_typedef" href="group__mqtt__struct__types.html#ga7769e434e7811caed8cd6fd7f9ec26ec">NetworkContext_t</a> * pContext, <span class="keywordtype">void</span> * pBuffer, <span class="keywordtype">size_t</span> bytes );</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><a class="code hl_struct" href="struct_m_q_t_t_context__t.html">MQTTContext_t</a> mqttContext;</div>
|
|
<div class="line"><a class="code hl_struct" href="struct_transport_interface__t.html">TransportInterface_t</a> transport;</div>
|
|
<div class="line"><a class="code hl_struct" href="struct_m_q_t_t_fixed_buffer__t.html">MQTTFixedBuffer_t</a> fixedBuffer;</div>
|
|
<div class="line">uint8_t buffer[ 1024 ];</div>
|
|
<div class="line"><span class="keyword">const</span> <span class="keywordtype">size_t</span> outgoingPublishCount = 30;</div>
|
|
<div class="line"><a class="code hl_struct" href="struct_m_q_t_t_pub_ack_info__t.html">MQTTPubAckInfo_t</a> outgoingPublishes[ outgoingPublishCount ];</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// Clear context.</span></div>
|
|
<div class="line">memset( ( <span class="keywordtype">void</span> * ) &mqttContext, 0x00, <span class="keyword">sizeof</span>( <a class="code hl_struct" href="struct_m_q_t_t_context__t.html">MQTTContext_t</a> ) );</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// Set transport interface members.</span></div>
|
|
<div class="line">transport.<a class="code hl_variable" href="struct_transport_interface__t.html#aaf4702050bef8d62714a4d3900e95087">pNetworkContext</a> = &someTransportContext;</div>
|
|
<div class="line">transport.<a class="code hl_variable" href="struct_transport_interface__t.html#a01cd9935e9a5266ca196243a0054d489">send</a> = networkSend;</div>
|
|
<div class="line">transport.<a class="code hl_variable" href="struct_transport_interface__t.html#a7c34e9b865e2a509306f09c7dfa3699e">recv</a> = networkRecv;</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// Set buffer members.</span></div>
|
|
<div class="line">fixedBuffer.<a class="code hl_variable" href="struct_m_q_t_t_fixed_buffer__t.html#acea147448e044870fb36b7fa2347dbd6">pBuffer</a> = buffer;</div>
|
|
<div class="line">fixedBuffer.<a class="code hl_variable" href="struct_m_q_t_t_fixed_buffer__t.html#a0b0b6a93cc62751ebeb03095d5431636">size</a> = 1024;</div>
|
|
<div class="line"> </div>
|
|
<div class="line">status = <a class="code hl_function" href="core__mqtt_8h.html#ae8444f3a85535e62cdb1ae9c192677d6">MQTT_Init</a>( &mqttContext, &transport, getTimeStampMs, eventCallback, &fixedBuffer );</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="keywordflow">if</span>( status == <a class="code hl_enumvalue" href="group__mqtt__enum__types.html#ggaba7ec045874a1c3432f99173367f735ca484e062cb4f3fccc1858dd25cfeee056">MQTTSuccess</a> )</div>
|
|
<div class="line">{</div>
|
|
<div class="line"> <span class="comment">// We do not expect any incoming publishes in this example, therefore the incoming</span></div>
|
|
<div class="line"> <span class="comment">// publish pointer is NULL and the count is zero.</span></div>
|
|
<div class="line"> status = <a class="code hl_function" href="core__mqtt_8h.html#afe4c020749e3b9ca044e0e9ad96025c5">MQTT_InitStatefulQoS</a>( &mqttContext, outgoingPublishes, outgoingPublishCount, NULL, 0 );</div>
|
|
<div class="line"> </div>
|
|
<div class="line"> <span class="comment">// Now QoS1 and/or QoS2 publishes can be sent with this context.</span></div>
|
|
<div class="line">}</div>
|
|
<div class="ttc" id="acore__mqtt_8h_html_afe4c020749e3b9ca044e0e9ad96025c5"><div class="ttname"><a href="core__mqtt_8h.html#afe4c020749e3b9ca044e0e9ad96025c5">MQTT_InitStatefulQoS</a></div><div class="ttdeci">MQTTStatus_t MQTT_InitStatefulQoS(MQTTContext_t *pContext, MQTTPubAckInfo_t *pOutgoingPublishRecords, size_t outgoingPublishCount, MQTTPubAckInfo_t *pIncomingPublishRecords, size_t incomingPublishCount)</div><div class="ttdoc">Initialize an MQTT context for QoS > 0.</div><div class="ttdef"><b>Definition:</b> core_mqtt.c:2590</div></div>
|
|
<div class="ttc" id="astruct_m_q_t_t_pub_ack_info__t_html"><div class="ttname"><a href="struct_m_q_t_t_pub_ack_info__t.html">MQTTPubAckInfo_t</a></div><div class="ttdoc">An element of the state engine records for QoS 1 or Qos 2 publishes.</div><div class="ttdef"><b>Definition:</b> core_mqtt.h:162</div></div>
|
|
</div><!-- fragment -->
|
|
</div>
|
|
</div>
|
|
<a id="aed1e4dc123a8ba79ac569cb17c69bfa0" name="aed1e4dc123a8ba79ac569cb17c69bfa0"></a>
|
|
<h2 class="memtitle"><span class="permalink"><a href="#aed1e4dc123a8ba79ac569cb17c69bfa0">◆ </a></span>MQTT_Connect()</h2>
|
|
|
|
<div class="memitem">
|
|
<div class="memproto">
|
|
<table class="memname">
|
|
<tr>
|
|
<td class="memname"><a class="el" href="group__mqtt__enum__types.html#gaba7ec045874a1c3432f99173367f735c">MQTTStatus_t</a> MQTT_Connect </td>
|
|
<td>(</td>
|
|
<td class="paramtype"><a class="el" href="struct_m_q_t_t_context__t.html">MQTTContext_t</a> * </td>
|
|
<td class="paramname"><em>pContext</em>, </td>
|
|
</tr>
|
|
<tr>
|
|
<td class="paramkey"></td>
|
|
<td></td>
|
|
<td class="paramtype">const <a class="el" href="struct_m_q_t_t_connect_info__t.html">MQTTConnectInfo_t</a> * </td>
|
|
<td class="paramname"><em>pConnectInfo</em>, </td>
|
|
</tr>
|
|
<tr>
|
|
<td class="paramkey"></td>
|
|
<td></td>
|
|
<td class="paramtype">const <a class="el" href="struct_m_q_t_t_publish_info__t.html">MQTTPublishInfo_t</a> * </td>
|
|
<td class="paramname"><em>pWillInfo</em>, </td>
|
|
</tr>
|
|
<tr>
|
|
<td class="paramkey"></td>
|
|
<td></td>
|
|
<td class="paramtype">uint32_t </td>
|
|
<td class="paramname"><em>timeoutMs</em>, </td>
|
|
</tr>
|
|
<tr>
|
|
<td class="paramkey"></td>
|
|
<td></td>
|
|
<td class="paramtype">bool * </td>
|
|
<td class="paramname"><em>pSessionPresent</em> </td>
|
|
</tr>
|
|
<tr>
|
|
<td></td>
|
|
<td>)</td>
|
|
<td></td><td></td>
|
|
</tr>
|
|
</table>
|
|
</div><div class="memdoc">
|
|
|
|
<p>Establish an MQTT session. </p>
|
|
<p>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.</p>
|
|
<p>The maximum time this function waits for a CONNACK is decided in one of the following ways:</p><ol type="1">
|
|
<li>If <code>timeoutMs</code> is greater than 0: <a class="el" href="struct_m_q_t_t_context__t.html#aabe1d302a16771292151013e8e30c582" title="Function used to get millisecond timestamps.">MQTTContext_t.getTime</a> is used to ensure that the function does not wait more than <code>timeoutMs</code> for CONNACK.</li>
|
|
<li>If <code>timeoutMs</code> is 0: The network receive for CONNACK is retried up to the number of times configured by <a class="el" href="core__mqtt__config__defaults_8h.html#a8ca6c96436d5e7c2c8a7933fb28a5c87" title="The number of retries for receiving CONNACK.">MQTT_MAX_CONNACK_RECEIVE_RETRY_COUNT</a>.</li>
|
|
</ol>
|
|
<dl class="section note"><dt>Note</dt><dd>If a dummy <a class="el" href="group__mqtt__callback__types.html#gae3bea55b0e49e5208b8c5709a5ea23aa" title="Application provided function to query the time elapsed since a given epoch in milliseconds.">MQTTGetCurrentTimeFunc_t</a> was passed to <a class="el" href="core__mqtt_8h.html#ae8444f3a85535e62cdb1ae9c192677d6" title="Initialize an MQTT context.">MQTT_Init</a>, then a timeout value of 0 MUST be passed to the API, and the <a class="el" href="core__mqtt__config__defaults_8h.html#a43dc9a67427d9e420a65955eea0e2671" title="The maximum duration between non-empty network reads while receiving an MQTT packet via the MQTT_Proc...">MQTT_RECV_POLLING_TIMEOUT_MS</a> and <a class="el" href="core__mqtt__config__defaults_8h.html#ac262cab68c4c713ebc2b91a2e4ab8b19" title="The maximum duration allowed to send an MQTT packet over the transport interface.">MQTT_SEND_TIMEOUT_MS</a> timeout configurations MUST be set to 0.</dd></dl>
|
|
<dl class="params"><dt>Parameters</dt><dd>
|
|
<table class="params">
|
|
<tr><td class="paramdir">[in]</td><td class="paramname">pContext</td><td>Initialized MQTT context. </td></tr>
|
|
<tr><td class="paramdir">[in]</td><td class="paramname">pConnectInfo</td><td>MQTT CONNECT packet information. </td></tr>
|
|
<tr><td class="paramdir">[in]</td><td class="paramname">pWillInfo</td><td>Last Will and Testament. Pass NULL if Last Will and Testament is not used. </td></tr>
|
|
<tr><td class="paramdir">[in]</td><td class="paramname">timeoutMs</td><td>Maximum time in milliseconds to wait for a CONNACK packet. A zero timeout makes use of the retries for receiving CONNACK as configured with <a class="el" href="core__mqtt__config__defaults_8h.html#a8ca6c96436d5e7c2c8a7933fb28a5c87" title="The number of retries for receiving CONNACK.">MQTT_MAX_CONNACK_RECEIVE_RETRY_COUNT</a>. </td></tr>
|
|
<tr><td class="paramdir">[out]</td><td class="paramname">pSessionPresent</td><td>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.</td></tr>
|
|
</table>
|
|
</dd>
|
|
</dl>
|
|
<dl class="section return"><dt>Returns</dt><dd><a class="el" href="group__mqtt__enum__types.html#ggaba7ec045874a1c3432f99173367f735cab1be4db832a0468f024243bca151a8df">MQTTNoMemory</a> if the <a class="el" href="struct_m_q_t_t_context__t.html#a231c5576a6ce389317a3f00f95628276" title="The buffer used in sending and receiving packets from the network.">MQTTContext_t.networkBuffer</a> is too small to hold the MQTT packet; <a class="el" href="group__mqtt__enum__types.html#ggaba7ec045874a1c3432f99173367f735caa39030c93b0263b2699502a074f003b5">MQTTBadParameter</a> if invalid parameters are passed; <a class="el" href="group__mqtt__enum__types.html#ggaba7ec045874a1c3432f99173367f735cafd06b63fe9677fa2af06b0f4c7d4ad55">MQTTSendFailed</a> if transport send failed; <a class="el" href="group__mqtt__enum__types.html#ggaba7ec045874a1c3432f99173367f735caa14bc8aa4ad218702d782366945d43ac">MQTTRecvFailed</a> if transport receive failed for CONNACK; <a class="el" href="group__mqtt__enum__types.html#ggaba7ec045874a1c3432f99173367f735ca676f21c0ddf297ae3ec874bc829aa957">MQTTNoDataAvailable</a> if no data available to receive in transport until the <code>timeoutMs</code> for CONNACK; <a class="el" href="group__mqtt__enum__types.html#ggaba7ec045874a1c3432f99173367f735ca484e062cb4f3fccc1858dd25cfeee056">MQTTSuccess</a> otherwise.</dd></dl>
|
|
<dl class="section note"><dt>Note</dt><dd>This API may spend more time than provided in the timeoutMS parameters in certain conditions as listed below:</dd></dl>
|
|
<ol type="1">
|
|
<li>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.</li>
|
|
<li>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.</li>
|
|
</ol>
|
|
<p><b>Example</b> </p><div class="fragment"><div class="line"><span class="comment">// Variables used in this example.</span></div>
|
|
<div class="line"><a class="code hl_enumeration" href="group__mqtt__enum__types.html#gaba7ec045874a1c3432f99173367f735c">MQTTStatus_t</a> status;</div>
|
|
<div class="line"><a class="code hl_struct" href="struct_m_q_t_t_connect_info__t.html">MQTTConnectInfo_t</a> connectInfo = { 0 };</div>
|
|
<div class="line"><a class="code hl_struct" href="struct_m_q_t_t_publish_info__t.html">MQTTPublishInfo_t</a> willInfo = { 0 };</div>
|
|
<div class="line"><span class="keywordtype">bool</span> sessionPresent;</div>
|
|
<div class="line"><span class="comment">// This is assumed to have been initialized before calling this function.</span></div>
|
|
<div class="line"><a class="code hl_struct" href="struct_m_q_t_t_context__t.html">MQTTContext_t</a> * pContext;</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// True for creating a new session with broker, false if we want to resume an old one.</span></div>
|
|
<div class="line">connectInfo.<a class="code hl_variable" href="struct_m_q_t_t_connect_info__t.html#a606e7765c4f2215fb2bf630f6eb9ff6b">cleanSession</a> = <span class="keyword">true</span>;</div>
|
|
<div class="line"><span class="comment">// Client ID must be unique to broker. This field is required.</span></div>
|
|
<div class="line">connectInfo.<a class="code hl_variable" href="struct_m_q_t_t_connect_info__t.html#a010f8f6993cbf8899648d5c515ff7884">pClientIdentifier</a> = <span class="stringliteral">"someClientID"</span>;</div>
|
|
<div class="line">connectInfo.<a class="code hl_variable" href="struct_m_q_t_t_connect_info__t.html#a8077ef36ab318f3d35bee6f098fa54d4">clientIdentifierLength</a> = strlen( connectInfo.<a class="code hl_variable" href="struct_m_q_t_t_connect_info__t.html#a010f8f6993cbf8899648d5c515ff7884">pClientIdentifier</a> );</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// The following fields are optional.</span></div>
|
|
<div class="line"><span class="comment">// Value for keep alive.</span></div>
|
|
<div class="line">connectInfo.<a class="code hl_variable" href="struct_m_q_t_t_connect_info__t.html#a7d05d53261732ebdfbb9ee665a347591">keepAliveSeconds</a> = 60;</div>
|
|
<div class="line"><span class="comment">// Optional username and password.</span></div>
|
|
<div class="line">connectInfo.<a class="code hl_variable" href="struct_m_q_t_t_connect_info__t.html#a1118d7d3251a11445318557280db53b4">pUserName</a> = <span class="stringliteral">"someUserName"</span>;</div>
|
|
<div class="line">connectInfo.<a class="code hl_variable" href="struct_m_q_t_t_connect_info__t.html#a7165be3bb06d4527ab4eb773b50e05e1">userNameLength</a> = strlen( connectInfo.<a class="code hl_variable" href="struct_m_q_t_t_connect_info__t.html#a1118d7d3251a11445318557280db53b4">pUserName</a> );</div>
|
|
<div class="line">connectInfo.<a class="code hl_variable" href="struct_m_q_t_t_connect_info__t.html#acec6c79a11d2f0f130802393f34d2b5e">pPassword</a> = <span class="stringliteral">"somePassword"</span>;</div>
|
|
<div class="line">connectInfo.<a class="code hl_variable" href="struct_m_q_t_t_connect_info__t.html#a818c4e212a12020a4109eb890ec96383">passwordLength</a> = strlen( connectInfo.<a class="code hl_variable" href="struct_m_q_t_t_connect_info__t.html#acec6c79a11d2f0f130802393f34d2b5e">pPassword</a> );</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// The last will and testament is optional, it will be published by the broker</span></div>
|
|
<div class="line"><span class="comment">// should this client disconnect without sending a DISCONNECT packet.</span></div>
|
|
<div class="line">willInfo.<a class="code hl_variable" href="struct_m_q_t_t_publish_info__t.html#a178224d02b4acdec7e08e88de0e4b399">qos</a> = <a class="code hl_enumvalue" href="group__mqtt__enum__types.html#ggae308a5928d7f537379c29a894228093aaad51b23a1ae1417f96d8f343c788d1d2">MQTTQoS0</a>;</div>
|
|
<div class="line">willInfo.<a class="code hl_variable" href="struct_m_q_t_t_publish_info__t.html#aa80e8ca282d01630f878ad0afe81d7a4">pTopicName</a> = <span class="stringliteral">"/lwt/topic/name"</span>;</div>
|
|
<div class="line">willInfo.<a class="code hl_variable" href="struct_m_q_t_t_publish_info__t.html#a6161c792d20cc7cf8284c1b71ea1145f">topicNameLength</a> = strlen( willInfo.<a class="code hl_variable" href="struct_m_q_t_t_publish_info__t.html#aa80e8ca282d01630f878ad0afe81d7a4">pTopicName</a> );</div>
|
|
<div class="line">willInfo.<a class="code hl_variable" href="struct_m_q_t_t_publish_info__t.html#afc28299f4f625f5e674bb61b42f03380">pPayload</a> = <span class="stringliteral">"LWT Message"</span>;</div>
|
|
<div class="line">willInfo.<a class="code hl_variable" href="struct_m_q_t_t_publish_info__t.html#a7997964e11571f35f0c3b729db0f760f">payloadLength</a> = strlen( <span class="stringliteral">"LWT Message"</span> );</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// Send the connect packet. Use 100 ms as the timeout to wait for the CONNACK packet.</span></div>
|
|
<div class="line">status = <a class="code hl_function" href="core__mqtt_8h.html#aed1e4dc123a8ba79ac569cb17c69bfa0">MQTT_Connect</a>( pContext, &connectInfo, &willInfo, 100, &sessionPresent );</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="keywordflow">if</span>( status == <a class="code hl_enumvalue" href="group__mqtt__enum__types.html#ggaba7ec045874a1c3432f99173367f735ca484e062cb4f3fccc1858dd25cfeee056">MQTTSuccess</a> )</div>
|
|
<div class="line">{</div>
|
|
<div class="line"> <span class="comment">// Since we requested a clean session, this must be false</span></div>
|
|
<div class="line"> assert( sessionPresent == <span class="keyword">false</span> );</div>
|
|
<div class="line"> </div>
|
|
<div class="line"> <span class="comment">// Do something with the connection.</span></div>
|
|
<div class="line">}</div>
|
|
<div class="ttc" id="acore__mqtt_8h_html_aed1e4dc123a8ba79ac569cb17c69bfa0"><div class="ttname"><a href="core__mqtt_8h.html#aed1e4dc123a8ba79ac569cb17c69bfa0">MQTT_Connect</a></div><div class="ttdeci">MQTTStatus_t MQTT_Connect(MQTTContext_t *pContext, const MQTTConnectInfo_t *pConnectInfo, const MQTTPublishInfo_t *pWillInfo, uint32_t timeoutMs, bool *pSessionPresent)</div><div class="ttdoc">Establish an MQTT session.</div><div class="ttdef"><b>Definition:</b> core_mqtt.c:2679</div></div>
|
|
<div class="ttc" id="agroup__mqtt__enum__types_html_gaba7ec045874a1c3432f99173367f735c"><div class="ttname"><a href="group__mqtt__enum__types.html#gaba7ec045874a1c3432f99173367f735c">MQTTStatus_t</a></div><div class="ttdeci">MQTTStatus_t</div><div class="ttdoc">Return codes from MQTT functions.</div><div class="ttdef"><b>Definition:</b> core_mqtt_serializer.h:87</div></div>
|
|
<div class="ttc" id="agroup__mqtt__enum__types_html_ggae308a5928d7f537379c29a894228093aaad51b23a1ae1417f96d8f343c788d1d2"><div class="ttname"><a href="group__mqtt__enum__types.html#ggae308a5928d7f537379c29a894228093aaad51b23a1ae1417f96d8f343c788d1d2">MQTTQoS0</a></div><div class="ttdeci">@ MQTTQoS0</div><div class="ttdef"><b>Definition:</b> core_mqtt_serializer.h:110</div></div>
|
|
<div class="ttc" id="astruct_m_q_t_t_connect_info__t_html"><div class="ttname"><a href="struct_m_q_t_t_connect_info__t.html">MQTTConnectInfo_t</a></div><div class="ttdoc">MQTT CONNECT packet parameters.</div><div class="ttdef"><b>Definition:</b> core_mqtt_serializer.h:133</div></div>
|
|
<div class="ttc" id="astruct_m_q_t_t_connect_info__t_html_a010f8f6993cbf8899648d5c515ff7884"><div class="ttname"><a href="struct_m_q_t_t_connect_info__t.html#a010f8f6993cbf8899648d5c515ff7884">MQTTConnectInfo_t::pClientIdentifier</a></div><div class="ttdeci">const char * pClientIdentifier</div><div class="ttdoc">MQTT client identifier. Must be unique per client.</div><div class="ttdef"><b>Definition:</b> core_mqtt_serializer.h:147</div></div>
|
|
<div class="ttc" id="astruct_m_q_t_t_connect_info__t_html_a1118d7d3251a11445318557280db53b4"><div class="ttname"><a href="struct_m_q_t_t_connect_info__t.html#a1118d7d3251a11445318557280db53b4">MQTTConnectInfo_t::pUserName</a></div><div class="ttdeci">const char * pUserName</div><div class="ttdoc">MQTT user name. Set to NULL if not used.</div><div class="ttdef"><b>Definition:</b> core_mqtt_serializer.h:157</div></div>
|
|
<div class="ttc" id="astruct_m_q_t_t_connect_info__t_html_a606e7765c4f2215fb2bf630f6eb9ff6b"><div class="ttname"><a href="struct_m_q_t_t_connect_info__t.html#a606e7765c4f2215fb2bf630f6eb9ff6b">MQTTConnectInfo_t::cleanSession</a></div><div class="ttdeci">bool cleanSession</div><div class="ttdoc">Whether to establish a new, clean session or resume a previous session.</div><div class="ttdef"><b>Definition:</b> core_mqtt_serializer.h:137</div></div>
|
|
<div class="ttc" id="astruct_m_q_t_t_connect_info__t_html_a7165be3bb06d4527ab4eb773b50e05e1"><div class="ttname"><a href="struct_m_q_t_t_connect_info__t.html#a7165be3bb06d4527ab4eb773b50e05e1">MQTTConnectInfo_t::userNameLength</a></div><div class="ttdeci">uint16_t userNameLength</div><div class="ttdoc">Length of MQTT user name. Set to 0 if not used.</div><div class="ttdef"><b>Definition:</b> core_mqtt_serializer.h:162</div></div>
|
|
<div class="ttc" id="astruct_m_q_t_t_connect_info__t_html_a7d05d53261732ebdfbb9ee665a347591"><div class="ttname"><a href="struct_m_q_t_t_connect_info__t.html#a7d05d53261732ebdfbb9ee665a347591">MQTTConnectInfo_t::keepAliveSeconds</a></div><div class="ttdeci">uint16_t keepAliveSeconds</div><div class="ttdoc">MQTT keep alive period.</div><div class="ttdef"><b>Definition:</b> core_mqtt_serializer.h:142</div></div>
|
|
<div class="ttc" id="astruct_m_q_t_t_connect_info__t_html_a8077ef36ab318f3d35bee6f098fa54d4"><div class="ttname"><a href="struct_m_q_t_t_connect_info__t.html#a8077ef36ab318f3d35bee6f098fa54d4">MQTTConnectInfo_t::clientIdentifierLength</a></div><div class="ttdeci">uint16_t clientIdentifierLength</div><div class="ttdoc">Length of the client identifier.</div><div class="ttdef"><b>Definition:</b> core_mqtt_serializer.h:152</div></div>
|
|
<div class="ttc" id="astruct_m_q_t_t_connect_info__t_html_a818c4e212a12020a4109eb890ec96383"><div class="ttname"><a href="struct_m_q_t_t_connect_info__t.html#a818c4e212a12020a4109eb890ec96383">MQTTConnectInfo_t::passwordLength</a></div><div class="ttdeci">uint16_t passwordLength</div><div class="ttdoc">Length of MQTT password. Set to 0 if not used.</div><div class="ttdef"><b>Definition:</b> core_mqtt_serializer.h:172</div></div>
|
|
<div class="ttc" id="astruct_m_q_t_t_connect_info__t_html_acec6c79a11d2f0f130802393f34d2b5e"><div class="ttname"><a href="struct_m_q_t_t_connect_info__t.html#acec6c79a11d2f0f130802393f34d2b5e">MQTTConnectInfo_t::pPassword</a></div><div class="ttdeci">const char * pPassword</div><div class="ttdoc">MQTT password. Set to NULL if not used.</div><div class="ttdef"><b>Definition:</b> core_mqtt_serializer.h:167</div></div>
|
|
<div class="ttc" id="astruct_m_q_t_t_publish_info__t_html"><div class="ttname"><a href="struct_m_q_t_t_publish_info__t.html">MQTTPublishInfo_t</a></div><div class="ttdoc">MQTT PUBLISH packet parameters.</div><div class="ttdef"><b>Definition:</b> core_mqtt_serializer.h:202</div></div>
|
|
<div class="ttc" id="astruct_m_q_t_t_publish_info__t_html_a178224d02b4acdec7e08e88de0e4b399"><div class="ttname"><a href="struct_m_q_t_t_publish_info__t.html#a178224d02b4acdec7e08e88de0e4b399">MQTTPublishInfo_t::qos</a></div><div class="ttdeci">MQTTQoS_t qos</div><div class="ttdoc">Quality of Service for message.</div><div class="ttdef"><b>Definition:</b> core_mqtt_serializer.h:206</div></div>
|
|
<div class="ttc" id="astruct_m_q_t_t_publish_info__t_html_a6161c792d20cc7cf8284c1b71ea1145f"><div class="ttname"><a href="struct_m_q_t_t_publish_info__t.html#a6161c792d20cc7cf8284c1b71ea1145f">MQTTPublishInfo_t::topicNameLength</a></div><div class="ttdeci">uint16_t topicNameLength</div><div class="ttdoc">Length of topic name.</div><div class="ttdef"><b>Definition:</b> core_mqtt_serializer.h:226</div></div>
|
|
<div class="ttc" id="astruct_m_q_t_t_publish_info__t_html_a7997964e11571f35f0c3b729db0f760f"><div class="ttname"><a href="struct_m_q_t_t_publish_info__t.html#a7997964e11571f35f0c3b729db0f760f">MQTTPublishInfo_t::payloadLength</a></div><div class="ttdeci">size_t payloadLength</div><div class="ttdoc">Message payload length.</div><div class="ttdef"><b>Definition:</b> core_mqtt_serializer.h:236</div></div>
|
|
<div class="ttc" id="astruct_m_q_t_t_publish_info__t_html_aa80e8ca282d01630f878ad0afe81d7a4"><div class="ttname"><a href="struct_m_q_t_t_publish_info__t.html#aa80e8ca282d01630f878ad0afe81d7a4">MQTTPublishInfo_t::pTopicName</a></div><div class="ttdeci">const char * pTopicName</div><div class="ttdoc">Topic name on which the message is published.</div><div class="ttdef"><b>Definition:</b> core_mqtt_serializer.h:221</div></div>
|
|
<div class="ttc" id="astruct_m_q_t_t_publish_info__t_html_afc28299f4f625f5e674bb61b42f03380"><div class="ttname"><a href="struct_m_q_t_t_publish_info__t.html#afc28299f4f625f5e674bb61b42f03380">MQTTPublishInfo_t::pPayload</a></div><div class="ttdeci">const void * pPayload</div><div class="ttdoc">Message payload.</div><div class="ttdef"><b>Definition:</b> core_mqtt_serializer.h:231</div></div>
|
|
</div><!-- fragment -->
|
|
</div>
|
|
</div>
|
|
<a id="a567aa9c38726a7879f9cbf943e813e8f" name="a567aa9c38726a7879f9cbf943e813e8f"></a>
|
|
<h2 class="memtitle"><span class="permalink"><a href="#a567aa9c38726a7879f9cbf943e813e8f">◆ </a></span>MQTT_Subscribe()</h2>
|
|
|
|
<div class="memitem">
|
|
<div class="memproto">
|
|
<table class="memname">
|
|
<tr>
|
|
<td class="memname"><a class="el" href="group__mqtt__enum__types.html#gaba7ec045874a1c3432f99173367f735c">MQTTStatus_t</a> MQTT_Subscribe </td>
|
|
<td>(</td>
|
|
<td class="paramtype"><a class="el" href="struct_m_q_t_t_context__t.html">MQTTContext_t</a> * </td>
|
|
<td class="paramname"><em>pContext</em>, </td>
|
|
</tr>
|
|
<tr>
|
|
<td class="paramkey"></td>
|
|
<td></td>
|
|
<td class="paramtype">const <a class="el" href="struct_m_q_t_t_subscribe_info__t.html">MQTTSubscribeInfo_t</a> * </td>
|
|
<td class="paramname"><em>pSubscriptionList</em>, </td>
|
|
</tr>
|
|
<tr>
|
|
<td class="paramkey"></td>
|
|
<td></td>
|
|
<td class="paramtype">size_t </td>
|
|
<td class="paramname"><em>subscriptionCount</em>, </td>
|
|
</tr>
|
|
<tr>
|
|
<td class="paramkey"></td>
|
|
<td></td>
|
|
<td class="paramtype">uint16_t </td>
|
|
<td class="paramname"><em>packetId</em> </td>
|
|
</tr>
|
|
<tr>
|
|
<td></td>
|
|
<td>)</td>
|
|
<td></td><td></td>
|
|
</tr>
|
|
</table>
|
|
</div><div class="memdoc">
|
|
|
|
<p>Sends MQTT SUBSCRIBE for the given list of topic filters to the broker. </p>
|
|
<dl class="params"><dt>Parameters</dt><dd>
|
|
<table class="params">
|
|
<tr><td class="paramdir">[in]</td><td class="paramname">pContext</td><td>Initialized MQTT context. </td></tr>
|
|
<tr><td class="paramdir">[in]</td><td class="paramname">pSubscriptionList</td><td>Array of MQTT subscription info. </td></tr>
|
|
<tr><td class="paramdir">[in]</td><td class="paramname">subscriptionCount</td><td>The number of elements in @ pSubscriptionList array. </td></tr>
|
|
<tr><td class="paramdir">[in]</td><td class="paramname">packetId</td><td>Packet ID generated by <a class="el" href="core__mqtt_8h.html#a00e1a3eba2c21899a6b4312c7d65d090" title="Get a packet ID that is valid according to the MQTT 3.1.1 spec.">MQTT_GetPacketId</a>.</td></tr>
|
|
</table>
|
|
</dd>
|
|
</dl>
|
|
<dl class="section return"><dt>Returns</dt><dd><a class="el" href="group__mqtt__enum__types.html#ggaba7ec045874a1c3432f99173367f735cab1be4db832a0468f024243bca151a8df">MQTTNoMemory</a> if the <a class="el" href="struct_m_q_t_t_context__t.html#a231c5576a6ce389317a3f00f95628276" title="The buffer used in sending and receiving packets from the network.">MQTTContext_t.networkBuffer</a> is too small to hold the MQTT packet; <a class="el" href="group__mqtt__enum__types.html#ggaba7ec045874a1c3432f99173367f735caa39030c93b0263b2699502a074f003b5">MQTTBadParameter</a> if invalid parameters are passed; <a class="el" href="group__mqtt__enum__types.html#ggaba7ec045874a1c3432f99173367f735cafd06b63fe9677fa2af06b0f4c7d4ad55">MQTTSendFailed</a> if transport write failed; <a class="el" href="group__mqtt__enum__types.html#ggaba7ec045874a1c3432f99173367f735ca484e062cb4f3fccc1858dd25cfeee056">MQTTSuccess</a> otherwise.</dd></dl>
|
|
<p><b>Example</b> </p><div class="fragment"><div class="line"><span class="comment">// Variables used in this example.</span></div>
|
|
<div class="line"><a class="code hl_enumeration" href="group__mqtt__enum__types.html#gaba7ec045874a1c3432f99173367f735c">MQTTStatus_t</a> status;</div>
|
|
<div class="line"><a class="code hl_struct" href="struct_m_q_t_t_subscribe_info__t.html">MQTTSubscribeInfo_t</a> subscriptionList[ NUMBER_OF_SUBSCRIPTIONS ] = { 0 };</div>
|
|
<div class="line">uint16_t packetId;</div>
|
|
<div class="line"><span class="comment">// This context is assumed to be initialized and connected.</span></div>
|
|
<div class="line"><a class="code hl_struct" href="struct_m_q_t_t_context__t.html">MQTTContext_t</a> * pContext;</div>
|
|
<div class="line"><span class="comment">// This is assumed to be a list of filters we want to subscribe to.</span></div>
|
|
<div class="line"><span class="keyword">const</span> <span class="keywordtype">char</span> * filters[ NUMBER_OF_SUBSCRIPTIONS ];</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// Set each subscription.</span></div>
|
|
<div class="line"><span class="keywordflow">for</span>( <span class="keywordtype">int</span> i = 0; i < NUMBER_OF_SUBSCRIPTIONS; i++ )</div>
|
|
<div class="line">{</div>
|
|
<div class="line"> subscriptionList[ i ].<a class="code hl_variable" href="struct_m_q_t_t_subscribe_info__t.html#a64cf2e423f60cfec122eeaef80c0fd86">qos</a> = <a class="code hl_enumvalue" href="group__mqtt__enum__types.html#ggae308a5928d7f537379c29a894228093aaad51b23a1ae1417f96d8f343c788d1d2">MQTTQoS0</a>;</div>
|
|
<div class="line"> <span class="comment">// Each subscription needs a topic filter.</span></div>
|
|
<div class="line"> subscriptionList[ i ].<a class="code hl_variable" href="struct_m_q_t_t_subscribe_info__t.html#adb0b28240fdcd82a85f11cf2f8b5bbf0">pTopicFilter</a> = filters[ i ];</div>
|
|
<div class="line"> subscriptionList[ i ].<a class="code hl_variable" href="struct_m_q_t_t_subscribe_info__t.html#a6972f8e036f8bde9b1f23a2aacb61382">topicFilterLength</a> = strlen( filters[ i ] );</div>
|
|
<div class="line">}</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// Obtain a new packet id for the subscription.</span></div>
|
|
<div class="line">packetId = <a class="code hl_function" href="core__mqtt_8h.html#a00e1a3eba2c21899a6b4312c7d65d090">MQTT_GetPacketId</a>( pContext );</div>
|
|
<div class="line"> </div>
|
|
<div class="line">status = <a class="code hl_function" href="core__mqtt_8h.html#a567aa9c38726a7879f9cbf943e813e8f">MQTT_Subscribe</a>( pContext, &subscriptionList[ 0 ], NUMBER_OF_SUBSCRIPTIONS, packetId );</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="keywordflow">if</span>( status == <a class="code hl_enumvalue" href="group__mqtt__enum__types.html#ggaba7ec045874a1c3432f99173367f735ca484e062cb4f3fccc1858dd25cfeee056">MQTTSuccess</a> )</div>
|
|
<div class="line">{</div>
|
|
<div class="line"> <span class="comment">// We must now call MQTT_ReceiveLoop() or MQTT_ProcessLoop() to receive the SUBACK.</span></div>
|
|
<div class="line"> <span class="comment">// If the broker accepts the subscription we can now receive publishes</span></div>
|
|
<div class="line"> <span class="comment">// on the requested topics.</span></div>
|
|
<div class="line">}</div>
|
|
<div class="ttc" id="acore__mqtt_8h_html_a00e1a3eba2c21899a6b4312c7d65d090"><div class="ttname"><a href="core__mqtt_8h.html#a00e1a3eba2c21899a6b4312c7d65d090">MQTT_GetPacketId</a></div><div class="ttdeci">uint16_t MQTT_GetPacketId(MQTTContext_t *pContext)</div><div class="ttdoc">Get a packet ID that is valid according to the MQTT 3.1.1 spec.</div><div class="ttdef"><b>Definition:</b> core_mqtt.c:3172</div></div>
|
|
<div class="ttc" id="acore__mqtt_8h_html_a567aa9c38726a7879f9cbf943e813e8f"><div class="ttname"><a href="core__mqtt_8h.html#a567aa9c38726a7879f9cbf943e813e8f">MQTT_Subscribe</a></div><div class="ttdeci">MQTTStatus_t MQTT_Subscribe(MQTTContext_t *pContext, const MQTTSubscribeInfo_t *pSubscriptionList, size_t subscriptionCount, uint16_t packetId)</div><div class="ttdoc">Sends MQTT SUBSCRIBE for the given list of topic filters to the broker.</div><div class="ttdef"><b>Definition:</b> core_mqtt.c:2761</div></div>
|
|
<div class="ttc" id="astruct_m_q_t_t_subscribe_info__t_html"><div class="ttname"><a href="struct_m_q_t_t_subscribe_info__t.html">MQTTSubscribeInfo_t</a></div><div class="ttdoc">MQTT SUBSCRIBE packet parameters.</div><div class="ttdef"><b>Definition:</b> core_mqtt_serializer.h:180</div></div>
|
|
<div class="ttc" id="astruct_m_q_t_t_subscribe_info__t_html_a64cf2e423f60cfec122eeaef80c0fd86"><div class="ttname"><a href="struct_m_q_t_t_subscribe_info__t.html#a64cf2e423f60cfec122eeaef80c0fd86">MQTTSubscribeInfo_t::qos</a></div><div class="ttdeci">MQTTQoS_t qos</div><div class="ttdoc">Quality of Service for subscription.</div><div class="ttdef"><b>Definition:</b> core_mqtt_serializer.h:184</div></div>
|
|
<div class="ttc" id="astruct_m_q_t_t_subscribe_info__t_html_a6972f8e036f8bde9b1f23a2aacb61382"><div class="ttname"><a href="struct_m_q_t_t_subscribe_info__t.html#a6972f8e036f8bde9b1f23a2aacb61382">MQTTSubscribeInfo_t::topicFilterLength</a></div><div class="ttdeci">uint16_t topicFilterLength</div><div class="ttdoc">Length of subscription topic filter.</div><div class="ttdef"><b>Definition:</b> core_mqtt_serializer.h:194</div></div>
|
|
<div class="ttc" id="astruct_m_q_t_t_subscribe_info__t_html_adb0b28240fdcd82a85f11cf2f8b5bbf0"><div class="ttname"><a href="struct_m_q_t_t_subscribe_info__t.html#adb0b28240fdcd82a85f11cf2f8b5bbf0">MQTTSubscribeInfo_t::pTopicFilter</a></div><div class="ttdeci">const char * pTopicFilter</div><div class="ttdoc">Topic filter to subscribe to.</div><div class="ttdef"><b>Definition:</b> core_mqtt_serializer.h:189</div></div>
|
|
</div><!-- fragment -->
|
|
</div>
|
|
</div>
|
|
<a id="a1d8217e9d30fb2aed002060a8c97c63e" name="a1d8217e9d30fb2aed002060a8c97c63e"></a>
|
|
<h2 class="memtitle"><span class="permalink"><a href="#a1d8217e9d30fb2aed002060a8c97c63e">◆ </a></span>MQTT_Publish()</h2>
|
|
|
|
<div class="memitem">
|
|
<div class="memproto">
|
|
<table class="memname">
|
|
<tr>
|
|
<td class="memname"><a class="el" href="group__mqtt__enum__types.html#gaba7ec045874a1c3432f99173367f735c">MQTTStatus_t</a> MQTT_Publish </td>
|
|
<td>(</td>
|
|
<td class="paramtype"><a class="el" href="struct_m_q_t_t_context__t.html">MQTTContext_t</a> * </td>
|
|
<td class="paramname"><em>pContext</em>, </td>
|
|
</tr>
|
|
<tr>
|
|
<td class="paramkey"></td>
|
|
<td></td>
|
|
<td class="paramtype">const <a class="el" href="struct_m_q_t_t_publish_info__t.html">MQTTPublishInfo_t</a> * </td>
|
|
<td class="paramname"><em>pPublishInfo</em>, </td>
|
|
</tr>
|
|
<tr>
|
|
<td class="paramkey"></td>
|
|
<td></td>
|
|
<td class="paramtype">uint16_t </td>
|
|
<td class="paramname"><em>packetId</em> </td>
|
|
</tr>
|
|
<tr>
|
|
<td></td>
|
|
<td>)</td>
|
|
<td></td><td></td>
|
|
</tr>
|
|
</table>
|
|
</div><div class="memdoc">
|
|
|
|
<p>Publishes a message to the given topic name. </p>
|
|
<dl class="params"><dt>Parameters</dt><dd>
|
|
<table class="params">
|
|
<tr><td class="paramdir">[in]</td><td class="paramname">pContext</td><td>Initialized MQTT context. </td></tr>
|
|
<tr><td class="paramdir">[in]</td><td class="paramname">pPublishInfo</td><td>MQTT PUBLISH packet parameters. </td></tr>
|
|
<tr><td class="paramdir">[in]</td><td class="paramname">packetId</td><td>packet ID generated by <a class="el" href="core__mqtt_8h.html#a00e1a3eba2c21899a6b4312c7d65d090" title="Get a packet ID that is valid according to the MQTT 3.1.1 spec.">MQTT_GetPacketId</a>.</td></tr>
|
|
</table>
|
|
</dd>
|
|
</dl>
|
|
<dl class="section return"><dt>Returns</dt><dd><a class="el" href="group__mqtt__enum__types.html#ggaba7ec045874a1c3432f99173367f735cab1be4db832a0468f024243bca151a8df">MQTTNoMemory</a> if pBuffer is too small to hold the MQTT packet; <a class="el" href="group__mqtt__enum__types.html#ggaba7ec045874a1c3432f99173367f735caa39030c93b0263b2699502a074f003b5">MQTTBadParameter</a> if invalid parameters are passed; <a class="el" href="group__mqtt__enum__types.html#ggaba7ec045874a1c3432f99173367f735cafd06b63fe9677fa2af06b0f4c7d4ad55">MQTTSendFailed</a> if transport write failed; <a class="el" href="group__mqtt__enum__types.html#ggaba7ec045874a1c3432f99173367f735ca484e062cb4f3fccc1858dd25cfeee056">MQTTSuccess</a> otherwise.</dd></dl>
|
|
<p><b>Example</b> </p><div class="fragment"><div class="line"><span class="comment">// Variables used in this example.</span></div>
|
|
<div class="line"><a class="code hl_enumeration" href="group__mqtt__enum__types.html#gaba7ec045874a1c3432f99173367f735c">MQTTStatus_t</a> status;</div>
|
|
<div class="line"><a class="code hl_struct" href="struct_m_q_t_t_publish_info__t.html">MQTTPublishInfo_t</a> publishInfo;</div>
|
|
<div class="line">uint16_t packetId;</div>
|
|
<div class="line"><span class="comment">// This context is assumed to be initialized and connected.</span></div>
|
|
<div class="line"><a class="code hl_struct" href="struct_m_q_t_t_context__t.html">MQTTContext_t</a> * pContext;</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// QoS of publish.</span></div>
|
|
<div class="line">publishInfo.<a class="code hl_variable" href="struct_m_q_t_t_publish_info__t.html#a178224d02b4acdec7e08e88de0e4b399">qos</a> = <a class="code hl_enumvalue" href="group__mqtt__enum__types.html#ggae308a5928d7f537379c29a894228093aa019d0b8a8cfadb6f98462b046bdacbb2">MQTTQoS1</a>;</div>
|
|
<div class="line">publishInfo.<a class="code hl_variable" href="struct_m_q_t_t_publish_info__t.html#aa80e8ca282d01630f878ad0afe81d7a4">pTopicName</a> = <span class="stringliteral">"/some/topic/name"</span>;</div>
|
|
<div class="line">publishInfo.<a class="code hl_variable" href="struct_m_q_t_t_publish_info__t.html#a6161c792d20cc7cf8284c1b71ea1145f">topicNameLength</a> = strlen( publishInfo.<a class="code hl_variable" href="struct_m_q_t_t_publish_info__t.html#aa80e8ca282d01630f878ad0afe81d7a4">pTopicName</a> );</div>
|
|
<div class="line">publishInfo.<a class="code hl_variable" href="struct_m_q_t_t_publish_info__t.html#afc28299f4f625f5e674bb61b42f03380">pPayload</a> = <span class="stringliteral">"Hello World!"</span>;</div>
|
|
<div class="line">publishInfo.<a class="code hl_variable" href="struct_m_q_t_t_publish_info__t.html#a7997964e11571f35f0c3b729db0f760f">payloadLength</a> = strlen( <span class="stringliteral">"Hello World!"</span> );</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// Packet ID is needed for QoS > 0.</span></div>
|
|
<div class="line">packetId = <a class="code hl_function" href="core__mqtt_8h.html#a00e1a3eba2c21899a6b4312c7d65d090">MQTT_GetPacketId</a>( pContext );</div>
|
|
<div class="line"> </div>
|
|
<div class="line">status = <a class="code hl_function" href="core__mqtt_8h.html#a1d8217e9d30fb2aed002060a8c97c63e">MQTT_Publish</a>( pContext, &publishInfo, packetId );</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="keywordflow">if</span>( status == <a class="code hl_enumvalue" href="group__mqtt__enum__types.html#ggaba7ec045874a1c3432f99173367f735ca484e062cb4f3fccc1858dd25cfeee056">MQTTSuccess</a> )</div>
|
|
<div class="line">{</div>
|
|
<div class="line"> <span class="comment">// Since the QoS is > 0, we will need to call MQTT_ReceiveLoop()</span></div>
|
|
<div class="line"> <span class="comment">// or MQTT_ProcessLoop() to process the publish acknowledgments.</span></div>
|
|
<div class="line">}</div>
|
|
<div class="ttc" id="acore__mqtt_8h_html_a1d8217e9d30fb2aed002060a8c97c63e"><div class="ttname"><a href="core__mqtt_8h.html#a1d8217e9d30fb2aed002060a8c97c63e">MQTT_Publish</a></div><div class="ttdeci">MQTTStatus_t MQTT_Publish(MQTTContext_t *pContext, const MQTTPublishInfo_t *pPublishInfo, uint16_t packetId)</div><div class="ttdoc">Publishes a message to the given topic name.</div><div class="ttdef"><b>Definition:</b> core_mqtt.c:2805</div></div>
|
|
<div class="ttc" id="agroup__mqtt__enum__types_html_ggae308a5928d7f537379c29a894228093aa019d0b8a8cfadb6f98462b046bdacbb2"><div class="ttname"><a href="group__mqtt__enum__types.html#ggae308a5928d7f537379c29a894228093aa019d0b8a8cfadb6f98462b046bdacbb2">MQTTQoS1</a></div><div class="ttdeci">@ MQTTQoS1</div><div class="ttdef"><b>Definition:</b> core_mqtt_serializer.h:111</div></div>
|
|
</div><!-- fragment -->
|
|
</div>
|
|
</div>
|
|
<a id="a31b74c34cd295b98ed5f5b4c15ed4a8b" name="a31b74c34cd295b98ed5f5b4c15ed4a8b"></a>
|
|
<h2 class="memtitle"><span class="permalink"><a href="#a31b74c34cd295b98ed5f5b4c15ed4a8b">◆ </a></span>MQTT_CancelCallback()</h2>
|
|
|
|
<div class="memitem">
|
|
<div class="memproto">
|
|
<table class="memname">
|
|
<tr>
|
|
<td class="memname"><a class="el" href="group__mqtt__enum__types.html#gaba7ec045874a1c3432f99173367f735c">MQTTStatus_t</a> MQTT_CancelCallback </td>
|
|
<td>(</td>
|
|
<td class="paramtype">const <a class="el" href="struct_m_q_t_t_context__t.html">MQTTContext_t</a> * </td>
|
|
<td class="paramname"><em>pContext</em>, </td>
|
|
</tr>
|
|
<tr>
|
|
<td class="paramkey"></td>
|
|
<td></td>
|
|
<td class="paramtype">uint16_t </td>
|
|
<td class="paramname"><em>packetId</em> </td>
|
|
</tr>
|
|
<tr>
|
|
<td></td>
|
|
<td>)</td>
|
|
<td></td><td></td>
|
|
</tr>
|
|
</table>
|
|
</div><div class="memdoc">
|
|
|
|
<p>Cancels an outgoing publish callback (only for QoS > QoS0) by removing it from the pending ACK list. </p>
|
|
<dl class="section note"><dt>Note</dt><dd>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.</dd></dl>
|
|
<dl class="params"><dt>Parameters</dt><dd>
|
|
<table class="params">
|
|
<tr><td class="paramdir">[in]</td><td class="paramname">pContext</td><td>Initialized MQTT context. </td></tr>
|
|
<tr><td class="paramdir">[in]</td><td class="paramname">packetId</td><td>packet ID corresponding to the outstanding publish.</td></tr>
|
|
</table>
|
|
</dd>
|
|
</dl>
|
|
<dl class="section return"><dt>Returns</dt><dd><a class="el" href="group__mqtt__enum__types.html#ggaba7ec045874a1c3432f99173367f735caa39030c93b0263b2699502a074f003b5">MQTTBadParameter</a> if invalid parameters are passed; <a class="el" href="group__mqtt__enum__types.html#ggaba7ec045874a1c3432f99173367f735ca484e062cb4f3fccc1858dd25cfeee056">MQTTSuccess</a> otherwise. </dd></dl>
|
|
|
|
</div>
|
|
</div>
|
|
<a id="a66eced0c62ace790354ae3de40fc0959" name="a66eced0c62ace790354ae3de40fc0959"></a>
|
|
<h2 class="memtitle"><span class="permalink"><a href="#a66eced0c62ace790354ae3de40fc0959">◆ </a></span>MQTT_Ping()</h2>
|
|
|
|
<div class="memitem">
|
|
<div class="memproto">
|
|
<table class="memname">
|
|
<tr>
|
|
<td class="memname"><a class="el" href="group__mqtt__enum__types.html#gaba7ec045874a1c3432f99173367f735c">MQTTStatus_t</a> MQTT_Ping </td>
|
|
<td>(</td>
|
|
<td class="paramtype"><a class="el" href="struct_m_q_t_t_context__t.html">MQTTContext_t</a> * </td>
|
|
<td class="paramname"><em>pContext</em></td><td>)</td>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div><div class="memdoc">
|
|
|
|
<p>Sends an MQTT PINGREQ to broker. </p>
|
|
<dl class="params"><dt>Parameters</dt><dd>
|
|
<table class="params">
|
|
<tr><td class="paramdir">[in]</td><td class="paramname">pContext</td><td>Initialized and connected MQTT context.</td></tr>
|
|
</table>
|
|
</dd>
|
|
</dl>
|
|
<dl class="section return"><dt>Returns</dt><dd><a class="el" href="group__mqtt__enum__types.html#ggaba7ec045874a1c3432f99173367f735cab1be4db832a0468f024243bca151a8df">MQTTNoMemory</a> if pBuffer is too small to hold the MQTT packet; <a class="el" href="group__mqtt__enum__types.html#ggaba7ec045874a1c3432f99173367f735caa39030c93b0263b2699502a074f003b5">MQTTBadParameter</a> if invalid parameters are passed; <a class="el" href="group__mqtt__enum__types.html#ggaba7ec045874a1c3432f99173367f735cafd06b63fe9677fa2af06b0f4c7d4ad55">MQTTSendFailed</a> if transport write failed; <a class="el" href="group__mqtt__enum__types.html#ggaba7ec045874a1c3432f99173367f735ca484e062cb4f3fccc1858dd25cfeee056">MQTTSuccess</a> otherwise. </dd></dl>
|
|
|
|
</div>
|
|
</div>
|
|
<a id="a77c911dbe24c5a51aaea88250895dba4" name="a77c911dbe24c5a51aaea88250895dba4"></a>
|
|
<h2 class="memtitle"><span class="permalink"><a href="#a77c911dbe24c5a51aaea88250895dba4">◆ </a></span>MQTT_Unsubscribe()</h2>
|
|
|
|
<div class="memitem">
|
|
<div class="memproto">
|
|
<table class="memname">
|
|
<tr>
|
|
<td class="memname"><a class="el" href="group__mqtt__enum__types.html#gaba7ec045874a1c3432f99173367f735c">MQTTStatus_t</a> MQTT_Unsubscribe </td>
|
|
<td>(</td>
|
|
<td class="paramtype"><a class="el" href="struct_m_q_t_t_context__t.html">MQTTContext_t</a> * </td>
|
|
<td class="paramname"><em>pContext</em>, </td>
|
|
</tr>
|
|
<tr>
|
|
<td class="paramkey"></td>
|
|
<td></td>
|
|
<td class="paramtype">const <a class="el" href="struct_m_q_t_t_subscribe_info__t.html">MQTTSubscribeInfo_t</a> * </td>
|
|
<td class="paramname"><em>pSubscriptionList</em>, </td>
|
|
</tr>
|
|
<tr>
|
|
<td class="paramkey"></td>
|
|
<td></td>
|
|
<td class="paramtype">size_t </td>
|
|
<td class="paramname"><em>subscriptionCount</em>, </td>
|
|
</tr>
|
|
<tr>
|
|
<td class="paramkey"></td>
|
|
<td></td>
|
|
<td class="paramtype">uint16_t </td>
|
|
<td class="paramname"><em>packetId</em> </td>
|
|
</tr>
|
|
<tr>
|
|
<td></td>
|
|
<td>)</td>
|
|
<td></td><td></td>
|
|
</tr>
|
|
</table>
|
|
</div><div class="memdoc">
|
|
|
|
<p>Sends MQTT UNSUBSCRIBE for the given list of topic filters to the broker. </p>
|
|
<dl class="params"><dt>Parameters</dt><dd>
|
|
<table class="params">
|
|
<tr><td class="paramdir">[in]</td><td class="paramname">pContext</td><td>Initialized MQTT context. </td></tr>
|
|
<tr><td class="paramdir">[in]</td><td class="paramname">pSubscriptionList</td><td>List of MQTT subscription info. </td></tr>
|
|
<tr><td class="paramdir">[in]</td><td class="paramname">subscriptionCount</td><td>The number of elements in pSubscriptionList. </td></tr>
|
|
<tr><td class="paramdir">[in]</td><td class="paramname">packetId</td><td>packet ID generated by <a class="el" href="core__mqtt_8h.html#a00e1a3eba2c21899a6b4312c7d65d090" title="Get a packet ID that is valid according to the MQTT 3.1.1 spec.">MQTT_GetPacketId</a>.</td></tr>
|
|
</table>
|
|
</dd>
|
|
</dl>
|
|
<dl class="section return"><dt>Returns</dt><dd><a class="el" href="group__mqtt__enum__types.html#ggaba7ec045874a1c3432f99173367f735cab1be4db832a0468f024243bca151a8df">MQTTNoMemory</a> if the <a class="el" href="struct_m_q_t_t_context__t.html#a231c5576a6ce389317a3f00f95628276" title="The buffer used in sending and receiving packets from the network.">MQTTContext_t.networkBuffer</a> is too small to hold the MQTT packet; <a class="el" href="group__mqtt__enum__types.html#ggaba7ec045874a1c3432f99173367f735caa39030c93b0263b2699502a074f003b5">MQTTBadParameter</a> if invalid parameters are passed; <a class="el" href="group__mqtt__enum__types.html#ggaba7ec045874a1c3432f99173367f735cafd06b63fe9677fa2af06b0f4c7d4ad55">MQTTSendFailed</a> if transport write failed; <a class="el" href="group__mqtt__enum__types.html#ggaba7ec045874a1c3432f99173367f735ca484e062cb4f3fccc1858dd25cfeee056">MQTTSuccess</a> otherwise.</dd></dl>
|
|
<p><b>Example</b> </p><div class="fragment"><div class="line"><span class="comment">// Variables used in this example.</span></div>
|
|
<div class="line"><a class="code hl_enumeration" href="group__mqtt__enum__types.html#gaba7ec045874a1c3432f99173367f735c">MQTTStatus_t</a> status;</div>
|
|
<div class="line"><a class="code hl_struct" href="struct_m_q_t_t_subscribe_info__t.html">MQTTSubscribeInfo_t</a> unsubscribeList[ NUMBER_OF_SUBSCRIPTIONS ] = { 0 };</div>
|
|
<div class="line">uint16_t packetId;</div>
|
|
<div class="line"><span class="comment">// This context is assumed to be initialized and connected.</span></div>
|
|
<div class="line"><a class="code hl_struct" href="struct_m_q_t_t_context__t.html">MQTTContext_t</a> * pContext;</div>
|
|
<div class="line"><span class="comment">// This is assumed to be a list of filters we want to unsubscribe from.</span></div>
|
|
<div class="line"><span class="keyword">const</span> <span class="keywordtype">char</span> * filters[ NUMBER_OF_SUBSCRIPTIONS ];</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// Set information for each unsubscribe request.</span></div>
|
|
<div class="line"><span class="keywordflow">for</span>( <span class="keywordtype">int</span> i = 0; i < NUMBER_OF_SUBSCRIPTIONS; i++ )</div>
|
|
<div class="line">{</div>
|
|
<div class="line"> unsubscribeList[ i ].<a class="code hl_variable" href="struct_m_q_t_t_subscribe_info__t.html#adb0b28240fdcd82a85f11cf2f8b5bbf0">pTopicFilter</a> = filters[ i ];</div>
|
|
<div class="line"> unsubscribeList[ i ].<a class="code hl_variable" href="struct_m_q_t_t_subscribe_info__t.html#a6972f8e036f8bde9b1f23a2aacb61382">topicFilterLength</a> = strlen( filters[ i ] );</div>
|
|
<div class="line"> </div>
|
|
<div class="line"> <span class="comment">// The QoS field of MQTT_SubscribeInfo_t is unused for unsubscribing.</span></div>
|
|
<div class="line">}</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// Obtain a new packet id for the unsubscribe request.</span></div>
|
|
<div class="line">packetId = <a class="code hl_function" href="core__mqtt_8h.html#a00e1a3eba2c21899a6b4312c7d65d090">MQTT_GetPacketId</a>( pContext );</div>
|
|
<div class="line"> </div>
|
|
<div class="line">status = <a class="code hl_function" href="core__mqtt_8h.html#a77c911dbe24c5a51aaea88250895dba4">MQTT_Unsubscribe</a>( pContext, &unsubscribeList[ 0 ], NUMBER_OF_SUBSCRIPTIONS, packetId );</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="keywordflow">if</span>( status == <a class="code hl_enumvalue" href="group__mqtt__enum__types.html#ggaba7ec045874a1c3432f99173367f735ca484e062cb4f3fccc1858dd25cfeee056">MQTTSuccess</a> )</div>
|
|
<div class="line">{</div>
|
|
<div class="line"> <span class="comment">// We must now call MQTT_ReceiveLoop() or MQTT_ProcessLoop() to receive the UNSUBACK.</span></div>
|
|
<div class="line"> <span class="comment">// After this the broker should no longer send publishes for these topics.</span></div>
|
|
<div class="line">}</div>
|
|
<div class="ttc" id="acore__mqtt_8h_html_a77c911dbe24c5a51aaea88250895dba4"><div class="ttname"><a href="core__mqtt_8h.html#a77c911dbe24c5a51aaea88250895dba4">MQTT_Unsubscribe</a></div><div class="ttdeci">MQTTStatus_t MQTT_Unsubscribe(MQTTContext_t *pContext, const MQTTSubscribeInfo_t *pSubscriptionList, size_t subscriptionCount, uint16_t packetId)</div><div class="ttdoc">Sends MQTT UNSUBSCRIBE for the given list of topic filters to the broker.</div><div class="ttdef"><b>Definition:</b> core_mqtt.c:3000</div></div>
|
|
</div><!-- fragment -->
|
|
</div>
|
|
</div>
|
|
<a id="ac79c366acbc3dddd88072d99ccb9140c" name="ac79c366acbc3dddd88072d99ccb9140c"></a>
|
|
<h2 class="memtitle"><span class="permalink"><a href="#ac79c366acbc3dddd88072d99ccb9140c">◆ </a></span>MQTT_Disconnect()</h2>
|
|
|
|
<div class="memitem">
|
|
<div class="memproto">
|
|
<table class="memname">
|
|
<tr>
|
|
<td class="memname"><a class="el" href="group__mqtt__enum__types.html#gaba7ec045874a1c3432f99173367f735c">MQTTStatus_t</a> MQTT_Disconnect </td>
|
|
<td>(</td>
|
|
<td class="paramtype"><a class="el" href="struct_m_q_t_t_context__t.html">MQTTContext_t</a> * </td>
|
|
<td class="paramname"><em>pContext</em></td><td>)</td>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div><div class="memdoc">
|
|
|
|
<p>Disconnect an MQTT session. </p>
|
|
<dl class="params"><dt>Parameters</dt><dd>
|
|
<table class="params">
|
|
<tr><td class="paramdir">[in]</td><td class="paramname">pContext</td><td>Initialized and connected MQTT context.</td></tr>
|
|
</table>
|
|
</dd>
|
|
</dl>
|
|
<dl class="section return"><dt>Returns</dt><dd><a class="el" href="group__mqtt__enum__types.html#ggaba7ec045874a1c3432f99173367f735cab1be4db832a0468f024243bca151a8df">MQTTNoMemory</a> if the <a class="el" href="struct_m_q_t_t_context__t.html#a231c5576a6ce389317a3f00f95628276" title="The buffer used in sending and receiving packets from the network.">MQTTContext_t.networkBuffer</a> is too small to hold the MQTT packet; <a class="el" href="group__mqtt__enum__types.html#ggaba7ec045874a1c3432f99173367f735caa39030c93b0263b2699502a074f003b5">MQTTBadParameter</a> if invalid parameters are passed; <a class="el" href="group__mqtt__enum__types.html#ggaba7ec045874a1c3432f99173367f735cafd06b63fe9677fa2af06b0f4c7d4ad55">MQTTSendFailed</a> if transport send failed; <a class="el" href="group__mqtt__enum__types.html#ggaba7ec045874a1c3432f99173367f735ca484e062cb4f3fccc1858dd25cfeee056">MQTTSuccess</a> otherwise. </dd></dl>
|
|
|
|
</div>
|
|
</div>
|
|
<a id="ab95d3d6b3eed98a6184fb2018c5b55d7" name="ab95d3d6b3eed98a6184fb2018c5b55d7"></a>
|
|
<h2 class="memtitle"><span class="permalink"><a href="#ab95d3d6b3eed98a6184fb2018c5b55d7">◆ </a></span>MQTT_ProcessLoop()</h2>
|
|
|
|
<div class="memitem">
|
|
<div class="memproto">
|
|
<table class="memname">
|
|
<tr>
|
|
<td class="memname"><a class="el" href="group__mqtt__enum__types.html#gaba7ec045874a1c3432f99173367f735c">MQTTStatus_t</a> MQTT_ProcessLoop </td>
|
|
<td>(</td>
|
|
<td class="paramtype"><a class="el" href="struct_m_q_t_t_context__t.html">MQTTContext_t</a> * </td>
|
|
<td class="paramname"><em>pContext</em></td><td>)</td>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div><div class="memdoc">
|
|
|
|
<p>Loop to receive packets from the transport interface. Handles keep alive. </p>
|
|
<dl class="section note"><dt>Note</dt><dd>If a dummy timer function, <a class="el" href="group__mqtt__callback__types.html#gae3bea55b0e49e5208b8c5709a5ea23aa" title="Application provided function to query the time elapsed since a given epoch in milliseconds.">MQTTGetCurrentTimeFunc_t</a>, is passed to the library, then the keep-alive mechanism is not supported by the <a class="el" href="core__mqtt_8h.html#ab95d3d6b3eed98a6184fb2018c5b55d7" title="Loop to receive packets from the transport interface. Handles keep alive.">MQTT_ProcessLoop</a> API. In that case, the <a class="el" href="core__mqtt_8h.html#aeb7c37284fcf6f68eb577427a6763fc6" title="Loop to receive packets from the transport interface. Does not handle keep alive.">MQTT_ReceiveLoop</a> API function should be used instead.</dd></dl>
|
|
<dl class="params"><dt>Parameters</dt><dd>
|
|
<table class="params">
|
|
<tr><td class="paramdir">[in]</td><td class="paramname">pContext</td><td>Initialized and connected MQTT context.</td></tr>
|
|
</table>
|
|
</dd>
|
|
</dl>
|
|
<dl class="section note"><dt>Note</dt><dd>Calling this function blocks the calling context for a time period that depends on the passed the configuration macros, <a class="el" href="core__mqtt__config__defaults_8h.html#a43dc9a67427d9e420a65955eea0e2671" title="The maximum duration between non-empty network reads while receiving an MQTT packet via the MQTT_Proc...">MQTT_RECV_POLLING_TIMEOUT_MS</a> and <a class="el" href="core__mqtt__config__defaults_8h.html#ac262cab68c4c713ebc2b91a2e4ab8b19" title="The maximum duration allowed to send an MQTT packet over the transport interface.">MQTT_SEND_TIMEOUT_MS</a>, and the underlying transport interface implementation timeouts, unless an error occurs. The blocking period also depends on the execution time of the <a class="el" href="group__mqtt__callback__types.html#ga00d348277ed4fde23c95bfc749ae954a" title="Application callback for receiving incoming publishes and incoming acks.">MQTTEventCallback_t</a> callback supplied to the library. It is recommended that the supplied <a class="el" href="group__mqtt__callback__types.html#ga00d348277ed4fde23c95bfc749ae954a" title="Application callback for receiving incoming publishes and incoming acks.">MQTTEventCallback_t</a> callback does not contain blocking operations to prevent potential non-deterministic blocking period of the <a class="el" href="core__mqtt_8h.html#ab95d3d6b3eed98a6184fb2018c5b55d7" title="Loop to receive packets from the transport interface. Handles keep alive.">MQTT_ProcessLoop</a> API call.</dd></dl>
|
|
<dl class="section return"><dt>Returns</dt><dd><a class="el" href="group__mqtt__enum__types.html#ggaba7ec045874a1c3432f99173367f735caa39030c93b0263b2699502a074f003b5">MQTTBadParameter</a> if context is NULL; <a class="el" href="group__mqtt__enum__types.html#ggaba7ec045874a1c3432f99173367f735caa14bc8aa4ad218702d782366945d43ac">MQTTRecvFailed</a> if a network error occurs during reception; <a class="el" href="group__mqtt__enum__types.html#ggaba7ec045874a1c3432f99173367f735cafd06b63fe9677fa2af06b0f4c7d4ad55">MQTTSendFailed</a> if a network error occurs while sending an ACK or PINGREQ; <a class="el" href="group__mqtt__enum__types.html#ggaba7ec045874a1c3432f99173367f735caa5d7507e7664a14d63a8bc44b280093e">MQTTBadResponse</a> if an invalid packet is received; <a class="el" href="group__mqtt__enum__types.html#ggaba7ec045874a1c3432f99173367f735ca076ca8965e836a06e707a94adb26144f">MQTTKeepAliveTimeout</a> if the server has not sent a PINGRESP before <a class="el" href="core__mqtt__config__defaults_8h.html#afa825fddb52da7df88fb56d2befcd2fa" title="Maximum number of milliseconds to wait for a ping response to a ping request as part of the keep-aliv...">MQTT_PINGRESP_TIMEOUT_MS</a> milliseconds; <a class="el" href="group__mqtt__enum__types.html#ggaba7ec045874a1c3432f99173367f735ca67905d7a05f98faa557a73eb5092bd8f">MQTTIllegalState</a> if an incoming QoS 1/2 publish or ack causes an invalid transition for the internal state machine; <a class="el" href="group__mqtt__enum__types.html#ggaba7ec045874a1c3432f99173367f735caa97df53014d919df5ecd54398f89f9b9">MQTTNeedMoreBytes</a> if MQTT_ProcessLoop has received incomplete data; it should be called again (probably after a delay); <a class="el" href="group__mqtt__enum__types.html#ggaba7ec045874a1c3432f99173367f735ca484e062cb4f3fccc1858dd25cfeee056">MQTTSuccess</a> on success.</dd></dl>
|
|
<p><b>Example</b> </p><div class="fragment"><div class="line"><span class="comment">// Variables used in this example.</span></div>
|
|
<div class="line"><a class="code hl_enumeration" href="group__mqtt__enum__types.html#gaba7ec045874a1c3432f99173367f735c">MQTTStatus_t</a> status;</div>
|
|
<div class="line"><span class="comment">// This context is assumed to be initialized and connected.</span></div>
|
|
<div class="line"><a class="code hl_struct" href="struct_m_q_t_t_context__t.html">MQTTContext_t</a> * pContext;</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="keywordflow">while</span>( <span class="keyword">true</span> )</div>
|
|
<div class="line">{</div>
|
|
<div class="line"> status = <a class="code hl_function" href="core__mqtt_8h.html#ab95d3d6b3eed98a6184fb2018c5b55d7">MQTT_ProcessLoop</a>( pContext );</div>
|
|
<div class="line"> </div>
|
|
<div class="line"> <span class="keywordflow">if</span>( status != <a class="code hl_enumvalue" href="group__mqtt__enum__types.html#ggaba7ec045874a1c3432f99173367f735ca484e062cb4f3fccc1858dd25cfeee056">MQTTSuccess</a> && status != <a class="code hl_enumvalue" href="group__mqtt__enum__types.html#ggaba7ec045874a1c3432f99173367f735caa97df53014d919df5ecd54398f89f9b9">MQTTNeedMoreBytes</a> )</div>
|
|
<div class="line"> {</div>
|
|
<div class="line"> <span class="comment">// Determine the error. It's possible we might need to disconnect</span></div>
|
|
<div class="line"> <span class="comment">// the underlying transport connection.</span></div>
|
|
<div class="line"> }</div>
|
|
<div class="line"> <span class="keywordflow">else</span></div>
|
|
<div class="line"> {</div>
|
|
<div class="line"> <span class="comment">// Other application functions.</span></div>
|
|
<div class="line"> }</div>
|
|
<div class="line">}</div>
|
|
<div class="ttc" id="acore__mqtt_8h_html_ab95d3d6b3eed98a6184fb2018c5b55d7"><div class="ttname"><a href="core__mqtt_8h.html#ab95d3d6b3eed98a6184fb2018c5b55d7">MQTT_ProcessLoop</a></div><div class="ttdeci">MQTTStatus_t MQTT_ProcessLoop(MQTTContext_t *pContext)</div><div class="ttdoc">Loop to receive packets from the transport interface. Handles keep alive.</div><div class="ttdef"><b>Definition:</b> core_mqtt.c:3119</div></div>
|
|
<div class="ttc" id="agroup__mqtt__enum__types_html_ggaba7ec045874a1c3432f99173367f735caa97df53014d919df5ecd54398f89f9b9"><div class="ttname"><a href="group__mqtt__enum__types.html#ggaba7ec045874a1c3432f99173367f735caa97df53014d919df5ecd54398f89f9b9">MQTTNeedMoreBytes</a></div><div class="ttdeci">@ MQTTNeedMoreBytes</div><div class="ttdef"><b>Definition:</b> core_mqtt_serializer.h:99</div></div>
|
|
</div><!-- fragment -->
|
|
</div>
|
|
</div>
|
|
<a id="aeb7c37284fcf6f68eb577427a6763fc6" name="aeb7c37284fcf6f68eb577427a6763fc6"></a>
|
|
<h2 class="memtitle"><span class="permalink"><a href="#aeb7c37284fcf6f68eb577427a6763fc6">◆ </a></span>MQTT_ReceiveLoop()</h2>
|
|
|
|
<div class="memitem">
|
|
<div class="memproto">
|
|
<table class="memname">
|
|
<tr>
|
|
<td class="memname"><a class="el" href="group__mqtt__enum__types.html#gaba7ec045874a1c3432f99173367f735c">MQTTStatus_t</a> MQTT_ReceiveLoop </td>
|
|
<td>(</td>
|
|
<td class="paramtype"><a class="el" href="struct_m_q_t_t_context__t.html">MQTTContext_t</a> * </td>
|
|
<td class="paramname"><em>pContext</em></td><td>)</td>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div><div class="memdoc">
|
|
|
|
<p>Loop to receive packets from the transport interface. Does not handle keep alive. </p>
|
|
<dl class="section note"><dt>Note</dt><dd>If a dummy <a class="el" href="group__mqtt__callback__types.html#gae3bea55b0e49e5208b8c5709a5ea23aa" title="Application provided function to query the time elapsed since a given epoch in milliseconds.">MQTTGetCurrentTimeFunc_t</a> was passed to <a class="el" href="core__mqtt_8h.html#ae8444f3a85535e62cdb1ae9c192677d6" title="Initialize an MQTT context.">MQTT_Init</a>, then the <a class="el" href="core__mqtt__config__defaults_8h.html#a43dc9a67427d9e420a65955eea0e2671" title="The maximum duration between non-empty network reads while receiving an MQTT packet via the MQTT_Proc...">MQTT_RECV_POLLING_TIMEOUT_MS</a> and <a class="el" href="core__mqtt__config__defaults_8h.html#ac262cab68c4c713ebc2b91a2e4ab8b19" title="The maximum duration allowed to send an MQTT packet over the transport interface.">MQTT_SEND_TIMEOUT_MS</a> timeout configurations MUST be set to 0.</dd></dl>
|
|
<dl class="params"><dt>Parameters</dt><dd>
|
|
<table class="params">
|
|
<tr><td class="paramdir">[in]</td><td class="paramname">pContext</td><td>Initialized and connected MQTT context.</td></tr>
|
|
</table>
|
|
</dd>
|
|
</dl>
|
|
<dl class="section note"><dt>Note</dt><dd>Calling this function blocks the calling context for a time period that depends on the the configuration macros, <a class="el" href="core__mqtt__config__defaults_8h.html#a43dc9a67427d9e420a65955eea0e2671" title="The maximum duration between non-empty network reads while receiving an MQTT packet via the MQTT_Proc...">MQTT_RECV_POLLING_TIMEOUT_MS</a> and <a class="el" href="core__mqtt__config__defaults_8h.html#ac262cab68c4c713ebc2b91a2e4ab8b19" title="The maximum duration allowed to send an MQTT packet over the transport interface.">MQTT_SEND_TIMEOUT_MS</a>, and the underlying transport interface implementation timeouts, unless an error occurs. The blocking period also depends on the execution time of the <a class="el" href="group__mqtt__callback__types.html#ga00d348277ed4fde23c95bfc749ae954a" title="Application callback for receiving incoming publishes and incoming acks.">MQTTEventCallback_t</a> callback supplied to the library. It is recommended that the supplied <a class="el" href="group__mqtt__callback__types.html#ga00d348277ed4fde23c95bfc749ae954a" title="Application callback for receiving incoming publishes and incoming acks.">MQTTEventCallback_t</a> callback does not contain blocking operations to prevent potential non-deterministic blocking period of the <a class="el" href="core__mqtt_8h.html#aeb7c37284fcf6f68eb577427a6763fc6" title="Loop to receive packets from the transport interface. Does not handle keep alive.">MQTT_ReceiveLoop</a> API call.</dd></dl>
|
|
<dl class="section return"><dt>Returns</dt><dd><a class="el" href="group__mqtt__enum__types.html#ggaba7ec045874a1c3432f99173367f735caa39030c93b0263b2699502a074f003b5">MQTTBadParameter</a> if context is NULL; <a class="el" href="group__mqtt__enum__types.html#ggaba7ec045874a1c3432f99173367f735caa14bc8aa4ad218702d782366945d43ac">MQTTRecvFailed</a> if a network error occurs during reception; <a class="el" href="group__mqtt__enum__types.html#ggaba7ec045874a1c3432f99173367f735cafd06b63fe9677fa2af06b0f4c7d4ad55">MQTTSendFailed</a> if a network error occurs while sending an ACK or PINGREQ; <a class="el" href="group__mqtt__enum__types.html#ggaba7ec045874a1c3432f99173367f735caa5d7507e7664a14d63a8bc44b280093e">MQTTBadResponse</a> if an invalid packet is received; <a class="el" href="group__mqtt__enum__types.html#ggaba7ec045874a1c3432f99173367f735ca67905d7a05f98faa557a73eb5092bd8f">MQTTIllegalState</a> if an incoming QoS 1/2 publish or ack causes an invalid transition for the internal state machine; <a class="el" href="group__mqtt__enum__types.html#ggaba7ec045874a1c3432f99173367f735caa97df53014d919df5ecd54398f89f9b9">MQTTNeedMoreBytes</a> if MQTT_ReceiveLoop has received incomplete data; it should be called again (probably after a delay); <a class="el" href="group__mqtt__enum__types.html#ggaba7ec045874a1c3432f99173367f735ca484e062cb4f3fccc1858dd25cfeee056">MQTTSuccess</a> on success.</dd></dl>
|
|
<p><b>Example</b> </p><div class="fragment"><div class="line"><span class="comment">// Variables used in this example.</span></div>
|
|
<div class="line"><a class="code hl_enumeration" href="group__mqtt__enum__types.html#gaba7ec045874a1c3432f99173367f735c">MQTTStatus_t</a> status;</div>
|
|
<div class="line">uint32_t keepAliveMs = 60 * 1000;</div>
|
|
<div class="line"><span class="comment">// This context is assumed to be initialized and connected.</span></div>
|
|
<div class="line"><a class="code hl_struct" href="struct_m_q_t_t_context__t.html">MQTTContext_t</a> * pContext;</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="keywordflow">while</span>( <span class="keyword">true</span> )</div>
|
|
<div class="line">{</div>
|
|
<div class="line"> status = <a class="code hl_function" href="core__mqtt_8h.html#aeb7c37284fcf6f68eb577427a6763fc6">MQTT_ReceiveLoop</a>( pContext );</div>
|
|
<div class="line"> </div>
|
|
<div class="line"> <span class="keywordflow">if</span>( status != <a class="code hl_enumvalue" href="group__mqtt__enum__types.html#ggaba7ec045874a1c3432f99173367f735ca484e062cb4f3fccc1858dd25cfeee056">MQTTSuccess</a> && status != <a class="code hl_enumvalue" href="group__mqtt__enum__types.html#ggaba7ec045874a1c3432f99173367f735caa97df53014d919df5ecd54398f89f9b9">MQTTNeedMoreBytes</a> )</div>
|
|
<div class="line"> {</div>
|
|
<div class="line"> <span class="comment">// Determine the error. It's possible we might need to disconnect</span></div>
|
|
<div class="line"> <span class="comment">// the underlying transport connection.</span></div>
|
|
<div class="line"> }</div>
|
|
<div class="line"> <span class="keywordflow">else</span></div>
|
|
<div class="line"> {</div>
|
|
<div class="line"> <span class="comment">// Since this function does not send pings, the application may need</span></div>
|
|
<div class="line"> <span class="comment">// to in order to comply with keep alive.</span></div>
|
|
<div class="line"> <span class="keywordflow">if</span>( ( pContext-><a class="code hl_variable" href="struct_m_q_t_t_context__t.html#aabe1d302a16771292151013e8e30c582">getTime</a>() - pContext-><a class="code hl_variable" href="struct_m_q_t_t_context__t.html#a01acf90953e830ba3e7f44182cb1d482">lastPacketTxTime</a> ) > keepAliveMs )</div>
|
|
<div class="line"> {</div>
|
|
<div class="line"> status = <a class="code hl_function" href="core__mqtt_8h.html#a66eced0c62ace790354ae3de40fc0959">MQTT_Ping</a>( pContext );</div>
|
|
<div class="line"> }</div>
|
|
<div class="line"> </div>
|
|
<div class="line"> <span class="comment">// Other application functions.</span></div>
|
|
<div class="line"> }</div>
|
|
<div class="line">}</div>
|
|
<div class="ttc" id="acore__mqtt_8h_html_a66eced0c62ace790354ae3de40fc0959"><div class="ttname"><a href="core__mqtt_8h.html#a66eced0c62ace790354ae3de40fc0959">MQTT_Ping</a></div><div class="ttdeci">MQTTStatus_t MQTT_Ping(MQTTContext_t *pContext)</div><div class="ttdoc">Sends an MQTT PINGREQ to broker.</div><div class="ttdef"><b>Definition:</b> core_mqtt.c:2922</div></div>
|
|
<div class="ttc" id="acore__mqtt_8h_html_aeb7c37284fcf6f68eb577427a6763fc6"><div class="ttname"><a href="core__mqtt_8h.html#aeb7c37284fcf6f68eb577427a6763fc6">MQTT_ReceiveLoop</a></div><div class="ttdeci">MQTTStatus_t MQTT_ReceiveLoop(MQTTContext_t *pContext)</div><div class="ttdoc">Loop to receive packets from the transport interface. Does not handle keep alive.</div><div class="ttdef"><b>Definition:</b> core_mqtt.c:3146</div></div>
|
|
<div class="ttc" id="astruct_m_q_t_t_context__t_html_a01acf90953e830ba3e7f44182cb1d482"><div class="ttname"><a href="struct_m_q_t_t_context__t.html#a01acf90953e830ba3e7f44182cb1d482">MQTTContext_t::lastPacketTxTime</a></div><div class="ttdeci">uint32_t lastPacketTxTime</div><div class="ttdoc">Timestamp of the last packet sent by the library.</div><div class="ttdef"><b>Definition:</b> core_mqtt.h:227</div></div>
|
|
<div class="ttc" id="astruct_m_q_t_t_context__t_html_aabe1d302a16771292151013e8e30c582"><div class="ttname"><a href="struct_m_q_t_t_context__t.html#aabe1d302a16771292151013e8e30c582">MQTTContext_t::getTime</a></div><div class="ttdeci">MQTTGetCurrentTimeFunc_t getTime</div><div class="ttdoc">Function used to get millisecond timestamps.</div><div class="ttdef"><b>Definition:</b> core_mqtt.h:217</div></div>
|
|
</div><!-- fragment -->
|
|
</div>
|
|
</div>
|
|
<a id="a00e1a3eba2c21899a6b4312c7d65d090" name="a00e1a3eba2c21899a6b4312c7d65d090"></a>
|
|
<h2 class="memtitle"><span class="permalink"><a href="#a00e1a3eba2c21899a6b4312c7d65d090">◆ </a></span>MQTT_GetPacketId()</h2>
|
|
|
|
<div class="memitem">
|
|
<div class="memproto">
|
|
<table class="memname">
|
|
<tr>
|
|
<td class="memname">uint16_t MQTT_GetPacketId </td>
|
|
<td>(</td>
|
|
<td class="paramtype"><a class="el" href="struct_m_q_t_t_context__t.html">MQTTContext_t</a> * </td>
|
|
<td class="paramname"><em>pContext</em></td><td>)</td>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div><div class="memdoc">
|
|
|
|
<p>Get a packet ID that is valid according to the MQTT 3.1.1 spec. </p>
|
|
<dl class="params"><dt>Parameters</dt><dd>
|
|
<table class="params">
|
|
<tr><td class="paramdir">[in]</td><td class="paramname">pContext</td><td>Initialized MQTT context.</td></tr>
|
|
</table>
|
|
</dd>
|
|
</dl>
|
|
<dl class="section return"><dt>Returns</dt><dd>A non-zero number. </dd></dl>
|
|
|
|
</div>
|
|
</div>
|
|
<a id="a633409812b18547365ec9b853069021b" name="a633409812b18547365ec9b853069021b"></a>
|
|
<h2 class="memtitle"><span class="permalink"><a href="#a633409812b18547365ec9b853069021b">◆ </a></span>MQTT_MatchTopic()</h2>
|
|
|
|
<div class="memitem">
|
|
<div class="memproto">
|
|
<table class="memname">
|
|
<tr>
|
|
<td class="memname"><a class="el" href="group__mqtt__enum__types.html#gaba7ec045874a1c3432f99173367f735c">MQTTStatus_t</a> MQTT_MatchTopic </td>
|
|
<td>(</td>
|
|
<td class="paramtype">const char * </td>
|
|
<td class="paramname"><em>pTopicName</em>, </td>
|
|
</tr>
|
|
<tr>
|
|
<td class="paramkey"></td>
|
|
<td></td>
|
|
<td class="paramtype">const uint16_t </td>
|
|
<td class="paramname"><em>topicNameLength</em>, </td>
|
|
</tr>
|
|
<tr>
|
|
<td class="paramkey"></td>
|
|
<td></td>
|
|
<td class="paramtype">const char * </td>
|
|
<td class="paramname"><em>pTopicFilter</em>, </td>
|
|
</tr>
|
|
<tr>
|
|
<td class="paramkey"></td>
|
|
<td></td>
|
|
<td class="paramtype">const uint16_t </td>
|
|
<td class="paramname"><em>topicFilterLength</em>, </td>
|
|
</tr>
|
|
<tr>
|
|
<td class="paramkey"></td>
|
|
<td></td>
|
|
<td class="paramtype">bool * </td>
|
|
<td class="paramname"><em>pIsMatch</em> </td>
|
|
</tr>
|
|
<tr>
|
|
<td></td>
|
|
<td>)</td>
|
|
<td></td><td></td>
|
|
</tr>
|
|
</table>
|
|
</div><div class="memdoc">
|
|
|
|
<p>A utility function that determines whether the passed topic filter and topic name match according to the MQTT 3.1.1 protocol specification. </p>
|
|
<dl class="params"><dt>Parameters</dt><dd>
|
|
<table class="params">
|
|
<tr><td class="paramdir">[in]</td><td class="paramname">pTopicName</td><td>The topic name to check. </td></tr>
|
|
<tr><td class="paramdir">[in]</td><td class="paramname">topicNameLength</td><td>Length of the topic name. </td></tr>
|
|
<tr><td class="paramdir">[in]</td><td class="paramname">pTopicFilter</td><td>The topic filter to check. </td></tr>
|
|
<tr><td class="paramdir">[in]</td><td class="paramname">topicFilterLength</td><td>Length of topic filter. </td></tr>
|
|
<tr><td class="paramdir">[out]</td><td class="paramname">pIsMatch</td><td>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.</td></tr>
|
|
</table>
|
|
</dd>
|
|
</dl>
|
|
<dl class="section note"><dt>Note</dt><dd>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.</dd></dl>
|
|
<dl class="section return"><dt>Returns</dt><dd>Returns one of the following:<ul>
|
|
<li><a class="el" href="group__mqtt__enum__types.html#ggaba7ec045874a1c3432f99173367f735caa39030c93b0263b2699502a074f003b5">MQTTBadParameter</a>, if any of the input parameters is invalid.</li>
|
|
<li><a class="el" href="group__mqtt__enum__types.html#ggaba7ec045874a1c3432f99173367f735ca484e062cb4f3fccc1858dd25cfeee056">MQTTSuccess</a>, if the matching operation was performed.</li>
|
|
</ul>
|
|
</dd></dl>
|
|
<p><b>Example</b> </p><div class="fragment"><div class="line"><span class="comment">// Variables used in this example.</span></div>
|
|
<div class="line"><span class="keyword">const</span> <span class="keywordtype">char</span> * pTopic = <span class="stringliteral">"topic/match/1"</span>;</div>
|
|
<div class="line"><span class="keyword">const</span> <span class="keywordtype">char</span> * pFilter = <span class="stringliteral">"topic/#"</span>;</div>
|
|
<div class="line"><a class="code hl_enumeration" href="group__mqtt__enum__types.html#gaba7ec045874a1c3432f99173367f735c">MQTTStatus_t</a> status = <a class="code hl_enumvalue" href="group__mqtt__enum__types.html#ggaba7ec045874a1c3432f99173367f735ca484e062cb4f3fccc1858dd25cfeee056">MQTTSuccess</a>;</div>
|
|
<div class="line"><span class="keywordtype">bool</span> match = <span class="keyword">false</span>;</div>
|
|
<div class="line"> </div>
|
|
<div class="line">status = <a class="code hl_function" href="core__mqtt_8h.html#a633409812b18547365ec9b853069021b">MQTT_MatchTopic</a>( pTopic, strlen( pTopic ), pFilter, strlen( pFilter ), &match );</div>
|
|
<div class="line"><span class="comment">// Our parameters were valid, so this will return success.</span></div>
|
|
<div class="line">assert( status == <a class="code hl_enumvalue" href="group__mqtt__enum__types.html#ggaba7ec045874a1c3432f99173367f735ca484e062cb4f3fccc1858dd25cfeee056">MQTTSuccess</a> );</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// For this specific example, we already know this value is true. This</span></div>
|
|
<div class="line"><span class="comment">// check is placed here as an example for use with variable topic names.</span></div>
|
|
<div class="line"><span class="keywordflow">if</span>( match )</div>
|
|
<div class="line">{</div>
|
|
<div class="line"> <span class="comment">// Application can decide what to do with the matching topic name.</span></div>
|
|
<div class="line">}</div>
|
|
<div class="ttc" id="acore__mqtt_8h_html_a633409812b18547365ec9b853069021b"><div class="ttname"><a href="core__mqtt_8h.html#a633409812b18547365ec9b853069021b">MQTT_MatchTopic</a></div><div class="ttdeci">MQTTStatus_t MQTT_MatchTopic(const char *pTopicName, const uint16_t topicNameLength, const char *pTopicFilter, const uint16_t topicFilterLength, bool *pIsMatch)</div><div class="ttdoc">A utility function that determines whether the passed topic filter and topic name match according to ...</div><div class="ttdef"><b>Definition:</b> core_mqtt.c:3201</div></div>
|
|
</div><!-- fragment -->
|
|
</div>
|
|
</div>
|
|
<a id="ac43449e06856c6703cda73359c222bd2" name="ac43449e06856c6703cda73359c222bd2"></a>
|
|
<h2 class="memtitle"><span class="permalink"><a href="#ac43449e06856c6703cda73359c222bd2">◆ </a></span>MQTT_GetSubAckStatusCodes()</h2>
|
|
|
|
<div class="memitem">
|
|
<div class="memproto">
|
|
<table class="memname">
|
|
<tr>
|
|
<td class="memname"><a class="el" href="group__mqtt__enum__types.html#gaba7ec045874a1c3432f99173367f735c">MQTTStatus_t</a> MQTT_GetSubAckStatusCodes </td>
|
|
<td>(</td>
|
|
<td class="paramtype">const <a class="el" href="struct_m_q_t_t_packet_info__t.html">MQTTPacketInfo_t</a> * </td>
|
|
<td class="paramname"><em>pSubackPacket</em>, </td>
|
|
</tr>
|
|
<tr>
|
|
<td class="paramkey"></td>
|
|
<td></td>
|
|
<td class="paramtype">uint8_t ** </td>
|
|
<td class="paramname"><em>pPayloadStart</em>, </td>
|
|
</tr>
|
|
<tr>
|
|
<td class="paramkey"></td>
|
|
<td></td>
|
|
<td class="paramtype">size_t * </td>
|
|
<td class="paramname"><em>pPayloadSize</em> </td>
|
|
</tr>
|
|
<tr>
|
|
<td></td>
|
|
<td>)</td>
|
|
<td></td><td></td>
|
|
</tr>
|
|
</table>
|
|
</div><div class="memdoc">
|
|
|
|
<p>Parses the payload of an MQTT SUBACK packet that contains status codes corresponding to topic filter subscription requests from the original subscribe packet. </p>
|
|
<p>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:</p><ul>
|
|
<li>0x00 - Success - Maximum QoS 0</li>
|
|
<li>0x01 - Success - Maximum QoS 1</li>
|
|
<li>0x02 - Success - Maximum QoS 2</li>
|
|
<li>0x80 - Failure Refer to <a class="el" href="group__mqtt__enum__types.html#ga48dabc1579e3c0ac6058ce9068054611" title="The status codes in the SUBACK response to a subscription request.">MQTTSubAckStatus_t</a> for the status codes.</li>
|
|
</ul>
|
|
<dl class="params"><dt>Parameters</dt><dd>
|
|
<table class="params">
|
|
<tr><td class="paramdir">[in]</td><td class="paramname">pSubackPacket</td><td>The SUBACK packet whose payload is to be parsed. </td></tr>
|
|
<tr><td class="paramdir">[out]</td><td class="paramname">pPayloadStart</td><td>This is populated with the starting address of the payload (or return codes for topic filters) in the SUBACK packet. </td></tr>
|
|
<tr><td class="paramdir">[out]</td><td class="paramname">pPayloadSize</td><td>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.</td></tr>
|
|
</table>
|
|
</dd>
|
|
</dl>
|
|
<dl class="section return"><dt>Returns</dt><dd>Returns one of the following:<ul>
|
|
<li><a class="el" href="group__mqtt__enum__types.html#ggaba7ec045874a1c3432f99173367f735caa39030c93b0263b2699502a074f003b5">MQTTBadParameter</a> if the input SUBACK packet is invalid.</li>
|
|
<li><a class="el" href="group__mqtt__enum__types.html#ggaba7ec045874a1c3432f99173367f735ca484e062cb4f3fccc1858dd25cfeee056">MQTTSuccess</a> if parsing the payload was successful.</li>
|
|
</ul>
|
|
</dd></dl>
|
|
<p><b>Example</b> </p><div class="fragment"><div class="line"><span class="comment">// Global variable used in this example.</span></div>
|
|
<div class="line"><span class="comment">// This is assumed to be the subscription list in the original SUBSCRIBE packet.</span></div>
|
|
<div class="line"><a class="code hl_struct" href="struct_m_q_t_t_subscribe_info__t.html">MQTTSubscribeInfo_t</a> pSubscribes[ NUMBER_OF_SUBSCRIPTIONS ];</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// MQTT_GetSubAckStatusCodes is intended to be used from the application</span></div>
|
|
<div class="line"><span class="comment">// callback that is called by the library in MQTT_ProcessLoop or MQTT_ReceiveLoop.</span></div>
|
|
<div class="line"><span class="keywordtype">void</span> eventCallback(</div>
|
|
<div class="line"> <a class="code hl_struct" href="struct_m_q_t_t_context__t.html">MQTTContext_t</a> * pContext,</div>
|
|
<div class="line"> <a class="code hl_struct" href="struct_m_q_t_t_packet_info__t.html">MQTTPacketInfo_t</a> * pPacketInfo,</div>
|
|
<div class="line"> <a class="code hl_struct" href="struct_m_q_t_t_deserialized_info__t.html">MQTTDeserializedInfo_t</a> * pDeserializedInfo</div>
|
|
<div class="line">)</div>
|
|
<div class="line">{</div>
|
|
<div class="line"> <a class="code hl_enumeration" href="group__mqtt__enum__types.html#gaba7ec045874a1c3432f99173367f735c">MQTTStatus_t</a> status = <a class="code hl_enumvalue" href="group__mqtt__enum__types.html#ggaba7ec045874a1c3432f99173367f735ca484e062cb4f3fccc1858dd25cfeee056">MQTTSuccess</a>;</div>
|
|
<div class="line"> uint8_t * pCodes;</div>
|
|
<div class="line"> <span class="keywordtype">size_t</span> numCodes;</div>
|
|
<div class="line"> </div>
|
|
<div class="line"> <span class="keywordflow">if</span>( pPacketInfo-><a class="code hl_variable" href="struct_m_q_t_t_packet_info__t.html#a7fef40548c1aa0f0e7f812a6a7243758">type</a> == <a class="code hl_define" href="group__mqtt__constants.html#ga307e0186aa17fdd0d6d181d3d2715766">MQTT_PACKET_TYPE_SUBACK</a> )</div>
|
|
<div class="line"> {</div>
|
|
<div class="line"> status = <a class="code hl_function" href="core__mqtt_8h.html#ac43449e06856c6703cda73359c222bd2">MQTT_GetSubAckStatusCodes</a>( pPacketInfo, &pCodes, &numCodes );</div>
|
|
<div class="line"> </div>
|
|
<div class="line"> <span class="comment">// Since the pointers to the payload and payload size are not NULL, and</span></div>
|
|
<div class="line"> <span class="comment">// we use the packet info struct passed to the app callback (verified</span></div>
|
|
<div class="line"> <span class="comment">// to be valid by the library), this function must return success.</span></div>
|
|
<div class="line"> assert( status == <a class="code hl_enumvalue" href="group__mqtt__enum__types.html#ggaba7ec045874a1c3432f99173367f735ca484e062cb4f3fccc1858dd25cfeee056">MQTTSuccess</a> );</div>
|
|
<div class="line"> <span class="comment">// The server must send a response code for each topic filter in the</span></div>
|
|
<div class="line"> <span class="comment">// original SUBSCRIBE packet.</span></div>
|
|
<div class="line"> assert( numCodes == NUMBER_OF_SUBSCRIPTIONS );</div>
|
|
<div class="line"> </div>
|
|
<div class="line"> <span class="keywordflow">for</span>( <span class="keywordtype">int</span> i = 0; i < numCodes; i++ )</div>
|
|
<div class="line"> {</div>
|
|
<div class="line"> <span class="comment">// The only failure code is 0x80 = MQTTSubAckFailure.</span></div>
|
|
<div class="line"> <span class="keywordflow">if</span>( pCodes[ i ] == <a class="code hl_enumvalue" href="group__mqtt__enum__types.html#gga48dabc1579e3c0ac6058ce9068054611aeb83b20da8eda934cde6b92db225a808">MQTTSubAckFailure</a> )</div>
|
|
<div class="line"> {</div>
|
|
<div class="line"> <span class="comment">// The subscription failed, we may want to retry the</span></div>
|
|
<div class="line"> <span class="comment">// subscription in pSubscribes[ i ] outside of this callback.</span></div>
|
|
<div class="line"> }</div>
|
|
<div class="line"> <span class="keywordflow">else</span></div>
|
|
<div class="line"> {</div>
|
|
<div class="line"> <span class="comment">// The subscription was granted, but the maximum QoS may be</span></div>
|
|
<div class="line"> <span class="comment">// lower than what was requested. We can verify the granted QoS.</span></div>
|
|
<div class="line"> <span class="keywordflow">if</span>( pSubscribes[ i ].qos != pCodes[ i ] )</div>
|
|
<div class="line"> {</div>
|
|
<div class="line"> <a class="code hl_define" href="core__mqtt__config__defaults_8h.html#a7da92048aaf0cbfcacde9539c98a0e05">LogWarn</a>( (</div>
|
|
<div class="line"> <span class="stringliteral">"Requested QoS %u, but granted QoS %u for %s"</span>,</div>
|
|
<div class="line"> pSubscribes[ i ].qos, pCodes[ i ], pSubscribes[ i ].pTopicFilter</div>
|
|
<div class="line"> ) );</div>
|
|
<div class="line"> }</div>
|
|
<div class="line"> }</div>
|
|
<div class="line"> }</div>
|
|
<div class="line"> }</div>
|
|
<div class="line"> <span class="comment">// Handle other packet types.</span></div>
|
|
<div class="line">}</div>
|
|
<div class="ttc" id="acore__mqtt_8h_html_ac43449e06856c6703cda73359c222bd2"><div class="ttname"><a href="core__mqtt_8h.html#ac43449e06856c6703cda73359c222bd2">MQTT_GetSubAckStatusCodes</a></div><div class="ttdeci">MQTTStatus_t MQTT_GetSubAckStatusCodes(const MQTTPacketInfo_t *pSubackPacket, uint8_t **pPayloadStart, size_t *pPayloadSize)</div><div class="ttdoc">Parses the payload of an MQTT SUBACK packet that contains status codes corresponding to topic filter ...</div><div class="ttdef"><b>Definition:</b> core_mqtt.c:3270</div></div>
|
|
<div class="ttc" id="acore__mqtt__config__defaults_8h_html_a7da92048aaf0cbfcacde9539c98a0e05"><div class="ttname"><a href="core__mqtt__config__defaults_8h.html#a7da92048aaf0cbfcacde9539c98a0e05">LogWarn</a></div><div class="ttdeci">#define LogWarn(message)</div><div class="ttdoc">Macro that is called in the MQTT library for logging "Warning" level messages.</div><div class="ttdef"><b>Definition:</b> core_mqtt_config_defaults.h:235</div></div>
|
|
<div class="ttc" id="agroup__mqtt__constants_html_ga307e0186aa17fdd0d6d181d3d2715766"><div class="ttname"><a href="group__mqtt__constants.html#ga307e0186aa17fdd0d6d181d3d2715766">MQTT_PACKET_TYPE_SUBACK</a></div><div class="ttdeci">#define MQTT_PACKET_TYPE_SUBACK</div><div class="ttdoc">SUBACK (server-to-client).</div><div class="ttdef"><b>Definition:</b> core_mqtt_serializer.h:61</div></div>
|
|
<div class="ttc" id="agroup__mqtt__enum__types_html_gga48dabc1579e3c0ac6058ce9068054611aeb83b20da8eda934cde6b92db225a808"><div class="ttname"><a href="group__mqtt__enum__types.html#gga48dabc1579e3c0ac6058ce9068054611aeb83b20da8eda934cde6b92db225a808">MQTTSubAckFailure</a></div><div class="ttdeci">@ MQTTSubAckFailure</div><div class="ttdoc">Failure.</div><div class="ttdef"><b>Definition:</b> core_mqtt.h:154</div></div>
|
|
<div class="ttc" id="astruct_m_q_t_t_packet_info__t_html_a7fef40548c1aa0f0e7f812a6a7243758"><div class="ttname"><a href="struct_m_q_t_t_packet_info__t.html#a7fef40548c1aa0f0e7f812a6a7243758">MQTTPacketInfo_t::type</a></div><div class="ttdeci">uint8_t type</div><div class="ttdoc">Type of incoming MQTT packet.</div><div class="ttdef"><b>Definition:</b> core_mqtt_serializer.h:248</div></div>
|
|
</div><!-- fragment -->
|
|
</div>
|
|
</div>
|
|
<a id="a05d9facfce89c5f9edef09ca13717f50" name="a05d9facfce89c5f9edef09ca13717f50"></a>
|
|
<h2 class="memtitle"><span class="permalink"><a href="#a05d9facfce89c5f9edef09ca13717f50">◆ </a></span>MQTT_Status_strerror()</h2>
|
|
|
|
<div class="memitem">
|
|
<div class="memproto">
|
|
<table class="memname">
|
|
<tr>
|
|
<td class="memname">const char * MQTT_Status_strerror </td>
|
|
<td>(</td>
|
|
<td class="paramtype"><a class="el" href="group__mqtt__enum__types.html#gaba7ec045874a1c3432f99173367f735c">MQTTStatus_t</a> </td>
|
|
<td class="paramname"><em>status</em></td><td>)</td>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div><div class="memdoc">
|
|
|
|
<p>Error code to string conversion for MQTT statuses. </p>
|
|
<dl class="params"><dt>Parameters</dt><dd>
|
|
<table class="params">
|
|
<tr><td class="paramdir">[in]</td><td class="paramname">status</td><td>The status to convert to a string.</td></tr>
|
|
</table>
|
|
</dd>
|
|
</dl>
|
|
<dl class="section return"><dt>Returns</dt><dd>The string representation of the status. </dd></dl>
|
|
|
|
</div>
|
|
</div>
|
|
</div><!-- contents -->
|
|
</div><!-- doc-content -->
|
|
<!-- start footer part -->
|
|
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
|
|
<ul>
|
|
<li class="navelem"><a class="el" href="dir_b2f33c71d4aa5e7af42a1ca61ff5af1b.html">source</a></li><li class="navelem"><a class="el" href="dir_8ee1a5e78eaec319fe5d64075812fc61.html">include</a></li><li class="navelem"><a class="el" href="core__mqtt_8h.html">core_mqtt.h</a></li>
|
|
<li class="footer">Generated by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.6 </li>
|
|
</ul>
|
|
</div>
|
|
</body>
|
|
</html>
|