Skip to content

Commit e30cfd8

Browse files
github-actions[bot]github-actions[bot]
committed
Update documentation
1 parent 1a68dcf commit e30cfd8

File tree

1 file changed

+165
-14
lines changed

1 file changed

+165
-14
lines changed

‎docs/api.md

Lines changed: 165 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
Members | Descriptions
44
--------------------------------|---------------------------------------------
55
`class ` [`ArduinoCellular`](#class_arduino_cellular) | This class provides methods to interact with the Arduino Pro Modem, such as connecting to the network, sending [SMS](#class_s_m_s) messages, getting GPS location, and more.
6+
`class ` [`ManagedTinyGsmClient`](#class_managed_tiny_gsm_client) | A managed client for TinyGSM that automatically handles socket allocation and release. This class allows you to create multiple clients without worrying about socket management. It uses a static bit field to track used sockets and provides methods to lock and unlock the sockets.
67
`class ` [`ModemInterface`](#class_modem_interface) | Represents the interface to the 4G modem module which extends the TinyGsmBG96 class.
78
`class ` [`SMS`](#class_s_m_s) | Represents an [SMS](#class_s_m_s) message.
89
`class ` [`Time`](#class_time) | Represents a point in time with year, month, day, hour, minute, second, and offset.
@@ -19,26 +20,28 @@ This class provides methods to interact with the Arduino Pro Modem, such as conn
1920
| [`ArduinoCellular`](#class_arduino_cellular_1a96d1d9f3fbe80adc3d460b4364d47870) | Creates an instance of the [ArduinoCellular](#class_arduino_cellular) class. |
2021
| [`begin`](#class_arduino_cellular_1ad5ca7cf61f48c40569f41f3029d6516e) | Initializes the modem. This function must be called before using any other functions in the library. |
2122
| [`unlockSIM`](#class_arduino_cellular_1aa0be2795ff7b23c39ecef90d9906bbdf) | Unlocks the SIM card using the specified PIN. |
22-
| [`connect`](#class_arduino_cellular_1a7fb3c3e841b39c4faacef32cec6277b4) | Registers with the cellular network and connects to the Internet if the APN, GPRS username, and GPRS password are provided. |
23+
| [`connect`](#class_arduino_cellular_1ad50b506df65a6ac4c81b9e88095ecd24) | Registers with the cellular network and connects to the Internet if the APN, GPRS username, and GPRS password are provided. |
24+
| [`connect`](#class_arduino_cellular_1a247ff63f5852b42f32103d4cef84b2a3) | Registers with the cellular network and connects to the Internet if the APN, GPRS username, and GPRS password are provided. |
2325
| [`isConnectedToOperator`](#class_arduino_cellular_1af7453ef90702e9042e2b4b18fa89db03) | Checks if the modem is registered on the network. |
2426
| [`isConnectedToInternet`](#class_arduino_cellular_1a6f8251e06de1810897b8bd8f8fb1b1a2) | Checks if the GPRS network is connected. |
2527
| [`enableGPS`](#class_arduino_cellular_1abe77a53e0eba6e8d62ba5db3bb6f5e92) | Enables or disables the GPS functionality. |
2628
| [`getGPSLocation`](#class_arduino_cellular_1a41225f52d059df173f028ecd0c039ec3) | Gets the GPS location. (Blocking call) |
2729
| [`getCellularTime`](#class_arduino_cellular_1a6b3ce5485badff582584d539e790aff4) | Gets the current time from the network. |
2830
| [`getGPSTime`](#class_arduino_cellular_1a4aeb898c958e6eb001d606f0c7da8799) | Gets the current time from the GPS module. |
2931
| [`sendSMS`](#class_arduino_cellular_1a371aef1318857f0863f443eaeabf4ac2) | Sends an [SMS](#class_s_m_s) message to the specified number. |
30-
| [`getReadSMS`](#class_arduino_cellular_1ae032c4e4cade6579a2c1edfe53d2ff2b) | Gets the list of read [SMS](#class_s_m_s) messages. |
31-
| [`getUnreadSMS`](#class_arduino_cellular_1a212513654884058947a2a4d332f6ccfc) | Gets the list of unread [SMS](#class_s_m_s) messages. |
32+
| [`getReadSMS`](#class_arduino_cellular_1a5da65683df86af75590c7a68766236ee) | Gets the list of read [SMS](#class_s_m_s) messages. |
33+
| [`getUnreadSMS`](#class_arduino_cellular_1af1e3b2fad0a64f3b7675c88100ddbca5) | Gets the list of unread [SMS](#class_s_m_s) messages. |
3234
| [`deleteSMS`](#class_arduino_cellular_1abe4337f0bc8c486a076011309120ace1) | Deletes an [SMS](#class_s_m_s) message at the specified index. |
3335
| [`sendATCommand`](#class_arduino_cellular_1a58a3e3713af0c01ad1075a2509c6874d) | Sends an AT command to the modem and waits for a response, then returns the response. |
3436
| [`sendUSSDCommand`](#class_arduino_cellular_1a6886aec5850836ea8e8f135d4e5632ab) | Sends a USSD command to the network operator and waits for a response. |
35-
| [`getNetworkClient`](#class_arduino_cellular_1acff92474af3bd819b62f132cf12f45ba) | Gets the Network client. (OSI Layer 3) |
37+
| [`getNetworkClient`](#class_arduino_cellular_1acff92474af3bd819b62f132cf12f45ba) | Gets a new Network client. (OSI Layer 3) The library automatically manages the sockets, so you can create multiple clients without worrying about socket management. You should ensure that you release the client when you are done with it. It's possible that the client is invalid if no sockets are available. This is indicated by the isValid() method and the socketId will be -1. |
3638
| [`getSecureNetworkClient`](#class_arduino_cellular_1a8b7486d1a682787588c015af8d65a38e) | Gets the Transport Layer Security (TLS) client. (OSI Layer 4) |
37-
| [`getHTTPClient`](#class_arduino_cellular_1aa1b4c3bbd14984d2a7ed1db7fa1ac930) | Gets the HTTP client for the specified server and port. |
38-
| [`getHTTPSClient`](#class_arduino_cellular_1aeb2d1bff0405e92197c0de750cef87e0) | Gets the HTTPS client for the specified server and port. |
39+
| [`getHTTPClient`](#class_arduino_cellular_1aa1b4c3bbd14984d2a7ed1db7fa1ac930) | Gets a HTTP client for the specified server and port. The maximum number of HTTP clients is limited by the number of sockets available. |
40+
| [`getHTTPSClient`](#class_arduino_cellular_1aeb2d1bff0405e92197c0de750cef87e0) | Gets a HTTPS client for the specified server and port. The maximum number of HTTP clients is limited by the number of sockets available. |
3941
| [`getIPAddress`](#class_arduino_cellular_1aabf2ad2144827d34c3ba298b5f423344) | Gets the local IP address. |
4042
| [`getSignalQuality`](#class_arduino_cellular_1aefdae9cb2b8c9f05130b09c18c3f245e) | Gets the signal quality. |
4143
| [`setDebugStream`](#class_arduino_cellular_1aae2cacf5a5778293f0bd3312d2289327) | Sets the debug stream for [ArduinoCellular](#class_arduino_cellular). |
44+
| [`getSimStatus`](#class_arduino_cellular_1a25aae9d375b5a0e1c4271f06815adc49) | Gets the SIM card status. |
4245

4346
## Members
4447

@@ -77,10 +80,10 @@ Unlocks the SIM card using the specified PIN.
7780
True if the SIM card is unlocked, false otherwise.
7881
<hr />
7982
80-
### `connect` <a id="class_arduino_cellular_1a7fb3c3e841b39c4faacef32cec6277b4" class="anchor"></a>
83+
### `connect` <a id="class_arduino_cellular_1ad50b506df65a6ac4c81b9e88095ecd24" class="anchor"></a>
8184
8285
```cpp
83-
bool connect(String apn, String username, String password)
86+
bool connect(String apn, String username, String password, bool waitForever)
8487
```
8588

8689
Registers with the cellular network and connects to the Internet if the APN, GPRS username, and GPRS password are provided.
@@ -92,6 +95,25 @@ Registers with the cellular network and connects to the Internet if the APN, GPR
9295

9396
* `password` The APN password.
9497

98+
* `waitForever` The function does not return unless a connection has been established
99+
100+
#### Returns
101+
True if the connection is successful, false otherwise.
102+
<hr />
103+
104+
### `connect` <a id="class_arduino_cellular_1a247ff63f5852b42f32103d4cef84b2a3" class="anchor"></a>
105+
106+
```cpp
107+
bool connect(String apn, bool waitForever)
108+
```
109+
110+
Registers with the cellular network and connects to the Internet if the APN, GPRS username, and GPRS password are provided.
111+
112+
#### Parameters
113+
* `apn` The Access Point Name.
114+
115+
* `waitForever` The function does not return unless a connection has been established
116+
95117
#### Returns
96118
True if the connection is successful, false otherwise.
97119
<hr />
@@ -188,7 +210,7 @@ Sends an [SMS](#class_s_m_s) message to the specified number.
188210
* `message` The message to send.
189211
<hr />
190212
191-
### `getReadSMS` <a id="class_arduino_cellular_1ae032c4e4cade6579a2c1edfe53d2ff2b" class="anchor"></a>
213+
### `getReadSMS` <a id="class_arduino_cellular_1a5da65683df86af75590c7a68766236ee" class="anchor"></a>
192214
193215
```cpp
194216
std::vector< SMS > getReadSMS()
@@ -200,7 +222,7 @@ Gets the list of read [SMS](#class_s_m_s) messages.
200222
A vector of [SMS](#class_s_m_s) messages.
201223
<hr />
202224

203-
### `getUnreadSMS` <a id="class_arduino_cellular_1a212513654884058947a2a4d332f6ccfc" class="anchor"></a>
225+
### `getUnreadSMS` <a id="class_arduino_cellular_1af1e3b2fad0a64f3b7675c88100ddbca5" class="anchor"></a>
204226

205227
```cpp
206228
std::vector< SMS > getUnreadSMS()
@@ -265,10 +287,10 @@ The response from the network operator. (Note: The response may be an [SMS](#cla
265287
TinyGsmClient getNetworkClient()
266288
```
267289

268-
Gets the Network client. (OSI Layer 3)
290+
Gets a new Network client. (OSI Layer 3) The library automatically manages the sockets, so you can create multiple clients without worrying about socket management. You should ensure that you release the client when you are done with it. It's possible that the client is invalid if no sockets are available. This is indicated by the isValid() method and the socketId will be -1.
269291

270292
#### Returns
271-
The GSM client.
293+
A GSM client object that can be used to connect to a server.
272294
<hr />
273295

274296
### `getSecureNetworkClient` <a id="class_arduino_cellular_1a8b7486d1a682787588c015af8d65a38e" class="anchor"></a>
@@ -289,7 +311,7 @@ The GSM client.
289311
HttpClient getHTTPClient(const char * server, const int port)
290312
```
291313
292-
Gets the HTTP client for the specified server and port.
314+
Gets a HTTP client for the specified server and port. The maximum number of HTTP clients is limited by the number of sockets available.
293315
294316
#### Parameters
295317
* `server` The server address.
@@ -306,7 +328,7 @@ The HTTP client.
306328
HttpClient getHTTPSClient(const char * server, const int port)
307329
```
308330

309-
Gets the HTTPS client for the specified server and port.
331+
Gets a HTTPS client for the specified server and port. The maximum number of HTTP clients is limited by the number of sockets available.
310332

311333
#### Parameters
312334
* `server` The server address.
@@ -355,6 +377,135 @@ This function allows you to set the debug stream for [ArduinoCellular](#class_ar
355377
* `stream` A pointer to the Stream object that will be used as the debug stream.
356378
<hr />
357379
380+
### `getSimStatus` <a id="class_arduino_cellular_1a25aae9d375b5a0e1c4271f06815adc49" class="anchor"></a>
381+
382+
```cpp
383+
SimStatus getSimStatus()
384+
```
385+
386+
Gets the SIM card status.
387+
388+
#### Returns
389+
The SIM card status.
390+
<hr />
391+
392+
# class `ManagedTinyGsmClient` <a id="class_managed_tiny_gsm_client" class="anchor"></a>
393+
394+
```cpp
395+
class ManagedTinyGsmClient
396+
: public TinyGsmClient
397+
```
398+
399+
A managed client for TinyGSM that automatically handles socket allocation and release. This class allows you to create multiple clients without worrying about socket management. It uses a static bit field to track used sockets and provides methods to lock and unlock the sockets.
400+
401+
## Summary
402+
403+
Members | Descriptions
404+
--------------------------------|---------------------------------------------
405+
| [`ManagedTinyGsmClient`](#class_managed_tiny_gsm_client_1ae8426b2b9cbc4fd5cc42fc63b29c4765) | Constructs a [ManagedTinyGsmClient](#class_managed_tiny_gsm_client) with the specified modem. |
406+
| [`ManagedTinyGsmClient`](#class_managed_tiny_gsm_client_1afaea0452624a337c1b9833be6ccb5432) | Copy constructor for [ManagedTinyGsmClient](#class_managed_tiny_gsm_client). This constructor allocates a new socket for the copied client. |
407+
| [`operator=`](#class_managed_tiny_gsm_client_1af87b0fec92e954c59b7a660f2fb4e8f4) | Assignment operator for [ManagedTinyGsmClient](#class_managed_tiny_gsm_client). |
408+
| [`ManagedTinyGsmClient`](#class_managed_tiny_gsm_client_1a50389bc67386357c251be242f8a5edb1) | Move constructor for [ManagedTinyGsmClient](#class_managed_tiny_gsm_client). |
409+
| [`operator=`](#class_managed_tiny_gsm_client_1aadcf674f40d9af11dae82fb85dde41d4) | Move assignment operator for [ManagedTinyGsmClient](#class_managed_tiny_gsm_client). This operator transfers ownership of the socket from the other client to this one. |
410+
| [`~ManagedTinyGsmClient`](#class_managed_tiny_gsm_client_1af227af40b0e787ef8323c5346b69679a) | Destructor for [ManagedTinyGsmClient](#class_managed_tiny_gsm_client). Releases the socket if it is valid. |
411+
| [`getSocketId`](#class_managed_tiny_gsm_client_1a8c1bd76a1728ddefacfdd30c81ac70d7) | Get the socket ID for this client. The maximum number of sockets is defined by TINY_GSM_MUX_COUNT. If the client is invalid, the socketId will be -1. |
412+
| [`isValid`](#class_managed_tiny_gsm_client_1a62617c1a63c68e4cd31a4fcca52fe229) | Check if the client is valid. A client is valid if it has a socket ID >= 0. This is useful to check if the client can be used for network operations. |
413+
414+
## Members
415+
416+
### `ManagedTinyGsmClient` <a id="class_managed_tiny_gsm_client_1ae8426b2b9cbc4fd5cc42fc63b29c4765" class="anchor"></a>
417+
418+
```cpp
419+
ManagedTinyGsmClient(TinyGsm & modem)
420+
```
421+
422+
Constructs a [ManagedTinyGsmClient](#class_managed_tiny_gsm_client) with the specified modem.
423+
424+
#### Parameters
425+
* `modem` The TinyGsm modem to use.
426+
<hr />
427+
428+
### `ManagedTinyGsmClient` <a id="class_managed_tiny_gsm_client_1afaea0452624a337c1b9833be6ccb5432" class="anchor"></a>
429+
430+
```cpp
431+
ManagedTinyGsmClient(const ManagedTinyGsmClient & other)
432+
```
433+
434+
Copy constructor for [ManagedTinyGsmClient](#class_managed_tiny_gsm_client). This constructor allocates a new socket for the copied client.
435+
#### Parameters
436+
* `other` The other [ManagedTinyGsmClient](#class_managed_tiny_gsm_client) to copy from. Note: If the other client is invalid, this will also create an invalid client. The socketId will be -1.
437+
<hr />
438+
439+
### `operator=` <a id="class_managed_tiny_gsm_client_1af87b0fec92e954c59b7a660f2fb4e8f4" class="anchor"></a>
440+
441+
```cpp
442+
ManagedTinyGsmClient & operator=(const ManagedTinyGsmClient & other)
443+
```
444+
445+
Assignment operator for [ManagedTinyGsmClient](#class_managed_tiny_gsm_client).
446+
#### Parameters
447+
* `other` The other [ManagedTinyGsmClient](#class_managed_tiny_gsm_client) to copy from.
448+
449+
#### Returns
450+
A reference to this [ManagedTinyGsmClient](#class_managed_tiny_gsm_client).
451+
<hr />
452+
453+
### `ManagedTinyGsmClient` <a id="class_managed_tiny_gsm_client_1a50389bc67386357c251be242f8a5edb1" class="anchor"></a>
454+
455+
```cpp
456+
ManagedTinyGsmClient( ManagedTinyGsmClient && other)
457+
```
458+
459+
Move constructor for [ManagedTinyGsmClient](#class_managed_tiny_gsm_client).
460+
#### Parameters
461+
* `other` The other [ManagedTinyGsmClient](#class_managed_tiny_gsm_client) to move from.
462+
<hr />
463+
464+
### `operator=` <a id="class_managed_tiny_gsm_client_1aadcf674f40d9af11dae82fb85dde41d4" class="anchor"></a>
465+
466+
```cpp
467+
ManagedTinyGsmClient & operator=( ManagedTinyGsmClient && other)
468+
```
469+
470+
Move assignment operator for [ManagedTinyGsmClient](#class_managed_tiny_gsm_client). This operator transfers ownership of the socket from the other client to this one.
471+
#### Parameters
472+
* `other` The other [ManagedTinyGsmClient](#class_managed_tiny_gsm_client) to move from.
473+
474+
#### Returns
475+
A reference to this [ManagedTinyGsmClient](#class_managed_tiny_gsm_client).
476+
<hr />
477+
478+
### `~ManagedTinyGsmClient` <a id="class_managed_tiny_gsm_client_1af227af40b0e787ef8323c5346b69679a" class="anchor"></a>
479+
480+
```cpp
481+
~ManagedTinyGsmClient()
482+
```
483+
484+
Destructor for [ManagedTinyGsmClient](#class_managed_tiny_gsm_client). Releases the socket if it is valid.
485+
<hr />
486+
487+
### `getSocketId` <a id="class_managed_tiny_gsm_client_1a8c1bd76a1728ddefacfdd30c81ac70d7" class="anchor"></a>
488+
489+
```cpp
490+
inline int getSocketId() const
491+
```
492+
493+
Get the socket ID for this client. The maximum number of sockets is defined by TINY_GSM_MUX_COUNT. If the client is invalid, the socketId will be -1.
494+
#### Returns
495+
The socket ID (0 - (TINY_GSM_MUX_COUNT - 1) or -1 if invalid).
496+
<hr />
497+
498+
### `isValid` <a id="class_managed_tiny_gsm_client_1a62617c1a63c68e4cd31a4fcca52fe229" class="anchor"></a>
499+
500+
```cpp
501+
inline bool isValid() const
502+
```
503+
504+
Check if the client is valid. A client is valid if it has a socket ID >= 0. This is useful to check if the client can be used for network operations.
505+
#### Returns
506+
True if the client is valid, false otherwise.
507+
<hr />
508+
358509
# class `ModemInterface` <a id="class_modem_interface" class="anchor"></a>
359510

360511
```cpp

0 commit comments

Comments
 (0)