---
title: GsmClient
---

# GsmClient (class)

**Module:** **[GsmClient](class_gsm_client.html)**

The TCP client class.



> [!NOTE]
> This is a base class for TCP clients, but it is NOT an inner class of the [TinyGsmTCP](../classes/class_tiny_gsm_t_c_p.md) class.


**Todo**: [todo](todo.html#_todo000025)

`#include <src/TinyGsmTCP.tpp>`


## Client constructors and initialization



### Public Functions

|                | Name           |
| -------------- | -------------- |
|  | **[GsmClient](#aaac2caa051e733446db50d3edc9d351c)**() <br>Create a new TCP client. |
|  | **[GsmClient](#ae9a7f8a471490153f35f2c71a8b32369)**(modemType & modem, uint8_t mux = 0) <br>Create a new TCP client and bind it to a modem and optionally a multiplexing channel. |
| *virtual*<br>bool | **[init](#a3dc5e17ba6749c68983d3bf39fabb29e)**(modemType * modem, uint8_t mux) = 0 <br>Initialize this client with modem context and multiplexing channel. |

## Arduino Client interface



### Public Functions

|                | Name           |
| -------------- | -------------- |
| *virtual*<br>int | **[connect](#ac3343dcdf3ba62f63aeb3b0775e4a93a)**(const char * host, uint16_t port, int timeout_s) = 0 <br>Connect to a server using a host name and port number, with a specified timeout. |
| *virtual*<br>int | **[connect](#aec4d4702d5652a7ccce867f0dcb1fd29)**(IPAddress ip, uint16_t port, int timeout_s) <br>Connect to a server using an IPAddress and port number, with a specified timeout. |
| *override*<br>int | **[connect](#a6e86eac67796044a92dba6695e2f6f9f)**(const char * host, uint16_t port) <br>Connect to a server using a host name and port number. |
| *override*<br>int | **[connect](#a19fa0b322c6fb17a1d0de28d747222ec)**(IPAddress ip, uint16_t port) <br>Connect to a server using an IPAddress and port number. |
| *virtual*<br>void | **[stop](#a138ad35447383cc62d99c037743e4210)**(uint32_t maxWaitMs) <br>Close the client connection, with a specified maximum wait time for the operation. |
| *override*<br>void | **[stop](#acac60bc3c9cb1e7d58e2b13833e4c720)**() <br>Close the client connection, with a default maximum wait time. |
| *override*<br>size_t | **[write](#a528d5a4c7d75a6951ec236b7b46fcedb)**(const uint8_t * buf, size_t size) <br>Writes data out on the client using the modem send functionality. |
| *override*<br>size_t | **[write](#a3afda0b395cdc163a542915c90c3647b)**(uint8_t c) <br>Writes a single byte of data to the modem for sending. |
| *override*<br>int | **[available](#a5327499ee49bd0f7ca6ea292de7fe492)**() <br>Get the number of bytes available for in the client&#x27;s receive buffer. This returns the combined total of the number of bytes available in the TinyGSM fifo and the modem chip&#x27;s internal fifo (where supported). |
| *override*<br>int | **[read](#a2cd9c417964981283684cdea7ac7d3c2)**(uint8_t * buf, size_t size) <br>Read data from the client&#x27;s receive buffer into a user provided buffer. |
| *override*<br>int | **[read](#af3b9f9b2908979e751098c222fc655d4)**() <br>Read a single byte from the client&#x27;s receive buffer. |
| *override*<br>int | **[peek](#aa684170a2aa623822ccc3d428568913e)**() <br>Peek at the next byte in the client&#x27;s receive buffer without removing it. |
| *override*<br>void | **[flush](#ad7f9b8cf52f29a390fafc3003f1ecd99)**() <br>Flush the client&#x27;s send buffer (ie, wait for all data to be sent). |
| *override*<br>uint8_t | **[connected](#a5eb01b0909582692e00b07c41ec7bd22)**() <br>Check if the client is connected. |
| *override*<br> | **[operator bool](#a4674f613e683a4b56ff42ac673573089)**() <br>Check if the client is connected (overrides operator bool). |
| *virtual*<br> | **[~GsmClient](#a7f3a7fe8dd9fd3d3abe41fa8e811bb50)**() <br>destructor - need to remove self from the socket pointer array |

## Extended Client API




These functions are **NOT** virtual to avoid linker errors if one or more of them are not implemented in a derived class. Derived classes that implement these functions can hide the base class versions to implement them.

### Public Functions

|                | Name           |
| -------------- | -------------- |
| String | **[remoteIP](#aad926ad92b0e7754620e9ab249ad73e8)**() <br>Get the remote IP address of the connected client. |
| uint8_t | **[getMux](#a9dc458d3a5eced0cfecdbdc72e06d6c0)**() <br>Get the <strong>zero-indexed</strong> position of the client in the corresponding modem&#x27;s socket array. |
| uint8_t | **[getConnectionID](#a198f6e1698d43841c3a1ab287bca914d)**() <br>Get the number that the modem uses internally to identify the connection. In most cases, this is the same as the socket position. |
| bool | **[beginWrite](#a3faf91fd6a17294a5915ce57ac5bdc0d)**(uint16_t size) <br>Begin writing to the modem client. |
| bool | **[endWrite](#a36e18c3adb596ab7d299796e658f42a5)**(uint16_t expected_size = 0) <br>Conclude a write to the module. |

## Public Functions Documentation

### Client constructors and initialization



#### functionGsmClient
<a id="aaac2caa051e733446db50d3edc9d351c"></a>

```cpp
 GsmClient()

```



> [!WARNING]
> You must call the [init()](class_gsm_client.md#a3dc5e17ba6749c68983d3bf39fabb29e) method before attempting to use a client created with this constructor.

#### functionGsmClient
<a id="ae9a7f8a471490153f35f2c71a8b32369"></a>

```cpp
explicit  GsmClient(modemType & modem, uint8_t mux = 0)

```



- **Parameters**:
  - **modem** Modem instance used by this client.
  - **mux** The <strong>zero-indexed</strong> position of this client in the corresponding modem&#x27;s socket array. For most modules, this is identical to the identifier the modem uses internally to identify the socket, but some modules (e.g., Sequans Monarch) use a 1-indexed identifier for the socket, so the mux number is not necessarily the same as the modem&#x27;s internal socket identifier.

#### functioninit
<a id="a3dc5e17ba6749c68983d3bf39fabb29e"></a>

```cpp
virtual bool init(modemType * modem, uint8_t mux) = 0

```



- **Parameters**:
  - **modem** Pointer to the modem instance.
  - **mux** The <strong>zero-indexed</strong> position of this client in the corresponding modem&#x27;s socket array. For most modules, this is identical to the identifier the modem uses internally to identify the socket, but some modules (e.g., Sequans Monarch) use a 1-indexed identifier for the socket, so the mux number is not necessarily the same as the modem&#x27;s internal socket identifier.
- **Return**: true if initialization completed.

### Arduino Client interface



#### functionconnect
<a id="ac3343dcdf3ba62f63aeb3b0775e4a93a"></a>

```cpp
virtual int connect(const char * host, uint16_t port, int timeout_s) = 0

```





> [!TIP]
> Every time you call the [connect()](class_gsm_client.md#ac3343dcdf3ba62f63aeb3b0775e4a93a) function, it will stop the socket if there was one and it was connected. It will also clear the receive buffer before connecting.

- **Parameters**:
  - **host** The host name of the server to connect to.
  - **port** The port number to connect to on the server.
  - **timeout_s** The timeout for the connection attempt, in seconds.
- **Return**: 1 if the connection was successful, 0 otherwise.

#### functionconnect
<a id="aec4d4702d5652a7ccce867f0dcb1fd29"></a>

```cpp
virtual int connect(IPAddress ip, uint16_t port, int timeout_s)

```


The default implementation of this function converts the IPAddress to a string and calls the [connect(const char* host, uint16_t port, int
timeout_s)](class_gsm_client.md#ac3343dcdf3ba62f63aeb3b0775e4a93a) function.

- **Parameters**:
  - **ip** The IP address of the server to connect to.
  - **port** The port number to connect to on the server.
  - **timeout_s** The timeout for the connection attempt, in seconds.
- **Return**: 1 if the connection was successful, 0 otherwise.

#### functionconnect
<a id="a6e86eac67796044a92dba6695e2f6f9f"></a>

```cpp
int connect(const char * host, uint16_t port) override

```



- **Parameters**:
  - **host** The host name of the server to connect to.
  - **port** The port number to connect to on the server.
- **Return**: 1 if the connection was successful, 0 otherwise.

#### functionconnect
<a id="a19fa0b322c6fb17a1d0de28d747222ec"></a>

```cpp
int connect(IPAddress ip, uint16_t port) override

```



- **Parameters**:
  - **ip** The IP address of the server to connect to.
  - **port** The port number to connect to on the server.
- **Return**: 1 if the connection was successful, 0 otherwise.

#### functionstop
<a id="a138ad35447383cc62d99c037743e4210"></a>

```cpp
virtual void stop(uint32_t maxWaitMs)

```


If there is modem remaining in the modem buffer before the connection is closed, it will be dumped and lost.



> [!NOTE]
> The max wait time is the time to give the modem to close the connection cleanly. If there is modem remaining in the modem buffer before the connection is closed, the total time before this function returns may be longer than the max wait time, as dumping the modem buffer may take additional time.

- **Parameters**:
  - **maxWaitMs** The maximum time to wait for the connection to close, in milliseconds.

#### functionstop
<a id="acac60bc3c9cb1e7d58e2b13833e4c720"></a>

```cpp
void stop() override

```



#### functionwrite
<a id="a528d5a4c7d75a6951ec236b7b46fcedb"></a>

```cpp
size_t write(const uint8_t * buf, size_t size) override

```



- **Parameters**:
  - **buf** The buffer of data to send
  - **size** The size of the buffer
- **Return**: The number of bytes written

#### functionwrite
<a id="a3afda0b395cdc163a542915c90c3647b"></a>

```cpp
size_t write(uint8_t c) override

```





> [!WARNING]
> This function is not efficient for sending large amounts of data. Use the [write(const uint8_t* buf, size_t size)](class_gsm_client.md#a528d5a4c7d75a6951ec236b7b46fcedb) or write(const
> char* str) function instead.

- **Parameters**:
  - **c** The byte of data to send
- **Return**: The number of bytes written

#### functionavailable
<a id="a5327499ee49bd0f7ca6ea292de7fe492"></a>

```cpp
int available() override

```



- **Return**: The number of bytes available in the client&#x27;s receive buffer.

#### functionread
<a id="a2cd9c417964981283684cdea7ac7d3c2"></a>

```cpp
int read(uint8_t * buf, size_t size) override

```



- **Parameters**:
  - **buf** The buffer to read data into.
  - **size** The maximum number of bytes to read.
- **Return**: The number of bytes actually read.

#### functionread
<a id="af3b9f9b2908979e751098c222fc655d4"></a>

```cpp
int read() override

```



- **Return**: The byte read, or -1 if no data is available.

#### functionpeek
<a id="aa684170a2aa623822ccc3d428568913e"></a>

```cpp
int peek() override

```



- **Return**: The next byte, or -1 if no data is available.

#### functionflush
<a id="ad7f9b8cf52f29a390fafc3003f1ecd99"></a>

```cpp
void flush() override

```



#### functionconnected
<a id="a5eb01b0909582692e00b07c41ec7bd22"></a>

```cpp
uint8_t connected() override

```



- **Return**: True if the client is connected, false otherwise.

#### functionoperator bool
<a id="a4674f613e683a4b56ff42ac673573089"></a>

```cpp
 operator bool() override

```



#### function~GsmClient
<a id="a7f3a7fe8dd9fd3d3abe41fa8e811bb50"></a>

```cpp
virtual  ~GsmClient()

```



### Extended Client API




These functions are **NOT** virtual to avoid linker errors if one or more of them are not implemented in a derived class. Derived classes that implement these functions can hide the base class versions to implement them.

#### functionremoteIP
<a id="aad926ad92b0e7754620e9ab249ad73e8"></a>

```cpp
String remoteIP()

```



- **Return**: The remote IP address as a String

#### functiongetMux
<a id="a9dc458d3a5eced0cfecdbdc72e06d6c0"></a>

```cpp
uint8_t getMux()

```



- **Return**: The socket position as a uint8_t

#### functiongetConnectionID
<a id="a198f6e1698d43841c3a1ab287bca914d"></a>

```cpp
uint8_t getConnectionID()

```



- **Return**: The internal connection number as a uint8_t

#### functionbeginWrite
<a id="a3faf91fd6a17294a5915ce57ac5bdc0d"></a>

```cpp
bool beginWrite(uint16_t size)

```


Use this to have the modem initiate a send data prompt which you can then fill using stream.write() commands. This is useful for sending large amounts of data in small chunks. It is analogous to the beginPublish() and endPublish() methods in PubSubClient.

- **Parameters**:
  - **size** The size of data to send. The maximum length varies by module
- **Return**: True if the module is ready to receive data to forward to the TCP connection.

#### functionendWrite
<a id="a36e18c3adb596ab7d299796e658f42a5"></a>

```cpp
bool endWrite(uint16_t expected_size = 0)

```



- **Parameters**:
  - **expected_size** The size of data that should have been sent. If a non-zero value is given, the function will check that the module has sent the expected amount of data. Does not work on all modules.
- **Return**: True if the module has successfully sent the data to the TCP connection.

-------------------------------

Generated by [Doxygen](https://www.doxygen.nl) and [m.css](https://mcss.mosra.cz/) with templates from [doxybook2](https://github.com/matusnovak/doxybook2)
Updated on 2026-09-11