-
Notifications
You must be signed in to change notification settings - Fork 0
/
index.html
1340 lines (1338 loc) · 244 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!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">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.9.1"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>CommsChampion Ecosystem MQTT-SN Client: MQTT-SN Client Library</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="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>
<link href="doxygen.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 style="height: 56px;">
<td id="projectalign" style="padding-left: 0.5em;">
<div id="projectname">CommsChampion Ecosystem MQTT-SN Client
</div>
<div id="projectbrief">MQTT-SN client library.</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.9.1 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
var searchBox = new SearchBox("searchBox", "search",false,'Search','.html');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
$(function() {
initMenu('',true,false,'search.php','Search');
$(document).ready(function() { init_search(); });
});
/* @license-end */</script>
<div id="main-nav"></div>
</div><!-- top -->
<!-- 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">
<iframe src="javascript:void(0)" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
<div class="PageDoc"><div class="header">
<div class="headertitle">
<div class="title">MQTT-SN Client Library </div> </div>
</div><!--header-->
<div class="contents">
<div class="toc"><h3>Table of Contents</h3>
<ul><li class="level1"><a href="#doc_cc_mqttsn_client_overview">Overview</a></li>
<li class="level1"><a href="#doc_cc_mqttsn_client_version">Version of the Library</a></li>
<li class="level1"><a href="#cc_mqttsn_client_header">Header</a></li>
<li class="level1"><a href="#doc_cc_mqttsn_client_allocation">Client Allocation</a></li>
<li class="level1"><a href="#doc_cc_mqttsn_client_callbacks">"Must Have" Callbacks Registration</a><ul><li class="level2"><a href="#doc_cc_mqttsn_client_callbacks_send_data">Sending Data To Gateway</a></li>
<li class="level2"><a href="#doc_cc_mqttsn_client_callbacks_gateway_disconnect">Reporting Unsolicited Gateway Disconnection</a></li>
<li class="level2"><a href="#doc_cc_mqttsn_client_callbacks_message">Reporting Received Message</a></li>
</ul>
</li>
<li class="level1"><a href="#doc_cc_mqttsn_client_time">Time Measurement</a></li>
<li class="level1"><a href="#doc_cc_mqttsn_client_log">Error Logging</a></li>
<li class="level1"><a href="#doc_cc_mqttsn_client_data">Reporting Incoming Data</a></li>
<li class="level1"><a href="#doc_cc_mqttsn_client_concepts">Operating Concepts</a></li>
<li class="level1"><a href="#doc_cc_mqttsn_client_retry_period">Default Retry Period</a></li>
<li class="level1"><a href="#doc_cc_mqttsn_client_retry_count">Default Retry Count</a></li>
<li class="level1"><a href="#doc_cc_mqttsn_client_broadcast_radius">Default Broadcast Radius</a></li>
<li class="level1"><a href="#doc_cc_mqttsn_client_gateway_discovery">Gateway Discovery</a><ul><li class="level2"><a href="#doc_cc_mqttsn_client_search_prepare">Preparing "Search" Operation.</a></li>
<li class="level2"><a href="#doc_cc_mqttsn_client_search_retry_period">Configuring "Search" Retry Period</a></li>
<li class="level2"><a href="#doc_cc_mqttsn_client_search_retry_count">Configuring "Search" Retry Count</a></li>
<li class="level2"><a href="#doc_cc_mqttsn_client_search_broadcast_radius">Configuring "Search" Broadcast Radius</a></li>
<li class="level2"><a href="#doc_cc_mqttsn_client_search_send">Sending Search Gateway Request</a></li>
<li class="level2"><a href="#doc_cc_mqttsn_client_search_cancel">Cancel the "Search" Operation.</a></li>
<li class="level2"><a href="#doc_cc_mqttsn_client_search_simplify">Simplifying the "Search" Operation Preparation</a></li>
</ul>
</li>
<li class="level1"><a href="#doc_cc_mqttsn_client_gateway_monitoring">Monitoring and Managing Available Gateways</a></li>
<li class="level1"><a href="#doc_cc_mqttsn_client_connect">Connecting to Gateway</a><ul><li class="level2"><a href="#doc_cc_mqttsn_client_connect_prepare">Preparing "Connect" Operation.</a></li>
<li class="level2"><a href="#doc_cc_mqttsn_client_connect_retry_period">Configuring "Connect" Retry Period</a></li>
<li class="level2"><a href="#doc_cc_mqttsn_client_connect_retry_count">Configuring "Connect" Retry Count</a></li>
<li class="level2"><a href="#doc_cc_mqttsn_client_connect_basic">Configuration of "Connect" Operation</a></li>
<li class="level2"><a href="#doc_cc_mqttsn_client_connect_will">Will Configuration</a></li>
<li class="level2"><a href="#doc_cc_mqttsn_client_connect_send">Sending Connection Request</a></li>
<li class="level2"><a href="#doc_cc_mqttsn_client_connect_cancel">Cancel the "Connect" Operation.</a></li>
<li class="level2"><a href="#doc_cc_mqttsn_client_connect_simplify">Simplifying the "Connect" Operation Preparation.</a></li>
<li class="level2"><a href="#doc_cc_mqttsn_client_connect_check">Check The Library Remains Connected</a></li>
</ul>
</li>
<li class="level1"><a href="#doc_cc_mqttsn_client_disconnect">Disconnecting From Gateway</a><ul><li class="level2"><a href="#doc_cc_mqttsn_client_disconnect_prepare">Preparing "Disconnect" Operation.</a></li>
<li class="level2"><a href="#doc_cc_mqttsn_client_disconnect_retry_period">Configuring "Disconnect" Retry Period</a></li>
<li class="level2"><a href="#doc_cc_mqttsn_client_disconnect_retry_count">Configuring "Disconnect" Retry Count</a></li>
<li class="level2"><a href="#doc_cc_mqttsn_client_disconnect_send">Sending Disconnection Request</a></li>
<li class="level2"><a href="#doc_cc_mqttsn_client_disconnect_cancel">Cancel the "Disconnect" Operation.</a></li>
<li class="level2"><a href="#doc_cc_mqttsn_client_disconnect_simplify">Simplifying the "Disconnect" Operation Preparation.</a></li>
</ul>
</li>
<li class="level1"><a href="#doc_cc_mqttsn_client_subscribe">Subscribing to Receive Messages</a><ul><li class="level2"><a href="#doc_cc_mqttsn_client_subscribe_prepare">Preparing "Subscribe" Operation.</a></li>
<li class="level2"><a href="#doc_cc_mqttsn_client_subscribe_retry_period">Configuring "Subscribe" Retry Period</a></li>
<li class="level2"><a href="#doc_cc_mqttsn_client_subscribe_retry_count">Configuring "Subscribe" Retry Count</a></li>
<li class="level2"><a href="#doc_cc_mqttsn_client_subscribe_config">Subscribe Configuration</a></li>
<li class="level2"><a href="#doc_cc_mqttsn_client_subscribe_send">Sending Subscription Request</a></li>
<li class="level2"><a href="#doc_cc_mqttsn_client_subscribe_cancel">Cancel the "Subscribe" Operation.</a></li>
<li class="level2"><a href="#doc_cc_mqttsn_client_subscribe_simplify">Simplifying the "Subscribe" Operation Preparation.</a></li>
</ul>
</li>
<li class="level1"><a href="#doc_cc_mqttsn_client_unsubscribe">Unsubscribing from Receiving Messages</a><ul><li class="level2"><a href="#doc_cc_mqttsn_client_unsubscribe_prepare">Preparing "Unsubscribe" Operation.</a></li>
<li class="level2"><a href="#doc_cc_mqttsn_client_unsubscribe_retry_period">Configuring "Unsubscribe" Retry Period</a></li>
<li class="level2"><a href="#doc_cc_mqttsn_client_unsubscribe_retry_count">Configuring "Unsubscribe" Retry Count</a></li>
<li class="level2"><a href="#doc_cc_mqttsn_client_unsubscribe_config">Unsubscribe Configuration</a></li>
<li class="level2"><a href="#doc_cc_mqttsn_client_unsubscribe_send">Sending Unsubscription Request</a></li>
<li class="level2"><a href="#doc_cc_mqttsn_client_unsubscribe_cancel">Cancel the "Unsubscribe" Operation.</a></li>
<li class="level2"><a href="#doc_cc_mqttsn_client_unsubscribe_simplify">Simplifying the "Unsubscribe" Operation Preparation.</a></li>
</ul>
</li>
<li class="level1"><a href="#doc_cc_mqttsn_client_publish">Publishing Messages</a><ul><li class="level2"><a href="#doc_cc_mqttsn_client_publish_prepare">Preparing "Publish" Operation.</a></li>
<li class="level2"><a href="#doc_cc_mqttsn_client_publish_retry_period">Configuring "Publish" Retry Period</a></li>
<li class="level2"><a href="#doc_cc_mqttsn_client_publish_retry_count">Configuring "Publish" Retry Count</a></li>
<li class="level2"><a href="#doc_cc_mqttsn_client_publish_config">Configuration of "Publish" Operation</a></li>
<li class="level2"><a href="#doc_cc_mqttsn_client_publish_send">Sending Publish Request</a></li>
<li class="level2"><a href="#doc_cc_mqttsn_client_publish_cancel">Cancel the "Publish" Operation.</a></li>
<li class="level2"><a href="#doc_cc_mqttsn_client_publish_simplify">Simplifying the "Publish" Operation Preparation.</a></li>
<li class="level2"><a href="#doc_cc_mqttsn_client_publish_reg_limit">Limiting Stored Outgoing Topic IDs</a></li>
</ul>
</li>
<li class="level1"><a href="#doc_cc_mqttsn_client_will">Updating Will</a><ul><li class="level2"><a href="#doc_cc_mqttsn_client_will_prepare">Preparing "Will" Operation.</a></li>
<li class="level2"><a href="#doc_cc_mqttsn_client_will_retry_period">Configuring "Will" Retry Period</a></li>
<li class="level2"><a href="#doc_cc_mqttsn_client_will_retry_count">Configuring "Will" Retry Count</a></li>
<li class="level2"><a href="#doc_cc_mqttsn_client_will_config">Configuration of "Will" Operation</a></li>
<li class="level2"><a href="#doc_cc_mqttsn_client_will_send">Sending Will Update Request</a></li>
<li class="level2"><a href="#doc_cc_mqttsn_client_will_cancel">Cancel the "Will" Operation.</a></li>
<li class="level2"><a href="#doc_cc_mqttsn_client_will_simplify">Simplifying the "Will" Operation Preparation.</a></li>
</ul>
</li>
<li class="level1"><a href="#doc_cc_mqttsn_client_receive">Receiving Messages</a></li>
<li class="level1"><a href="#doc_cc_mqttsn_client_sleep">Sleeping</a><ul><li class="level2"><a href="#doc_cc_mqttsn_client_sleep_prepare">Preparing "Sleep" Operation.</a></li>
<li class="level2"><a href="#doc_cc_mqttsn_client_sleep_retry_period">Configuring "Sleep" Retry Period</a></li>
<li class="level2"><a href="#doc_cc_mqttsn_client_sleep_retry_count">Configuring "Sleep" Retry Count</a></li>
<li class="level2"><a href="#doc_cc_mqttsn_client_sleep_config">Configuration of "Sleep" Operation</a></li>
<li class="level2"><a href="#doc_cc_mqttsn_client_sleep_send">Sending Sleep Request</a></li>
<li class="level2"><a href="#doc_cc_mqttsn_client_sleep_cancel">Cancel the "Sleep" Operation.</a></li>
<li class="level2"><a href="#doc_cc_mqttsn_client_sleep_simplify">Simplifying the "Sleep" Operation Preparation.</a></li>
<li class="level2"><a href="#doc_cc_mqttsn_client_sleep_recv">Receiving Messages During "Sleep" State.</a></li>
</ul>
</li>
<li class="level1"><a href="#doc_cc_mqttsn_client_unsolicited_disconnect">Unsolicited Gateway Disconnection</a><ul><li class="level2"><a href="#doc_cc_mqttsn_client_unsolicited_disconnect_keep_alive">Keep Alive Timeout</a></li>
<li class="level2"><a href="#doc_cc_mqttsn_client_unsolicited_disconnect_message">Receiving DISCONNECT message</a></li>
</ul>
</li>
<li class="level1"><a href="#doc_cc_mqttsn_client_thread_safety">Thread Safety</a></li>
<li class="level1"><a href="#doc_cc_mqttsn_client_debug_build">Debug Build</a></li>
</ul>
</div>
<div class="textblock"><h1><a class="anchor" id="doc_cc_mqttsn_client_overview"></a>
Overview</h1>
<p>The <b>MQTT-SN Client Library</b> from the <a href="https://commschamp.github.io/">CommsChampion Ecosystem</a> provides simple, asynchronous, non-blocking, and easy to use interface to operate MQTT-SN client. The library doesn't make any assumption on the system it is running on, as well as on the type of I/O link being used to communicate its data to the MQTT-SN gateway.</p>
<p>It is a responsibility of the calling application to manage network connectivity as well as measure time required for the correct operation of the MQTT-SN protocol.</p>
<p>The library allows the application to have a full control over the raw data for any extra analysis and/or manipulation, such as encryption or extra framing.</p>
<h1><a class="anchor" id="doc_cc_mqttsn_client_version"></a>
Version of the Library</h1>
<p>The version is of the library applicable to this documentation is defined in the <a class="el" href="common_8h.html">cc_mqttsn_client/common.h</a> file using the following defines: </p><ul>
<li><a class="el" href="group__global.html#ga9cfd05cb01bb3b66bff4ec42717d97f3">CC_MQTTSN_CLIENT_MAJOR_VERSION</a> </li>
<li><a class="el" href="group__global.html#gac9359cd3ada2e40ab8263d04698c6aca">CC_MQTTSN_CLIENT_MINOR_VERSION</a> </li>
<li><a class="el" href="group__global.html#ga00acea6ed2147ecb0eb9845a1cc882ef">CC_MQTTSN_CLIENT_PATCH_VERSION</a></li>
</ul>
<h1><a class="anchor" id="cc_mqttsn_client_header"></a>
Header</h1>
<p>To use this <b>MQTT-SN Client Library</b> use the following single include statement: </p><div class="fragment"><div class="line"><span class="preprocessor">#include "cc_mqttsn_client/client.h"</span></div>
</div><!-- fragment --><h1><a class="anchor" id="doc_cc_mqttsn_client_allocation"></a>
Client Allocation</h1>
<p>The library supports multiple independent MQTT-SN client sessions. The allocation of data structures relevant to a single client is performed using <b><a class="el" href="group__client.html#gaf652749014fcbe9a4fd26a60c875947a" title="Allocate new client.">cc_mqttsn_client_alloc()</a></b> function. </p><div class="fragment"><div class="line"><a class="code" href="group__client.html#gac0001ebe73d8670a38077f4206228ab1">CC_MqttsnClientHandle</a> client = <a class="code" href="group__client.html#gaf652749014fcbe9a4fd26a60c875947a">cc_mqttsn_client_alloc</a>();</div>
<div class="ttc" id="agroup__client_html_gac0001ebe73d8670a38077f4206228ab1"><div class="ttname"><a href="group__client.html#gac0001ebe73d8670a38077f4206228ab1">CC_MqttsnClientHandle</a></div><div class="ttdeci">struct CC_MqttsnClient * CC_MqttsnClientHandle</div><div class="ttdoc">Handler used to access client specific data structures.</div><div class="ttdef"><b>Definition:</b> common.h:144</div></div>
<div class="ttc" id="agroup__client_html_gaf652749014fcbe9a4fd26a60c875947a"><div class="ttname"><a href="group__client.html#gaf652749014fcbe9a4fd26a60c875947a">cc_mqttsn_client_alloc</a></div><div class="ttdeci">CC_MqttsnClientHandle cc_mqttsn_client_alloc()</div><div class="ttdoc">Allocate new client.</div></div>
</div><!-- fragment --><p> All other functions are client specific, they receive the returned handle as their first parameter.</p>
<p>When work with allocated client is complete, it must be freed using <b><a class="el" href="group__client.html#gac2704529f901991b0b14ef363d45f3e3" title="Free previously allocated client.">cc_mqttsn_client_free()</a></b> function. </p><div class="fragment"><div class="line"><a class="code" href="group__client.html#gac2704529f901991b0b14ef363d45f3e3">cc_mqttsn_client_free</a>(client);</div>
<div class="ttc" id="agroup__client_html_gac2704529f901991b0b14ef363d45f3e3"><div class="ttname"><a href="group__client.html#gac2704529f901991b0b14ef363d45f3e3">cc_mqttsn_client_free</a></div><div class="ttdeci">void cc_mqttsn_client_free(CC_MqttsnClientHandle client)</div><div class="ttdoc">Free previously allocated client.</div></div>
</div><!-- fragment --><p>When working with C++ it is advised to use a smart pointer with a custom deleter. </p><div class="fragment"><div class="line"><span class="keyword">struct </span>MyDeleter</div>
<div class="line">{</div>
<div class="line"> <span class="keywordtype">void</span> operator()(CC_MqttsnClient* ptr)</div>
<div class="line"> {</div>
<div class="line"> <a class="code" href="group__client.html#gac2704529f901991b0b14ef363d45f3e3">::cc_mqttsn_client_free</a>(ptr);</div>
<div class="line"> }</div>
<div class="line">};</div>
<div class="line"> </div>
<div class="line"><span class="keyword">using</span> MyClientPtr = std::unique_ptr<CC_MqttsnClient, MyDeleter>;</div>
<div class="line"> </div>
<div class="line">MyClientPtr clientPtr(::<a class="code" href="group__client.html#gaf652749014fcbe9a4fd26a60c875947a">cc_mqttsn_client_alloc</a>());</div>
<div class="line"><a class="code" href="group__client.html#gac0001ebe73d8670a38077f4206228ab1">CC_MqttsnClientHandle</a> client = clientPtr.get();</div>
</div><!-- fragment --><p><b>IMPORTANT:</b> The function <b><a class="el" href="group__client.html#gac2704529f901991b0b14ef363d45f3e3" title="Free previously allocated client.">cc_mqttsn_client_free()</a></b> must <b>NOT</b> be called from within a callback. Use next event loop iteration.</p>
<h1><a class="anchor" id="doc_cc_mqttsn_client_callbacks"></a>
"Must Have" Callbacks Registration</h1>
<p>In order to properly function the library requires setting several callbacks.</p>
<h2><a class="anchor" id="doc_cc_mqttsn_client_callbacks_send_data"></a>
Sending Data To Gateway</h2>
<p>To client application must assign a callback for the library to be able to send binary data out to the connected gateway. </p><div class="fragment"><div class="line"><span class="keywordtype">void</span> my_send_data_cb(<span class="keywordtype">void</span>* data, <span class="keyword">const</span> <span class="keywordtype">unsigned</span> <span class="keywordtype">char</span>* buf, <span class="keywordtype">unsigned</span> bufLen, <span class="keywordtype">unsigned</span> broadcastRadius)</div>
<div class="line">{</div>
<div class="line"> <span class="keywordflow">if</span> (broadcastRadius > 0) {</div>
<div class="line"> ... <span class="comment">// broadcast the message data</span></div>
<div class="line"> }</div>
<div class="line"> <span class="keywordflow">else</span> {</div>
<div class="line"> ... <span class="comment">// unicast the message data to a known gateway address</span></div>
<div class="line"> }</div>
<div class="line">}</div>
<div class="line"> </div>
<div class="line"><a class="code" href="group__client.html#ga160cb0356a15a1afd54c4c18e7002039">cc_mqttsn_client_set_send_output_data_callback</a>(client, &my_send_data_cb, data);</div>
<div class="ttc" id="agroup__client_html_ga160cb0356a15a1afd54c4c18e7002039"><div class="ttname"><a href="group__client.html#ga160cb0356a15a1afd54c4c18e7002039">cc_mqttsn_client_set_send_output_data_callback</a></div><div class="ttdeci">void cc_mqttsn_client_set_send_output_data_callback(CC_MqttsnClientHandle client, CC_MqttsnSendOutputDataCb cb, void *data)</div><div class="ttdoc">Set callback to send raw data over I/O link.</div></div>
</div><!-- fragment --><p> See also the documentation of the <a class="el" href="group__client.html#gaa370e3d3734f804f2d025f8067166909">CC_MqttsnSendOutputDataCb</a> callback function definition.</p>
<p>In the invoked callback the application is responsible to send the provided data over the I/O link. The application can also perform extra data manipulation like encryption.</p>
<p>The reported data resides in internal data structures of the client library, which can be updated / deleted right after the callback function returns. It means the data may need to be copied into some other buffer, which will be held intact until the send over I/O link operation is complete.</p>
<h2><a class="anchor" id="doc_cc_mqttsn_client_callbacks_gateway_disconnect"></a>
Reporting Unsolicited Gateway Disconnection</h2>
<p>The client application must assign a callback for the library to report discovered gateway disconnection. </p><div class="fragment"><div class="line"><span class="keywordtype">void</span> my_gateway_disconnected_cb(<span class="keywordtype">void</span>* data, <a class="code" href="group__global.html#ga81e18fb1f210d2ba0af8d23051c76835">CC_MqttsnGatewayDisconnectReason</a> reason)</div>
<div class="line">{</div>
<div class="line"> ... <span class="comment">/* handle gatewau disconnection */</span></div>
<div class="line">}</div>
<div class="line"> </div>
<div class="line"><a class="code" href="group__client.html#ga352965e77ad4fda6698b43b7ae6e4457">cc_mqttsn_client_set_gw_disconnect_report_callback</a>(client, &my_gateway_disconnected_cb, data);</div>
<div class="ttc" id="agroup__client_html_ga352965e77ad4fda6698b43b7ae6e4457"><div class="ttname"><a href="group__client.html#ga352965e77ad4fda6698b43b7ae6e4457">cc_mqttsn_client_set_gw_disconnect_report_callback</a></div><div class="ttdeci">void cc_mqttsn_client_set_gw_disconnect_report_callback(CC_MqttsnClientHandle client, CC_MqttsnGwDisconnectedReportCb cb, void *data)</div><div class="ttdoc">Set callback to report unsolicited disconnection of the gateway.</div></div>
<div class="ttc" id="agroup__global_html_ga81e18fb1f210d2ba0af8d23051c76835"><div class="ttname"><a href="group__global.html#ga81e18fb1f210d2ba0af8d23051c76835">CC_MqttsnGatewayDisconnectReason</a></div><div class="ttdeci">CC_MqttsnGatewayDisconnectReason</div><div class="ttdoc">Reason for reporting unsolicited gateway disconnection.</div><div class="ttdef"><b>Definition:</b> common.h:101</div></div>
</div><!-- fragment --><p> See also the documentation of the <a class="el" href="group__client.html#ga876378a44d1f41b8d4f3f019aeb65f9b">CC_MqttsnGwDisconnectedReportCb</a> callback function definition.</p>
<p>See also <a class="el" href="index.html#doc_cc_mqttsn_client_unsolicited_disconnect">Unsolicited Gateway Disconnection</a> below for details.</p>
<h2><a class="anchor" id="doc_cc_mqttsn_client_callbacks_message"></a>
Reporting Received Message</h2>
<p>The client application must assign a callback for the library to report application level messages received from the gateway. </p><div class="fragment"><div class="line"><span class="keywordtype">void</span> my_message_received_cb(<span class="keywordtype">void</span>* data, <span class="keyword">const</span> <a class="code" href="structCC__MqttsnMessageInfo.html">CC_MqttsnMessageInfo</a>* info)</div>
<div class="line">{</div>
<div class="line"> ... <span class="comment">/* handle the received message */</span></div>
<div class="line">}</div>
<div class="line"> </div>
<div class="line"><a class="code" href="group__client.html#gaef6207129578b99d4890a25b4e77932c">cc_mqttsn_client_set_message_report_callback</a>(client, &my_message_received_cb, data);</div>
<div class="ttc" id="agroup__client_html_gaef6207129578b99d4890a25b4e77932c"><div class="ttname"><a href="group__client.html#gaef6207129578b99d4890a25b4e77932c">cc_mqttsn_client_set_message_report_callback</a></div><div class="ttdeci">void cc_mqttsn_client_set_message_report_callback(CC_MqttsnClientHandle client, CC_MqttsnMessageReportCb cb, void *data)</div><div class="ttdoc">Set callback to report incoming messages.</div></div>
<div class="ttc" id="astructCC__MqttsnMessageInfo_html"><div class="ttname"><a href="structCC__MqttsnMessageInfo.html">CC_MqttsnMessageInfo</a></div><div class="ttdoc">Incoming message information.</div><div class="ttdef"><b>Definition:</b> common.h:225</div></div>
</div><!-- fragment --><p> See also the documentation of the <a class="el" href="group__client.html#ga75e88d1eb39e68b63724ecb7441d5254">CC_MqttsnMessageReportCb</a> callback function definition.</p>
<h1><a class="anchor" id="doc_cc_mqttsn_client_time"></a>
Time Measurement</h1>
<p>For the correct operation of the MQTT-SN client side of the protocol, the library requires an ability to measure time. This responsibility is delegated to the application.</p>
<p>The easiest (although not very efficient or very precise) method is to periodically (say every 20ms - 50ms) call the <b><a class="el" href="group__client.html#ga6108ef600fa00cc79e269b13035d6c6c" title="Notify client about requested time expiry.">cc_mqttsn_client_tick()</a></b> function reporting the amount of elapsed milliseconds: </p><div class="fragment"><div class="line"><a class="code" href="group__client.html#ga6108ef600fa00cc79e269b13035d6c6c">cc_mqttsn_client_tick</a>(client, 50U);</div>
<div class="ttc" id="agroup__client_html_ga6108ef600fa00cc79e269b13035d6c6c"><div class="ttname"><a href="group__client.html#ga6108ef600fa00cc79e269b13035d6c6c">cc_mqttsn_client_tick</a></div><div class="ttdeci">void cc_mqttsn_client_tick(CC_MqttsnClientHandle client, unsigned ms)</div><div class="ttdoc">Notify client about requested time expiry.</div></div>
</div><!-- fragment --><p> The library will check if some inner timer has expired and may initiate some response via invocation one of the registered callbacks.</p>
<p>Another (recommended) method is to register a callback so the library may request the time measurement from the application, and when the requested time expires, the application is expected to call the <b><a class="el" href="group__client.html#ga6108ef600fa00cc79e269b13035d6c6c" title="Notify client about requested time expiry.">cc_mqttsn_client_tick()</a></b> function reporting amount of elapsed milliseconds. </p><div class="fragment"><div class="line"><span class="keywordtype">void</span> my_tick_program_cb(<span class="keywordtype">void</span>* data, <span class="keywordtype">unsigned</span> ms)</div>
<div class="line">{</div>
<div class="line"> ... <span class="comment">// program appropriate timer</span></div>
<div class="line">}</div>
<div class="line"> </div>
<div class="line"><a class="code" href="group__client.html#gacb5e689f4fe7da7e216a7af0fff708d4">cc_mqttsn_client_set_next_tick_program_callback</a>(client, &my_tick_program_cb, data);</div>
<div class="ttc" id="agroup__client_html_gacb5e689f4fe7da7e216a7af0fff708d4"><div class="ttname"><a href="group__client.html#gacb5e689f4fe7da7e216a7af0fff708d4">cc_mqttsn_client_set_next_tick_program_callback</a></div><div class="ttdeci">void cc_mqttsn_client_set_next_tick_program_callback(CC_MqttsnClientHandle client, CC_MqttsnNextTickProgramCb cb, void *data)</div><div class="ttdoc">Set callback to call when time measurement is required.</div></div>
</div><!-- fragment --><p> It is allowed to invoke the <b><a class="el" href="group__client.html#ga6108ef600fa00cc79e269b13035d6c6c" title="Notify client about requested time expiry.">cc_mqttsn_client_tick()</a></b> before the actual requested timeout has expired, just make sure that the correct amount of elapsed milliseconds is reported. When the <b><a class="el" href="group__client.html#ga6108ef600fa00cc79e269b13035d6c6c" title="Notify client about requested time expiry.">cc_mqttsn_client_tick()</a></b> is invoked, it is assumed that the previously requested tick programming has been cancelled and the registered callback requesting to re-program the timer may be invoked again from within the <b><a class="el" href="group__client.html#ga6108ef600fa00cc79e269b13035d6c6c" title="Notify client about requested time expiry.">cc_mqttsn_client_tick()</a></b>.</p>
<p>See also the documentation of the <a class="el" href="group__client.html#ga8b45621ac2da99fbff143a403cd1bf51">CC_MqttsnNextTickProgramCb</a> callback function definition.</p>
<p>In case of callback approach for time measurement is chosen, another callback function (in addition to requesting the new timer programming) to allow interruption of the previously programmed timer must also to be registered. </p><div class="fragment"><div class="line"><span class="keywordtype">unsigned</span> my_cancel_tick_program_cb(<span class="keywordtype">void</span>* data)</div>
<div class="line">{</div>
<div class="line"> ...</div>
<div class="line"> <span class="keywordflow">return</span> ... <span class="comment">// return amount of elapsed milliseconds since last tick program</span></div>
<div class="line">}</div>
<div class="line"> </div>
<div class="line"><a class="code" href="group__client.html#gae0c0a200ca917e08623ea855a8c9a36b">cc_mqttsn_client_set_cancel_next_tick_wait_callback</a>(client, &my_cancel_tick_program_cb, data);</div>
<div class="ttc" id="agroup__client_html_gae0c0a200ca917e08623ea855a8c9a36b"><div class="ttname"><a href="group__client.html#gae0c0a200ca917e08623ea855a8c9a36b">cc_mqttsn_client_set_cancel_next_tick_wait_callback</a></div><div class="ttdeci">void cc_mqttsn_client_set_cancel_next_tick_wait_callback(CC_MqttsnClientHandle client, CC_MqttsnCancelNextTickWaitCb cb, void *data)</div><div class="ttdoc">Set callback to terminate current time measurement.</div></div>
</div><!-- fragment --><p> See also the documentation of the <a class="el" href="group__client.html#gac9b867aa622afafdd4dd3d9579145a14">CC_MqttsnCancelNextTickWaitCb</a> callback function definition.</p>
<p>Usually the callbacks of canceling the previously programmed tick and programming a new one will be invoked as a side effect of other events, like report of the incoming data or client requesting to perform one of the available operations.</p>
<h1><a class="anchor" id="doc_cc_mqttsn_client_log"></a>
Error Logging</h1>
<p>Sometimes the library may exhibit unexpected behaviour, like rejecting some of the parameters. To allow getting extra guidance information of what went wrong it is possible to register optional error logging callback. </p><div class="fragment"><div class="line"><span class="keywordtype">void</span> my_error_log_cb(<span class="keywordtype">void</span>* data, <span class="keyword">const</span> <span class="keywordtype">char</span>* msg)</div>
<div class="line">{</div>
<div class="line"> printf(<span class="stringliteral">"ERROR: %s\n"</span>, msg);</div>
<div class="line">}</div>
<div class="line"> </div>
<div class="line"><a class="code" href="group__client.html#gaf9aed825fea81da9d72de8a37166783e">cc_mqttsn_client_set_error_log_callback</a>(client, &my_error_log_cb, data);</div>
<div class="ttc" id="agroup__client_html_gaf9aed825fea81da9d72de8a37166783e"><div class="ttname"><a href="group__client.html#gaf9aed825fea81da9d72de8a37166783e">cc_mqttsn_client_set_error_log_callback</a></div><div class="ttdeci">void cc_mqttsn_client_set_error_log_callback(CC_MqttsnClientHandle client, CC_MqttsnErrorLogCb cb, void *data)</div><div class="ttdoc">Set callback to report error messages.</div></div>
</div><!-- fragment --><p> See also the documentation of the <a class="el" href="group__client.html#gace21abbdb49c64945708d5dc176cc212">CC_MqttsnErrorLogCb</a> callback function definition.</p>
<h1><a class="anchor" id="doc_cc_mqttsn_client_data"></a>
Reporting Incoming Data</h1>
<p>It is the responsibility of the application to receive data from the other nodes on the network and report it to the library. The report is performed using the <b><a class="el" href="group__client.html#ga1ebe2c929a061a0c15e3157c3c276e8c" title="Provide data, received over I/O link, to the library for processing.">cc_mqttsn_client_process_data()</a></b> function. </p><div class="fragment"><div class="line">uint8_t buf[MAX_BUF_SIZE];</div>
<div class="line">... <span class="comment">// Receive data into buffer</span></div>
<div class="line"><span class="keywordtype">unsigned</span> bufLen = ...; <span class="comment">// Amount of received bytes in the buffer.</span></div>
<div class="line"><a class="code" href="group__global.html#gaed6d2565a631c653533fc041d00f0456">CC_MqttsnDataOrigin</a> origin = ...;</div>
<div class="line"><a class="code" href="group__client.html#ga1ebe2c929a061a0c15e3157c3c276e8c">cc_mqttsn_client_process_data</a>(client, buf, bufLen, origin);</div>
<div class="ttc" id="agroup__client_html_ga1ebe2c929a061a0c15e3157c3c276e8c"><div class="ttname"><a href="group__client.html#ga1ebe2c929a061a0c15e3157c3c276e8c">cc_mqttsn_client_process_data</a></div><div class="ttdeci">void cc_mqttsn_client_process_data(CC_MqttsnClientHandle client, const unsigned char *buf, unsigned bufLen, CC_MqttsnDataOrigin origin)</div><div class="ttdoc">Provide data, received over I/O link, to the library for processing.</div></div>
<div class="ttc" id="agroup__global_html_gaed6d2565a631c653533fc041d00f0456"><div class="ttname"><a href="group__global.html#gaed6d2565a631c653533fc041d00f0456">CC_MqttsnDataOrigin</a></div><div class="ttdeci">CC_MqttsnDataOrigin</div><div class="ttdoc">Data origin.</div><div class="ttdef"><b>Definition:</b> common.h:131</div></div>
</div><!-- fragment --><p> The application is responsible to maintain the input buffer. The MQTT-SN protocol assumes datagram packets, where each packets contains a valid single MQTT-SN message. The client library decodes and processes the message at the beginning of the reported buffer and discards any extra bytes that might follow.</p>
<p>The application is also responsible to allow input from multiple sources and determine the <a class="el" href="group__global.html#gaed6d2565a631c653533fc041d00f0456">origin</a> of the input data. It allows the library to differentiate between the messages from the legit gateway to which the application is connected and other nodes on the network.</p>
<p>When new data chunk is reported the library may invoke several callbacks, such as reporting received message, sending new data out, as well as canceling the old and programming new tick timeout.</p>
<h1><a class="anchor" id="doc_cc_mqttsn_client_concepts"></a>
Operating Concepts</h1>
<p>The library abstracts away multiple MQTT-SN protocol based "operations". Every such operation has multiple stages: </p><ul>
<li><b>prepare</b> - The operation is "allocated" and relevant handle is returned. </li>
<li><b>configure</b> - Apply one or multiple configurations to the prepared operation. </li>
<li><b>send</b> - Send the configured operation message to the gateway.</li>
</ul>
<p>During the <b>send</b> stage the application is expected to provide the callback to report to the application when the operation is complete. One of the parameters of the callback is always "status" of the <a class="el" href="group__global.html#gab0af1cb13f466184b8ecc4b1a86ec55f">CC_MqttsnAsyncOpStatus</a> type. It indicates whether the operation was successfully complete. In addition to the status it reports some extra information reported by the gateway. The information from the gateway is available <b>if and only if</b> the status is <a class="el" href="group__global.html#ggab0af1cb13f466184b8ecc4b1a86ec55fa8151e18fea364efd22acf9589fa3323c">CC_MqttsnAsyncOpStatus_Complete</a>.</p>
<p>The <b>send</b> stage function also returns <a class="el" href="group__global.html#gade7e7c53c5ca30c6134f60607b01079f">CC_MqttsnErrorCode</a> value to indicate whether the <b>send</b> was successfully performed. The provided callback will be invoked <b>if and only if</b> the <b>send</b> returns <a class="el" href="group__global.html#ggade7e7c53c5ca30c6134f60607b01079faa71957fe69fa1b94d1d0cbc3c7558e1f">CC_MqttsnErrorCode_Success</a>.</p>
<p>After the <b>send</b> stage the handle returned in the <b>prepare</b> stage can be discarded (no explicit de-allocation is needed / supported) regardless of the return code. After successful <b>send</b> the handle still remains valid until the callback invocation and can be used to <b>cancel</b> the operation. Note that in case the appropriate message has already be <b>sent</b> to the gateway, cancelling the outstanding operation can be dangerous. When gateway sends a response and client is not expecting it any more, unexpected behaviour may happen.</p>
<p>In case something went wrong during the <b>configure</b> stage, it is possible to de-allocate the prepared operation using the <b>cancel</b> request. After performing the <b>cancel</b> stage the allocated handle is no longer valid.</p>
<p><b>IMPORTANT LIBRARY LIMITATION</b>: Once an operation is <b>prepared</b>, it must be be immediately <b>configured</b> and <b>sent</b> (or <b>cancelled</b>) before any other other operation can be <b>prepared</b>. For example: </p><div class="fragment"><div class="line"><a class="code" href="group__global.html#gade7e7c53c5ca30c6134f60607b01079f">CC_MqttsnErrorCode</a> ec = <a class="code" href="group__global.html#ggade7e7c53c5ca30c6134f60607b01079faa71957fe69fa1b94d1d0cbc3c7558e1f">CC_MqttsnErrorCode_Success</a>;</div>
<div class="line"><a class="code" href="group__connect.html#ga2becb99684d975dd3c16a1234182ae54">CC_MqttsnConnectHandle</a> connect = <a class="code" href="group__search.html#gadadf9dd82526dab95e1878cd78a6dce3">cc_mqttsn_client_search_prepare</a>(...);</div>
<div class="line">assert(connect != NULL);</div>
<div class="line"> </div>
<div class="line"><span class="comment">// The following attempt to prepare the "subscribe" operation will fail because</span></div>
<div class="line"><span class="comment">// previously allocated "search" hasn't been sent or cancelled yet.</span></div>
<div class="line"><a class="code" href="group__subscribe.html#ga7671bb34c5f4d33f498404fbe3c533c7">CC_MqttsnSubscribeHandle</a> subscribe = <a class="code" href="group__subscribe.html#ga3091b015e0703efbbc6909ad15dca798">cc_mqttsn_client_subscribe_prepare</a>(...);</div>
<div class="line">assert(subscribe == NULL);</div>
<div class="ttc" id="agroup__connect_html_ga2becb99684d975dd3c16a1234182ae54"><div class="ttname"><a href="group__connect.html#ga2becb99684d975dd3c16a1234182ae54">CC_MqttsnConnectHandle</a></div><div class="ttdeci">struct CC_MqttsnConnect * CC_MqttsnConnectHandle</div><div class="ttdoc">Handle for "connect" operation.</div><div class="ttdef"><b>Definition:</b> common.h:162</div></div>
<div class="ttc" id="agroup__global_html_gade7e7c53c5ca30c6134f60607b01079f"><div class="ttname"><a href="group__global.html#gade7e7c53c5ca30c6134f60607b01079f">CC_MqttsnErrorCode</a></div><div class="ttdeci">CC_MqttsnErrorCode</div><div class="ttdoc">Error code returned by various API functions.</div><div class="ttdef"><b>Definition:</b> common.h:53</div></div>
<div class="ttc" id="agroup__global_html_ggade7e7c53c5ca30c6134f60607b01079faa71957fe69fa1b94d1d0cbc3c7558e1f"><div class="ttname"><a href="group__global.html#ggade7e7c53c5ca30c6134f60607b01079faa71957fe69fa1b94d1d0cbc3c7558e1f">CC_MqttsnErrorCode_Success</a></div><div class="ttdeci">@ CC_MqttsnErrorCode_Success</div><div class="ttdoc">The requested operation was successfully started.</div><div class="ttdef"><b>Definition:</b> common.h:54</div></div>
<div class="ttc" id="agroup__search_html_gadadf9dd82526dab95e1878cd78a6dce3"><div class="ttname"><a href="group__search.html#gadadf9dd82526dab95e1878cd78a6dce3">cc_mqttsn_client_search_prepare</a></div><div class="ttdeci">CC_MqttsnSearchHandle cc_mqttsn_client_search_prepare(CC_MqttsnClientHandle client, CC_MqttsnErrorCode *ec)</div><div class="ttdoc">Prepare "search" operation.</div></div>
<div class="ttc" id="agroup__subscribe_html_ga3091b015e0703efbbc6909ad15dca798"><div class="ttname"><a href="group__subscribe.html#ga3091b015e0703efbbc6909ad15dca798">cc_mqttsn_client_subscribe_prepare</a></div><div class="ttdeci">CC_MqttsnSubscribeHandle cc_mqttsn_client_subscribe_prepare(CC_MqttsnClientHandle client, CC_MqttsnErrorCode *ec)</div><div class="ttdoc">Prepare "subscribe" operation.</div></div>
<div class="ttc" id="agroup__subscribe_html_ga7671bb34c5f4d33f498404fbe3c533c7"><div class="ttname"><a href="group__subscribe.html#ga7671bb34c5f4d33f498404fbe3c533c7">CC_MqttsnSubscribeHandle</a></div><div class="ttdeci">struct CC_MqttsnSubscribe * CC_MqttsnSubscribeHandle</div><div class="ttdoc">Handle for "subscribe" operation.</div><div class="ttdef"><b>Definition:</b> common.h:180</div></div>
</div><!-- fragment --><h1><a class="anchor" id="doc_cc_mqttsn_client_retry_period"></a>
Default Retry Period</h1>
<p>After sending any operation request to the gateway, the client library has to allow some time for the gateway to process the request (<b>T<sub>retry</sub></b> from the spec). If it takes too much time, the client must retry it several times (see <a class="el" href="index.html#doc_cc_mqttsn_client_retry_count">Default Retry Count</a>) and report that operation has failed via the set callback in case there is no response. By default the client library allows <b>10</b> seconds for such response to arrive. Changing this default value is possible using the <b><a class="el" href="group__client.html#ga5a4092f4849987a83aeeaa94f543a946" title="Set retry period to wait between resending unacknowledged message to the gateway (Tretry from spec).">cc_mqttsn_client_set_default_retry_period()</a></b> function, and retrieving of the currently configured value can be done using the <b><a class="el" href="group__client.html#ga48445d62037357a5860147a08e79093f" title="Set configured retry period to wait between resending unacknowledged message to the gateway (Tretry f...">cc_mqttsn_client_get_default_retry_period()</a></b> function. </p><div class="fragment"><div class="line"><a class="code" href="group__global.html#gade7e7c53c5ca30c6134f60607b01079f">CC_MqttsnErrorCode</a> ec = <a class="code" href="group__client.html#ga5a4092f4849987a83aeeaa94f543a946">cc_mqttsn_client_set_default_retry_period</a>(client, 15000 <span class="comment">/* in ms */</span>);</div>
<div class="line"><span class="keywordflow">if</span> (ec != <a class="code" href="group__global.html#ggade7e7c53c5ca30c6134f60607b01079faa71957fe69fa1b94d1d0cbc3c7558e1f">CC_MqttsnErrorCode_Success</a>) {</div>
<div class="line"> ... <span class="comment">/* Something went wrong */</span></div>
<div class="line">}</div>
<div class="ttc" id="agroup__client_html_ga5a4092f4849987a83aeeaa94f543a946"><div class="ttname"><a href="group__client.html#ga5a4092f4849987a83aeeaa94f543a946">cc_mqttsn_client_set_default_retry_period</a></div><div class="ttdeci">CC_MqttsnErrorCode cc_mqttsn_client_set_default_retry_period(CC_MqttsnClientHandle client, unsigned value)</div><div class="ttdoc">Set retry period to wait between resending unacknowledged message to the gateway (Tretry from spec).</div></div>
</div><!-- fragment --><h1><a class="anchor" id="doc_cc_mqttsn_client_retry_count"></a>
Default Retry Count</h1>
<p>As was mentioned in the <a class="el" href="index.html#doc_cc_mqttsn_client_retry_period">Default Retry Period</a> section above the client library retries to send unacknowledged messaged several times before giving up (<b>N<sub>retry</sub></b> from the spec). By default the client library allows <b>3</b> times to re-send the message. Changing this default value is possible using the <b><a class="el" href="group__client.html#ga3094189071d8f4dd60492fee40abe8aa" title="Set number of retry attempts to perform before reporting unsuccessful result of the operation (Nretry...">cc_mqttsn_client_set_default_retry_count()</a></b> function, and retrieving of the currently configured value can be done using the <b><a class="el" href="group__client.html#gaf3d621c69e506bafd09e2b8389f586ab" title="Get configured number of retry attempts to perform before reporting unsuccessful result of the operat...">cc_mqttsn_client_get_default_retry_count()</a></b> function. </p><div class="fragment"><div class="line"><a class="code" href="group__global.html#gade7e7c53c5ca30c6134f60607b01079f">CC_MqttsnErrorCode</a> ec = <a class="code" href="group__client.html#ga3094189071d8f4dd60492fee40abe8aa">cc_mqttsn_client_set_default_retry_count</a>(client, 5);</div>
<div class="line"><span class="keywordflow">if</span> (ec != <a class="code" href="group__global.html#ggade7e7c53c5ca30c6134f60607b01079faa71957fe69fa1b94d1d0cbc3c7558e1f">CC_MqttsnErrorCode_Success</a>) {</div>
<div class="line"> ... <span class="comment">/* Something went wrong */</span></div>
<div class="line">}</div>
<div class="ttc" id="agroup__client_html_ga3094189071d8f4dd60492fee40abe8aa"><div class="ttname"><a href="group__client.html#ga3094189071d8f4dd60492fee40abe8aa">cc_mqttsn_client_set_default_retry_count</a></div><div class="ttdeci">CC_MqttsnErrorCode cc_mqttsn_client_set_default_retry_count(CC_MqttsnClientHandle client, unsigned value)</div><div class="ttdoc">Set number of retry attempts to perform before reporting unsuccessful result of the operation (Nretry...</div></div>
</div><!-- fragment --><p> Note that the function specify number of <b>retries</b>, i.e. when number of retries is <b>1</b> the relevant message will be sent twice before reporting failure (in case there is no response of course): once when the send is explicitly requested and the second time is an actual retry. Following the same logic, when the configured number of retries is <b>0</b>, the message will be send only once (when the request is issued) and will not try to re-send it when the response is not received in time.</p>
<h1><a class="anchor" id="doc_cc_mqttsn_client_broadcast_radius"></a>
Default Broadcast Radius</h1>
<p>The MQTT-SN protocol defines several messages that are broadcasted. When requesting to broadcast the message, the client library also specifies the broadcast radius. The default broadcast radius value is <b>3</b>. To change the default configuration value use <b><a class="el" href="group__client.html#gafa80d845b1647710dc74998f04316a48" title="Set broadcast radius.">cc_mqttsn_client_set_default_broadcast_radius()</a></b> function. To retrieve the current configuration use <b><a class="el" href="group__client.html#ga99d986094bb9da20614f495b228fb718" title="Get current broadcast radius configuration.">cc_mqttsn_client_get_default_broadcast_radius()</a></b>. </p><div class="fragment"><div class="line"><a class="code" href="group__global.html#gade7e7c53c5ca30c6134f60607b01079f">CC_MqttsnErrorCode</a> ec = <a class="code" href="group__client.html#gafa80d845b1647710dc74998f04316a48">cc_mqttsn_client_set_default_broadcast_radius</a>(client, 5);</div>
<div class="line"><span class="keywordflow">if</span> (ec != <a class="code" href="group__global.html#ggade7e7c53c5ca30c6134f60607b01079faa71957fe69fa1b94d1d0cbc3c7558e1f">CC_MqttsnErrorCode_Success</a>) {</div>
<div class="line"> ... <span class="comment">/* Something went wrong */</span></div>
<div class="line">}</div>
<div class="ttc" id="agroup__client_html_gafa80d845b1647710dc74998f04316a48"><div class="ttname"><a href="group__client.html#gafa80d845b1647710dc74998f04316a48">cc_mqttsn_client_set_default_broadcast_radius</a></div><div class="ttdeci">CC_MqttsnErrorCode cc_mqttsn_client_set_default_broadcast_radius(CC_MqttsnClientHandle client, unsigned value)</div><div class="ttdoc">Set broadcast radius.</div></div>
</div><!-- fragment --><h1><a class="anchor" id="doc_cc_mqttsn_client_gateway_discovery"></a>
Gateway Discovery</h1>
<p>The MQTT-SN protocol supports having multiple gateway on the same network and their discovery. When the application <a class="el" href="index.html#doc_cc_mqttsn_client_allocation">allocates</a> the client object, it can either connect directly to the gateway (if such is known) or initiate gateway discovery by using <a class="el" href="group__search.html">search</a> operation. The MQTT-SN specification recommends to wait some time (up to <b>T<sub>searchgw</sub></b>) to prevent sending broadcast storm of the <b>SEARCHGW</b> messages when all clients start at once. It is up to the application to decide whether and when to issue the <a class="el" href="group__search.html">search</a> operation.</p>
<h2><a class="anchor" id="doc_cc_mqttsn_client_search_prepare"></a>
Preparing "Search" Operation.</h2>
<div class="fragment"><div class="line"><a class="code" href="group__global.html#gade7e7c53c5ca30c6134f60607b01079f">CC_MqttsnErrorCode</a> ec = <a class="code" href="group__global.html#ggade7e7c53c5ca30c6134f60607b01079faa71957fe69fa1b94d1d0cbc3c7558e1f">CC_MqttsnErrorCode_Success</a>;</div>
<div class="line"><a class="code" href="group__search.html#gaa79c418e536d423f55dba3da2f9db062">CC_MqttsnSearchHandle</a> search = <a class="code" href="group__search.html#gadadf9dd82526dab95e1878cd78a6dce3">cc_mqttsn_client_search_prepare</a>(client, &ec);</div>
<div class="line"><span class="keywordflow">if</span> (search == NULL) {</div>
<div class="line"> printf(<span class="stringliteral">"ERROR: Search allocation failed with ec=%d\n"</span>, ec);</div>
<div class="line">}</div>
<div class="ttc" id="agroup__search_html_gaa79c418e536d423f55dba3da2f9db062"><div class="ttname"><a href="group__search.html#gaa79c418e536d423f55dba3da2f9db062">CC_MqttsnSearchHandle</a></div><div class="ttdeci">struct CC_MqttsnSearch * CC_MqttsnSearchHandle</div><div class="ttdoc">Handle for "search" operation.</div><div class="ttdef"><b>Definition:</b> common.h:153</div></div>
</div><!-- fragment --><h2><a class="anchor" id="doc_cc_mqttsn_client_search_retry_period"></a>
Configuring "Search" Retry Period</h2>
<p>When created, the "search" operation inherits the <a class="el" href="index.html#doc_cc_mqttsn_client_retry_period">Default Retry Period</a> configuration. It can be changed for the allocated operation using the <b><a class="el" href="group__search.html#ga6bd73974bf028cd72b9eb73f5219a93e" title="Configure the retry period for the "search" operation.">cc_mqttsn_client_search_set_retry_period()</a></b> function. </p><div class="fragment"><div class="line">ec = <a class="code" href="group__search.html#ga6bd73974bf028cd72b9eb73f5219a93e">cc_mqttsn_client_search_set_retry_period</a>(search, 15000);</div>
<div class="line"><span class="keywordflow">if</span> (ec != <a class="code" href="group__global.html#ggade7e7c53c5ca30c6134f60607b01079faa71957fe69fa1b94d1d0cbc3c7558e1f">CC_MqttsnErrorCode_Success</a>) {</div>
<div class="line"> ... <span class="comment">/* Something went wrong */</span></div>
<div class="line">}</div>
<div class="ttc" id="agroup__search_html_ga6bd73974bf028cd72b9eb73f5219a93e"><div class="ttname"><a href="group__search.html#ga6bd73974bf028cd72b9eb73f5219a93e">cc_mqttsn_client_search_set_retry_period</a></div><div class="ttdeci">CC_MqttsnErrorCode cc_mqttsn_client_search_set_retry_period(CC_MqttsnSearchHandle handle, unsigned ms)</div><div class="ttdoc">Configure the retry period for the "search" operation.</div></div>
</div><!-- fragment --><p> To retrieve the configured retry period use the <b><a class="el" href="group__search.html#gad9259ab33f592ad1baeff96e13d406dc" title="Retrieve the configured retry period for the "search" operation.">cc_mqttsn_client_search_get_retry_period()</a></b> function.</p>
<h2><a class="anchor" id="doc_cc_mqttsn_client_search_retry_count"></a>
Configuring "Search" Retry Count</h2>
<p>When created, the "search" operation inherits the <a class="el" href="index.html#doc_cc_mqttsn_client_retry_count">Default Retry Count</a> configuration. It can be changed for the allocated operation using the <b><a class="el" href="group__search.html#ga39e659006c5a9be96f4b3be6eb20d5b9" title="Configure the retry count for the "search" operation.">cc_mqttsn_client_search_set_retry_count()</a></b> function. </p><div class="fragment"><div class="line">ec = <a class="code" href="group__search.html#ga39e659006c5a9be96f4b3be6eb20d5b9">cc_mqttsn_client_search_set_retry_count</a>(search, 5);</div>
<div class="line"><span class="keywordflow">if</span> (ec != <a class="code" href="group__global.html#ggade7e7c53c5ca30c6134f60607b01079faa71957fe69fa1b94d1d0cbc3c7558e1f">CC_MqttsnErrorCode_Success</a>) {</div>
<div class="line"> ... <span class="comment">/* Something went wrong */</span></div>
<div class="line">}</div>
<div class="ttc" id="agroup__search_html_ga39e659006c5a9be96f4b3be6eb20d5b9"><div class="ttname"><a href="group__search.html#ga39e659006c5a9be96f4b3be6eb20d5b9">cc_mqttsn_client_search_set_retry_count</a></div><div class="ttdeci">CC_MqttsnErrorCode cc_mqttsn_client_search_set_retry_count(CC_MqttsnSearchHandle handle, unsigned count)</div><div class="ttdoc">Configure the retry count for the "search" operation.</div></div>
</div><!-- fragment --><p> To retrieve the configured retry count use the <b><a class="el" href="group__search.html#ga47c60bcaad46f510bd707528a1fd5810" title="Retrieve the configured retry count for the "search" operation.">cc_mqttsn_client_search_get_retry_count()</a></b> function.</p>
<h2><a class="anchor" id="doc_cc_mqttsn_client_search_broadcast_radius"></a>
Configuring "Search" Broadcast Radius</h2>
<p>The "search" operation is expected to broadcast the <b>SEARCHGW</b> message. When created, the "search" operation inherits the <a class="el" href="index.html#doc_cc_mqttsn_client_broadcast_radius">Default Broadcast Radius</a> configuration. It can be changed for the allocated operation using the <b><a class="el" href="group__search.html#ga19be4e9eafcc9431a7dad198b8e3fa52" title="Configure the broadcast radius for the "search" operation.">cc_mqttsn_client_search_set_broadcast_radius()</a></b> function. </p><div class="fragment"><div class="line">ec = <a class="code" href="group__search.html#ga19be4e9eafcc9431a7dad198b8e3fa52">cc_mqttsn_client_search_set_broadcast_radius</a>(search, 5);</div>
<div class="line"><span class="keywordflow">if</span> (ec != <a class="code" href="group__global.html#ggade7e7c53c5ca30c6134f60607b01079faa71957fe69fa1b94d1d0cbc3c7558e1f">CC_MqttsnErrorCode_Success</a>) {</div>
<div class="line"> ... <span class="comment">/* Something went wrong */</span></div>
<div class="line">}</div>
<div class="ttc" id="agroup__search_html_ga19be4e9eafcc9431a7dad198b8e3fa52"><div class="ttname"><a href="group__search.html#ga19be4e9eafcc9431a7dad198b8e3fa52">cc_mqttsn_client_search_set_broadcast_radius</a></div><div class="ttdeci">CC_MqttsnErrorCode cc_mqttsn_client_search_set_broadcast_radius(CC_MqttsnSearchHandle handle, unsigned broadcastRadius)</div><div class="ttdoc">Configure the broadcast radius for the "search" operation.</div></div>
</div><!-- fragment --><p> To retrieve the configured retry count use the <b><a class="el" href="group__search.html#gad81295700722a2a4befc6b729815be91" title="Retrieve the configured broadcast radius for the "search" operation.">cc_mqttsn_client_search_get_broadcast_radius()</a></b> function.</p>
<h2><a class="anchor" id="doc_cc_mqttsn_client_search_send"></a>
Sending Search Gateway Request</h2>
<p>When all the necessary configurations are performed for the allocated "search" operation it can actually be sent on the network. To initiate sending use the <b><a class="el" href="group__search.html#ga69a2454162a8168ac236babfd0ac2806" title="Send the "search" operation.">cc_mqttsn_client_search_send()</a></b> function. </p><div class="fragment"><div class="line"><span class="keywordtype">void</span> my_search_complete_cb(<span class="keywordtype">void</span>* data, <a class="code" href="group__global.html#gab0af1cb13f466184b8ecc4b1a86ec55f">CC_MqttsnAsyncOpStatus</a> status, <span class="keyword">const</span> <a class="code" href="structCC__MqttsnGatewayInfo.html">CC_MqttsnGatewayInfo</a>* info)</div>
<div class="line">{</div>
<div class="line"> <span class="keywordflow">if</span> (status != <a class="code" href="group__global.html#ggab0af1cb13f466184b8ecc4b1a86ec55fa8151e18fea364efd22acf9589fa3323c">CC_MqttsnAsyncOpStatus_Complete</a>) {</div>
<div class="line"> printf(<span class="stringliteral">"ERROR: The search operation has failed with status=%d\n"</span>, status);</div>
<div class="line"> ... <span class="comment">// handle error.</span></div>
<div class="line"> <span class="keywordflow">return</span>;</div>
<div class="line"> }</div>
<div class="line"> </div>
<div class="line"> <span class="comment">// "info" is not NULL when status is CC_MqttsnAsyncOpStatus_Complete.</span></div>
<div class="line"> assert(info != NULL);</div>
<div class="line"> ... <span class="comment">// Analyze found gateway information.</span></div>
<div class="line">}</div>
<div class="line"> </div>
<div class="line">ec = <a class="code" href="group__search.html#ga69a2454162a8168ac236babfd0ac2806">cc_mqttsn_client_search_send</a>(search, &my_search_complete_cb, data);</div>
<div class="line"><span class="keywordflow">if</span> (ec != <a class="code" href="group__global.html#ggade7e7c53c5ca30c6134f60607b01079faa71957fe69fa1b94d1d0cbc3c7558e1f">CC_MqttsnErrorCode_Success</a>) {</div>
<div class="line"> printf(<span class="stringliteral">"ERROR: Failed to send search request with ec=%d\n"</span>, ec);</div>
<div class="line"> ...</div>
<div class="line">}</div>
<div class="ttc" id="agroup__global_html_gab0af1cb13f466184b8ecc4b1a86ec55f"><div class="ttname"><a href="group__global.html#gab0af1cb13f466184b8ecc4b1a86ec55f">CC_MqttsnAsyncOpStatus</a></div><div class="ttdeci">CC_MqttsnAsyncOpStatus</div><div class="ttdoc">Status of the asynchronous operation.</div><div class="ttdef"><b>Definition:</b> common.h:87</div></div>
<div class="ttc" id="agroup__global_html_ggab0af1cb13f466184b8ecc4b1a86ec55fa8151e18fea364efd22acf9589fa3323c"><div class="ttname"><a href="group__global.html#ggab0af1cb13f466184b8ecc4b1a86ec55fa8151e18fea364efd22acf9589fa3323c">CC_MqttsnAsyncOpStatus_Complete</a></div><div class="ttdeci">@ CC_MqttsnAsyncOpStatus_Complete</div><div class="ttdoc">The requested operation has been completed, refer to reported extra details for information.</div><div class="ttdef"><b>Definition:</b> common.h:88</div></div>
<div class="ttc" id="agroup__search_html_ga69a2454162a8168ac236babfd0ac2806"><div class="ttname"><a href="group__search.html#ga69a2454162a8168ac236babfd0ac2806">cc_mqttsn_client_search_send</a></div><div class="ttdeci">CC_MqttsnErrorCode cc_mqttsn_client_search_send(CC_MqttsnSearchHandle handle, CC_MqttsnSearchCompleteCb cb, void *cbData)</div><div class="ttdoc">Send the "search" operation.</div></div>
<div class="ttc" id="astructCC__MqttsnGatewayInfo_html"><div class="ttname"><a href="structCC__MqttsnGatewayInfo.html">CC_MqttsnGatewayInfo</a></div><div class="ttdoc">Gateway information.</div><div class="ttdef"><b>Definition:</b> common.h:237</div></div>
</div><!-- fragment --><p> The provided callback will be invoked when the "search" operation is complete <b> if and only if</b> the function returns <a class="el" href="group__global.html#ggade7e7c53c5ca30c6134f60607b01079faa71957fe69fa1b94d1d0cbc3c7558e1f">CC_MqttsnErrorCode_Success</a>.</p>
<p>The handle returned by the <b><a class="el" href="group__search.html#gadadf9dd82526dab95e1878cd78a6dce3" title="Prepare "search" operation.">cc_mqttsn_client_search_prepare()</a></b> function can be discarded (there is no free / de-allocation) right after the <b><a class="el" href="group__search.html#ga69a2454162a8168ac236babfd0ac2806" title="Send the "search" operation.">cc_mqttsn_client_search_send()</a></b> invocation regardless of the returned error code. However, the handle remains valid until the callback is called (in case the <a class="el" href="group__global.html#ggade7e7c53c5ca30c6134f60607b01079faa71957fe69fa1b94d1d0cbc3c7558e1f">CC_MqttsnErrorCode_Success</a> was returned). The valid handle can be used to <a class="el" href="index.html#doc_cc_mqttsn_client_search_cancel">cancel</a> the operation before the completion callback is invoked.</p>
<p>When the "search" operation completion callback is invoked the reported "info" information is present <b>if and only if</b> the "status" is <a class="el" href="group__global.html#ggab0af1cb13f466184b8ecc4b1a86ec55fa8151e18fea364efd22acf9589fa3323c">CC_MqttsnAsyncOpStatus_Complete</a>.</p>
<p><b>NOTE</b> that only single "search" operation is allowed at a time, any attempt to prepare a new one via <b><a class="el" href="group__search.html#gadadf9dd82526dab95e1878cd78a6dce3" title="Prepare "search" operation.">cc_mqttsn_client_search_prepare()</a></b> will be rejected until the "search" operation completion callback is invoked or the operation is <a class="el" href="index.html#doc_cc_mqttsn_client_search_cancel">cancelled</a>.</p>
<p>The "search" operation is complete when the valid <b>GWINFO</b> message is received. Such message can be sent either by the gateway itself or by another client on behalf of the gateway. When they <b>GWINFO</b> message is sent by another client it specifies the actual address of the gateway (reported via the <a class="el" href="structCC__MqttsnGatewayInfo.html#aaf2ef4ae5c9b9e8f3886371dc7b68b64">CC_MqttsnGatewayInfo::m_addr</a> and <a class="el" href="structCC__MqttsnGatewayInfo.html#a96a441b1071e315d2a60731e8287aa0c">CC_MqttsnGatewayInfo::m_addrLen</a>). When the <b>GWINFO</b> message is sent by the gateway itself, the address information inside the reported <a class="el" href="structCC__MqttsnGatewayInfo.html">CC_MqttsnGatewayInfo</a> structure will be empty.</p>
<p>Upon reception of any new data packet from the I/O link, the application is expected to detect and save the origin address of the sender. In case the reported gateway address is empty, the application is expected to use the saved origin address of the data packet as the one of the gateway. The application is also expected to update the address info stored by the library using the <b><a class="el" href="group__client.html#gaeb25973846c3af5eddb01732aef37322" title="Update stored available gateway information.">cc_mqttsn_client_set_available_gateway_info()</a></b> function. The details are in the <a class="el" href="index.html#doc_cc_mqttsn_client_gateway_monitoring">Monitoring and Managing Available Gateways</a> section below.</p>
<h2><a class="anchor" id="doc_cc_mqttsn_client_search_cancel"></a>
Cancel the "Search" Operation.</h2>
<p>While the handle returned by the <b><a class="el" href="group__search.html#gadadf9dd82526dab95e1878cd78a6dce3" title="Prepare "search" operation.">cc_mqttsn_client_search_prepare()</a></b> is still valid it is possible to cancel / discard the operation. </p><div class="fragment"><div class="line"><a class="code" href="group__global.html#gade7e7c53c5ca30c6134f60607b01079f">CC_MqttsnErrorCode</a> ec = <a class="code" href="group__search.html#gaf5ddf0910376136b1ece7ac6c3a9c327">cc_mqttsn_client_search_cancel</a>(search);</div>
<div class="line"><span class="keywordflow">if</span> (ec != <a class="code" href="group__global.html#ggade7e7c53c5ca30c6134f60607b01079faa71957fe69fa1b94d1d0cbc3c7558e1f">CC_MqttsnErrorCode_Success</a>) {</div>
<div class="line"> printf(<span class="stringliteral">"ERROR: Failed to cancel search with ec=%d\n"</span>, ec);</div>
<div class="line"> ...</div>
<div class="line">}</div>
<div class="ttc" id="agroup__search_html_gaf5ddf0910376136b1ece7ac6c3a9c327"><div class="ttname"><a href="group__search.html#gaf5ddf0910376136b1ece7ac6c3a9c327">cc_mqttsn_client_search_cancel</a></div><div class="ttdeci">CC_MqttsnErrorCode cc_mqttsn_client_search_cancel(CC_MqttsnSearchHandle handle)</div><div class="ttdoc">Cancel the allocated "search" operation.</div></div>
</div><!-- fragment --><p> In case the <b><a class="el" href="group__search.html#ga69a2454162a8168ac236babfd0ac2806" title="Send the "search" operation.">cc_mqttsn_client_search_send()</a></b> function was successfully called before the <b><a class="el" href="group__search.html#gaf5ddf0910376136b1ece7ac6c3a9c327" title="Cancel the allocated "search" operation.">cc_mqttsn_client_search_cancel()</a></b>, the operation is cancelled <b>without</b> callback invocation.</p>
<h2><a class="anchor" id="doc_cc_mqttsn_client_search_simplify"></a>
Simplifying the "Search" Operation Preparation</h2>
<p>In many use cases the "search" operation can be quite simple with a lot of defaults. To simplify the sequence of the operation preparation and handling of errors, the library provides the <b><a class="el" href="group__search.html#ga84f10e49dafd598347a0952d6b3f6cc9" title="Prepare and send "search" request in one go.">cc_mqttsn_client_search()</a></b> wrapper function.</p>
<p>For example: </p><div class="fragment"><div class="line"><a class="code" href="group__global.html#gade7e7c53c5ca30c6134f60607b01079f">CC_MqttsnErrorCode</a> ec = <a class="code" href="group__search.html#ga84f10e49dafd598347a0952d6b3f6cc9">cc_mqttsn_client_search</a>(client, &my_search_complete_cb, data);</div>
<div class="line"><span class="keywordflow">if</span> (ec != <a class="code" href="group__global.html#ggade7e7c53c5ca30c6134f60607b01079faa71957fe69fa1b94d1d0cbc3c7558e1f">CC_MqttsnErrorCode_Success</a>) {</div>
<div class="line"> printf(<span class="stringliteral">"ERROR: Failed to send search request with ec=%d\n"</span>, ec);</div>
<div class="line"> ...</div>
<div class="line">}</div>
<div class="ttc" id="agroup__search_html_ga84f10e49dafd598347a0952d6b3f6cc9"><div class="ttname"><a href="group__search.html#ga84f10e49dafd598347a0952d6b3f6cc9">cc_mqttsn_client_search</a></div><div class="ttdeci">CC_MqttsnErrorCode cc_mqttsn_client_search(CC_MqttsnClientHandle handle, CC_MqttsnSearchCompleteCb cb, void *cbData)</div><div class="ttdoc">Prepare and send "search" request in one go.</div></div>
</div><!-- fragment --><p> Note that the wrapper functions do NOT expose the handle returned by the <b><a class="el" href="group__search.html#gadadf9dd82526dab95e1878cd78a6dce3" title="Prepare "search" operation.">cc_mqttsn_client_search_prepare()</a></b>. It means that it's not possible to cancel the "search" operation before its completion.</p>
<h1><a class="anchor" id="doc_cc_mqttsn_client_gateway_monitoring"></a>
Monitoring and Managing Available Gateways</h1>
<p>The MQTT-SN gateways are also expected to periodically advertise their presence. The client library keeps track of the discovered gateways on the network. It is possible to retrieve the information on the available gateways at any time. </p><div class="fragment"><div class="line"><span class="keywordtype">unsigned</span> numOfAvailableGateways = <a class="code" href="group__client.html#gaffc43bf87291019ca2b6772b310d0a29">cc_mqttsn_client_get_available_gateways_count</a>(client);</div>
<div class="line"><span class="keywordflow">for</span> (idx=0; idx < numOfAvailableGateways; ++idx) {</div>
<div class="line"> <a class="code" href="structCC__MqttsnGatewayInfo.html">CC_MqttsnGatewayInfo</a> info;</div>
<div class="line"> <a class="code" href="group__global.html#gade7e7c53c5ca30c6134f60607b01079f">CC_MqttsnErrorCode</a> ec = <a class="code" href="group__client.html#gaee61e9b1ee2de09d48b82804b57531b8">cc_mqttsn_client_get_available_gateway_info</a>(client, idx, &info);</div>
<div class="line"> <span class="keywordflow">if</span> (ec != <a class="code" href="group__global.html#ggade7e7c53c5ca30c6134f60607b01079faa71957fe69fa1b94d1d0cbc3c7558e1f">CC_MqttsnErrorCode_Success</a>) {</div>
<div class="line"> printf(<span class="stringliteral">"Something is wrong\n"</span>);</div>
<div class="line"> <span class="keywordflow">continue</span>;</div>
<div class="line"> }</div>
<div class="line"> </div>
<div class="line"> ... <span class="comment">// Process updated info.</span></div>
<div class="line">}</div>
<div class="ttc" id="agroup__client_html_gaee61e9b1ee2de09d48b82804b57531b8"><div class="ttname"><a href="group__client.html#gaee61e9b1ee2de09d48b82804b57531b8">cc_mqttsn_client_get_available_gateway_info</a></div><div class="ttdeci">CC_MqttsnErrorCode cc_mqttsn_client_get_available_gateway_info(CC_MqttsnClientHandle client, unsigned idx, CC_MqttsnGatewayInfo *info)</div><div class="ttdoc">Retrieve stored available gateway information.</div></div>
<div class="ttc" id="agroup__client_html_gaffc43bf87291019ca2b6772b310d0a29"><div class="ttname"><a href="group__client.html#gaffc43bf87291019ca2b6772b310d0a29">cc_mqttsn_client_get_available_gateways_count</a></div><div class="ttdeci">unsigned cc_mqttsn_client_get_available_gateways_count(CC_MqttsnClientHandle client)</div><div class="ttdoc">Get number of available gateways.</div></div>
</div><!-- fragment --><p>The application can receive ongoing notifications if a status of any gateway changes. </p><div class="fragment"><div class="line"><span class="keywordtype">void</span> my_gw_status_report_cb(<span class="keywordtype">void</span>* data, <a class="code" href="group__global.html#ga55fac5d32cd1c5ab28bd9f4866410f2f">CC_MqttsnGwStatus</a> status, <span class="keyword">const</span> <a class="code" href="structCC__MqttsnGatewayInfo.html">CC_MqttsnGatewayInfo</a>* info)</div>
<div class="line">{</div>
<div class="line"> ...</div>
<div class="line">}</div>
<div class="line"> </div>
<div class="line"><a class="code" href="group__client.html#gaf95c1f555c1954bbd94c2c4276ae9f59">cc_mqttsn_client_set_gw_status_report_callback</a>(client, &my_gw_status_report_cb, data);</div>
<div class="ttc" id="agroup__client_html_gaf95c1f555c1954bbd94c2c4276ae9f59"><div class="ttname"><a href="group__client.html#gaf95c1f555c1954bbd94c2c4276ae9f59">cc_mqttsn_client_set_gw_status_report_callback</a></div><div class="ttdeci">void cc_mqttsn_client_set_gw_status_report_callback(CC_MqttsnClientHandle client, CC_MqttsnGwStatusReportCb cb, void *data)</div><div class="ttdoc">Set callback to report status of the gateway.</div></div>
<div class="ttc" id="agroup__global_html_ga55fac5d32cd1c5ab28bd9f4866410f2f"><div class="ttname"><a href="group__global.html#ga55fac5d32cd1c5ab28bd9f4866410f2f">CC_MqttsnGwStatus</a></div><div class="ttdeci">CC_MqttsnGwStatus</div><div class="ttdoc">Status of the gateway.</div><div class="ttdef"><b>Definition:</b> common.h:74</div></div>
</div><!-- fragment --><p> The <b>status</b> parameter to the callback function indicates the status of the gateway, while <b>info</b> reports the currently stored gateway information. The callback (if registered) is invoked every time the <b>ADVERTISE</b> as well as <b>GWINFO</b> messages are received or not received in time. The <a class="el" href="group__global.html#ga55fac5d32cd1c5ab28bd9f4866410f2f">status</a> value indicates of whether the gateway information is newly added, updated or the old info is confirmed.</p>
<p>When the expected <b>ADVERTISE</b> message doesn't arrive in time, it can be due to packet loss on the network rather than the gateway itself going offline. The library allows configuration of allowed losses of the <b>ADVERTISE</b> message before the gateway is reported to be <a class="el" href="group__global.html#gga55fac5d32cd1c5ab28bd9f4866410f2fa6510f6a7ea5ee10eb9d33fdef2c926f3">CC_MqttsnGwStatus_Removed</a> and its info removed from the internal data structures. </p><div class="fragment"><div class="line"><a class="code" href="group__global.html#gade7e7c53c5ca30c6134f60607b01079f">CC_MqttsnErrorCode</a> ec = <a class="code" href="group__client.html#ga2ca9522ae41e12b2a40c47ba9453acd5">cc_mqttsn_client_set_allowed_adv_losses</a>(client, 2);</div>
<div class="ttc" id="agroup__client_html_ga2ca9522ae41e12b2a40c47ba9453acd5"><div class="ttname"><a href="group__client.html#ga2ca9522ae41e12b2a40c47ba9453acd5">cc_mqttsn_client_set_allowed_adv_losses</a></div><div class="ttdeci">CC_MqttsnErrorCode cc_mqttsn_client_set_allowed_adv_losses(CC_MqttsnClientHandle client, unsigned count)</div><div class="ttdoc">Set number of allowed ADVERTISE message misses.</div></div>
</div><!-- fragment --><p> The configured count is how many <b>ADVERTISE</b> messages can be <b>lost</b>, i.e. when configured to be <b>0</b>, the gateway info is removed on the first missing <b>ADVERTISE</b> packet. When configured to be <b>1</b> (or greater), the reported gateway status will be <a class="el" href="group__global.html#gga55fac5d32cd1c5ab28bd9f4866410f2faa7c7dad3a0e7f27e964899788b8292a9">CC_MqttsnGwStatus_Tentative</a> when the expected advertising packet doesn't arrive in time until the inner count of allowed losses goes to <b>0</b> and then the gateway status is reported to be <a class="el" href="group__global.html#gga55fac5d32cd1c5ab28bd9f4866410f2fa6510f6a7ea5ee10eb9d33fdef2c926f3">CC_MqttsnGwStatus_Removed</a>. The default allowed count of the <b>ADVERTISE</b> losses is <b>1</b>. The current configuration can be retrieved using <b><a class="el" href="group__client.html#ga495839ffcb4f4fac987590df1c4e2b9c" title="Get current configuration of allowed ADVERTISE message misses.">cc_mqttsn_client_get_allowed_adv_losses()</a></b>. When the <b>ADVERTISE</b> or <b>GWINFO</b> from the gateway message arrive, the library reports <a class="el" href="group__global.html#gga55fac5d32cd1c5ab28bd9f4866410f2fa37a33d0b849e78a0ad7036b9caedac80">CC_MqttsnGwStatus_Alive</a> as the status gateway.</p>
<p>Upon reception of the <b>ADVERTISE</b> or <b>GWINFO</b> from the gateway, the address information may be missing (or wrong). The application is expected to record the origin of the recent message and this information can be used to update the recorded information. The application can invoke the <b><a class="el" href="group__client.html#gaeb25973846c3af5eddb01732aef37322" title="Update stored available gateway information.">cc_mqttsn_client_set_available_gateway_info()</a></b> function at any time to update / override the stored address information about the gateway. It is also applicable to the <a class="el" href="index.html#doc_cc_mqttsn_client_search_send">search</a> operation. The <b><a class="el" href="group__client.html#gaeb25973846c3af5eddb01732aef37322" title="Update stored available gateway information.">cc_mqttsn_client_set_available_gateway_info()</a></b> can be called from withing the operation completion callback to update the stored gateway address. </p><div class="fragment"><div class="line"><a class="code" href="structCC__MqttsnGatewayInfo.html">CC_MqttsnGatewayInfo</a> info;</div>
<div class="line"><a class="code" href="group__client.html#gae027c2bff48ca6c5a42d8f6b6d2f6d7a">cc_mqttsn_client_init_gateway_info</a>(&info);</div>
<div class="line">info.<a class="code" href="structCC__MqttsnGatewayInfo.html#ae18157a73ea40747632c12f77c08b622">m_gwId</a> = ...;</div>
<div class="line">info.<a class="code" href="structCC__MqttsnGatewayInfo.html#aaf2ef4ae5c9b9e8f3886371dc7b68b64">m_addr</a> = ...;</div>
<div class="line">info.<a class="code" href="structCC__MqttsnGatewayInfo.html#a96a441b1071e315d2a60731e8287aa0c">m_addrLen</a> = ...;</div>
<div class="line"><a class="code" href="group__global.html#gade7e7c53c5ca30c6134f60607b01079f">CC_MqttsnErrorCode</a> ec = <a class="code" href="group__client.html#gaeb25973846c3af5eddb01732aef37322">cc_mqttsn_client_set_available_gateway_info</a>(client, &info);</div>
<div class="line"><span class="keywordflow">if</span> (ec != <a class="code" href="group__global.html#ggade7e7c53c5ca30c6134f60607b01079faa71957fe69fa1b94d1d0cbc3c7558e1f">CC_MqttsnErrorCode_Success</a>) {</div>
<div class="line"> printf(<span class="stringliteral">"Something is wrong"</span>);</div>
<div class="line">}</div>
<div class="ttc" id="agroup__client_html_gae027c2bff48ca6c5a42d8f6b6d2f6d7a"><div class="ttname"><a href="group__client.html#gae027c2bff48ca6c5a42d8f6b6d2f6d7a">cc_mqttsn_client_init_gateway_info</a></div><div class="ttdeci">void cc_mqttsn_client_init_gateway_info(CC_MqttsnGatewayInfo *info)</div><div class="ttdoc">Initialize the CC_MqttsnGatewayInfo structure.</div></div>
<div class="ttc" id="agroup__client_html_gaeb25973846c3af5eddb01732aef37322"><div class="ttname"><a href="group__client.html#gaeb25973846c3af5eddb01732aef37322">cc_mqttsn_client_set_available_gateway_info</a></div><div class="ttdeci">CC_MqttsnErrorCode cc_mqttsn_client_set_available_gateway_info(CC_MqttsnClientHandle client, const CC_MqttsnGatewayInfo *info)</div><div class="ttdoc">Update stored available gateway information.</div></div>
<div class="ttc" id="astructCC__MqttsnGatewayInfo_html_a96a441b1071e315d2a60731e8287aa0c"><div class="ttname"><a href="structCC__MqttsnGatewayInfo.html#a96a441b1071e315d2a60731e8287aa0c">CC_MqttsnGatewayInfo::m_addrLen</a></div><div class="ttdeci">unsigned m_addrLen</div><div class="ttdoc">Length of the address.</div><div class="ttdef"><b>Definition:</b> common.h:240</div></div>
<div class="ttc" id="astructCC__MqttsnGatewayInfo_html_aaf2ef4ae5c9b9e8f3886371dc7b68b64"><div class="ttname"><a href="structCC__MqttsnGatewayInfo.html#aaf2ef4ae5c9b9e8f3886371dc7b68b64">CC_MqttsnGatewayInfo::m_addr</a></div><div class="ttdeci">const unsigned char * m_addr</div><div class="ttdoc">Address of the gateway if known, NULL if not.</div><div class="ttdef"><b>Definition:</b> common.h:239</div></div>
<div class="ttc" id="astructCC__MqttsnGatewayInfo_html_ae18157a73ea40747632c12f77c08b622"><div class="ttname"><a href="structCC__MqttsnGatewayInfo.html#ae18157a73ea40747632c12f77c08b622">CC_MqttsnGatewayInfo::m_gwId</a></div><div class="ttdeci">unsigned char m_gwId</div><div class="ttdoc">Gateway ID.</div><div class="ttdef"><b>Definition:</b> common.h:238</div></div>
</div><!-- fragment --><p> It is recommended to initialize <a class="el" href="structCC__MqttsnGatewayInfo.html">CC_MqttsnGatewayInfo</a> structure using the <b><a class="el" href="group__client.html#gae027c2bff48ca6c5a42d8f6b6d2f6d7a" title="Initialize the CC_MqttsnGatewayInfo structure.">cc_mqttsn_client_init_gateway_info()</a></b> function before update, even though all the member fields are assigned new values.</p>
<p>The application can force the library to discard the available gateway information by issuing the <b><a class="el" href="group__client.html#gaf3c4babe08a8b83b67e13cb41b287f00" title="Discard stored available gateway information.">cc_mqttsn_client_discard_available_gateway_info()</a></b> function. </p><div class="fragment"><div class="line"><a class="code" href="group__global.html#gade7e7c53c5ca30c6134f60607b01079f">CC_MqttsnErrorCode</a> ec = <a class="code" href="group__client.html#gaf3c4babe08a8b83b67e13cb41b287f00">cc_mqttsn_client_discard_available_gateway_info</a>(client, 1 <span class="comment">/* gateway id */</span>);</div>
<div class="line"><span class="keywordflow">if</span> (ec != <a class="code" href="group__global.html#ggade7e7c53c5ca30c6134f60607b01079faa71957fe69fa1b94d1d0cbc3c7558e1f">CC_MqttsnErrorCode_Success</a>) {</div>
<div class="line"> printf(<span class="stringliteral">"Something is wrong"</span>);</div>
<div class="line">}</div>
<div class="ttc" id="agroup__client_html_gaf3c4babe08a8b83b67e13cb41b287f00"><div class="ttname"><a href="group__client.html#gaf3c4babe08a8b83b67e13cb41b287f00">cc_mqttsn_client_discard_available_gateway_info</a></div><div class="ttdeci">CC_MqttsnErrorCode cc_mqttsn_client_discard_available_gateway_info(CC_MqttsnClientHandle client, unsigned char gwId)</div><div class="ttdoc">Discard stored available gateway information.</div></div>
</div><!-- fragment --><p>It is possible to discard information on all the gateways in one go: </p><div class="fragment"><div class="line"><a class="code" href="group__global.html#gade7e7c53c5ca30c6134f60607b01079f">CC_MqttsnErrorCode</a> ec = <a class="code" href="group__client.html#ga0f62f6a86744d84c31e751cb1e7ea9aa">cc_mqttsn_client_discard_all_gateway_infos</a>(client);</div>
<div class="line"><span class="keywordflow">if</span> (ec != <a class="code" href="group__global.html#ggade7e7c53c5ca30c6134f60607b01079faa71957fe69fa1b94d1d0cbc3c7558e1f">CC_MqttsnErrorCode_Success</a>) {</div>
<div class="line"> printf(<span class="stringliteral">"Something is wrong"</span>);</div>
<div class="line">}</div>
<div class="ttc" id="agroup__client_html_ga0f62f6a86744d84c31e751cb1e7ea9aa"><div class="ttname"><a href="group__client.html#ga0f62f6a86744d84c31e751cb1e7ea9aa">cc_mqttsn_client_discard_all_gateway_infos</a></div><div class="ttdeci">void cc_mqttsn_client_discard_all_gateway_infos(CC_MqttsnClientHandle client)</div><div class="ttdoc">Discard stored information on all available gateways.</div></div>
</div><!-- fragment --><p>When the client receives <b>GWINFO</b> message before <b>ADVERTISE</b>, the advertising period of the gateway is not known yet. For the gateway tracking and management functionality there is a need to assume some kind of default duration. The default value is <b>15 minutes</b>. To update it use <b><a class="el" href="group__client.html#gaf9b86b346a1fa88a2cfb5dbabc13baeb" title="Set default gateway advertise duration.">cc_mqttsn_client_set_default_gw_adv_duration()</a></b> function. </p><div class="fragment"><div class="line"><a class="code" href="group__global.html#gade7e7c53c5ca30c6134f60607b01079f">CC_MqttsnErrorCode</a> ec = <a class="code" href="group__client.html#gaf9b86b346a1fa88a2cfb5dbabc13baeb">cc_mqttsn_client_set_default_gw_adv_duration</a>(client, 20 * 60 * 1000 <span class="comment">/* 20 minutes in milliseconds */</span>);</div>
<div class="line"><span class="keywordflow">if</span> (ec != <a class="code" href="group__global.html#ggade7e7c53c5ca30c6134f60607b01079faa71957fe69fa1b94d1d0cbc3c7558e1f">CC_MqttsnErrorCode_Success</a>) {</div>
<div class="line"> printf(<span class="stringliteral">"Something is wrong"</span>);</div>
<div class="line">}</div>
<div class="ttc" id="agroup__client_html_gaf9b86b346a1fa88a2cfb5dbabc13baeb"><div class="ttname"><a href="group__client.html#gaf9b86b346a1fa88a2cfb5dbabc13baeb">cc_mqttsn_client_set_default_gw_adv_duration</a></div><div class="ttdeci">CC_MqttsnErrorCode cc_mqttsn_client_set_default_gw_adv_duration(CC_MqttsnClientHandle client, unsigned ms)</div><div class="ttdoc">Set default gateway advertise duration.</div></div>
</div><!-- fragment --><p> To retrieve the current configuration use <b><a class="el" href="group__client.html#ga3f258f2614a81d2f9ca78826b8ceb74f" title="Get current default gateway advertise configuration.">cc_mqttsn_client_get_default_gw_adv_duration()</a></b> function.</p>
<h1><a class="anchor" id="doc_cc_mqttsn_client_connect"></a>
Connecting to Gateway</h1>
<p>To connect to gateway use <a class="el" href="group__connect.html">connect</a> operation.</p>
<h2><a class="anchor" id="doc_cc_mqttsn_client_connect_prepare"></a>
Preparing "Connect" Operation.</h2>
<div class="fragment"><div class="line"><a class="code" href="group__global.html#gade7e7c53c5ca30c6134f60607b01079f">CC_MqttsnErrorCode</a> ec = <a class="code" href="group__global.html#ggade7e7c53c5ca30c6134f60607b01079faa71957fe69fa1b94d1d0cbc3c7558e1f">CC_MqttsnErrorCode_Success</a>;</div>
<div class="line"><a class="code" href="group__connect.html#ga2becb99684d975dd3c16a1234182ae54">CC_MqttsnConnectHandle</a> connect = <a class="code" href="group__connect.html#ga416eaa2f9728807519d4b5a92adc9ef5">cc_mqttsn_client_connect_prepare</a>(client, &ec);</div>
<div class="line"><span class="keywordflow">if</span> (connect == NULL) {</div>
<div class="line"> printf(<span class="stringliteral">"ERROR: Connect allocation failed with ec=%d\n"</span>, ec);</div>
<div class="line">}</div>
<div class="ttc" id="agroup__connect_html_ga416eaa2f9728807519d4b5a92adc9ef5"><div class="ttname"><a href="group__connect.html#ga416eaa2f9728807519d4b5a92adc9ef5">cc_mqttsn_client_connect_prepare</a></div><div class="ttdeci">CC_MqttsnConnectHandle cc_mqttsn_client_connect_prepare(CC_MqttsnClientHandle client, CC_MqttsnErrorCode *ec)</div><div class="ttdoc">Prepare "connect" operation.</div></div>
</div><!-- fragment --><p> <b>NOTE</b> that the <b><a class="el" href="group__connect.html#ga416eaa2f9728807519d4b5a92adc9ef5" title="Prepare "connect" operation.">cc_mqttsn_client_connect_prepare()</a></b> cannot be called from within a callback. For example, if the gateway disconnection is reported via <a class="el" href="index.html#doc_cc_mqttsn_client_callbacks_gateway_disconnect">callback</a> then the <b><a class="el" href="group__connect.html#ga416eaa2f9728807519d4b5a92adc9ef5" title="Prepare "connect" operation.">cc_mqttsn_client_connect_prepare()</a></b> cannot be invoked right away. It needs to be postponed until the next event loop iteration.</p>
<h2><a class="anchor" id="doc_cc_mqttsn_client_connect_retry_period"></a>
Configuring "Connect" Retry Period</h2>
<p>When created, the "connect" operation inherits the <a class="el" href="index.html#doc_cc_mqttsn_client_retry_period">Default Retry Period</a> configuration. It can be changed for the allocated operation using the <b><a class="el" href="group__connect.html#gac16b149d46f8c79401ff4af4a0a710bd" title="Configure the retry period for the "connect" operation.">cc_mqttsn_client_connect_set_retry_period()</a></b> function. </p><div class="fragment"><div class="line">ec = <a class="code" href="group__connect.html#gac16b149d46f8c79401ff4af4a0a710bd">cc_mqttsn_client_connect_set_retry_period</a>(connect, 1000);</div>
<div class="line"><span class="keywordflow">if</span> (ec != <a class="code" href="group__global.html#ggade7e7c53c5ca30c6134f60607b01079faa71957fe69fa1b94d1d0cbc3c7558e1f">CC_MqttsnErrorCode_Success</a>) {</div>
<div class="line"> ... <span class="comment">/* Something went wrong */</span></div>
<div class="line">}</div>
<div class="ttc" id="agroup__connect_html_gac16b149d46f8c79401ff4af4a0a710bd"><div class="ttname"><a href="group__connect.html#gac16b149d46f8c79401ff4af4a0a710bd">cc_mqttsn_client_connect_set_retry_period</a></div><div class="ttdeci">CC_MqttsnErrorCode cc_mqttsn_client_connect_set_retry_period(CC_MqttsnConnectHandle handle, unsigned ms)</div><div class="ttdoc">Configure the retry period for the "connect" operation.</div></div>
</div><!-- fragment --><p> To retrieve the configured response timeout use the <b><a class="el" href="group__connect.html#ga6dfb0251e7ae7df498e9470ae9a8576a" title="Retrieve the configured retry period for the "connect" operation.">cc_mqttsn_client_connect_get_retry_period()</a></b> function.</p>
<h2><a class="anchor" id="doc_cc_mqttsn_client_connect_retry_count"></a>
Configuring "Connect" Retry Count</h2>
<p>When created, the "connect" operation inherits the <a class="el" href="index.html#doc_cc_mqttsn_client_retry_count">Default Retry Count</a> configuration. It can be changed for the allocated operation using the <b><a class="el" href="group__connect.html#ga4d6c3eef20b46f19ebf780593a779c70" title="Configure the retry count for the "connect" operation.">cc_mqttsn_client_connect_set_retry_count()</a></b> function. </p><div class="fragment"><div class="line">ec = <a class="code" href="group__connect.html#ga4d6c3eef20b46f19ebf780593a779c70">cc_mqttsn_client_connect_set_retry_count</a>(connect, 2);</div>
<div class="line"><span class="keywordflow">if</span> (ec != <a class="code" href="group__global.html#ggade7e7c53c5ca30c6134f60607b01079faa71957fe69fa1b94d1d0cbc3c7558e1f">CC_MqttsnErrorCode_Success</a>) {</div>
<div class="line"> ... <span class="comment">/* Something went wrong */</span></div>
<div class="line">}</div>
<div class="ttc" id="agroup__connect_html_ga4d6c3eef20b46f19ebf780593a779c70"><div class="ttname"><a href="group__connect.html#ga4d6c3eef20b46f19ebf780593a779c70">cc_mqttsn_client_connect_set_retry_count</a></div><div class="ttdeci">CC_MqttsnErrorCode cc_mqttsn_client_connect_set_retry_count(CC_MqttsnConnectHandle handle, unsigned count)</div><div class="ttdoc">Configure the retry count for the "connect" operation.</div></div>
</div><!-- fragment --><p> To retrieve the configured response timeout use the <b><a class="el" href="group__connect.html#gaa07989682c7f9734839e7d76b6154d08" title="Retrieve the configured retry count for the "connect" operation.">cc_mqttsn_client_connect_get_retry_count()</a></b> function.</p>
<h2><a class="anchor" id="doc_cc_mqttsn_client_connect_basic"></a>
Configuration of "Connect" Operation</h2>
<p>To configure "connect" operation use <b><a class="el" href="group__connect.html#gafc35618a7025f8e592a72628d20367bd" title="Perform configuration of the "connect" operation.">cc_mqttsn_client_connect_config()</a></b> function. </p><div class="fragment"><div class="line"><a class="code" href="structCC__MqttsnConnectConfig.html">CC_MqttsnConnectConfig</a> config;</div>
<div class="line"> </div>
<div class="line"><span class="comment">// Assign default values to the "config"</span></div>
<div class="line"><a class="code" href="group__connect.html#gaaa42d96b0cf032892d79467275bfbc06">cc_mqttsn_client_connect_init_config</a>(&config);</div>
<div class="line"> </div>
<div class="line"><span class="comment">// Update the values if needed:</span></div>
<div class="line">config.<a class="code" href="structCC__MqttsnConnectConfig.html#aced31e92c5360b3c91fcf445342be801">m_clientId</a> = <span class="stringliteral">"some_client"</span>;</div>
<div class="line">config.<a class="code" href="structCC__MqttsnConnectConfig.html#a0d27aa69ba181ffc2eaf5ab150e38dd1">m_cleanSession</a> = <span class="keyword">true</span>;</div>
<div class="line"> </div>
<div class="line"><span class="comment">// Perform the configuration</span></div>
<div class="line">ec = <a class="code" href="group__connect.html#gafc35618a7025f8e592a72628d20367bd">cc_mqttsn_client_connect_config</a>(connect, &config);</div>
<div class="line"><span class="keywordflow">if</span> (ec != <a class="code" href="group__global.html#ggade7e7c53c5ca30c6134f60607b01079faa71957fe69fa1b94d1d0cbc3c7558e1f">CC_MqttsnErrorCode_Success</a>) {</div>
<div class="line"> printf(<span class="stringliteral">"ERROR: Connect configuration failed with ec=%d\n"</span>, ec);</div>
<div class="line"> ...</div>
<div class="line">}</div>
<div class="ttc" id="agroup__connect_html_gaaa42d96b0cf032892d79467275bfbc06"><div class="ttname"><a href="group__connect.html#gaaa42d96b0cf032892d79467275bfbc06">cc_mqttsn_client_connect_init_config</a></div><div class="ttdeci">void cc_mqttsn_client_connect_init_config(CC_MqttsnConnectConfig *config)</div><div class="ttdoc">Intialize the CC_MqttsnConnectConfig configuration structure.</div></div>
<div class="ttc" id="agroup__connect_html_gafc35618a7025f8e592a72628d20367bd"><div class="ttname"><a href="group__connect.html#gafc35618a7025f8e592a72628d20367bd">cc_mqttsn_client_connect_config</a></div><div class="ttdeci">CC_MqttsnErrorCode cc_mqttsn_client_connect_config(CC_MqttsnConnectHandle handle, const CC_MqttsnConnectConfig *config)</div><div class="ttdoc">Perform configuration of the "connect" operation.</div></div>
<div class="ttc" id="astructCC__MqttsnConnectConfig_html"><div class="ttname"><a href="structCC__MqttsnConnectConfig.html">CC_MqttsnConnectConfig</a></div><div class="ttdoc">Configuration the "connect" operation.</div><div class="ttdef"><b>Definition:</b> common.h:246</div></div>
<div class="ttc" id="astructCC__MqttsnConnectConfig_html_a0d27aa69ba181ffc2eaf5ab150e38dd1"><div class="ttname"><a href="structCC__MqttsnConnectConfig.html#a0d27aa69ba181ffc2eaf5ab150e38dd1">CC_MqttsnConnectConfig::m_cleanSession</a></div><div class="ttdeci">bool m_cleanSession</div><div class="ttdoc">Clean session configuration.</div><div class="ttdef"><b>Definition:</b> common.h:249</div></div>
<div class="ttc" id="astructCC__MqttsnConnectConfig_html_aced31e92c5360b3c91fcf445342be801"><div class="ttname"><a href="structCC__MqttsnConnectConfig.html#aced31e92c5360b3c91fcf445342be801">CC_MqttsnConnectConfig::m_clientId</a></div><div class="ttdeci">const char * m_clientId</div><div class="ttdoc">Client ID.</div><div class="ttdef"><b>Definition:</b> common.h:247</div></div>
</div><!-- fragment --><p><b>IMPORTANT</b>: MQTT-SN specification allows reconnection to the gateway while requesting previous session restoration (via "clean session" bit). By default, the client library verifies that the message received from the gateway was actually subscribed to before reporting the message to the application (see <a class="el" href="index.html#doc_cc_mqttsn_client_receive">Receiving Messages</a> for details). To prevent potential errors of the client and gateway inner states being out of sync, the <b>first</b> "connect" operation requires setting the <a class="el" href="structCC__MqttsnConnectConfig.html#a0d27aa69ba181ffc2eaf5ab150e38dd1">CC_MqttsnConnectConfig::m_cleanSession</a> value to <b>true</b>. The only exception to this rule is when the subscription verification on message reception was disabled (described in the <a class="el" href="index.html#doc_cc_mqttsn_client_receive">Receiving Messages</a> section below). In case the subscription verification is still enabled and the <a class="el" href="structCC__MqttsnConnectConfig.html#a0d27aa69ba181ffc2eaf5ab150e38dd1">CC_MqttsnConnectConfig::m_cleanSession</a> value is <b>NOT</b> set to <b>true</b>, the function rejects the configuration with the <a class="el" href="group__global.html#ggade7e7c53c5ca30c6134f60607b01079fad7e86d67bfcdb1ad6dfe7c8183a7d31d">CC_MqttsnErrorCode_BadParam</a> error code. Any subsequent reconnection attempts will allow setting the value to <b>false</b>.</p>
<p>See also documentation of the <a class="el" href="structCC__MqttsnConnectConfig.html">CC_MqttsnConnectConfig</a> structure.</p>
<h2><a class="anchor" id="doc_cc_mqttsn_client_connect_will"></a>
Will Configuration</h2>
<p>To perform will configuration use the <b><a class="el" href="group__connect.html#ga8c7b7cf2f7a3797ef6f3a3aa9f9aaa07" title="Perform will configuration of the "connect" operation.">cc_mqttsn_client_connect_config_will()</a></b> function. </p><div class="fragment"><div class="line"><a class="code" href="structCC__MqttsnWillConfig.html">CC_MqttsnWillConfig</a> willConfig;</div>
<div class="line"> </div>
<div class="line"><span class="comment">// Assign default values to the configuration</span></div>
<div class="line"><a class="code" href="group__connect.html#ga56f4475acdda90da87fa699af24f1ed5">cc_mqttsn_client_connect_init_config_will</a>(&willConfig);</div>
<div class="line"> </div>
<div class="line"><span class="comment">// Update values if needed</span></div>
<div class="line">willConfig.<a class="code" href="structCC__MqttsnWillConfig.html#ade69ab118e4cae42026c478f44e3335e">m_topic</a> = <span class="stringliteral">"some/topic"</span>;</div>
<div class="line">willConfig.<a class="code" href="structCC__MqttsnWillConfig.html#a299c450ae9412737e65ea7384276ac50">m_data</a> = ...;</div>
<div class="line">willConfig.<a class="code" href="structCC__MqttsnWillConfig.html#a46e7512ba5be0e7504e511dec5c713f8">m_dataLen</a> = ...;</div>
<div class="line">...</div>
<div class="line"> </div>
<div class="line"><span class="comment">// Perform the configuration</span></div>
<div class="line">ec = <a class="code" href="group__connect.html#ga8c7b7cf2f7a3797ef6f3a3aa9f9aaa07">cc_mqttsn_client_connect_config_will</a>(connect, &willConfig);</div>
<div class="line"><span class="keywordflow">if</span> (ec != <a class="code" href="group__global.html#ggade7e7c53c5ca30c6134f60607b01079faa71957fe69fa1b94d1d0cbc3c7558e1f">CC_MqttsnErrorCode_Success</a>) {</div>
<div class="line"> printf(<span class="stringliteral">"ERROR: Will configuration failed with ec=%d\n"</span>, ec);</div>
<div class="line"> ...</div>
<div class="line">}</div>
<div class="ttc" id="agroup__connect_html_ga56f4475acdda90da87fa699af24f1ed5"><div class="ttname"><a href="group__connect.html#ga56f4475acdda90da87fa699af24f1ed5">cc_mqttsn_client_connect_init_config_will</a></div><div class="ttdeci">void cc_mqttsn_client_connect_init_config_will(CC_MqttsnWillConfig *config)</div><div class="ttdoc">Intialize the CC_MqttsnWillConfig configuration structure.</div></div>
<div class="ttc" id="agroup__connect_html_ga8c7b7cf2f7a3797ef6f3a3aa9f9aaa07"><div class="ttname"><a href="group__connect.html#ga8c7b7cf2f7a3797ef6f3a3aa9f9aaa07">cc_mqttsn_client_connect_config_will</a></div><div class="ttdeci">CC_MqttsnErrorCode cc_mqttsn_client_connect_config_will(CC_MqttsnConnectHandle handle, const CC_MqttsnWillConfig *config)</div><div class="ttdoc">Perform will configuration of the "connect" operation.</div></div>
<div class="ttc" id="astructCC__MqttsnWillConfig_html"><div class="ttname"><a href="structCC__MqttsnWillConfig.html">CC_MqttsnWillConfig</a></div><div class="ttdoc">Configuration the will for "connect" and "will" operations.</div><div class="ttdef"><b>Definition:</b> common.h:262</div></div>
<div class="ttc" id="astructCC__MqttsnWillConfig_html_a299c450ae9412737e65ea7384276ac50"><div class="ttname"><a href="structCC__MqttsnWillConfig.html#a299c450ae9412737e65ea7384276ac50">CC_MqttsnWillConfig::m_data</a></div><div class="ttdeci">const unsigned char * m_data</div><div class="ttdoc">Will data (message).</div><div class="ttdef"><b>Definition:</b> common.h:264</div></div>
<div class="ttc" id="astructCC__MqttsnWillConfig_html_a46e7512ba5be0e7504e511dec5c713f8"><div class="ttname"><a href="structCC__MqttsnWillConfig.html#a46e7512ba5be0e7504e511dec5c713f8">CC_MqttsnWillConfig::m_dataLen</a></div><div class="ttdeci">unsigned m_dataLen</div><div class="ttdoc">Will data (message) length.</div><div class="ttdef"><b>Definition:</b> common.h:265</div></div>
<div class="ttc" id="astructCC__MqttsnWillConfig_html_ade69ab118e4cae42026c478f44e3335e"><div class="ttname"><a href="structCC__MqttsnWillConfig.html#ade69ab118e4cae42026c478f44e3335e">CC_MqttsnWillConfig::m_topic</a></div><div class="ttdeci">const char * m_topic</div><div class="ttdoc">Will topic.</div><div class="ttdef"><b>Definition:</b> common.h:263</div></div>
</div><!-- fragment --><p> See also documentation of the <a class="el" href="structCC__MqttsnWillConfig.html">CC_MqttsnWillConfig</a> structure.</p>
<h2><a class="anchor" id="doc_cc_mqttsn_client_connect_send"></a>
Sending Connection Request</h2>
<p>When all the necessary configurations are performed for the allocated "connect" operation it can actually be sent to the gateway. To initiate sending use the <b><a class="el" href="group__connect.html#gaebdd4cff9545d2ead8616bd662cb191f" title="Send the "connect" operation.">cc_mqttsn_client_connect_send()</a></b> function. </p><div class="fragment"><div class="line"><span class="keywordtype">void</span> my_connect_complete_cb(<span class="keywordtype">void</span>* data, <a class="code" href="group__global.html#gab0af1cb13f466184b8ecc4b1a86ec55f">CC_MqttsnAsyncOpStatus</a> status, <span class="keyword">const</span> <a class="code" href="structCC__MqttsnConnectInfo.html">CC_MqttsnConnectInfo</a>* info)</div>
<div class="line">{</div>
<div class="line"> <span class="keywordflow">if</span> (status != <a class="code" href="group__global.html#ggab0af1cb13f466184b8ecc4b1a86ec55fa8151e18fea364efd22acf9589fa3323c">CC_MqttsnAsyncOpStatus_Complete</a>) {</div>
<div class="line"> printf(<span class="stringliteral">"ERROR: The connection operation has failed with status=%d\n"</span>, status);</div>
<div class="line"> ... <span class="comment">// handle error.</span></div>
<div class="line"> <span class="keywordflow">return</span>;</div>
<div class="line"> }</div>
<div class="line"> </div>
<div class="line"> <span class="comment">// "info" is not NULL when status is CC_MqttsnAsyncOpStatus_Complete.</span></div>
<div class="line"> assert(info != NULL);</div>
<div class="line"> ... <span class="comment">// Analyze info values.</span></div>
<div class="line">}</div>
<div class="line"> </div>
<div class="line">ec = <a class="code" href="group__connect.html#gaebdd4cff9545d2ead8616bd662cb191f">cc_mqttsn_client_connect_send</a>(connect, &my_connect_complete_cb, data);</div>
<div class="line"><span class="keywordflow">if</span> (ec != <a class="code" href="group__global.html#ggade7e7c53c5ca30c6134f60607b01079faa71957fe69fa1b94d1d0cbc3c7558e1f">CC_MqttsnErrorCode_Success</a>) {</div>
<div class="line"> printf(<span class="stringliteral">"ERROR: Failed to send connect request with ec=%d\n"</span>, ec);</div>
<div class="line"> ...</div>
<div class="line">}</div>
<div class="ttc" id="agroup__connect_html_gaebdd4cff9545d2ead8616bd662cb191f"><div class="ttname"><a href="group__connect.html#gaebdd4cff9545d2ead8616bd662cb191f">cc_mqttsn_client_connect_send</a></div><div class="ttdeci">CC_MqttsnErrorCode cc_mqttsn_client_connect_send(CC_MqttsnConnectHandle handle, CC_MqttsnConnectCompleteCb cb, void *cbData)</div><div class="ttdoc">Send the "connect" operation.</div></div>
<div class="ttc" id="astructCC__MqttsnConnectInfo_html"><div class="ttname"><a href="structCC__MqttsnConnectInfo.html">CC_MqttsnConnectInfo</a></div><div class="ttdoc">Information on the "connect" operation completion.</div><div class="ttdef"><b>Definition:</b> common.h:255</div></div>
</div><!-- fragment --><p> The provided callback will be invoked when the "connect" operation is complete <b> if and only if</b> the function returns <a class="el" href="group__global.html#ggade7e7c53c5ca30c6134f60607b01079faa71957fe69fa1b94d1d0cbc3c7558e1f">CC_MqttsnErrorCode_Success</a>.</p>
<p>The handle returned by the <b><a class="el" href="group__connect.html#ga416eaa2f9728807519d4b5a92adc9ef5" title="Prepare "connect" operation.">cc_mqttsn_client_connect_prepare()</a></b> function can be discarded (there is no free / de-allocation) right after the <b><a class="el" href="group__connect.html#gaebdd4cff9545d2ead8616bd662cb191f" title="Send the "connect" operation.">cc_mqttsn_client_connect_send()</a></b> invocation regardless of the returned error code. However, the handle remains valid until the callback is called (in case the <a class="el" href="group__global.html#ggade7e7c53c5ca30c6134f60607b01079faa71957fe69fa1b94d1d0cbc3c7558e1f">CC_MqttsnErrorCode_Success</a> was returned). The valid handle can be used to <a class="el" href="index.html#doc_cc_mqttsn_client_connect_cancel">cancel</a> the operation before the completion callback is invoked.</p>
<p>When the "connect" operation completion callback is invoked the reported "info" is present <b>if and only if</b> the "status" is <a class="el" href="group__global.html#ggab0af1cb13f466184b8ecc4b1a86ec55fa8151e18fea364efd22acf9589fa3323c">CC_MqttsnAsyncOpStatus_Complete</a>.</p>
<p><b>NOTE</b> that only single "connect" / "disconnect" / "sleep" operation is allowed at a time, any attempt to prepare a new one via <b><a class="el" href="group__connect.html#ga416eaa2f9728807519d4b5a92adc9ef5" title="Prepare "connect" operation.">cc_mqttsn_client_connect_prepare()</a></b> will be rejected until the blocking operation completion callback is invoked or the operation is <a class="el" href="index.html#doc_cc_mqttsn_client_connect_cancel">cancelled</a>.</p>
<p>When the callback reporting the connection status is invoked, it is responsibility of the application to check the <a class="el" href="structCC__MqttsnConnectInfo.html#acfdf0d2c158f8f6b49f5203f7e79419b">CC_MqttsnConnectInfo::m_returnCode</a> value. If it's not <a class="el" href="group__global.html#gga00a4c2f75665b86f76e7244f1a173010ad9311fa083af14bd93fb1e15b5fb6ab7">CC_MqttsnReturnCode_Accepted</a>, the application is responsible retry the "connect" operation later. The same should be done when the "connect" operation is not properly completed, i.e. the reported status is <b>NOT</b> <a class="el" href="group__global.html#ggab0af1cb13f466184b8ecc4b1a86ec55fa8151e18fea364efd22acf9589fa3323c">CC_MqttsnAsyncOpStatus_Complete</a>.</p>
<p>The "connect" operation can be <a class="el" href="index.html#doc_cc_mqttsn_client_connect_send">sent</a> at any time, even if it's already <a class="el" href="index.html#doc_cc_mqttsn_client_connect_check">connected</a>. However, upon failing attempt to re-connect the assumed inner state becomes <a class="el" href="group__global.html#gga04828fffed9eca6af394a8113dbc36f6a56d78334405fe217e869debfb78e1bfd">CC_MqttsnConnectionStatus_Disconnected</a>.</p>
<h2><a class="anchor" id="doc_cc_mqttsn_client_connect_cancel"></a>
Cancel the "Connect" Operation.</h2>
<p>While the handle returned by the <b><a class="el" href="group__connect.html#ga416eaa2f9728807519d4b5a92adc9ef5" title="Prepare "connect" operation.">cc_mqttsn_client_connect_prepare()</a></b> is still valid it is possible to cancel / discard the operation. </p><div class="fragment"><div class="line">ec = <a class="code" href="group__connect.html#ga3b0221016c887dc9da8fe1a9830ba9c5">cc_mqttsn_client_connect_cancel</a>(connect);</div>
<div class="line"><span class="keywordflow">if</span> (ec != <a class="code" href="group__global.html#ggade7e7c53c5ca30c6134f60607b01079faa71957fe69fa1b94d1d0cbc3c7558e1f">CC_MqttsnErrorCode_Success</a>) {</div>
<div class="line"> printf(<span class="stringliteral">"ERROR: Failed to cancel connect with ec=%d\n"</span>, ec);</div>
<div class="line"> ...</div>
<div class="line">}</div>
<div class="ttc" id="agroup__connect_html_ga3b0221016c887dc9da8fe1a9830ba9c5"><div class="ttname"><a href="group__connect.html#ga3b0221016c887dc9da8fe1a9830ba9c5">cc_mqttsn_client_connect_cancel</a></div><div class="ttdeci">CC_MqttsnErrorCode cc_mqttsn_client_connect_cancel(CC_MqttsnConnectHandle handle)</div><div class="ttdoc">Cancel the allocated "connect" operation.</div></div>
</div><!-- fragment --><p> In case the <b><a class="el" href="group__connect.html#gaebdd4cff9545d2ead8616bd662cb191f" title="Send the "connect" operation.">cc_mqttsn_client_connect_send()</a></b> function was successfully called before the <b><a class="el" href="group__connect.html#ga3b0221016c887dc9da8fe1a9830ba9c5" title="Cancel the allocated "connect" operation.">cc_mqttsn_client_connect_cancel()</a></b>, the operation is cancelled <b>without</b> callback invocation.</p>
<h2><a class="anchor" id="doc_cc_mqttsn_client_connect_simplify"></a>
Simplifying the "Connect" Operation Preparation.</h2>
<p>In many use cases the "connect" operation can be quite simple with a lot of defaults. To simplify the sequence of the operation preparation and handling of errors, the library provides wrapper function(s) that can be used: </p><ul>
<li><b><a class="el" href="group__connect.html#gaef2b1ef547dae0c40497283841de5a3c" title="Prepare and send "connect" request in one go.">cc_mqttsn_client_connect()</a></b> </li>
</ul>
<p>For example: </p><div class="fragment"><div class="line"><a class="code" href="structCC__MqttsnConnectConfig.html">CC_MqttsnConnectConfig</a> config;</div>
<div class="line"> </div>
<div class="line"><span class="comment">// Assign default values to the "config"</span></div>
<div class="line"><a class="code" href="group__connect.html#gaaa42d96b0cf032892d79467275bfbc06">cc_mqttsn_client_connect_init_config</a>(&config);</div>
<div class="line"> </div>
<div class="line"><span class="comment">// Update the values if needed:</span></div>
<div class="line">config.<a class="code" href="structCC__MqttsnConnectConfig.html#aced31e92c5360b3c91fcf445342be801">m_clientId</a> = <span class="stringliteral">"some_client"</span>;</div>
<div class="line">config.<a class="code" href="structCC__MqttsnConnectConfig.html#a0d27aa69ba181ffc2eaf5ab150e38dd1">m_cleanSession</a> = <span class="keyword">true</span>;</div>
<div class="line"> </div>
<div class="line">ec = <a class="code" href="group__connect.html#gaef2b1ef547dae0c40497283841de5a3c">cc_mqttsn_client_connect</a>(client, config, <span class="keyword">null</span>, &my_connect_complete_cb, data);</div>
<div class="line"><span class="keywordflow">if</span> (ec != <a class="code" href="group__global.html#ggade7e7c53c5ca30c6134f60607b01079faa71957fe69fa1b94d1d0cbc3c7558e1f">CC_MqttsnErrorCode_Success</a>) {</div>
<div class="line"> printf(<span class="stringliteral">"ERROR: Failed to send connect request with ec=%d\n"</span>, ec);</div>
<div class="line"> ...</div>
<div class="line">}</div>
<div class="ttc" id="agroup__connect_html_gaef2b1ef547dae0c40497283841de5a3c"><div class="ttname"><a href="group__connect.html#gaef2b1ef547dae0c40497283841de5a3c">cc_mqttsn_client_connect</a></div><div class="ttdeci">CC_MqttsnErrorCode cc_mqttsn_client_connect(CC_MqttsnClientHandle client, const CC_MqttsnConnectConfig *config, const CC_MqttsnWillConfig *willConfig, CC_MqttsnConnectCompleteCb cb, void *cbData)</div><div class="ttdoc">Prepare and send "connect" request in one go.</div></div>
</div><!-- fragment --><p> Note that the wrapper function does NOT expose the handle returned by the <b><a class="el" href="group__connect.html#ga416eaa2f9728807519d4b5a92adc9ef5" title="Prepare "connect" operation.">cc_mqttsn_client_connect_prepare()</a></b>. It means that it's not possible to cancel the "connect" operation before its completion.</p>
<h2><a class="anchor" id="doc_cc_mqttsn_client_connect_check"></a>
Check The Library Remains Connected</h2>
<p>At any time it is possible to check the internal state of the library of whether it's properly connected to the gateway. </p><div class="fragment"><div class="line"><a class="code" href="group__global.html#ga04828fffed9eca6af394a8113dbc36f6">CC_MqttsnConnectionStatus</a> connStatus = <a class="code" href="group__connect.html#gad348cc1698b6e76a364b5d3b4798ef7f">cc_mqttsn_client_get_connection_status</a>(client);</div>
<div class="ttc" id="agroup__connect_html_gad348cc1698b6e76a364b5d3b4798ef7f"><div class="ttname"><a href="group__connect.html#gad348cc1698b6e76a364b5d3b4798ef7f">cc_mqttsn_client_get_connection_status</a></div><div class="ttdeci">CC_MqttsnConnectionStatus cc_mqttsn_client_get_connection_status(CC_MqttsnClientHandle client)</div><div class="ttdoc">Check the inner state of the library of whether it's connected to the gateway.</div></div>
<div class="ttc" id="agroup__global_html_ga04828fffed9eca6af394a8113dbc36f6"><div class="ttname"><a href="group__global.html#ga04828fffed9eca6af394a8113dbc36f6">CC_MqttsnConnectionStatus</a></div><div class="ttdeci">CC_MqttsnConnectionStatus</div><div class="ttdoc">Connection state.</div><div class="ttdef"><b>Definition:</b> common.h:121</div></div>
</div><!-- fragment --><h1><a class="anchor" id="doc_cc_mqttsn_client_disconnect"></a>
Disconnecting From Gateway</h1>
<p>To intentionally disconnect from gateway use <a class="el" href="group__disconnect.html">disconnect</a> operation. The unsolicited disconnection from the gateway is described in ref <a class="el" href="index.html#doc_cc_mqttsn_client_unsolicited_disconnect">Unsolicited Gateway Disconnection</a> section below.</p>
<h2><a class="anchor" id="doc_cc_mqttsn_client_disconnect_prepare"></a>
Preparing "Disconnect" Operation.</h2>
<div class="fragment"><div class="line"><a class="code" href="group__global.html#gade7e7c53c5ca30c6134f60607b01079f">CC_MqttsnErrorCode</a> ec = <a class="code" href="group__global.html#ggade7e7c53c5ca30c6134f60607b01079faa71957fe69fa1b94d1d0cbc3c7558e1f">CC_MqttsnErrorCode_Success</a>;</div>
<div class="line"><a class="code" href="group__disconnect.html#ga04022e3fd06ebba9a13832224f4c3ff3">CC_MqttsnDisconnectHandle</a> disconnect = <a class="code" href="group__disconnect.html#ga709ddc5f66c73f4c750b651e3061eb5a">cc_mqttsn_client_disconnect_prepare</a>(client, &ec);</div>
<div class="line"><span class="keywordflow">if</span> (disconnect == NULL) {</div>
<div class="line"> printf(<span class="stringliteral">"ERROR: Disconnect allocation failed with ec=%d\n"</span>, ec);</div>
<div class="line">}</div>
<div class="ttc" id="agroup__disconnect_html_ga04022e3fd06ebba9a13832224f4c3ff3"><div class="ttname"><a href="group__disconnect.html#ga04022e3fd06ebba9a13832224f4c3ff3">CC_MqttsnDisconnectHandle</a></div><div class="ttdeci">struct CC_MqttsnDisconnect * CC_MqttsnDisconnectHandle</div><div class="ttdoc">Handle for "disconnect" operation.</div><div class="ttdef"><b>Definition:</b> common.h:171</div></div>
<div class="ttc" id="agroup__disconnect_html_ga709ddc5f66c73f4c750b651e3061eb5a"><div class="ttname"><a href="group__disconnect.html#ga709ddc5f66c73f4c750b651e3061eb5a">cc_mqttsn_client_disconnect_prepare</a></div><div class="ttdeci">CC_MqttsnDisconnectHandle cc_mqttsn_client_disconnect_prepare(CC_MqttsnClientHandle client, CC_MqttsnErrorCode *ec)</div><div class="ttdoc">Prepare "disconnect" operation.</div></div>
</div><!-- fragment --><h2><a class="anchor" id="doc_cc_mqttsn_client_disconnect_retry_period"></a>
Configuring "Disconnect" Retry Period</h2>
<p>When created, the "disconnect" operation inherits the <a class="el" href="index.html#doc_cc_mqttsn_client_retry_period">Default Retry Period</a> configuration. It can be changed for the allocated operation using the <b><a class="el" href="group__disconnect.html#gae9b5167b777bc16c0ea9157c5325771a" title="Configure the retry period for the "disconnect" operation.">cc_mqttsn_client_disconnect_set_retry_period()</a></b> function. </p><div class="fragment"><div class="line">ec = <a class="code" href="group__disconnect.html#gae9b5167b777bc16c0ea9157c5325771a">cc_mqttsn_client_disconnect_set_retry_period</a>(disconnect, 1000);</div>
<div class="line"><span class="keywordflow">if</span> (ec != <a class="code" href="group__global.html#ggade7e7c53c5ca30c6134f60607b01079faa71957fe69fa1b94d1d0cbc3c7558e1f">CC_MqttsnErrorCode_Success</a>) {</div>
<div class="line"> ... <span class="comment">/* Something went wrong */</span></div>
<div class="line">}</div>
<div class="ttc" id="agroup__disconnect_html_gae9b5167b777bc16c0ea9157c5325771a"><div class="ttname"><a href="group__disconnect.html#gae9b5167b777bc16c0ea9157c5325771a">cc_mqttsn_client_disconnect_set_retry_period</a></div><div class="ttdeci">CC_MqttsnErrorCode cc_mqttsn_client_disconnect_set_retry_period(CC_MqttsnDisconnectHandle handle, unsigned ms)</div><div class="ttdoc">Configure the retry period for the "disconnect" operation.</div></div>
</div><!-- fragment --><p> To retrieve the configured response timeout use the <b><a class="el" href="group__disconnect.html#ga3dc5976ef418a7f0385dfe49613b8007" title="Retrieve the configured retry period for the "disconnect" operation.">cc_mqttsn_client_disconnect_get_retry_period()</a></b> function.</p>
<h2><a class="anchor" id="doc_cc_mqttsn_client_disconnect_retry_count"></a>
Configuring "Disconnect" Retry Count</h2>
<p>When created, the "disconnect" operation inherits the <a class="el" href="index.html#doc_cc_mqttsn_client_retry_count">Default Retry Count</a> configuration. It can be changed for the allocated operation using the <b><a class="el" href="group__disconnect.html#ga6b41c7c3379bca9c53ce79bb4764b40d" title="Configure the retry count for the "disconnect" operation.">cc_mqttsn_client_disconnect_set_retry_count()</a></b> function. </p><div class="fragment"><div class="line">ec = <a class="code" href="group__disconnect.html#ga6b41c7c3379bca9c53ce79bb4764b40d">cc_mqttsn_client_disconnect_set_retry_count</a>(disconnect, 2);</div>
<div class="line"><span class="keywordflow">if</span> (ec != <a class="code" href="group__global.html#ggade7e7c53c5ca30c6134f60607b01079faa71957fe69fa1b94d1d0cbc3c7558e1f">CC_MqttsnErrorCode_Success</a>) {</div>
<div class="line"> ... <span class="comment">/* Something went wrong */</span></div>
<div class="line">}</div>
<div class="ttc" id="agroup__disconnect_html_ga6b41c7c3379bca9c53ce79bb4764b40d"><div class="ttname"><a href="group__disconnect.html#ga6b41c7c3379bca9c53ce79bb4764b40d">cc_mqttsn_client_disconnect_set_retry_count</a></div><div class="ttdeci">CC_MqttsnErrorCode cc_mqttsn_client_disconnect_set_retry_count(CC_MqttsnDisconnectHandle handle, unsigned count)</div><div class="ttdoc">Configure the retry count for the "disconnect" operation.</div></div>
</div><!-- fragment --><p> To retrieve the configured response timeout use the <b><a class="el" href="group__disconnect.html#ga353fe93b18ead450d3ee1b643f457700" title="Retrieve the configured retry count for the "disconnect" operation.">cc_mqttsn_client_disconnect_get_retry_count()</a></b> function.</p>
<h2><a class="anchor" id="doc_cc_mqttsn_client_disconnect_send"></a>
Sending Disconnection Request</h2>
<p>When the necessary configuration is performed for the allocated "disconnect" operation it can be sent to the gateway. To initiate sending use the <b><a class="el" href="group__disconnect.html#ga6bb5af2a1d022ee2634ae72275307912" title="Send the "disconnect" operation.">cc_mqttsn_client_disconnect_send()</a></b> function. </p><div class="fragment"><div class="line"><span class="keywordtype">void</span> my_disconnect_complete_cb(<span class="keywordtype">void</span>* data, <a class="code" href="group__global.html#gab0af1cb13f466184b8ecc4b1a86ec55f">CC_MqttsnAsyncOpStatus</a> status)</div>
<div class="line">{</div>
<div class="line"> <span class="keywordflow">if</span> (status != <a class="code" href="group__global.html#ggab0af1cb13f466184b8ecc4b1a86ec55fa8151e18fea364efd22acf9589fa3323c">CC_MqttsnAsyncOpStatus_Complete</a>) {</div>
<div class="line"> printf(<span class="stringliteral">"ERROR: The disconnection operation has failed with status=%d\n"</span>, status);</div>
<div class="line"> ... <span class="comment">// handle error.</span></div>
<div class="line"> <span class="keywordflow">return</span>;</div>
<div class="line"> }</div>
<div class="line"> ...</div>
<div class="line">}</div>
<div class="line"> </div>
<div class="line">ec = <a class="code" href="group__disconnect.html#ga6bb5af2a1d022ee2634ae72275307912">cc_mqttsn_client_disconnect_send</a>(disconnect, &my_disconnect_complete_cb, data);</div>
<div class="line"><span class="keywordflow">if</span> (ec != <a class="code" href="group__global.html#ggade7e7c53c5ca30c6134f60607b01079faa71957fe69fa1b94d1d0cbc3c7558e1f">CC_MqttsnErrorCode_Success</a>) {</div>
<div class="line"> printf(<span class="stringliteral">"ERROR: Failed to send disconnect request with ec=%d\n"</span>, ec);</div>
<div class="line"> ...</div>
<div class="line">}</div>
<div class="ttc" id="agroup__disconnect_html_ga6bb5af2a1d022ee2634ae72275307912"><div class="ttname"><a href="group__disconnect.html#ga6bb5af2a1d022ee2634ae72275307912">cc_mqttsn_client_disconnect_send</a></div><div class="ttdeci">CC_MqttsnErrorCode cc_mqttsn_client_disconnect_send(CC_MqttsnDisconnectHandle handle, CC_MqttsnDisconnectCompleteCb cb, void *cbData)</div><div class="ttdoc">Send the "disconnect" operation.</div></div>
</div><!-- fragment --><p> The provided callback will be invoked when the "disconnect" operation is complete <b> if and only if</b> the function returns <a class="el" href="group__global.html#ggade7e7c53c5ca30c6134f60607b01079faa71957fe69fa1b94d1d0cbc3c7558e1f">CC_MqttsnErrorCode_Success</a>.</p>
<p>The handle returned by the <b><a class="el" href="group__disconnect.html#ga709ddc5f66c73f4c750b651e3061eb5a" title="Prepare "disconnect" operation.">cc_mqttsn_client_disconnect_prepare()</a></b> function can be discarded (there is no free / de-allocation) right after the <b><a class="el" href="group__disconnect.html#ga6bb5af2a1d022ee2634ae72275307912" title="Send the "disconnect" operation.">cc_mqttsn_client_disconnect_send()</a></b> invocation regardless of the returned error code. However, the handle remains valid until the callback is called (in case the <a class="el" href="group__global.html#ggade7e7c53c5ca30c6134f60607b01079faa71957fe69fa1b94d1d0cbc3c7558e1f">CC_MqttsnErrorCode_Success</a> was returned). The valid handle can be used to <a class="el" href="index.html#doc_cc_mqttsn_client_disconnect_cancel">cancel</a> the operation before the completion callback is invoked.</p>
<p><b>NOTE</b> that only single "connect" / "disconnect" / "sleep" operation is allowed at a time, any attempt to prepare a new one via <b><a class="el" href="group__disconnect.html#ga709ddc5f66c73f4c750b651e3061eb5a" title="Prepare "disconnect" operation.">cc_mqttsn_client_disconnect_prepare()</a></b> will be rejected until the blocking operation completion callback is invoked or the operation is <a class="el" href="index.html#doc_cc_mqttsn_client_disconnect_cancel">cancelled</a>.</p>
<p>In case there are other asynchronous operations that hasn't been completed yet, their completion callback is automatically invoked with <a class="el" href="group__global.html#ggab0af1cb13f466184b8ecc4b1a86ec55fa3c36cd944f5865d6b7d0055d02750478">CC_MqttsnAsyncOpStatus_Aborted</a> status.</p>
<p><b>IMPORTANT:</b> In case of sending the explicit disconnection request the <a class="el" href="index.html#doc_cc_mqttsn_client_callbacks_gateway_disconnect">registered unsolicited disconnection callback</a> is <b>NOT</b> invoked.</p>
<p>After the disconnection the application can re-establish network connection to the gateway (if needed) and perform the <a class="el" href="index.html#doc_cc_mqttsn_client_connect">connect</a> operation again.</p>
<h2><a class="anchor" id="doc_cc_mqttsn_client_disconnect_cancel"></a>
Cancel the "Disconnect" Operation.</h2>
<p>While the handle returned by the <b><a class="el" href="group__disconnect.html#ga709ddc5f66c73f4c750b651e3061eb5a" title="Prepare "disconnect" operation.">cc_mqttsn_client_disconnect_prepare()</a></b> is still valid it is possible to cancel / discard the operation. </p><div class="fragment"><div class="line">ec = <a class="code" href="group__disconnect.html#gaca3f601b33c6fe40690a478efff89ade">cc_mqttsn_client_disconnect_cancel</a>(disconnect);</div>
<div class="line"><span class="keywordflow">if</span> (ec != <a class="code" href="group__global.html#ggade7e7c53c5ca30c6134f60607b01079faa71957fe69fa1b94d1d0cbc3c7558e1f">CC_MqttsnErrorCode_Success</a>) {</div>
<div class="line"> printf(<span class="stringliteral">"ERROR: Failed to cancel disconnect with ec=%d\n"</span>, ec);</div>
<div class="line"> ...</div>
<div class="line">}</div>
<div class="ttc" id="agroup__disconnect_html_gaca3f601b33c6fe40690a478efff89ade"><div class="ttname"><a href="group__disconnect.html#gaca3f601b33c6fe40690a478efff89ade">cc_mqttsn_client_disconnect_cancel</a></div><div class="ttdeci">CC_MqttsnErrorCode cc_mqttsn_client_disconnect_cancel(CC_MqttsnDisconnectHandle handle)</div><div class="ttdoc">Cancel the allocated "disconnect" operation.</div></div>
</div><!-- fragment --><h2><a class="anchor" id="doc_cc_mqttsn_client_disconnect_simplify"></a>
Simplifying the "Disconnect" Operation Preparation.</h2>
<p>In many use cases the "disconnect" operation can be quite simple. To simplify the sequence of the operation preparation and handling of errors, the library provides wrapper function(s) that can be used: </p><ul>
<li><b><a class="el" href="group__disconnect.html#ga031c683f64b06b3f97315ddfcd481893" title="Prepare and send "disconnect" request in one go.">cc_mqttsn_client_disconnect()</a></b> </li>
</ul>
<p>For example: </p><div class="fragment"><div class="line">ec = <a class="code" href="group__disconnect.html#ga031c683f64b06b3f97315ddfcd481893">cc_mqttsn_client_disconnect</a>(client, &my_disconnect_complete_cb, data);</div>
<div class="line"><span class="keywordflow">if</span> (ec != <a class="code" href="group__global.html#ggade7e7c53c5ca30c6134f60607b01079faa71957fe69fa1b94d1d0cbc3c7558e1f">CC_MqttsnErrorCode_Success</a>) {</div>
<div class="line"> printf(<span class="stringliteral">"ERROR: Failed to send disconnect request with ec=%d\n"</span>, ec);</div>
<div class="line"> ...</div>
<div class="line">}</div>
<div class="ttc" id="agroup__disconnect_html_ga031c683f64b06b3f97315ddfcd481893"><div class="ttname"><a href="group__disconnect.html#ga031c683f64b06b3f97315ddfcd481893">cc_mqttsn_client_disconnect</a></div><div class="ttdeci">CC_MqttsnErrorCode cc_mqttsn_client_disconnect(CC_MqttsnClientHandle client, CC_MqttsnDisconnectCompleteCb cb, void *cbData)</div><div class="ttdoc">Prepare and send "disconnect" request in one go.</div></div>
</div><!-- fragment --><h1><a class="anchor" id="doc_cc_mqttsn_client_subscribe"></a>
Subscribing to Receive Messages</h1>
<p>To subscribe to receive incoming messages use <a class="el" href="group__subscribe.html">subscribe</a> operation. The application can issue multiple "subscribe" operations in parallel.</p>
<h2><a class="anchor" id="doc_cc_mqttsn_client_subscribe_prepare"></a>
Preparing "Subscribe" Operation.</h2>
<div class="fragment"><div class="line"><a class="code" href="group__global.html#gade7e7c53c5ca30c6134f60607b01079f">CC_MqttsnErrorCode</a> ec = <a class="code" href="group__global.html#ggade7e7c53c5ca30c6134f60607b01079faa71957fe69fa1b94d1d0cbc3c7558e1f">CC_MqttsnErrorCode_Success</a>;</div>
<div class="line"><a class="code" href="group__subscribe.html#ga7671bb34c5f4d33f498404fbe3c533c7">CC_MqttsnSubscribeHandle</a> subscribe = <a class="code" href="group__subscribe.html#ga3091b015e0703efbbc6909ad15dca798">cc_mqttsn_client_subscribe_prepare</a>(client, &ec);</div>
<div class="line"><span class="keywordflow">if</span> (subscribe == NULL) {</div>
<div class="line"> printf(<span class="stringliteral">"ERROR: Subscribe allocation failed with ec=%d\n"</span>, ec);</div>
<div class="line">}</div>
</div><!-- fragment --><h2><a class="anchor" id="doc_cc_mqttsn_client_subscribe_retry_period"></a>
Configuring "Subscribe" Retry Period</h2>
<p>When created, the "subscribe" operation inherits the <a class="el" href="index.html#doc_cc_mqttsn_client_retry_period">Default Retry Period</a> configuration. It can be changed for the allocated operation using the <b><a class="el" href="group__subscribe.html#gacd856ca1c02c9512f8d079ff0b60ac71" title="Configure the retry period for the "subscribe" operation.">cc_mqttsn_client_subscribe_set_retry_period()</a></b> function. </p><div class="fragment"><div class="line">ec = <a class="code" href="group__subscribe.html#gacd856ca1c02c9512f8d079ff0b60ac71">cc_mqttsn_client_subscribe_set_retry_period</a>(subscribe, 1000);</div>
<div class="line"><span class="keywordflow">if</span> (ec != <a class="code" href="group__global.html#ggade7e7c53c5ca30c6134f60607b01079faa71957fe69fa1b94d1d0cbc3c7558e1f">CC_MqttsnErrorCode_Success</a>) {</div>
<div class="line"> ... <span class="comment">/* Something went wrong */</span></div>
<div class="line">}</div>
<div class="ttc" id="agroup__subscribe_html_gacd856ca1c02c9512f8d079ff0b60ac71"><div class="ttname"><a href="group__subscribe.html#gacd856ca1c02c9512f8d079ff0b60ac71">cc_mqttsn_client_subscribe_set_retry_period</a></div><div class="ttdeci">CC_MqttsnErrorCode cc_mqttsn_client_subscribe_set_retry_period(CC_MqttsnSubscribeHandle handle, unsigned ms)</div><div class="ttdoc">Configure the retry period for the "subscribe" operation.</div></div>
</div><!-- fragment --><p> To retrieve the configured response timeout use the <b><a class="el" href="group__subscribe.html#ga3bdc813549fbff0faa1177c59705dcc9" title="Retrieve the configured retry period for the "subscribe" operation.">cc_mqttsn_client_subscribe_get_retry_period()</a></b> function.</p>
<h2><a class="anchor" id="doc_cc_mqttsn_client_subscribe_retry_count"></a>
Configuring "Subscribe" Retry Count</h2>
<p>When created, the "subscribe" operation inherits the <a class="el" href="index.html#doc_cc_mqttsn_client_retry_count">Default Retry Count</a> configuration. It can be changed for the allocated operation using the <b><a class="el" href="group__subscribe.html#gaad27e8c00d3b9236da17b815852d7e03" title="Configure the retry count for the "subscribe" operation.">cc_mqttsn_client_subscribe_set_retry_count()</a></b> function. </p><div class="fragment"><div class="line">ec = <a class="code" href="group__subscribe.html#gaad27e8c00d3b9236da17b815852d7e03">cc_mqttsn_client_subscribe_set_retry_count</a>(subscribe, 2);</div>
<div class="line"><span class="keywordflow">if</span> (ec != <a class="code" href="group__global.html#ggade7e7c53c5ca30c6134f60607b01079faa71957fe69fa1b94d1d0cbc3c7558e1f">CC_MqttsnErrorCode_Success</a>) {</div>
<div class="line"> ... <span class="comment">/* Something went wrong */</span></div>
<div class="line">}</div>
<div class="ttc" id="agroup__subscribe_html_gaad27e8c00d3b9236da17b815852d7e03"><div class="ttname"><a href="group__subscribe.html#gaad27e8c00d3b9236da17b815852d7e03">cc_mqttsn_client_subscribe_set_retry_count</a></div><div class="ttdeci">CC_MqttsnErrorCode cc_mqttsn_client_subscribe_set_retry_count(CC_MqttsnSubscribeHandle handle, unsigned count)</div><div class="ttdoc">Configure the retry count for the "subscribe" operation.</div></div>
</div><!-- fragment --><p> To retrieve the configured response timeout use the <b><a class="el" href="group__subscribe.html#ga2c05d997c5ed31c03e22c46a74ecd6ce" title="Retrieve the configured retry count for the "subscribe" operation.">cc_mqttsn_client_subscribe_get_retry_count()</a></b> function.</p>
<h2><a class="anchor" id="doc_cc_mqttsn_client_subscribe_config"></a>
Subscribe Configuration</h2>
<p>To configure "subscribe" operation use <b><a class="el" href="group__subscribe.html#ga55da11762083b06f9a9cf2d14ee2cbae" title="Perform configuration of the "subscribe" operation.">cc_mqttsn_client_subscribe_config()</a></b> function. </p><div class="fragment"><div class="line"><a class="code" href="structCC__MqttsnSubscribeConfig.html">CC_MqttsnSubscribeConfig</a> config;</div>
<div class="line"> </div>
<div class="line"><span class="comment">// Assign default values to the configuration</span></div>
<div class="line"><a class="code" href="group__subscribe.html#gae36ee47ba5a631559f5806799a1daddb">cc_mqttsn_client_subscribe_init_config</a>(&config);</div>
<div class="line">assert(config.<a class="code" href="structCC__MqttsnSubscribeConfig.html#ad04e5922eea5a9be28c231ecc4cd81c1">m_qos</a> == <a class="code" href="group__global.html#ggadf1bd91b9b557d00ba1d2fbd604151a6a768097d6c1c08cc69b85848c28db31f5">CC_MqttsnQoS_ExactlyOnceDelivery</a>); <span class="comment">// Initialization puts the maximum allowed QoS</span></div>
<div class="line"> </div>
<div class="line"><span class="comment">// Update values if needed</span></div>
<div class="line">config.<a class="code" href="structCC__MqttsnSubscribeConfig.html#a28f5b1f247108f532ae8d48b0141460e">m_topic</a> = <span class="stringliteral">"some/topic"</span>;</div>
<div class="line"> </div>
<div class="line"><span class="comment">// Perform the configuration</span></div>
<div class="line">ec = <a class="code" href="group__subscribe.html#ga55da11762083b06f9a9cf2d14ee2cbae">cc_mqttsn_client_subscribe_config</a>(subscribe, &config);</div>
<div class="line"><span class="keywordflow">if</span> (ec != <a class="code" href="group__global.html#ggade7e7c53c5ca30c6134f60607b01079faa71957fe69fa1b94d1d0cbc3c7558e1f">CC_MqttsnErrorCode_Success</a>) {</div>
<div class="line"> printf(<span class="stringliteral">"ERROR: Topic configuration failed with ec=%d\n"</span>, ec);</div>
<div class="line"> ...</div>
<div class="line">}</div>
<div class="ttc" id="agroup__global_html_ggadf1bd91b9b557d00ba1d2fbd604151a6a768097d6c1c08cc69b85848c28db31f5"><div class="ttname"><a href="group__global.html#ggadf1bd91b9b557d00ba1d2fbd604151a6a768097d6c1c08cc69b85848c28db31f5">CC_MqttsnQoS_ExactlyOnceDelivery</a></div><div class="ttdeci">@ CC_MqttsnQoS_ExactlyOnceDelivery</div><div class="ttdoc">QoS=2. Exactly once delivery.</div><div class="ttdef"><b>Definition:</b> common.h:46</div></div>
<div class="ttc" id="agroup__subscribe_html_ga55da11762083b06f9a9cf2d14ee2cbae"><div class="ttname"><a href="group__subscribe.html#ga55da11762083b06f9a9cf2d14ee2cbae">cc_mqttsn_client_subscribe_config</a></div><div class="ttdeci">CC_MqttsnErrorCode cc_mqttsn_client_subscribe_config(CC_MqttsnSubscribeHandle handle, const CC_MqttsnSubscribeConfig *config)</div><div class="ttdoc">Perform configuration of the "subscribe" operation.</div></div>
<div class="ttc" id="agroup__subscribe_html_gae36ee47ba5a631559f5806799a1daddb"><div class="ttname"><a href="group__subscribe.html#gae36ee47ba5a631559f5806799a1daddb">cc_mqttsn_client_subscribe_init_config</a></div><div class="ttdeci">void cc_mqttsn_client_subscribe_init_config(CC_MqttsnSubscribeConfig *config)</div><div class="ttdoc">Intialize the CC_MqttsnSubscribeConfig configuration structure.</div></div>
<div class="ttc" id="astructCC__MqttsnSubscribeConfig_html"><div class="ttname"><a href="structCC__MqttsnSubscribeConfig.html">CC_MqttsnSubscribeConfig</a></div><div class="ttdoc">Configuration the "subscribe" operation.</div><div class="ttdef"><b>Definition:</b> common.h:273</div></div>
<div class="ttc" id="astructCC__MqttsnSubscribeConfig_html_a28f5b1f247108f532ae8d48b0141460e"><div class="ttname"><a href="structCC__MqttsnSubscribeConfig.html#a28f5b1f247108f532ae8d48b0141460e">CC_MqttsnSubscribeConfig::m_topic</a></div><div class="ttdeci">const char * m_topic</div><div class="ttdoc">Subscription topic, can be NULL when pre-defined topic ID is used.</div><div class="ttdef"><b>Definition:</b> common.h:274</div></div>
<div class="ttc" id="astructCC__MqttsnSubscribeConfig_html_ad04e5922eea5a9be28c231ecc4cd81c1"><div class="ttname"><a href="structCC__MqttsnSubscribeConfig.html#ad04e5922eea5a9be28c231ecc4cd81c1">CC_MqttsnSubscribeConfig::m_qos</a></div><div class="ttdeci">CC_MqttsnQoS m_qos</div><div class="ttdoc">Max QoS value.</div><div class="ttdef"><b>Definition:</b> common.h:276</div></div>
</div><!-- fragment --><p> When there is a need to use a predefined topic id instead of the topic string use <a class="el" href="structCC__MqttsnSubscribeConfig.html#a36773e9cb84514a09c9a6dfcd2072433">m_topicId</a> member instead of <a class="el" href="structCC__MqttsnSubscribeConfig.html#a28f5b1f247108f532ae8d48b0141460e">m_topic</a>. </p><div class="fragment"><div class="line"><span class="comment">// Assign default values to the configuration</span></div>
<div class="line"><a class="code" href="group__subscribe.html#gae36ee47ba5a631559f5806799a1daddb">cc_mqttsn_client_subscribe_init_config</a>(&config);</div>
<div class="line"> </div>
<div class="line"><span class="comment">// Update values if needed</span></div>
<div class="line">config.<a class="code" href="structCC__MqttsnSubscribeConfig.html#a36773e9cb84514a09c9a6dfcd2072433">m_topicId</a> = 123;</div>
<div class="ttc" id="astructCC__MqttsnSubscribeConfig_html_a36773e9cb84514a09c9a6dfcd2072433"><div class="ttname"><a href="structCC__MqttsnSubscribeConfig.html#a36773e9cb84514a09c9a6dfcd2072433">CC_MqttsnSubscribeConfig::m_topicId</a></div><div class="ttdeci">CC_MqttsnTopicId m_topicId</div><div class="ttdoc">Pre-defined topic ID, should be 0 when topic is not NULL.</div><div class="ttdef"><b>Definition:</b> common.h:275</div></div>
</div><!-- fragment --><p> See also documentation of the <a class="el" href="structCC__MqttsnSubscribeConfig.html">CC_MqttsnSubscribeConfig</a> structure.</p>
<p>The MQTT-SN specification also specifies short topics of 2 byte length. The library detects this case by analysing the string assigned to the <a class="el" href="structCC__MqttsnSubscribeConfig.html#a28f5b1f247108f532ae8d48b0141460e">m_topic</a> member and uses appropriate message configuration if needed.</p>
<p>By default the library will perform the analysis of the submitted topic format and reject it if topic format is incorrect. However, for performance reasons it is possible to disable such verification when client application ensures that no invalid topics are used. </p><div class="fragment"><div class="line">ec = <a class="code" href="group__client.html#ga0bd029baf641267fcf18580704246ac4">cc_mqttsn_client_set_verify_outgoing_topic_enabled</a>(client, <span class="keyword">false</span>);</div>
<div class="line"><span class="keywordflow">if</span> (ec != <a class="code" href="group__global.html#ggade7e7c53c5ca30c6134f60607b01079faa71957fe69fa1b94d1d0cbc3c7558e1f">CC_MqttsnErrorCode_Success</a>) {</div>
<div class="line"> ... <span class="comment">/* Something is wrong */</span></div>
<div class="line">}</div>
<div class="ttc" id="agroup__client_html_ga0bd029baf641267fcf18580704246ac4"><div class="ttname"><a href="group__client.html#ga0bd029baf641267fcf18580704246ac4">cc_mqttsn_client_set_verify_outgoing_topic_enabled</a></div><div class="ttdeci">CC_MqttsnErrorCode cc_mqttsn_client_set_verify_outgoing_topic_enabled(CC_MqttsnClientHandle client, bool enabled)</div><div class="ttdoc">Control outgoing topic format verification.</div></div>
</div><!-- fragment --><p> <b>NOTE</b> that the configuration is global per client and not per "subscribe" operation.</p>
<p>Also <b>note</b> that the same function controls the verification of the "subscribe", "unsubscribe" and "publish" topic formats.</p>
<p>To retrieve the current configuration use <b><a class="el" href="group__client.html#gaf81914ccda622d45808da56a49226aeb" title="Retrieve current outgoing topic format verification control.">cc_mqttsn_client_get_verify_outgoing_topic_enabled()</a></b> function.</p>
<h2><a class="anchor" id="doc_cc_mqttsn_client_subscribe_send"></a>
Sending Subscription Request</h2>
<p>When all the necessary configurations are performed for the allocated "subscribe" operation it can actually be sent to the gateway. To initiate sending use the <b><a class="el" href="group__subscribe.html#ga8543790da308f013c7524be7f0b9b517" title="Send the "subscribe" operation.">cc_mqttsn_client_subscribe_send()</a></b> function. </p><div class="fragment"><div class="line"><span class="keywordtype">void</span> my_subscribe_complete_cb(<span class="keywordtype">void</span>* data, <a class="code" href="group__subscribe.html#ga7671bb34c5f4d33f498404fbe3c533c7">CC_MqttsnSubscribeHandle</a> handle, <a class="code" href="group__global.html#gab0af1cb13f466184b8ecc4b1a86ec55f">CC_MqttsnAsyncOpStatus</a> status, <span class="keyword">const</span> <a class="code" href="structCC__MqttsnSubscribeInfo.html">CC_MqttsnSubscribeInfo</a>* info)</div>
<div class="line">{</div>
<div class="line"> <span class="keywordflow">if</span> (status != <a class="code" href="group__global.html#ggab0af1cb13f466184b8ecc4b1a86ec55fa8151e18fea364efd22acf9589fa3323c">CC_MqttsnAsyncOpStatus_Complete</a>) {</div>
<div class="line"> printf(<span class="stringliteral">"ERROR: The subscription operation has failed with status=%d\n"</span>, status);</div>
<div class="line"> ... <span class="comment">// handle error.</span></div>
<div class="line"> <span class="keywordflow">return</span>;</div>
<div class="line"> }</div>
<div class="line"> </div>
<div class="line"> <span class="comment">// "info" is not NULL when status is CC_MqttsnAsyncOpStatus_Complete.</span></div>
<div class="line"> assert(info != NULL);</div>
<div class="line"> ... <span class="comment">// Analyze response values.</span></div>
<div class="line">}</div>
<div class="line"> </div>
<div class="line">ec = <a class="code" href="group__subscribe.html#ga8543790da308f013c7524be7f0b9b517">cc_mqttsn_client_subscribe_send</a>(subscribe, &my_subscribe_complete_cb, data);</div>
<div class="line"><span class="keywordflow">if</span> (ec != <a class="code" href="group__global.html#ggade7e7c53c5ca30c6134f60607b01079faa71957fe69fa1b94d1d0cbc3c7558e1f">CC_MqttsnErrorCode_Success</a>) {</div>
<div class="line"> printf(<span class="stringliteral">"ERROR: Failed to send subscribe request with ec=%d\n"</span>, ec);</div>
<div class="line"> ...</div>
<div class="line">}</div>
<div class="ttc" id="agroup__subscribe_html_ga8543790da308f013c7524be7f0b9b517"><div class="ttname"><a href="group__subscribe.html#ga8543790da308f013c7524be7f0b9b517">cc_mqttsn_client_subscribe_send</a></div><div class="ttdeci">CC_MqttsnErrorCode cc_mqttsn_client_subscribe_send(CC_MqttsnSubscribeHandle handle, CC_MqttsnSubscribeCompleteCb cb, void *cbData)</div><div class="ttdoc">Send the "subscribe" operation.</div></div>
<div class="ttc" id="astructCC__MqttsnSubscribeInfo_html"><div class="ttname"><a href="structCC__MqttsnSubscribeInfo.html">CC_MqttsnSubscribeInfo</a></div><div class="ttdoc">Information on the "subscribe" operation completion.</div><div class="ttdef"><b>Definition:</b> common.h:282</div></div>
</div><!-- fragment --><p> The provided callback will be invoked when the "subscribe" operation is complete <b> if and only if</b> the function returns <a class="el" href="group__global.html#ggade7e7c53c5ca30c6134f60607b01079faa71957fe69fa1b94d1d0cbc3c7558e1f">CC_MqttsnErrorCode_Success</a>.</p>
<p>The handle returned by the <b><a class="el" href="group__subscribe.html#ga3091b015e0703efbbc6909ad15dca798" title="Prepare "subscribe" operation.">cc_mqttsn_client_subscribe_prepare()</a></b> function can be discarded (there is no free / de-allocation) right after the <b><a class="el" href="group__subscribe.html#ga8543790da308f013c7524be7f0b9b517" title="Send the "subscribe" operation.">cc_mqttsn_client_subscribe_send()</a></b> invocation regardless of the returned error code. However, the handle remains valid until the callback is called (in case the <a class="el" href="group__global.html#ggade7e7c53c5ca30c6134f60607b01079faa71957fe69fa1b94d1d0cbc3c7558e1f">CC_MqttsnErrorCode_Success</a> was returned). The valid handle can be used to <a class="el" href="index.html#doc_cc_mqttsn_client_subscribe_cancel">cancel</a> the operation before the completion callback is invoked.</p>
<p>The MQTT-SN spec demands that the <b>SUBSCRIBE</b> transactions be issued one at a time. However, the library allows <a class="el" href="index.html#doc_cc_mqttsn_client_subscribe_prepare">preparing</a> and <a class="el" href="index.html#doc_cc_mqttsn_client_subscribe_send">sending</a> multiple subscription requests in parallel before completion of the first one. The library will retain the requested "subscribe" operation requests internally and will issue them one after another to comply with the specification.</p>
<p>Note that the callback function receives the "subscribe" operation handle as its second parameter. Although the handle is already invalid and cannot be used in any other function, it allows the application to identify the original "subscribe" request if multiple have been issued in parallel and use the same callback function for all of them.</p>
<p>When the "subscribe" operation completion callback is invoked the reported response information is present <b>if and only if</b> the "status" is <a class="el" href="group__global.html#ggab0af1cb13f466184b8ecc4b1a86ec55fa8151e18fea364efd22acf9589fa3323c">CC_MqttsnAsyncOpStatus_Complete</a>.</p>
<h2><a class="anchor" id="doc_cc_mqttsn_client_subscribe_cancel"></a>
Cancel the "Subscribe" Operation.</h2>
<p>While the handle returned by the <b><a class="el" href="group__subscribe.html#ga3091b015e0703efbbc6909ad15dca798" title="Prepare "subscribe" operation.">cc_mqttsn_client_subscribe_prepare()</a></b> is still valid it is possible to cancel / discard the operation. </p><div class="fragment"><div class="line">ec = <a class="code" href="group__subscribe.html#gabb4d3d2a3863123be6de28c74a015863">cc_mqttsn_client_subscribe_cancel</a>(subscribe);</div>
<div class="line"><span class="keywordflow">if</span> (ec != <a class="code" href="group__global.html#ggade7e7c53c5ca30c6134f60607b01079faa71957fe69fa1b94d1d0cbc3c7558e1f">CC_MqttsnErrorCode_Success</a>) {</div>
<div class="line"> printf(<span class="stringliteral">"ERROR: Failed to cancel subscribe with ec=%d\n"</span>, ec);</div>
<div class="line"> ...</div>
<div class="line">}</div>
<div class="ttc" id="agroup__subscribe_html_gabb4d3d2a3863123be6de28c74a015863"><div class="ttname"><a href="group__subscribe.html#gabb4d3d2a3863123be6de28c74a015863">cc_mqttsn_client_subscribe_cancel</a></div><div class="ttdeci">CC_MqttsnErrorCode cc_mqttsn_client_subscribe_cancel(CC_MqttsnSubscribeHandle handle)</div><div class="ttdoc">Cancel the allocated "subscribe" operation.</div></div>
</div><!-- fragment --><p> In case the <b><a class="el" href="group__subscribe.html#ga8543790da308f013c7524be7f0b9b517" title="Send the "subscribe" operation.">cc_mqttsn_client_subscribe_send()</a></b> function was successfully called before the <b><a class="el" href="group__subscribe.html#gabb4d3d2a3863123be6de28c74a015863" title="Cancel the allocated "subscribe" operation.">cc_mqttsn_client_subscribe_cancel()</a></b>, the operation is cancelled <b>without</b> callback invocation.</p>
<h2><a class="anchor" id="doc_cc_mqttsn_client_subscribe_simplify"></a>
Simplifying the "Subscribe" Operation Preparation.</h2>
<p>In many use cases the "subscribe" operation can be quite simple with a lot of defaults. To simplify the sequence of the operation preparation and handling of errors, the library provides wrapper function that can be used: </p><ul>
<li><b><a class="el" href="group__subscribe.html#gaea6119d9e25f715933bf31a8d93ad277" title="Prepare and send "subscribe" request in one go.">cc_mqttsn_client_subscribe()</a></b> </li>
</ul>
<p>For example: </p><div class="fragment"><div class="line"><a class="code" href="structCC__MqttsnSubscribeConfig.html">CC_MqttsnSubscribeConfig</a> config;</div>
<div class="line"> </div>
<div class="line"><span class="comment">// Assign default values to the configuration</span></div>
<div class="line"><a class="code" href="group__subscribe.html#gae36ee47ba5a631559f5806799a1daddb">cc_mqttsn_client_subscribe_init_config</a>(&config);</div>
<div class="line"> </div>
<div class="line"><span class="comment">// Update values if needed</span></div>
<div class="line">config.<a class="code" href="structCC__MqttsnSubscribeConfig.html#a28f5b1f247108f532ae8d48b0141460e">m_topic</a> = <span class="stringliteral">"some/topic"</span>;</div>
<div class="line"> </div>
<div class="line">ec = <a class="code" href="group__subscribe.html#gaea6119d9e25f715933bf31a8d93ad277">cc_mqttsn_client_subscribe</a>(client, &config, &my_subscribe_complete_cb, data);</div>
<div class="line"><span class="keywordflow">if</span> (ec != <a class="code" href="group__global.html#ggade7e7c53c5ca30c6134f60607b01079faa71957fe69fa1b94d1d0cbc3c7558e1f">CC_MqttsnErrorCode_Success</a>) {</div>
<div class="line"> printf(<span class="stringliteral">"ERROR: Failed to send subscribe request with ec=%d\n"</span>, ec);</div>
<div class="line"> ...</div>
<div class="line">}</div>
<div class="ttc" id="agroup__subscribe_html_gaea6119d9e25f715933bf31a8d93ad277"><div class="ttname"><a href="group__subscribe.html#gaea6119d9e25f715933bf31a8d93ad277">cc_mqttsn_client_subscribe</a></div><div class="ttdeci">CC_MqttsnErrorCode cc_mqttsn_client_subscribe(CC_MqttsnClientHandle client, const CC_MqttsnSubscribeConfig *config, CC_MqttsnSubscribeCompleteCb cb, void *cbData)</div><div class="ttdoc">Prepare and send "subscribe" request in one go.</div></div>
</div><!-- fragment --><p> Note that the wrapper function does NOT expose the handle returned by the <b><a class="el" href="group__subscribe.html#ga3091b015e0703efbbc6909ad15dca798" title="Prepare "subscribe" operation.">cc_mqttsn_client_subscribe_prepare()</a></b>. It means that it's not possible to cancel the "subscribe" operation before its completion or identify the subscribe operation by the reported handle when the completion callback is invoked.</p>
<h1><a class="anchor" id="doc_cc_mqttsn_client_unsubscribe"></a>
Unsubscribing from Receiving Messages</h1>
<p>To unsubscribe to receive incoming messages use <a class="el" href="group__unsubscribe.html">unsubscribe</a> operation. The application can issue multiple "unsubscribe" operations in parallel.</p>
<h2><a class="anchor" id="doc_cc_mqttsn_client_unsubscribe_prepare"></a>
Preparing "Unsubscribe" Operation.</h2>
<div class="fragment"><div class="line"><a class="code" href="group__global.html#gade7e7c53c5ca30c6134f60607b01079f">CC_MqttsnErrorCode</a> ec = <a class="code" href="group__global.html#ggade7e7c53c5ca30c6134f60607b01079faa71957fe69fa1b94d1d0cbc3c7558e1f">CC_MqttsnErrorCode_Success</a>;</div>
<div class="line"><a class="code" href="group__subscribe.html#ga02212232e0f2e963de716361b933ea6e">CC_MqttsnUnsubscribeHandle</a> unsubscribe = <a class="code" href="group__unsubscribe.html#ga809bcab51f5ac63f211aacd4d1e7cdde">cc_mqttsn_client_unsubscribe_prepare</a>(client, &ec);</div>
<div class="line"><span class="keywordflow">if</span> (unsubscribe == NULL) {</div>
<div class="line"> printf(<span class="stringliteral">"ERROR: Unsubscribe allocation failed with ec=%d\n"</span>, ec);</div>
<div class="line">}</div>
<div class="ttc" id="agroup__subscribe_html_ga02212232e0f2e963de716361b933ea6e"><div class="ttname"><a href="group__subscribe.html#ga02212232e0f2e963de716361b933ea6e">CC_MqttsnUnsubscribeHandle</a></div><div class="ttdeci">struct CC_MqttsnUnsubscribe * CC_MqttsnUnsubscribeHandle</div><div class="ttdoc">Handle for "unsubscribe" operation.</div><div class="ttdef"><b>Definition:</b> common.h:189</div></div>
<div class="ttc" id="agroup__unsubscribe_html_ga809bcab51f5ac63f211aacd4d1e7cdde"><div class="ttname"><a href="group__unsubscribe.html#ga809bcab51f5ac63f211aacd4d1e7cdde">cc_mqttsn_client_unsubscribe_prepare</a></div><div class="ttdeci">CC_MqttsnUnsubscribeHandle cc_mqttsn_client_unsubscribe_prepare(CC_MqttsnClientHandle client, CC_MqttsnErrorCode *ec)</div><div class="ttdoc">Prepare "unsubscribe" operation.</div></div>
</div><!-- fragment --><h2><a class="anchor" id="doc_cc_mqttsn_client_unsubscribe_retry_period"></a>
Configuring "Unsubscribe" Retry Period</h2>
<p>When created, the "unsubscribe" operation inherits the <a class="el" href="index.html#doc_cc_mqttsn_client_retry_period">Default Retry Period</a> configuration. It can be changed for the allocated operation using the <b><a class="el" href="group__unsubscribe.html#gaf7e9dc0a34a2054a15da6ca119bfe791" title="Configure the retry period for the "unsubscribe" operation.">cc_mqttsn_client_unsubscribe_set_retry_period()</a></b> function. </p><div class="fragment"><div class="line">ec = <a class="code" href="group__unsubscribe.html#gaf7e9dc0a34a2054a15da6ca119bfe791">cc_mqttsn_client_unsubscribe_set_retry_period</a>(unsubscribe, 1000);</div>
<div class="line"><span class="keywordflow">if</span> (ec != <a class="code" href="group__global.html#ggade7e7c53c5ca30c6134f60607b01079faa71957fe69fa1b94d1d0cbc3c7558e1f">CC_MqttsnErrorCode_Success</a>) {</div>
<div class="line"> ... <span class="comment">/* Something went wrong */</span></div>
<div class="line">}</div>
<div class="ttc" id="agroup__unsubscribe_html_gaf7e9dc0a34a2054a15da6ca119bfe791"><div class="ttname"><a href="group__unsubscribe.html#gaf7e9dc0a34a2054a15da6ca119bfe791">cc_mqttsn_client_unsubscribe_set_retry_period</a></div><div class="ttdeci">CC_MqttsnErrorCode cc_mqttsn_client_unsubscribe_set_retry_period(CC_MqttsnUnsubscribeHandle handle, unsigned ms)</div><div class="ttdoc">Configure the retry period for the "unsubscribe" operation.</div></div>
</div><!-- fragment --><p> To retrieve the configured response timeout use the <b><a class="el" href="group__unsubscribe.html#ga3aba42b30aff61a9b632ea1ab32c6aa5" title="Retrieve the configured retry period for the "unsubscribe" operation.">cc_mqttsn_client_unsubscribe_get_retry_period()</a></b> function.</p>
<h2><a class="anchor" id="doc_cc_mqttsn_client_unsubscribe_retry_count"></a>
Configuring "Unsubscribe" Retry Count</h2>
<p>When created, the "unsubscribe" operation inherits the <a class="el" href="index.html#doc_cc_mqttsn_client_retry_count">Default Retry Count</a> configuration. It can be changed for the allocated operation using the <b><a class="el" href="group__unsubscribe.html#ga78d949e80997e9392a68c607d8c28d4e" title="Configure the retry count for the "unsubscribe" operation.">cc_mqttsn_client_unsubscribe_set_retry_count()</a></b> function. </p><div class="fragment"><div class="line">ec = <a class="code" href="group__unsubscribe.html#ga78d949e80997e9392a68c607d8c28d4e">cc_mqttsn_client_unsubscribe_set_retry_count</a>(unsubscribe, 2);</div>
<div class="line"><span class="keywordflow">if</span> (ec != <a class="code" href="group__global.html#ggade7e7c53c5ca30c6134f60607b01079faa71957fe69fa1b94d1d0cbc3c7558e1f">CC_MqttsnErrorCode_Success</a>) {</div>
<div class="line"> ... <span class="comment">/* Something went wrong */</span></div>
<div class="line">}</div>
<div class="ttc" id="agroup__unsubscribe_html_ga78d949e80997e9392a68c607d8c28d4e"><div class="ttname"><a href="group__unsubscribe.html#ga78d949e80997e9392a68c607d8c28d4e">cc_mqttsn_client_unsubscribe_set_retry_count</a></div><div class="ttdeci">CC_MqttsnErrorCode cc_mqttsn_client_unsubscribe_set_retry_count(CC_MqttsnUnsubscribeHandle handle, unsigned count)</div><div class="ttdoc">Configure the retry count for the "unsubscribe" operation.</div></div>
</div><!-- fragment --><p> To retrieve the configured response timeout use the <b><a class="el" href="group__unsubscribe.html#ga82c64da21d4e53f9b4484feb9da3801e" title="Retrieve the configured retry count for the "unsubscribe" operation.">cc_mqttsn_client_unsubscribe_get_retry_count()</a></b> function.</p>
<h2><a class="anchor" id="doc_cc_mqttsn_client_unsubscribe_config"></a>
Unsubscribe Configuration</h2>
<p>To configure "unsubscribe" operation use <b><a class="el" href="group__unsubscribe.html#gad99c6cfcc7a0b728e746434a0366e7e6" title="Perform configuration of the "unsubscribe" operation.">cc_mqttsn_client_unsubscribe_config()</a></b> function. </p><div class="fragment"><div class="line"><a class="code" href="structCC__MqttsnUnsubscribeConfig.html">CC_MqttsnUnsubscribeConfig</a> config;</div>
<div class="line"> </div>
<div class="line"><span class="comment">// Assign default values to the configuration</span></div>
<div class="line"><a class="code" href="group__unsubscribe.html#gaa85b0dfe3029e8ff1e5de149000ce122">cc_mqttsn_client_unsubscribe_init_config</a>(&config);</div>
<div class="line"> </div>
<div class="line"><span class="comment">// Update values if needed</span></div>
<div class="line">config.<a class="code" href="structCC__MqttsnUnsubscribeConfig.html#ab7e885786f0692e3fd30de43a00a9b04">m_topic</a> = <span class="stringliteral">"some/topic"</span>;</div>
<div class="line"> </div>
<div class="line"><span class="comment">// Perform the configuration</span></div>
<div class="line">ec = <a class="code" href="group__unsubscribe.html#gad99c6cfcc7a0b728e746434a0366e7e6">cc_mqttsn_client_unsubscribe_config</a>(unsubscribe, &config);</div>
<div class="line"><span class="keywordflow">if</span> (ec != <a class="code" href="group__global.html#ggade7e7c53c5ca30c6134f60607b01079faa71957fe69fa1b94d1d0cbc3c7558e1f">CC_MqttsnErrorCode_Success</a>) {</div>
<div class="line"> printf(<span class="stringliteral">"ERROR: Topic configuration failed with ec=%d\n"</span>, ec);</div>
<div class="line"> ...</div>
<div class="line">}</div>
<div class="ttc" id="agroup__unsubscribe_html_gaa85b0dfe3029e8ff1e5de149000ce122"><div class="ttname"><a href="group__unsubscribe.html#gaa85b0dfe3029e8ff1e5de149000ce122">cc_mqttsn_client_unsubscribe_init_config</a></div><div class="ttdeci">void cc_mqttsn_client_unsubscribe_init_config(CC_MqttsnUnsubscribeConfig *config)</div><div class="ttdoc">Intialize the CC_MqttsnUnsubscribeConfig configuration structure.</div></div>
<div class="ttc" id="agroup__unsubscribe_html_gad99c6cfcc7a0b728e746434a0366e7e6"><div class="ttname"><a href="group__unsubscribe.html#gad99c6cfcc7a0b728e746434a0366e7e6">cc_mqttsn_client_unsubscribe_config</a></div><div class="ttdeci">CC_MqttsnErrorCode cc_mqttsn_client_unsubscribe_config(CC_MqttsnUnsubscribeHandle handle, const CC_MqttsnUnsubscribeConfig *config)</div><div class="ttdoc">Perform configuration of the "unsubscribe" operation.</div></div>
<div class="ttc" id="astructCC__MqttsnUnsubscribeConfig_html"><div class="ttname"><a href="structCC__MqttsnUnsubscribeConfig.html">CC_MqttsnUnsubscribeConfig</a></div><div class="ttdoc">Configuration the "unsubscribe" operation.</div><div class="ttdef"><b>Definition:</b> common.h:290</div></div>
<div class="ttc" id="astructCC__MqttsnUnsubscribeConfig_html_ab7e885786f0692e3fd30de43a00a9b04"><div class="ttname"><a href="structCC__MqttsnUnsubscribeConfig.html#ab7e885786f0692e3fd30de43a00a9b04">CC_MqttsnUnsubscribeConfig::m_topic</a></div><div class="ttdeci">const char * m_topic</div><div class="ttdoc">Subscription topic, can be NULL when pre-defined topic ID is used.</div><div class="ttdef"><b>Definition:</b> common.h:291</div></div>
</div><!-- fragment --><p> When there is a need to use a predefined topic id instead of the topic string use <a class="el" href="structCC__MqttsnUnsubscribeConfig.html#ad9f404f8407866971bb77c763593604c">m_topicId</a> member instead of <a class="el" href="structCC__MqttsnUnsubscribeConfig.html#ab7e885786f0692e3fd30de43a00a9b04">m_topic</a>. </p><div class="fragment"><div class="line"><span class="comment">// Assign default values to the configuration</span></div>
<div class="line"><a class="code" href="group__unsubscribe.html#gaa85b0dfe3029e8ff1e5de149000ce122">cc_mqttsn_client_unsubscribe_init_config</a>(&config);</div>
<div class="line"> </div>
<div class="line"><span class="comment">// Update values if needed</span></div>
<div class="line">config.<a class="code" href="structCC__MqttsnUnsubscribeConfig.html#ad9f404f8407866971bb77c763593604c">m_topicId</a> = 123;</div>
<div class="ttc" id="astructCC__MqttsnUnsubscribeConfig_html_ad9f404f8407866971bb77c763593604c"><div class="ttname"><a href="structCC__MqttsnUnsubscribeConfig.html#ad9f404f8407866971bb77c763593604c">CC_MqttsnUnsubscribeConfig::m_topicId</a></div><div class="ttdeci">CC_MqttsnTopicId m_topicId</div><div class="ttdoc">Pre-defined topic ID, should be 0 when topic is not NULL.</div><div class="ttdef"><b>Definition:</b> common.h:292</div></div>
</div><!-- fragment --><p> See also documentation of the <a class="el" href="structCC__MqttsnUnsubscribeConfig.html">CC_MqttsnUnsubscribeConfig</a> structure.</p>
<p>The MQTT-SN specification also specifies short topics of 2 byte length. The library detects this case by analysing the string assigned to the <a class="el" href="structCC__MqttsnUnsubscribeConfig.html#ab7e885786f0692e3fd30de43a00a9b04">m_topic</a> member and uses appropriate message configuration if needed.</p>
<p>By default the library will perform the analysis of the submitted topic format and reject it if topic format is incorrect. However, for performance reasons it is possible to disable such verification when client application ensures that no invalid topics are used. </p><div class="fragment"><div class="line">ec = <a class="code" href="group__client.html#ga0bd029baf641267fcf18580704246ac4">cc_mqttsn_client_set_verify_outgoing_topic_enabled</a>(client, <span class="keyword">false</span>);</div>
<div class="line"><span class="keywordflow">if</span> (ec != <a class="code" href="group__global.html#ggade7e7c53c5ca30c6134f60607b01079faa71957fe69fa1b94d1d0cbc3c7558e1f">CC_MqttsnErrorCode_Success</a>) {</div>
<div class="line"> ... <span class="comment">/* Something is wrong */</span></div>
<div class="line">}</div>
</div><!-- fragment --><p> <b>NOTE</b> that the configuration is global per client and not per "unsubscribe" operation.</p>
<p>Also <b>note</b> that the same function controls the verification of the "subscribe", "subscribe" and "publish" topic formats.</p>
<p>To retrieve the current configuration use <b><a class="el" href="group__client.html#gaf81914ccda622d45808da56a49226aeb" title="Retrieve current outgoing topic format verification control.">cc_mqttsn_client_get_verify_outgoing_topic_enabled()</a></b> function.</p>
<h2><a class="anchor" id="doc_cc_mqttsn_client_unsubscribe_send"></a>
Sending Unsubscription Request</h2>
<p>When all the necessary configurations are performed for the allocated "unsubscribe" operation it can actually be sent to the gateway. To initiate sending use the <b><a class="el" href="group__unsubscribe.html#gad020e62cac1bb374104d607922a6af07" title="Send the "unsubscribe" operation.">cc_mqttsn_client_unsubscribe_send()</a></b> function. </p><div class="fragment"><div class="line"><span class="keywordtype">void</span> my_unsubscribe_complete_cb(<span class="keywordtype">void</span>* data, <a class="code" href="group__subscribe.html#ga02212232e0f2e963de716361b933ea6e">CC_MqttsnUnsubscribeHandle</a> handle, <a class="code" href="group__global.html#gab0af1cb13f466184b8ecc4b1a86ec55f">CC_MqttsnAsyncOpStatus</a> status)</div>
<div class="line">{</div>
<div class="line"> <span class="keywordflow">if</span> (status != <a class="code" href="group__global.html#ggab0af1cb13f466184b8ecc4b1a86ec55fa8151e18fea364efd22acf9589fa3323c">CC_MqttsnAsyncOpStatus_Complete</a>) {</div>
<div class="line"> printf(<span class="stringliteral">"ERROR: The subscription operation has failed with status=%d\n"</span>, status);</div>
<div class="line"> ... <span class="comment">// handle error.</span></div>
<div class="line"> <span class="keywordflow">return</span>;</div>
<div class="line"> }</div>
<div class="line">}</div>
<div class="line"> </div>
<div class="line">ec = <a class="code" href="group__unsubscribe.html#gad020e62cac1bb374104d607922a6af07">cc_mqttsn_client_unsubscribe_send</a>(unsubscribe, &my_unsubscribe_complete_cb, data);</div>
<div class="line"><span class="keywordflow">if</span> (ec != <a class="code" href="group__global.html#ggade7e7c53c5ca30c6134f60607b01079faa71957fe69fa1b94d1d0cbc3c7558e1f">CC_MqttsnErrorCode_Success</a>) {</div>
<div class="line"> printf(<span class="stringliteral">"ERROR: Failed to send unsubscribe request with ec=%d\n"</span>, ec);</div>
<div class="line"> ...</div>
<div class="line">}</div>
<div class="ttc" id="agroup__unsubscribe_html_gad020e62cac1bb374104d607922a6af07"><div class="ttname"><a href="group__unsubscribe.html#gad020e62cac1bb374104d607922a6af07">cc_mqttsn_client_unsubscribe_send</a></div><div class="ttdeci">CC_MqttsnErrorCode cc_mqttsn_client_unsubscribe_send(CC_MqttsnUnsubscribeHandle handle, CC_MqttsnUnsubscribeCompleteCb cb, void *cbData)</div><div class="ttdoc">Send the "unsubscribe" operation.</div></div>
</div><!-- fragment --><p> The provided callback will be invoked when the "unsubscribe" operation is complete <b> if and only if</b> the function returns <a class="el" href="group__global.html#ggade7e7c53c5ca30c6134f60607b01079faa71957fe69fa1b94d1d0cbc3c7558e1f">CC_MqttsnErrorCode_Success</a>.</p>
<p>The handle returned by the <b><a class="el" href="group__unsubscribe.html#ga809bcab51f5ac63f211aacd4d1e7cdde" title="Prepare "unsubscribe" operation.">cc_mqttsn_client_unsubscribe_prepare()</a></b> function can be discarded (there is no free / de-allocation) right after the <b><a class="el" href="group__unsubscribe.html#gad020e62cac1bb374104d607922a6af07" title="Send the "unsubscribe" operation.">cc_mqttsn_client_unsubscribe_send()</a></b> invocation regardless of the returned error code. However, the handle remains valid until the callback is called (in case the <a class="el" href="group__global.html#ggade7e7c53c5ca30c6134f60607b01079faa71957fe69fa1b94d1d0cbc3c7558e1f">CC_MqttsnErrorCode_Success</a> was returned). The valid handle can be used to <a class="el" href="index.html#doc_cc_mqttsn_client_unsubscribe_cancel">cancel</a> the operation before the completion callback is invoked.</p>
<p>The MQTT-SN spec demands that the <b>UNSUBSCRIBE</b> transactions be issued one at a time. However, the library allows <a class="el" href="index.html#doc_cc_mqttsn_client_unsubscribe_prepare">preparing</a> and <a class="el" href="index.html#doc_cc_mqttsn_client_unsubscribe_send">sending</a> multiple unsubscription requests in parallel before completion of the first one. The library will retain the requested "unsubscribe" operation requests internally and will issue them one after another to comply with the specification.</p>
<p>Note that the callback function receives the "unsubscribe" operation handle as its second parameter. Although the handle is already invalid and cannot be used in any other function, it allows the application to identify the original "unsubscribe" request if multiple have been issued in parallel and use the same callback function for all of them.</p>
<h2><a class="anchor" id="doc_cc_mqttsn_client_unsubscribe_cancel"></a>
Cancel the "Unsubscribe" Operation.</h2>
<p>While the handle returned by the <b><a class="el" href="group__unsubscribe.html#ga809bcab51f5ac63f211aacd4d1e7cdde" title="Prepare "unsubscribe" operation.">cc_mqttsn_client_unsubscribe_prepare()</a></b> is still valid it is possible to cancel / discard the operation. </p><div class="fragment"><div class="line">ec = <a class="code" href="group__unsubscribe.html#gaeb7e7e36c08b4af26e6cb8d49f858ba8">cc_mqttsn_client_unsubscribe_cancel</a>(unsubscribe);</div>
<div class="line"><span class="keywordflow">if</span> (ec != <a class="code" href="group__global.html#ggade7e7c53c5ca30c6134f60607b01079faa71957fe69fa1b94d1d0cbc3c7558e1f">CC_MqttsnErrorCode_Success</a>) {</div>
<div class="line"> printf(<span class="stringliteral">"ERROR: Failed to cancel unsubscribe with ec=%d\n"</span>, ec);</div>
<div class="line"> ...</div>
<div class="line">}</div>
<div class="ttc" id="agroup__unsubscribe_html_gaeb7e7e36c08b4af26e6cb8d49f858ba8"><div class="ttname"><a href="group__unsubscribe.html#gaeb7e7e36c08b4af26e6cb8d49f858ba8">cc_mqttsn_client_unsubscribe_cancel</a></div><div class="ttdeci">CC_MqttsnErrorCode cc_mqttsn_client_unsubscribe_cancel(CC_MqttsnUnsubscribeHandle handle)</div><div class="ttdoc">Cancel the allocated "unsubscribe" operation.</div></div>
</div><!-- fragment --><p> In case the <b><a class="el" href="group__unsubscribe.html#gad020e62cac1bb374104d607922a6af07" title="Send the "unsubscribe" operation.">cc_mqttsn_client_unsubscribe_send()</a></b> function was successfully called before the <b><a class="el" href="group__unsubscribe.html#gaeb7e7e36c08b4af26e6cb8d49f858ba8" title="Cancel the allocated "unsubscribe" operation.">cc_mqttsn_client_unsubscribe_cancel()</a></b>, the operation is cancelled <b>without</b> callback invocation.</p>
<h2><a class="anchor" id="doc_cc_mqttsn_client_unsubscribe_simplify"></a>
Simplifying the "Unsubscribe" Operation Preparation.</h2>
<p>In many use cases the "unsubscribe" operation can be quite simple with a lot of defaults. To simplify the sequence of the operation preparation and handling of errors, the library provides wrapper function that can be used: </p><ul>
<li><b><a class="el" href="group__unsubscribe.html#gaff3fac35dc2b6a52ce571c4d4e203d94" title="Prepare and send "unsubscribe" request in one go.">cc_mqttsn_client_unsubscribe()</a></b> </li>
</ul>
<p>For example: </p><div class="fragment"><div class="line"><a class="code" href="structCC__MqttsnUnsubscribeConfig.html">CC_MqttsnUnsubscribeConfig</a> config;</div>
<div class="line"> </div>
<div class="line"><span class="comment">// Assign default values to the configuration</span></div>
<div class="line"><a class="code" href="group__unsubscribe.html#gaa85b0dfe3029e8ff1e5de149000ce122">cc_mqttsn_client_unsubscribe_init_config</a>(&config);</div>
<div class="line"> </div>
<div class="line"><span class="comment">// Update values if needed</span></div>
<div class="line">config.<a class="code" href="structCC__MqttsnUnsubscribeConfig.html#ab7e885786f0692e3fd30de43a00a9b04">m_topic</a> = <span class="stringliteral">"some/topic"</span>;</div>
<div class="line"> </div>
<div class="line">ec = <a class="code" href="group__unsubscribe.html#gaff3fac35dc2b6a52ce571c4d4e203d94">cc_mqttsn_client_unsubscribe</a>(client, &config, &my_unsubscribe_complete_cb, data);</div>
<div class="line"><span class="keywordflow">if</span> (ec != <a class="code" href="group__global.html#ggade7e7c53c5ca30c6134f60607b01079faa71957fe69fa1b94d1d0cbc3c7558e1f">CC_MqttsnErrorCode_Success</a>) {</div>
<div class="line"> printf(<span class="stringliteral">"ERROR: Failed to send unsubscribe request with ec=%d\n"</span>, ec);</div>
<div class="line"> ...</div>
<div class="line">}</div>
<div class="ttc" id="agroup__unsubscribe_html_gaff3fac35dc2b6a52ce571c4d4e203d94"><div class="ttname"><a href="group__unsubscribe.html#gaff3fac35dc2b6a52ce571c4d4e203d94">cc_mqttsn_client_unsubscribe</a></div><div class="ttdeci">CC_MqttsnErrorCode cc_mqttsn_client_unsubscribe(CC_MqttsnClientHandle client, const CC_MqttsnUnsubscribeConfig *config, CC_MqttsnUnsubscribeCompleteCb cb, void *cbData)</div><div class="ttdoc">Prepare and send "unsubscribe" request in one go.</div></div>
</div><!-- fragment --><p> Note that the wrapper function does NOT expose the handle returned by the <b><a class="el" href="group__unsubscribe.html#ga809bcab51f5ac63f211aacd4d1e7cdde" title="Prepare "unsubscribe" operation.">cc_mqttsn_client_unsubscribe_prepare()</a></b>. It means that it's not possible to cancel the "unsubscribe" operation before its completion or identify the unsubscribe operation by the reported handle when the completion callback is invoked.</p>
<h1><a class="anchor" id="doc_cc_mqttsn_client_publish"></a>
Publishing Messages</h1>
<p>To publish messages to the gateway use <a class="el" href="group__publish.html">publish</a> operation.</p>
<h2><a class="anchor" id="doc_cc_mqttsn_client_publish_prepare"></a>
Preparing "Publish" Operation.</h2>
<div class="fragment"><div class="line"><a class="code" href="group__global.html#gade7e7c53c5ca30c6134f60607b01079f">CC_MqttsnErrorCode</a> ec = <a class="code" href="group__global.html#ggade7e7c53c5ca30c6134f60607b01079faa71957fe69fa1b94d1d0cbc3c7558e1f">CC_MqttsnErrorCode_Success</a>;</div>
<div class="line"><a class="code" href="group__publish.html#ga028aeb1e89c70b73ac05f78c9b38f169">CC_MqttsnPublishHandle</a> publish = <a class="code" href="group__publish.html#ga21c0c04dcea20c48dec324f8c8cefe73">cc_mqttsn_client_publish_prepare</a>(client, &ec);</div>
<div class="line"><span class="keywordflow">if</span> (publish == NULL) {</div>
<div class="line"> printf(<span class="stringliteral">"ERROR: Publish allocation failed with ec=%d\n"</span>, ec);</div>
<div class="line">}</div>
<div class="ttc" id="agroup__publish_html_ga028aeb1e89c70b73ac05f78c9b38f169"><div class="ttname"><a href="group__publish.html#ga028aeb1e89c70b73ac05f78c9b38f169">CC_MqttsnPublishHandle</a></div><div class="ttdeci">struct CC_MqttsnPublish * CC_MqttsnPublishHandle</div><div class="ttdoc">Handle for "publish" operation.</div><div class="ttdef"><b>Definition:</b> common.h:198</div></div>
<div class="ttc" id="agroup__publish_html_ga21c0c04dcea20c48dec324f8c8cefe73"><div class="ttname"><a href="group__publish.html#ga21c0c04dcea20c48dec324f8c8cefe73">cc_mqttsn_client_publish_prepare</a></div><div class="ttdeci">CC_MqttsnPublishHandle cc_mqttsn_client_publish_prepare(CC_MqttsnClientHandle client, CC_MqttsnErrorCode *ec)</div><div class="ttdoc">Prepare "publish" operation.</div></div>
</div><!-- fragment --><h2><a class="anchor" id="doc_cc_mqttsn_client_publish_retry_period"></a>
Configuring "Publish" Retry Period</h2>
<p>When created, the "publish" operation inherits the <a class="el" href="index.html#doc_cc_mqttsn_client_retry_period">Default Retry Period</a> configuration. It can be changed for the allocated operation using the <b><a class="el" href="group__publish.html#gaef5743a0fa4a46921b956ca7201a193c" title="Configure the retry period for the "publish" operation.">cc_mqttsn_client_publish_set_retry_period()</a></b> function. </p><div class="fragment"><div class="line">ec = <a class="code" href="group__publish.html#gaef5743a0fa4a46921b956ca7201a193c">cc_mqttsn_client_publish_set_retry_period</a>(publish, 1000);</div>
<div class="line"><span class="keywordflow">if</span> (ec != <a class="code" href="group__global.html#ggade7e7c53c5ca30c6134f60607b01079faa71957fe69fa1b94d1d0cbc3c7558e1f">CC_MqttsnErrorCode_Success</a>) {</div>
<div class="line"> ... <span class="comment">/* Something went wrong */</span></div>
<div class="line">}</div>
<div class="ttc" id="agroup__publish_html_gaef5743a0fa4a46921b956ca7201a193c"><div class="ttname"><a href="group__publish.html#gaef5743a0fa4a46921b956ca7201a193c">cc_mqttsn_client_publish_set_retry_period</a></div><div class="ttdeci">CC_MqttsnErrorCode cc_mqttsn_client_publish_set_retry_period(CC_MqttsnPublishHandle handle, unsigned ms)</div><div class="ttdoc">Configure the retry period for the "publish" operation.</div></div>
</div><!-- fragment --><p> To retrieve the configured response timeout use the <b><a class="el" href="group__publish.html#ga192e7e6728c4e98cf3533b8ef82e4f80" title="Retrieve the configured retry period for the "publish" operation.">cc_mqttsn_client_publish_get_retry_period()</a></b> function.</p>
<h2><a class="anchor" id="doc_cc_mqttsn_client_publish_retry_count"></a>
Configuring "Publish" Retry Count</h2>
<p>When created, the "publish" operation inherits the <a class="el" href="index.html#doc_cc_mqttsn_client_retry_count">Default Retry Count</a> configuration. It can be changed for the allocated operation using the <b><a class="el" href="group__publish.html#ga24fc2f8fa1d78eda392cbba989c2c1ef" title="Configure the retry count for the "publish" operation.">cc_mqttsn_client_publish_set_retry_count()</a></b> function. </p><div class="fragment"><div class="line">ec = <a class="code" href="group__unsubscribe.html#ga78d949e80997e9392a68c607d8c28d4e">cc_mqttsn_client_unsubscribe_set_retry_count</a>(publish, 2);</div>
<div class="line"><span class="keywordflow">if</span> (ec != <a class="code" href="group__global.html#ggade7e7c53c5ca30c6134f60607b01079faa71957fe69fa1b94d1d0cbc3c7558e1f">CC_MqttsnErrorCode_Success</a>) {</div>
<div class="line"> ... <span class="comment">/* Something went wrong */</span></div>
<div class="line">}</div>
</div><!-- fragment --><p> To retrieve the configured response timeout use the <b><a class="el" href="group__publish.html#ga9b353cc24e5add4dc7add388c17b793a" title="Retrieve the configured retry count for the "publish" operation.">cc_mqttsn_client_publish_get_retry_count()</a></b> function.</p>
<p>The publish operation can exchange multiple messages in a single transaction. For example, when publishing <b>QoS2</b> messages which require registration, the client will send <b>REGISTER</b>, <b>PUBLISH</b>, and <b>PUBREL</b> messages and will expect <b>REGACK</b>, <b>PUBREC</b>, and <b>PUBCOMP</b> messages as their respective acknowledgements. The configuration of the retry count is per such single message exchange. In other words when 2 retries are allowed, the client will allow 2 retries for <b>REGISTER</b> <-> <b>REGACK</b>, 2 retries for <b>PUBLISH</b> <-> <b>PUBREC</b> and 2 retries for <b>PUBREL</b> <-> <b>PUBCOMP</b> exchanges.</p>
<h2><a class="anchor" id="doc_cc_mqttsn_client_publish_config"></a>
Configuration of "Publish" Operation</h2>
<div class="fragment"><div class="line"><a class="code" href="structCC__MqttsnPublishConfig.html">CC_MqttsnPublishConfig</a> config;</div>
<div class="line"> </div>
<div class="line"><span class="comment">// Assign default values to the "config"</span></div>
<div class="line"><a class="code" href="group__publish.html#gaf7544ae47cf78a704500726afa79d5dd">cc_mqttsn_client_publish_init_config</a>(&config);</div>
<div class="line"> </div>
<div class="line"><span class="comment">// Update the required values</span></div>
<div class="line">config.<a class="code" href="structCC__MqttsnPublishConfig.html#a3cee31310a8c916256ef9f41c7bbdd43">m_topic</a> = <span class="stringliteral">"some/topic"</span>;</div>
<div class="line">config.<a class="code" href="structCC__MqttsnPublishConfig.html#a51d76311da23c78053e2592d034cb06b">m_data</a> = &some_buf[0];</div>
<div class="line">config.<a class="code" href="structCC__MqttsnPublishConfig.html#a3ac6e17a622dad35c63b630f244720e1">m_dataLen</a> = ...;</div>
<div class="line">config.<a class="code" href="structCC__MqttsnPublishConfig.html#af5aca2577f4b79e9f27e507fec528390">m_qos</a> = ...;</div>
<div class="line"> </div>
<div class="line"><span class="comment">// Perform the configuration</span></div>
<div class="line">ec = <a class="code" href="group__publish.html#ga5c8212866973ffa9a676938b54461bb1">cc_mqttsn_client_publish_config</a>(publish, &config);</div>
<div class="line"><span class="keywordflow">if</span> (ec != <a class="code" href="group__global.html#ggade7e7c53c5ca30c6134f60607b01079faa71957fe69fa1b94d1d0cbc3c7558e1f">CC_MqttsnErrorCode_Success</a>) {</div>
<div class="line"> printf(<span class="stringliteral">"ERROR: Configuration failed with ec=%d\n"</span>, ec);</div>
<div class="line"> ...</div>
<div class="line">}</div>
<div class="ttc" id="agroup__publish_html_ga5c8212866973ffa9a676938b54461bb1"><div class="ttname"><a href="group__publish.html#ga5c8212866973ffa9a676938b54461bb1">cc_mqttsn_client_publish_config</a></div><div class="ttdeci">CC_MqttsnErrorCode cc_mqttsn_client_publish_config(CC_MqttsnPublishHandle handle, const CC_MqttsnPublishConfig *config)</div><div class="ttdoc">Perform configuration of the "publish" operation.</div></div>
<div class="ttc" id="agroup__publish_html_gaf7544ae47cf78a704500726afa79d5dd"><div class="ttname"><a href="group__publish.html#gaf7544ae47cf78a704500726afa79d5dd">cc_mqttsn_client_publish_init_config</a></div><div class="ttdeci">void cc_mqttsn_client_publish_init_config(CC_MqttsnPublishConfig *config)</div><div class="ttdoc">Intialize the CC_MqttsnPublishConfig configuration structure.</div></div>
<div class="ttc" id="astructCC__MqttsnPublishConfig_html"><div class="ttname"><a href="structCC__MqttsnPublishConfig.html">CC_MqttsnPublishConfig</a></div><div class="ttdoc">Configuration the will for "publish" operations.</div><div class="ttdef"><b>Definition:</b> common.h:298</div></div>
<div class="ttc" id="astructCC__MqttsnPublishConfig_html_a3ac6e17a622dad35c63b630f244720e1"><div class="ttname"><a href="structCC__MqttsnPublishConfig.html#a3ac6e17a622dad35c63b630f244720e1">CC_MqttsnPublishConfig::m_dataLen</a></div><div class="ttdeci">unsigned m_dataLen</div><div class="ttdoc">Publish data (message) length.</div><div class="ttdef"><b>Definition:</b> common.h:301</div></div>
<div class="ttc" id="astructCC__MqttsnPublishConfig_html_a3cee31310a8c916256ef9f41c7bbdd43"><div class="ttname"><a href="structCC__MqttsnPublishConfig.html#a3cee31310a8c916256ef9f41c7bbdd43">CC_MqttsnPublishConfig::m_topic</a></div><div class="ttdeci">const char * m_topic</div><div class="ttdoc">Publish topic.</div><div class="ttdef"><b>Definition:</b> common.h:299</div></div>
<div class="ttc" id="astructCC__MqttsnPublishConfig_html_a51d76311da23c78053e2592d034cb06b"><div class="ttname"><a href="structCC__MqttsnPublishConfig.html#a51d76311da23c78053e2592d034cb06b">CC_MqttsnPublishConfig::m_data</a></div><div class="ttdeci">const unsigned char * m_data</div><div class="ttdoc">Publish data (message).</div><div class="ttdef"><b>Definition:</b> common.h:300</div></div>
<div class="ttc" id="astructCC__MqttsnPublishConfig_html_af5aca2577f4b79e9f27e507fec528390"><div class="ttname"><a href="structCC__MqttsnPublishConfig.html#af5aca2577f4b79e9f27e507fec528390">CC_MqttsnPublishConfig::m_qos</a></div><div class="ttdeci">CC_MqttsnQoS m_qos</div><div class="ttdoc">Publish message QoS.</div><div class="ttdef"><b>Definition:</b> common.h:303</div></div>
</div><!-- fragment --><p> See also documentation of the <a class="el" href="structCC__MqttsnPublishConfig.html">CC_MqttsnPublishConfig</a> structure.</p>
<p>Similar to the <a class="el" href="index.html#doc_cc_mqttsn_client_subscribe">subscribe</a> operation it is possible to use predefined topic id by setting <a class="el" href="structCC__MqttsnPublishConfig.html#ac497cbbac018bffbe9c98df25ba503a5">topicId</a> member instead of <a class="el" href="structCC__MqttsnPublishConfig.html#a3cee31310a8c916256ef9f41c7bbdd43">m_topic</a>. </p><div class="fragment"><div class="line"><span class="comment">// Update the required values</span></div>
<div class="line">config.<a class="code" href="structCC__MqttsnPublishConfig.html#ac497cbbac018bffbe9c98df25ba503a5">m_topicId</a> = 123;</div>
<div class="ttc" id="astructCC__MqttsnPublishConfig_html_ac497cbbac018bffbe9c98df25ba503a5"><div class="ttname"><a href="structCC__MqttsnPublishConfig.html#ac497cbbac018bffbe9c98df25ba503a5">CC_MqttsnPublishConfig::m_topicId</a></div><div class="ttdeci">CC_MqttsnTopicId m_topicId</div><div class="ttdoc">Pre-defined topic ID, should be 0 when topic is not NULL.</div><div class="ttdef"><b>Definition:</b> common.h:302</div></div>
</div><!-- fragment --><p>By default the library will perform the analysis of the submitted topic format and reject it if topic format is incorrect. However, for performance reasons it is possible to disable such verification when client application ensures that no invalid topics are used. </p><div class="fragment"><div class="line">ec = <a class="code" href="group__client.html#ga0bd029baf641267fcf18580704246ac4">cc_mqttsn_client_set_verify_outgoing_topic_enabled</a>(client, <span class="keyword">false</span>);</div>
<div class="line"><span class="keywordflow">if</span> (ec != <a class="code" href="group__global.html#ggade7e7c53c5ca30c6134f60607b01079faa71957fe69fa1b94d1d0cbc3c7558e1f">CC_MqttsnErrorCode_Success</a>) {</div>
<div class="line"> ... <span class="comment">/* Something is wrong */</span></div>
<div class="line">}</div>
</div><!-- fragment --><p> To retrieve the current configuration use the <b><a class="el" href="group__client.html#gaf81914ccda622d45808da56a49226aeb" title="Retrieve current outgoing topic format verification control.">cc_mqttsn_client_get_verify_outgoing_topic_enabled()</a></b> function.</p>
<p><b>NOTE</b> that the configuration is global per client and not per "publish" operation.</p>
<p>Also <b>note</b> that the same function controls the verification of the "subscribe", "unsubscribe", and "publish" filter / topic formats.</p>
<h2><a class="anchor" id="doc_cc_mqttsn_client_publish_send"></a>
Sending Publish Request</h2>
<p>When all the necessary configurations are performed for the allocated "publish" operation it can actually be sent to the gateway. To initiate sending use the <b><a class="el" href="group__publish.html#gad00866c76083140dec9acbc3f5c98ff5" title="Send the "publish" operation.">cc_mqttsn_client_publish_send()</a></b> function. </p><div class="fragment"><div class="line"><span class="keywordtype">void</span> my_publish_complete_cb(<span class="keywordtype">void</span>* data, <a class="code" href="group__publish.html#ga028aeb1e89c70b73ac05f78c9b38f169">CC_MqttsnPublishHandle</a> handle, <a class="code" href="group__global.html#gab0af1cb13f466184b8ecc4b1a86ec55f">CC_MqttsnAsyncOpStatus</a> status, <span class="keyword">const</span> <a class="code" href="structCC__MqttsnPublishInfo.html">CC_MqttsnPublishInfo</a>* info)</div>
<div class="line">{</div>