class_gsm_client

---

title: GsmClient

GsmClient (class)

Module: GsmClient

The TCP client class.

Note

This is a base class for TCP clients, but it is NOT an inner class of the TinyGsmTCP class.

Todo: todo

#include <src/TinyGsmTCP.tpp>

Client constructors and initialization

Public Functions

	Name
	GsmClient() Create a new TCP client.
	GsmClient(modemType & modem, uint8_t mux = 0) Create a new TCP client and bind it to a modem and optionally a multiplexing channel.
virtual bool	init(modemType * modem, uint8_t mux) = 0 Initialize this client with modem context and multiplexing channel.

Arduino Client interface

Public Functions

	Name
virtual int	connect(const char * host, uint16_t port, int timeout_s) = 0 Connect to a server using a host name and port number, with a specified timeout.
virtual int	connect(IPAddress ip, uint16_t port, int timeout_s) Connect to a server using an IPAddress and port number, with a specified timeout.
override int	connect(const char * host, uint16_t port) Connect to a server using a host name and port number.
override int	connect(IPAddress ip, uint16_t port) Connect to a server using an IPAddress and port number.
virtual void	stop(uint32_t maxWaitMs) Close the client connection, with a specified maximum wait time for the operation.
override void	stop() Close the client connection, with a default maximum wait time.
override size_t	write(const uint8_t * buf, size_t size) Writes data out on the client using the modem send functionality.
override size_t	write(uint8_t c) Writes a single byte of data to the modem for sending.
override int	available() Get the number of bytes available for in the client's receive buffer. This returns the combined total of the number of bytes available in the TinyGSM fifo and the modem chip's internal fifo (where supported).
override int	read(uint8_t * buf, size_t size) Read data from the client's receive buffer into a user provided buffer.
override int	read() Read a single byte from the client's receive buffer.
override int	peek() Peek at the next byte in the client's receive buffer without removing it.
override void	flush() Flush the client's send buffer (ie, wait for all data to be sent).
override uint8_t	connected() Check if the client is connected.
override	operator bool() Check if the client is connected (overrides operator bool).
virtual	~GsmClient() 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() Get the remote IP address of the connected client.
uint8_t	getMux() Get the zero-indexed position of the client in the corresponding modem's socket array.
uint8_t	getConnectionID() 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(uint16_t size) Begin writing to the modem client.
bool	endWrite(uint16_t expected_size = 0) Conclude a write to the module.

Public Functions Documentation

Client constructors and initialization

functionGsmClient

 GsmClient()

Warning

You must call the init() method before attempting to use a client created with this constructor.

functionGsmClient

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

• Parameters:
  • modem Modem instance used by this client.
  • mux The zero-indexed position of this client in the corresponding modem'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's internal socket identifier.

functioninit

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

• Parameters:
  • modem Pointer to the modem instance.
  • mux The zero-indexed position of this client in the corresponding modem'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's internal socket identifier.
• Return: true if initialization completed.

Arduino Client interface

functionconnect

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

Tip

Every time you call the connect() 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

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) 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

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

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

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

void stop() override

functionwrite

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

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) or write(const char* str) function instead.

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

functionavailable

int available() override

• Return: The number of bytes available in the client's receive buffer.

functionread

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

int read() override

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

functionpeek

int peek() override

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

functionflush

void flush() override

functionconnected

uint8_t connected() override

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

functionoperator bool

 operator bool() override

function~GsmClient

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

String remoteIP()

• Return: The remote IP address as a String

functiongetMux

uint8_t getMux()

• Return: The socket position as a uint8_t

functiongetConnectionID

uint8_t getConnectionID()

• Return: The internal connection number as a uint8_t

functionbeginWrite

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

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 and m.css with templates from doxybook2 Updated on 2026-09-11