-
Notifications
You must be signed in to change notification settings - Fork 82
/
u_cell_net.h
996 lines (936 loc) · 49.7 KB
/
u_cell_net.h
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
/*
* Copyright 2019-2024 u-blox
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
#ifndef _U_CELL_NET_H_
#define _U_CELL_NET_H_
/* Only header files representing a direct and unavoidable
* dependency between the API of this module and the API
* of another module should be included here; otherwise
* please keep #includes to your .c files. */
#include "u_device.h"
/** \addtogroup _cell
* @{
*/
/** @file
* @brief This header file defines the APIs that control the network
* connectivity of a cellular module. These functions are thread-safe
* unless otherwise specified with the proviso that a cellular instance
* should not be accessed before it has been added or after it has been
* removed.
*/
#ifdef __cplusplus
extern "C" {
#endif
/* ----------------------------------------------------------------
* COMPILE-TIME MACROS
* -------------------------------------------------------------- */
/** The number of digits in an IP address, which could be IPV6
* and includes room for a null terminator.
*/
#define U_CELL_NET_IP_ADDRESS_SIZE 64
#ifndef U_CELL_NET_CONTEXT_ID
/** The PDP context ID to use.
*/
# define U_CELL_NET_CONTEXT_ID 1
#endif
#ifndef U_CELL_NET_PROFILE_ID
/** The module profile ID to use: has to be zero for SARA-R4.
*/
# define U_CELL_NET_PROFILE_ID 0
#endif
/** The maximum number of PDP contexts that can be exist
* (3GPP defined).
*/
#define U_CELL_NET_MAX_NUM_CONTEXTS 7
/** The number of bytes required to represent an MCC/MNC string
* with null terminator, enough for the 3-digit MNC case,
* for example "722320".
*/
#define U_CELL_NET_MCC_MNC_LENGTH_BYTES 7
#ifndef U_CELL_NET_MAX_NAME_LENGTH_BYTES
/** The number of bytes required to store a network name,
* including terminator.
*/
# define U_CELL_NET_MAX_NAME_LENGTH_BYTES 64
#endif
#ifndef U_CELL_NET_MAX_APN_LENGTH_BYTES
/** The number of bytes required to store an APN, including
* terminator.
*/
# define U_CELL_NET_MAX_APN_LENGTH_BYTES 101
#endif
/* NOTE TO MAINTAINERS: if you change this #define you will
* need to change u-blox,ubxlib-network-cell.yaml over in
* /port/platform/zephyr/dts/bindings to match.
*/
#ifndef U_CELL_NET_CONNECT_TIMEOUT_SECONDS
/** The time in seconds allowed for a connection to complete.
* This is a long time since, in the worst case, deep scan
* on an NB1 network could take this long. To shorten the
* connection time, pass a pKeepGoingCallback() parameter
* to the connection function.
*/
# define U_CELL_NET_CONNECT_TIMEOUT_SECONDS (60 * 30)
#endif
#ifndef U_CELL_NET_UPSD_CONTEXT_ACTIVATION_TIME_SECONDS
/** Where a module uses the AT+UPSD command to activate
* a context for the internal IP stack of the module,
* we have to just wait on the "OK" being returned;
* there is no other feedback and we can't abort.
* This sets the amount of time to wait at each attempt.
* Should not be less than 30 seconds.
*/
# define U_CELL_NET_UPSD_CONTEXT_ACTIVATION_TIME_SECONDS (60 * 3)
#endif
#ifndef U_CELL_NET_SCAN_RETRIES
/** How many times to retry a network scan if there is no
* response at all within #U_CELL_NET_SCAN_TIME_SECONDS.
*/
# define U_CELL_NET_SCAN_RETRIES 2
#endif
#ifndef U_CELL_NET_SCAN_TIME_SECONDS
/** How long to allow for a network scan; note that this is
* the scan time but the uCellNetScanGetFirst() function
* may retry up to #U_CELL_NET_SCAN_RETRIES times if the module
* offers no response at all within this time.
*
* This is the worst case wait-time when an NB1 RAT is included.
*/
# define U_CELL_NET_SCAN_TIME_SECONDS 1580
#endif
/** Determine if a given cellular network status value means that
* we're registered with the network.
*/
#define U_CELL_NET_STATUS_MEANS_REGISTERED(status) \
(((status) == U_CELL_NET_STATUS_REGISTERED_HOME) || \
((status) == U_CELL_NET_STATUS_REGISTERED_ROAMING) || \
((status) == U_CELL_NET_STATUS_REGISTERED_SMS_ONLY_HOME) || \
((status) == U_CELL_NET_STATUS_REGISTERED_SMS_ONLY_ROAMING) || \
((status) == U_CELL_NET_STATUS_REGISTERED_NO_CSFB_HOME) || \
((status) == U_CELL_NET_STATUS_REGISTERED_NO_CSFB_ROAMING))
#ifndef U_CELL_NET_DEEP_SCAN_RETRIES
/** The number of times to retry a deep scan on error.
*/
# define U_CELL_NET_DEEP_SCAN_RETRIES 2
#endif
#ifndef U_CELL_NET_DEEP_SCAN_TIME_SECONDS
/** A guard time-out value for uCellNetDeepScan().
*/
# define U_CELL_NET_DEEP_SCAN_TIME_SECONDS 240
#endif
#ifndef U_CELL_NET_APN_DB_AUTHENTICATION_MODE
/** The default authentication mode to use for an APN picked from
* the APN database where a username and password is required.
* Where a module supports automatic authentication mode, that will
* be used instead. If a user has specified an authentication mode
* with a call to uCellNetSetAuthenticationMode(), that will be used
* instead; this allows the user to switch from CHAP to PAP
* authentication mode on APNs chosen from the AP if required.
*/
#define U_CELL_NET_APN_DB_AUTHENTICATION_MODE U_CELL_NET_AUTHENTICATION_MODE_CHAP
#endif
/* ----------------------------------------------------------------
* TYPES
* -------------------------------------------------------------- */
/** The current network status. Note that these are
* offset by one in value from the 3GPP values since
* zero is used to mean "unknown" (and negative values
* are used to indicate errors).
*/
//lint -estring(788, uCellNetStatus_t::U_CELL_NET_STATUS_MAX_NUM)
// Suppress not used within defaulted switch
//lint -estring(788, uCellNetStatus_t::U_CELL_NET_STATUS_DUMMY)
// Suppress not used within defaulted switch
typedef enum {
U_CELL_NET_STATUS_DUMMY = -1, /**< added to ensure that the
compiler treats values of
this type as signed in case
an error code is to be returned
as this type. Otherwise the enum
could, in some cases, have an
underlying type of unsigned and
hence < 0 checks will always be
false and you might not be warned
of this. */
U_CELL_NET_STATUS_UNKNOWN,
U_CELL_NET_STATUS_NOT_REGISTERED, /**< +CEREG: 0. */
U_CELL_NET_STATUS_REGISTERED_HOME, /**< +CEREG: 1. */
U_CELL_NET_STATUS_SEARCHING, /**< +CEREG: 2. */
U_CELL_NET_STATUS_REGISTRATION_DENIED, /**< +CEREG: 3. */
U_CELL_NET_STATUS_OUT_OF_COVERAGE, /**< +CEREG: 4. */
U_CELL_NET_STATUS_REGISTERED_ROAMING, /**< +CEREG: 5. */
U_CELL_NET_STATUS_REGISTERED_SMS_ONLY_HOME, /**< +CEREG: 6. */
U_CELL_NET_STATUS_REGISTERED_SMS_ONLY_ROAMING, /**< +CEREG: 7. */
U_CELL_NET_STATUS_EMERGENCY_ONLY, /**< +CEREG: 8. */
U_CELL_NET_STATUS_REGISTERED_NO_CSFB_HOME, /**< +CEREG: 9. */
U_CELL_NET_STATUS_REGISTERED_NO_CSFB_ROAMING, /**< +CEREG: 10. */
U_CELL_NET_STATUS_TEMPORARY_NETWORK_BARRING,
U_CELL_NET_STATUS_MAX_NUM
} uCellNetStatus_t;
/** The possible radio access technologies. Note that
* these are offset by one in value from the 3GPP values
* returned in the AT+COPS or AT+CxREG commands since
* zero is used to mean "unknown/not used" (and negative
* values are used to indicate errors).
*/
//lint -estring(788, uCellNetRat_t::U_CELL_NET_RAT_MAX_NUM)
// Suppress not used within defaulted switch
//lint -estring(788, uCellNetRat_t::U_CELL_NET_RAT_DUMMY)
// Suppress not used within defaulted switch
typedef enum {
U_CELL_NET_RAT_DUMMY = -1, /**< added to ensure that the
compiler treats values of
this type as signed in case
an error code is to be returned
as this type. Otherwise the enum
could, in some cases, have an
underlying type of unsigned and
hence < 0 checks will always be
false and you might not be warned
of this. */
U_CELL_NET_RAT_UNKNOWN_OR_NOT_USED = 0,
U_CELL_NET_RAT_GSM_GPRS_EGPRS = 1,
U_CELL_NET_RAT_GSM_COMPACT = 2, /**< this RAT is not supported
by any of the supported
u-blox modules. */
U_CELL_NET_RAT_UTRAN = 3,
U_CELL_NET_RAT_EGPRS = 4, /**< this RAT can be detected as active
but cannot be individually configured
using uCellCfgSetRat() or
uCellCfgSetRatRank(). */
U_CELL_NET_RAT_HSDPA = 5, /**< this RAT can be detected as active
but cannot be individually configured
using uCellCfgSetRat() or
uCellCfgSetRatRank(). */
U_CELL_NET_RAT_HSUPA = 6, /**< this RAT can be detected as active
but cannot be individually configured
using uCellCfgSetRat() or
uCellCfgSetRatRank(). */
U_CELL_NET_RAT_HSDPA_HSUPA = 7, /**< this RAT can be detected as active
but cannot be individually configured
using uCellCfgSetRat() or
uCellCfgSetRatRank(). */
U_CELL_NET_RAT_LTE = 8, /**< supported by LARA-R6. */
U_CELL_NET_RAT_EC_GSM = 9, /**< this RAT is not supported
by any of the supported
u-blox modules. */
U_CELL_NET_RAT_CATM1 = 10,
U_CELL_NET_RAT_NB1 = 11,
U_CELL_NET_RAT_GSM_UMTS = 12, /**< this dual-RAT is not supported by any
u-blox modules that are supported by ubxlib. */
U_CELL_NET_RAT_GSM_UMTS_LTE = 13, /**< this tri-RAT is not supported by any
u-blox modules that are supported by ubxlib. */
U_CELL_NET_RAT_GSM_LTE = 14, /**< supported by LENA-R8. */
U_CELL_NET_RAT_UMTS_LTE = 15, /**< this dual-RAT is not supported by any u-blox
modules that are supported by ubxlib. */
U_CELL_NET_RAT_MAX_NUM
} uCellNetRat_t;
/** The possible registration types.
*/
//lint -estring(788, uCellNetRegDomain_t::U_CELL_NET_REG_DOMAIN_MAX_NUM)
// Suppress not used within defaulted switch
typedef enum {
U_CELL_NET_REG_DOMAIN_CS, /**< circuit switched (AT+CREG). */
U_CELL_NET_REG_DOMAIN_PS, /**< packet switched (AT+CGREG/AT+CEREG). */
U_CELL_NET_REG_DOMAIN_MAX_NUM
} uCellNetRegDomain_t;
/** The possible authentication modes for the network connection.
*
* Note: there is also a #uPortPppAuthenticationMode_t enumeration
* which is set to match this one. If you make a change here you
* may need to make a change there also.
*/
typedef enum {
U_CELL_NET_AUTHENTICATION_MODE_NONE = 0, /**< \deprecated please use #U_CELL_NET_AUTHENTICATION_MODE_NOT_SET. */
U_CELL_NET_AUTHENTICATION_MODE_NOT_SET = 0, /**< where a module supports automatic
authentication mode (for example
SARA-R5 and SARA-U201) then that will
be used; where a module does not support
automatic authentication mode (for example
SARA-R4, LARA-R6 and LENA-R8) and a
user name and password are required,
authentication will fail: please use
uCellNetSetAuthenticationMode() to
choose #U_CELL_NET_AUTHENTICATION_MODE_PAP
or #U_CELL_NET_AUTHENTICATION_MODE_CHAP. */
U_CELL_NET_AUTHENTICATION_MODE_PAP = 1,
U_CELL_NET_AUTHENTICATION_MODE_CHAP = 2,
U_CELL_NET_AUTHENTICATION_MODE_AUTOMATIC = 3, /**< not supported by all module types. */
U_CELL_NET_AUTHENTICATION_MODE_MAX_NUM
} uCellNetAuthenticationMode_t;
/** Information on a cell, passed to the callback of uCellNetDeepScan(),
* could be used in a call to uCellTimeSyncCellEnable().
*/
typedef struct {
int32_t mcc; /**< mobile country code. */
int32_t mnc; /**< mobile network code. */
int32_t tac; /**< tracking area code. */
int32_t earfcnDownlink; /**< downlink E-UTRAN absolute radio frequency channel number. */
int32_t earfcnUplink; /**< uplink E-UTRAN absolute radio frequency channel number. */
int32_t cellIdLogical; /**< logical cell ID. */
int32_t cellIdPhysical; /**< physical cell ID. */
int32_t rsrpDbm; /**< current reference signal received power in dBm. */
int32_t rsrqDb; /**< current reference signal received quality in dB. */
} uCellNetCellInfo_t;
/* ----------------------------------------------------------------
* FUNCTIONS
* -------------------------------------------------------------- */
/** Register with the cellular network and activate a PDP context.
* This function provides the registration and activation of the
* PDP context in one call. To split these operations up use the
* uCellNetRegister() and uCellNetActivate() functions instead.
* If a connection is already active this function will simply
* return unless the requested APN is different from the APN of
* the current connection, in which case that PDP context will be
* deactivated (and potentially deregistration may occur) then
* [registration will occur and] the new context will be activated.
*
* Note: if you are required to set a user name and password then
* you MAY also need to set the authentication mode that will be
* used; see uCellNetSetAuthenticationMode() for this.
*
* @param cellHandle the handle of the cellular instance.
* @param[in] pMccMnc pointer to a string giving the MCC and
* MNC of the PLMN to use (for example "23410")
* for manual connection; set to NULL if
* automatic PLMN selection (AT+COPS=0)
* is required.
* @param[in] pApn pointer to a string giving the APN to
* use; set to NULL if no APN is specified
* by the service provider, in which
* case the APN database in u_cell_apn_db.h
* will be used to determine a default APN.
* To force an empty APN to be used, specify
* "" for pApn. Note: if the APN is chosen
* from the APN database and that APN requires
* a username and password then, if the
* module does not aupport automatic choice
* of authentication mode (e.g. SARA-R4,
* LARA-R6 and LENA-R8 do not), the
* authentication mode set with the last
* call to uCellNetSetAuthenticationMode()
* will be used or, if that function has
* never been called,
* #U_CELL_NET_APN_DB_AUTHENTICATION_MODE
* will be used.
* @param[in] pUsername pointer to a string giving the user name
* for PPP authentication; may be set to
* NULL if no user name or password is
* required.
* @param[in] pPassword pointer to a string giving the password
* for PPP authentication; must be
* non-NULL if pUsername is non-NULL, ignored
* if pUsername is NULL.
* @param[in] pKeepGoingCallback a callback function that governs how
* long a connection attempt will continue
* for. This function is called once a second
* while waiting for a connection attempt
* to complete; the connection attempt
* will only continue while it returns
* true. This allows the caller to
* terminate the connection attempt at their
* convenience. This function may also be
* used to feed any watchdog timer that
* might be running during longer cat-M1/NB1
* network search periods. May be NULL, in
* which case the connection attempt will
* eventually time out on failure.
* @return zero on success or negative error code on
* failure.
*/
int32_t uCellNetConnect(uDeviceHandle_t cellHandle,
const char *pMccMnc,
const char *pApn, const char *pUsername,
const char *pPassword,
bool (*pKeepGoingCallback) (uDeviceHandle_t));
/** Register with the cellular network. Note that on EUTRAN (LTE)
* networks, registration and context activation are done at the same
* time and hence, if you want to specify an APN rather than rely
* on the default APN provided by the network, you should use
* uCellConnect() instead.
*
* @param cellHandle the handle of the cellular instance.
* @param[in] pMccMnc pointer to a string giving the MCC and
* MNC of the PLMN to use (for example "23410")
* for manual connection; set to NULL if
* automatic PLMN selection (AT+COPS=0)
* is required.
* @param[in] pKeepGoingCallback a callback function that governs how
* long registration will continue for.
* This function is called once a second
* while waiting for registration to finish;
* registration will only continue while it
* returns true. This allows the caller to
* terminate registration at their convenience.
* This function may also be used to feed
* any watchdog timer that might be running
* during longer cat-M1/NB1 network search
* periods. May be NULL, in which case the
* registration attempt will eventually
* time out on failure.
* @return zero on success or negative error code on
* failure.
*/
int32_t uCellNetRegister(uDeviceHandle_t cellHandle,
const char *pMccMnc,
bool (*pKeepGoingCallback) (uDeviceHandle_t));
/** Activate the PDP context. If a PDP context is already active
* this function will simply return unless the requested APN
* is different from the APN of the current PDP context,
* in which case the current PDP context will be deactivated and
* the new one activated. Note that on EUTRAN (LTE) networks and
* on SARA-R4 modules the APN is set during registration and so
* this will result in de-registration and re-registration with the
* network.
*
* Note: if you are required to set a user name and password then
* you MAY also need to set the authentication mode that will be
* used; see uCellNetSetAuthenticationMode() for this.
*
* @param cellHandle the handle of the cellular instance.
* @param[in] pApn pointer to a string giving the APN to
* use; set to NULL if no APN is specified
* by the service provider, in which
* case the APN database in u_cell_apn_db.h
* will be used to determine a default APN.
* To force an empty APN to be used, specify
* "" for pApn. Note: if the APN is chosen
* from the APN database and that APN requires
* a username and password then, if the
* module does not aupport automatic choice
* of authentication mode (e.g. SARA-R4,
* LARA-R6 and LENA-R8 do not), the
* authentication mode set with the last
* call to uCellNetSetAuthenticationMode()
* will be used or, if that function has
* never been called,
* #U_CELL_NET_APN_DB_AUTHENTICATION_MODE
* will be used.
* @param[in] pUsername pointer to a string giving the user name
* for PPP authentication; may be set to
* NULL if no user name or password is
* required.
* @param[in] pPassword pointer to a string giving the password
* for PPP authentication; ignored if pUsername
* is NULL, must be non-NULL if pUsername is
* non-NULL.
* @param[in] pKeepGoingCallback a callback function that governs how
* long an activation attempt will continue
* for. This function is called once a second
* while waiting for an activation attempt
* to complete; the activation attempt
* will only continue while it returns
* true. This allows the caller to
* terminate the activation attempt at their
* convenience. This function may also be
* used to feed any watchdog timer that
* might be running during longer cat-M1/NB1
* network search periods. May be NULL,
* in which case the activation attempt
* will eventually time out on failure.
* @return zero on success or negative error code on
* failure.
*/
int32_t uCellNetActivate(uDeviceHandle_t cellHandle,
const char *pApn, const char *pUsername,
const char *pPassword,
bool (*pKeepGoingCallback) (uDeviceHandle_t));
/** Deactivate the PDP context. On EUTRAN (LTE) networks and on
* SARA-R4 modules irrespective of the radio access technology, it is
* not permitted to have no context and therefore this function
* will also result in deregistration from the network.
*
* @param cellHandle the handle of the cellular instance.
* @param[in] pKeepGoingCallback a call-back function that governs how
* long deactivation will continue for.
* This function is called once a second
* while waiting for deactivation to
* finish; deactivation will only
* continue while it returns true. This
* allows the caller to terminate
* activation at their convenience.
* May be NULL.
* @return zero on success or negative error code
* on failure.
*/
int32_t uCellNetDeactivate(uDeviceHandle_t cellHandle,
bool (*pKeepGoingCallback) (uDeviceHandle_t));
/** Disconnect from the network. If there is an active PDP Context it
* will be deactivated. The state of the module will be that the
* radio is in airplane mode (AT+CFUN=4).
*
* @param cellHandle the handle of the cellular instance.
* @param[in] pKeepGoingCallback a call-back function that governs how
* long de-registration will continue for.
* This function is called once a second
* while waiting for de-registration to
* finish; de-registration will only
* continue while it returns true. This
* allows the caller to terminate
* registration at their convenience.
* May be NULL.
* @return zero on success or negative error code on
* failure.
*/
int32_t uCellNetDisconnect(uDeviceHandle_t cellHandle,
bool (*pKeepGoingCallback) (uDeviceHandle_t));
/** Initiate a network scan and return the first result after
* it has completed; uCellNetScanGetNext() should be called
* repeatedly to iterate through subsequent results from the
* scan. This function is not thread-safe in that there is a
* single scan list for any given cellHandle.
*
* For instance, to print out the MCC/MNC's of all the visible
* networks:
*
* ```
* char buffer[U_CELL_NET_MCC_MNC_LENGTH_BYTES];
*
* for (int32_t x = uCellNetScanGetFirst(handle, NULL, 0,
buffer, NULL, NULL);
* x >= 0;
* x = uCellNetScanGetNext(handle, NULL, 0, buffer, NULL)) {
* printf("%s\n", buffer);
* }
* ```
*
* @param cellHandle the handle of the cellular instance.
* @param[out] pName a place to put the name of the first
* network found; may be NULL.
* @param nameSize the amount of storage at pName, must
* be non-zero if pName is non-NULL.
* No more than #U_CELL_NET_MAX_NAME_LENGTH_BYTES
* (which includes room for a terminator)
* are required.
* @param[out] pMccMnc a pointer to #U_CELL_NET_MCC_MNC_LENGTH_BYTES
* of storage in which the MCC/MNC
* string representing the first network
* will be stored; may be NULL.
* @param[out] pRat pointer to a place to put the radio
* access technology of the network;
* may be NULL.
* @param[in] pKeepGoingCallback network scanning can take some time, up
* to #U_CELL_NET_SCAN_TIME_SECONDS if an NB1
* RAT is included. This call-back is called
* once a second during the scan, allowing a
* watch-dog function to be called if required;
* may be NULL. The function should return
* true; if it returns false the network
* scan will be aborted.
* @return the number of networks found or negative
* error code. If
* #U_CELL_ERROR_TEMPORARY_FAILURE is returned
* then the module is currently in a state
* where it is unable to perform a network
* search (e.g. if it is already doing one
* for other reasons) and in this case it
* is worth waiting a little while (e.g. 10
* seconds) and trying again.
*/
int32_t uCellNetScanGetFirst(uDeviceHandle_t cellHandle,
char *pName, size_t nameSize,
char *pMccMnc, uCellNetRat_t *pRat,
bool (*pKeepGoingCallback) (uDeviceHandle_t));
/** Return subsequent results from a network scan. Use
* uCellNetScanGetFirst() to get the number of results and
* return the first result and then call this "number of
* results" times to read out all of the search results.
* Calling this "number of results" times will free
* the memory that held the search results after the final
* call (otherwise it will be freed when the cellular
* instance is removed or another scan is initiated, or
* can be freed with a call to uCellNetScanGetLast()).
* This function is not thread-safe in that there is a
* single scan list for all threads.
*
* @param cellHandle the handle of the cellular instance.
* @param[out] pName a place to put the name of the next
* network found; may be NULL.
* @param nameSize the amount of storage at pName, must
* be non-zero if pName is non-NULL.
* No more than #U_CELL_NET_MAX_NAME_LENGTH_BYTES
* (which includes room for a terminator)
* are required.
* @param[out] pMccMnc a pointer to #U_CELL_NET_MCC_MNC_LENGTH_BYTES
* of storage in which the MCC/MNC
* string representing the next network
* will be stored; may be NULL.
* @param[out] pRat pointer to a place to put the radio
* access technology of the network;
* may be NULL.
* @return the number of networks remaining *after*
* this one has been read or negative error
* code.
*/
int32_t uCellNetScanGetNext(uDeviceHandle_t cellHandle,
char *pName, size_t nameSize,
char *pMccMnc, uCellNetRat_t *pRat);
/** It is good practice to call this to clear up memory
* from uCellNetScanGetFirst() if you are not going to
* iterate through the whole list with uCellNetScanGetNext().
*
* @param cellHandle the handle of the cellular instance.
*/
void uCellNetScanGetLast(uDeviceHandle_t cellHandle);
/** Do an extended network search, AT+COPS=5; only supported on SARA-R5.
* The detected cells may be used with uCellTimeSyncCellEnable(),
* supported on SARA-R5xx-01B and later modules.
*
* @param cellHandle the handle of the cellular instance.
* @param[in] pCallback pointer to a function to process each
* result, as they are returned, where the
* first parameter is the handle of the
* cellular device, the second parameter
* is a pointer to the cell information
* WHICH MAY BE NULL if pCallback is just
* being called as a periodic "keep going"
* check (the contents of a (non-NULL) pointer
* MUST be copied by the callback as it
* will no longer be valid once the
* callback has returned) and the third
* parameter is the value of pCallbackParameter;
* the function should return true to
* continue the scan or it may return false
* to abort the scan (e.g. if it has been
* informed of a good enough cell).
* May be NULL (useful for debugging only).
* A scan will be aborted if more than
* #U_CELL_NET_DEEP_SCAN_TIME_SECONDS pass.
* IMPORTANT: the callback function should
* not call back into this API (which will
* be locked): it must return false to allow
* uCellNetDeepScan() to exit and only then
* should it call, for instance,
* uCellTimeSyncCellEnable().
* @param[in,out] pCallbackParameter a pointer to be passed to pCallback
* as its third parameter; may be NULL.
* @return on success the number of cells that were
* detected else negative error code; note that
* this is the number of cells in a complete
* and successful scan. If the scan had to
* be repeated because the module indicated
* a failure part way through then the
* callback may end up being called more
* times than the return value might suggest.
* A value of zero will be returned if the
* scan succeeds but returns no cells.
*/
int32_t uCellNetDeepScan(uDeviceHandle_t cellHandle,
bool (*pCallback) (uDeviceHandle_t,
uCellNetCellInfo_t *,
void *),
void *pCallbackParameter);
/** Enable or disable the registration status call-back. This
* call-back allows the application to know the various
* states of the network scanning, registration and rejections
* from the networks.
*
* You may use the #U_CELL_NET_STATUS_MEANS_REGISTERED macro
* with the second parameter passed to the callback to
* determine if the status value means that the module is
* currently registered with the network or not.
*
* @param cellHandle the handle of the cellular
* instance.
* @param[in] pCallback pointer to the function to
* handle any registration
* state changes. Use NULL to
* deactivate a previously
* active registration status
* callback.
* @param[in] pCallbackParameter a pointer to be passed to
* the call-back as its third
* parameter; may be NULL.
* @return zero on success or negative
* error code on failure.
*/
int32_t uCellNetSetRegistrationStatusCallback(uDeviceHandle_t cellHandle,
void (*pCallback) (uCellNetRegDomain_t,
uCellNetStatus_t,
void *),
void *pCallbackParameter);
/** Enable or disable the module's base station connection
* call-back. The callback will be called with the Boolean
* parameter set to true when it enters connected state and
* false when it leaves connected state. It is module
* dependent as to whether such an indication is supported:
* for instance SARA-U201 and SARA-R410M-02B do NOT support
* such an indication; if the module does not support such
* an indication under any circumstances an error will be
* returned by this function.
*
* Note that the state of the base station connection and
* that of registration are not the same: the
* base station connection will be active while the module
* is communicating with, or maintaining readiness to
* communicate with, the base station. It is possible to
* be connected but not registered and vice-versa.
*
* @param cellHandle the handle of the
* cellular instance.
* @param[in] pCallback pointer to the
* function to handle
* any connection state
* changes. Use NULL
* to deactivate a previously
* active connection status
* call-back.
* @param[in] pCallbackParameter a pointer to be passed
* to the call-back as its
* second parameter; may be
* NULL.
* @return zero on success or negative
* error code on failure.
*/
int32_t uCellNetSetBaseStationConnectionStatusCallback(uDeviceHandle_t cellHandle,
void (*pCallback) (bool,
void *),
void *pCallbackParameter);
/** Get the current network registration status. If you
* simply want to confirm that registration has been
* achieved, use uCellNetIsRegistered() instead.
*
* @param cellHandle the handle of the cellular instance.
* @param domain you may be registered on a cellular
* network for circuit switched or
* packet switched access, where the one
* you will get depends upon the
* subscription you have purchased or
* possibly the roaming agreement your
* home operator has with a visited
* network. 99% of the time you will
* only care about #U_CELL_NET_REG_DOMAIN_PS.
* but you may set #U_CELL_NET_REG_DOMAIN_CS
* to specifically check the status for
* circuit switched service only.
* @return the current status.
*/
uCellNetStatus_t uCellNetGetNetworkStatus(uDeviceHandle_t cellHandle,
uCellNetRegDomain_t domain);
/** Get the last EMM reject cause value sent by the network; not
* supported by all module types (for example SARA-R4 series
* modules do not support this). If there is nothing to report
* zero will be returned. Note that the error may have
* occurred some time in the past, e.g. you may be successfully
* registered but if, on the way, you were temporarily denied
* service then this function will likely return the reason for
* that denial (e.g. 11 for "PLMN not allowed"), rather than zero.
*
* @param cellHandle the handle of the cellular instance.
* @return on success the last EMM cause from the network,
* see appendix A.3 of the AT commands manual,
* else negative error code.
*/
int32_t uCellNetGetLastEmmRejectCause(uDeviceHandle_t cellHandle);
/** Get a value indicating whether the module is registered on
* the network, roaming or home networks.
*
* @param cellHandle the handle of the cellular instance.
* @return true if registered either on roaming or home
* networks, false otherwise.
*/
bool uCellNetIsRegistered(uDeviceHandle_t cellHandle);
/** Return the RAT that is currently in use.
*
* @param cellHandle the handle of the cellular instance.
* @return the current RAT or -1 on failure (which means
* that the module is not registered on any RAT).
*/
uCellNetRat_t uCellNetGetActiveRat(uDeviceHandle_t cellHandle);
/** Get the name of the operator on which the cellular module is
* registered. An error will be returned if the module is not
* registered on the network at the time this is called.
*
* @param cellHandle the handle of the cellular instance.
* @param[out] pStr a pointer to size bytes of storage into which
* the operator name will be copied. Room
* should be allowed for a null terminator, which
* will be added to terminate the string. This
* pointer cannot be NULL.
* @param size the number of bytes available at pStr, including
* room for a null terminator. Must be greater
* than zero.
* @return on success, the number of characters copied into
* pStr NOT including the terminator (as strlen()
* would return), on failure negative error code.
*/
int32_t uCellNetGetOperatorStr(uDeviceHandle_t cellHandle,
char *pStr, size_t size);
/** Get the MCC/MNC of the network on which the cellular module is
* registered. An error will be returned if the module is not
* registered on the network at the time this is called.
* To get the returned values into the same form as the
* pMccMnc strings used elsewhere in this API, snprintf() them
* into a buffer of length #U_CELL_NET_MCC_MNC_LENGTH_BYTES with
* the formatter "%03d%02d".
*
* @param cellHandle the handle of the cellular instance.
* @param[out] pMcc pointer to a place to store the MCC; cannot
* be NULL.
* @param[out] pMnc pointer to a place to store the MNC; cannot
* be NULL.
* @return zero on success else negative error code.
*/
int32_t uCellNetGetMccMnc(uDeviceHandle_t cellHandle,
int32_t *pMcc, int32_t *pMnc);
/** Return the IP address of the currently active connection.
*
* @param cellHandle the handle of the cellular instance.
* @param[out] pStr should point to storage of length at least
* #U_CELL_NET_IP_ADDRESS_SIZE bytes in size.
* On return the IP address will be written to
* pStr as a string and a null terminator will
* be added.
* May be set to NULL for a simple test as to
* whether an IP address has been allocated or not.
* @return on success, the number of characters that would
* be copied into into pStr if it is not NULL,
* NOT including the terminator (as strlen()
* would return), on failure negative error code.
*/
int32_t uCellNetGetIpAddressStr(uDeviceHandle_t cellHandle, char *pStr);
/** Return the IP addresses of the first and second DNS assigned
* by the network. Without a DNS the module is unable to
* use hostnames in these API functions, only IP addresses. Note
* that some modules do not support reading out the DNS address
* (e.g. LENA-R8 does not).
*
* @param cellHandle the handle of the cellular instance.
* @param v6 set this to true if IPV6 DNS addresses
* should be returned, else IPV4 addresses
* will be returned. In some cases it is
* not possible to return IPV6 addresses
* (e.g. the IP stack inside SARA-U201 is
* IPV4 only), in which case IPV4 addresses
* may be returned even when IPV6 addresses
* have been requested: the user should
* expect either.
* @param[out] pStrDns1 a pointer to storage of length at least
* #U_CELL_NET_IP_ADDRESS_SIZE bytes in size.
* On return the primary DNS address will be
* written to pStr as a string and a null
* terminator will be added.
* May be set to NULL for a simple test as to
* whether a DNS address has been allocated or
* not.
* @param[out] pStrDns2 a pointer to storage of length at least
* #U_CELL_NET_IP_ADDRESS_SIZE bytes in size.
* On return the secondary DNS address will be
* written to pStr as a string and a null
* terminator will be added. May be set to NULL.
* @return zero if at least one DNS address has been
* assigned (either v4 or v6, irrespective
* of the setting of the v6 parameter) else
* negative error code.
*/
int32_t uCellNetGetDnsStr(uDeviceHandle_t cellHandle, bool v6,
char *pStrDns1, char *pStrDns2);
/** Get the APN currently in use. Not all modules support this
* (e.g. LENA-R8 does not).
*
* @param cellHandle the handle of the cellular instance.
* @param[out] pStr a pointer to size bytes of storage into which
* the APN string will be copied. Room should be
* allowed for a null terminator, which will be
* added to terminate the string; to ensure
* the maximum number of characters for an APN
* can be stored, allocate
* #U_CELL_NET_MAX_APN_LENGTH_BYTES. This pointer
* cannot be NULL.
* @param size the number of bytes available at pStr, including
* room for a null terminator. Must be greater
* than zero.
* @return on success, the number of characters copied into
* pStr NOT including the terminator (as strlen()
* would return), on failure negative error code.
*/
int32_t uCellNetGetApnStr(uDeviceHandle_t cellHandle, char *pStr, size_t size);
/* ----------------------------------------------------------------
* FUNCTIONS: DATA COUNTERS
* -------------------------------------------------------------- */
/** Get the current value of the transmit data counter. Only
* available when a connection is active.
*
* @param cellHandle the handle of the cellular instance.
* @return the number of data bytes transmitted, since
* the cellular connection was made, or negative
* error code. The count resets to zero when
* the connection is dropped.
*/
int32_t uCellNetGetDataCounterTx(uDeviceHandle_t cellHandle);
/** Get the current value of the receive data counter. Only
* available when a connection is active.
*
* @param cellHandle the handle of the cellular instance.
* @return the number of data bytes received, since
* the cellular connection was made, or negative
* error code. The count resets to zero when
* the connection is dropped.
*/
int32_t uCellNetGetDataCounterRx(uDeviceHandle_t cellHandle);
/** Reset the transmit and receive data counters. Only
* available when a connection is active.
*
* @param cellHandle the handle of the cellular instance.
* @return zero on success, else negative error code.
*/
int32_t uCellNetResetDataCounters(uDeviceHandle_t cellHandle);
/* ----------------------------------------------------------------
* FUNCTIONS: AUTHENTICATION MODE
* -------------------------------------------------------------- */
/** Get the authentication mode that the module will use if a
* user name and password is included with uCellNetConnect()
* and uCellNetActivate().
*
* @param cellHandle the handle of the cellular instance.
* @return on success the authentication mode, from
* #uCellNetAuthenticationMode_t, else negative
* error code.
*/
int32_t uCellNetGetAuthenticationMode(uDeviceHandle_t cellHandle);
/** Set the authentication mode: this is ONLY relevant if a user name
* and password is required by the network (see uCellNetConnect()
* and uCellNetActivate()) and the cellular module does NOT support
* automatic authentication mode. You may determine if automatic
* authentication mode is supported by calling
* uCellNetGetAuthenticationMode(): if automatic authentication mode
* is supported then it will be the default and
* #U_CELL_NET_AUTHENTICATION_MODE_AUTOMATIC will be returned, else
* the default authentication mode will be
* #U_CELL_NET_AUTHENTICATION_MODE_NOT_SET and you must call
* uCellNetSetAuthenticationMode() to set it. If the authentication
* mode turns out to be #U_CELL_NET_AUTHENTICATION_MODE_NOT_SET then
* you MUST call this function before you call uCellNetConnect() or
* uCellNetActivate() with a non-NULL user name and password,
* otherwise those functions will return an error and no connection
* will be made.
*
* Note: there is no need to set the authentication mode to
* #U_CELL_NET_AUTHENTICATION_MODE_NOT_SET; the setting will only be
* applied if a username and password are in use, should they not
* be in use then the authentiction mode will in any case be "none".
*
* @param cellHandle the handle of the cellular instance.
* @param mode the authentication mode.
* @return zero on success, else negative error code.
*/
int32_t uCellNetSetAuthenticationMode(uDeviceHandle_t cellHandle,
uCellNetAuthenticationMode_t mode);
#ifdef __cplusplus
}
#endif
/** @}*/
#endif // _U_CELL_NET_H_
// End of file