mirror of
https://github.com/FreeRTOS/coreMQTT
synced 2025-05-12 21:35:41 +08:00
189 lines
20 KiB
HTML
189 lines
20 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: MQTT_Init</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.2.0</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('mqtt_init_function.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><div class="header">
|
|
<div class="headertitle"><div class="title">MQTT_Init </div></div>
|
|
</div><!--header-->
|
|
<div class="contents">
|
|
<div class="textblock"><div class="fragment"><div class="line"><a class="code hl_enumeration" href="group__mqtt__enum__types.html#gaba7ec045874a1c3432f99173367f735c">MQTTStatus_t</a> <a class="code hl_function" href="core__mqtt_8h.html#ae8444f3a85535e62cdb1ae9c192677d6">MQTT_Init</a>( <a class="code hl_struct" href="struct_m_q_t_t_context__t.html">MQTTContext_t</a> * pContext,</div>
|
|
<div class="line"> <span class="keyword">const</span> <a class="code hl_struct" href="struct_transport_interface__t.html">TransportInterface_t</a> * pTransportInterface,</div>
|
|
<div class="line"> <a class="code hl_typedef" href="group__mqtt__callback__types.html#gae3bea55b0e49e5208b8c5709a5ea23aa">MQTTGetCurrentTimeFunc_t</a> getTimeFunction,</div>
|
|
<div class="line"> <a class="code hl_typedef" href="group__mqtt__callback__types.html#ga00d348277ed4fde23c95bfc749ae954a">MQTTEventCallback_t</a> userCallback,</div>
|
|
<div class="line"> <span class="keyword">const</span> <a class="code hl_struct" href="struct_m_q_t_t_fixed_buffer__t.html">MQTTFixedBuffer_t</a> * pNetworkBuffer );</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__callback__types_html_ga00d348277ed4fde23c95bfc749ae954a"><div class="ttname"><a href="group__mqtt__callback__types.html#ga00d348277ed4fde23c95bfc749ae954a">MQTTEventCallback_t</a></div><div class="ttdeci">void(* MQTTEventCallback_t)(struct MQTTContext *pContext, struct MQTTPacketInfo *pPacketInfo, struct MQTTDeserializedInfo *pDeserializedInfo)</div><div class="ttdoc">Application callback for receiving incoming publishes and incoming acks.</div><div class="ttdef"><b>Definition:</b> core_mqtt.h:97</div></div>
|
|
<div class="ttc" id="agroup__mqtt__callback__types_html_gae3bea55b0e49e5208b8c5709a5ea23aa"><div class="ttname"><a href="group__mqtt__callback__types.html#gae3bea55b0e49e5208b8c5709a5ea23aa">MQTTGetCurrentTimeFunc_t</a></div><div class="ttdeci">uint32_t(* MQTTGetCurrentTimeFunc_t)(void)</div><div class="ttdoc">Application provided function to query the time elapsed since a given epoch in milliseconds.</div><div class="ttdef"><b>Definition:</b> core_mqtt.h:82</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="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:170</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_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><!-- fragment --><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="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_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:254</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_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><!-- contents -->
|
|
</div><!-- PageDoc -->
|
|
</div><!-- doc-content -->
|
|
<!-- start footer part -->
|
|
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
|
|
<ul>
|
|
<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>
|