Class

# EasyTCPSocket

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

## Description

Communicates with remote Xojo applications with a proprietary protocol that is implemented over TCP. It is provided so that a user who is new to TCP/IP communications can use a higher-level class than the `TCPSocket</api/networking/tcpsocket>` class to network their applications.

## Properties

<div class="rst-class">

table-centered_columns_3_and_4

</div>

| Name                                               | Type                                                 | Read-Only | Shared |
|----------------------------------------------------|------------------------------------------------------|-----------|--------|
| `Address<easytcpsocket.address>`                   | `String</api/data_types/string>`                     |           |        |
| `BytesAvailable<easytcpsocket.bytesavailable>`     | `Integer</api/data_types/integer>`                   | ✓         |        |
| `BytesLeftToSend<easytcpsocket.byteslefttosend>`   | `Integer</api/data_types/integer>`                   | ✓         |        |
| `Handle<easytcpsocket.handle>`                     | `Integer</api/data_types/integer>`                   | ✓         |        |
| `IsConnected<easytcpsocket.isconnected>`           | `Boolean</api/data_types/boolean>`                   | ✓         |        |
| `LocalAddress<easytcpsocket.localaddress>`         | `String</api/data_types/string>`                     | ✓         |        |
| `NetworkInterface<easytcpsocket.networkinterface>` | `NetworkInterface</api/networking/networkinterface>` |           |        |
| `Port<easytcpsocket.port>`                         | `Integer</api/data_types/integer>`                   |           |        |
| `RemoteAddress<easytcpsocket.remoteaddress>`       | `String</api/data_types/string>`                     | ✓         |        |

## Methods

<div class="rst-class">

table-centered_column_4

</div>

| Name                                                 | Parameters                                                                                                | Returns                            | Shared |
|------------------------------------------------------|-----------------------------------------------------------------------------------------------------------|------------------------------------|--------|
| `Close<easytcpsocket.close>`                         |                                                                                                           |                                    |        |
| `Connect<easytcpsocket.connect>`                     |                                                                                                           |                                    |        |
| `Disconnect<easytcpsocket.disconnect>`               |                                                                                                           |                                    |        |
| `EndOfFile<easytcpsocket.endoffile>`                 |                                                                                                           | `Boolean</api/data_types/boolean>` |        |
| `Flush<easytcpsocket.flush>`                         |                                                                                                           |                                    |        |
| `Listen<easytcpsocket.listen>`                       |                                                                                                           |                                    |        |
| `Lookahead<easytcpsocket.lookahead>`                 | encoding As `TextEncoding</api/text/encoding_text/textencoding>` = `Nil</api/language/nil>`               | `String</api/data_types/string>`   |        |
| `Poll<easytcpsocket.poll>`                           |                                                                                                           |                                    |        |
| `Purge<easytcpsocket.purge>`                         |                                                                                                           |                                    |        |
| `Read<easytcpsocket.read>`                           | count As `Integer</api/data_types/integer>`                                                               | `String</api/data_types/string>`   |        |
| `ReadAll<easytcpsocket.readall>`                     |                                                                                                           | `String</api/data_types/string>`   |        |
| `ReadError<easytcpsocket.readerror>`                 |                                                                                                           | `Boolean</api/data_types/boolean>` |        |
| `SendMessage<easytcpsocket.sendmessage>`             | Command As `Int32</api/data_types/additional_types/int32>`, Data As `String</api/data_types/string>`      |                                    |        |
| `WaitForConnection<easytcpsocket.waitforconnection>` | Timeout As `Integer</api/data_types/integer>`                                                             | `Boolean</api/data_types/boolean>` |        |
| `WaitForMessage<easytcpsocket.waitformessage>`       | Command As `Int32</api/data_types/additional_types/int32>`, Timeout As `Integer</api/data_types/integer>` | `String</api/data_types/string>`   |        |
| `Write<easytcpsocket.write>`                         | Data As `String</api/data_types/string>`                                                                  |                                    |        |
| `WriteError<easytcpsocket.writeerror>`               |                                                                                                           | `Boolean</api/data_types/boolean>` |        |

## Events

<div class="rst-class">

table-centered_column_4

</div>

| Name                                             | Parameters                                                                                           | Returns                            |
|--------------------------------------------------|------------------------------------------------------------------------------------------------------|------------------------------------|
| `Connected<easytcpsocket.connected>`             |                                                                                                      |                                    |
| `Error<easytcpsocket.error>`                     | e As `RuntimeException</api/exceptions/runtimeexception>`                                            |                                    |
| `ReceivedMessage<easytcpsocket.receivedmessage>` | Command As `Int32</api/data_types/additional_types/int32>`, Data As `String</api/data_types/string>` |                                    |
| `SendComplete<easytcpsocket.sendcomplete>`       | UserAborted As `Boolean</api/data_types/boolean>`                                                    |                                    |
| `SendProgress<easytcpsocket.sendprogress>`       | BytesSent As `Integer</api/data_types/integer>`, BytesLeft As `Integer</api/data_types/integer>`     | `Boolean</api/data_types/boolean>` |

## Constants

> These constants indicate which error occurred. They are the same error codes returned by `SocketCore</api/networking/socketcore>`. When an Error event occurs, check the value of the passed parameter Code against these class constants.
>
> | Error Code | Class Constant      |
> |------------|---------------------|
> | 100        | OpenDriverError     |
> | 102        | LostConnection      |
> | 103        | NameResolutionError |
> | 105        | AddressInUseError   |
> | 106        | InvalidStateError   |
> | 107        | InvalidPortError    |
> | 108        | OutOfMemoryError    |

## Property descriptions

<div id="easytcpsocket.address">

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

</div>

<div class="rst-class">

forsearch

</div>

EasyTCPSocket.Address

**Address** As `String</api/data_types/string>`

> The TCP/IP address to try to connect to.
>
> In this example, the address has been entered into a `TextField</api/user_interface/desktop/desktoptextfield>`.
>
> ``` xojo
> EasyTCPSocket1.Address = TextField1.Text
> ```

<div id="easytcpsocket.bytesavailable">

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

</div>

<div class="rst-class">

forsearch

</div>

EasyTCPSocket.BytesAvailable

**BytesAvailable** As `Integer</api/data_types/integer>`

> The number of bytes of data are available in the internal receive buffer.
>
> This property is read-only.
>
> ``` xojo
> TextField1.Text = Me.BytesAvailable.ToString
> ```

<div id="easytcpsocket.byteslefttosend">

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

</div>

<div class="rst-class">

forsearch

</div>

EasyTCPSocket.BytesLeftToSend

**BytesLeftToSend** As `Integer</api/data_types/integer>`

> The number of bytes left in the queue remaining to be sent.
>
> This property is read-only.
>
> This enables you to create a synchronous socket without needing to subclass it.
>
> ``` xojo
> TextField1.Text = Me.BytesLeftToSend.ToString
> ```

<div id="easytcpsocket.handle">

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

</div>

<div class="rst-class">

forsearch

</div>

EasyTCPSocket.Handle

**Handle** As `Integer</api/data_types/integer>`

> This is the socket's internal descriptor and it can be used with `Declare</api/language/declare>` statements.
>
> This property is read-only.
>
> - On Windows, Handle is a Socket, suitable for use in `Declares</api/language/declare>` on Windows.
> - On macOS and Linux, Handle is a UNIX socket descriptor.
>
> The descriptor is platform-specific. If *Handle* is less than zero, the descriptor is not available.

<div id="easytcpsocket.isconnected">

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

</div>

<div class="rst-class">

forsearch

</div>

EasyTCPSocket.IsConnected

**IsConnected** As `Boolean</api/data_types/boolean>`

> Indicates whether the socket is currently connected.
>
> This property is read-only.
>
> For `TCPSockets</api/networking/tcpsocket>`, a connection means you can send and receive data and are connected to a remote machine. For `UDPSockets</api/networking/udpsocket>`, this means that you are bound to the port and are able to send, receive, join or leave multicast groups, or set socket options.
>
> ``` xojo
> If EasyTCPSocket1.IsConnected Then
>   ' proceed using the connection
> Else
>   MessageBox("Connection failed!")
> End If
> ```

<div id="easytcpsocket.localaddress">

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

</div>

<div class="rst-class">

forsearch

</div>

EasyTCPSocket.LocalAddress

**LocalAddress** As `String</api/data_types/string>`

> The local IP address of the computer.
>
> This property is read-only.
>
> ``` xojo
> Var localIP As String = EasyTCPSocket1.LocalAddress
> ```

<div id="easytcpsocket.networkinterface">

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

</div>

<div class="rst-class">

forsearch

</div>

EasyTCPSocket.NetworkInterface

**NetworkInterface** As `NetworkInterface</api/networking/networkinterface>`

> Specifies which network interface the socket should use when binding.
>
> You can get the network interface(s) of the user's computer by calling the `GetNetworkInterface<system.networkinterface>` method of the `System</api/os/system>` module.
>
> Leaving this property set to `Nil</api/language/nil>` will use the currently selected interface. In the case of `UDPSockets</api/networking/udpsocket>`, if you assign a non-`Nil</api/language/nil>` value, the socket may not be able to receive broadcast messages. The behavior is OS-dependent; it appears to work on Windows but not on other supported operating systems. If you wish to send broadcast packets out, then you should not bind to a specific interface because the behavior is undefined.
>
> This example specifies that the <span class="title-ref">EasyTCPSocket</span> will use the first Network Interface on the user's computer.
>
> ``` xojo
> EasyTCPSocket1.NetworkInterface = System.NetworkInterface(0)
> ```

<div id="easytcpsocket.port">

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

</div>

<div class="rst-class">

forsearch

</div>

EasyTCPSocket.Port

**Port** As `Integer</api/data_types/integer>`

> The port to bind on or connect to.
>
> On most operating systems, attempting to bind to a port less than 1024 causes a `Error<socketcore.error>` event to fire with an error number 107 unless the application is running with administrative permissions. This is due to security features built into the underlying OS.
>
> You need to set the port property explicitly before any call to Listen or Connect as the Port property will be modified to reflect what the actual bound port is during the various stages of operation.
>
> For instance, if you listen on port 8080 and a connection comes in, you can check the Port property to ensure that you're still listening on port 8080 (that the port hasn't been hijacked). Or, if you connect to a socket on port 8080, once the connection occurs, you can check to see what port the OS has bound you to. This will be a random-seeming port number.
>
> This trick can be very useful when you do things like Listen on port 0. In that case, the OS will pick a port for you and listen on it. Then you can check the Port property to see which port the OS picked. This functionality is used for various protocols, such as FTP.
>
> This example sets the Port to 8080.
>
> ``` xojo
> EasyTCPSocket1.Port = 8080
> ```

<div id="easytcpsocket.remoteaddress">

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

</div>

<div class="rst-class">

forsearch

</div>

EasyTCPSocket.RemoteAddress

**RemoteAddress** As `String</api/data_types/string>`

> The address of the remote machine you are connected to.
>
> This property is read-only.
>
> Use this instead of the Address property to determine the address of the machine you are actually connected to.
>
> This example reports the address of the remote machine that the user is connected to. It is in the Connected event.
>
> ``` xojo
> TextField1.Text = Me.RemoteAddress
> ```

## Method descriptions

<div id="easytcpsocket.close">

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

</div>

<div class="rst-class">

forsearch

</div>

EasyTCPSocket.Close

**Close**

> Closes the socket's connection, closes any connections the socket may have, and resets the socket.
>
> The only information that is retained after calling Close is the socket's port, address (in the case of `TCPSockets</api/networking/tcpsocket>`), LastErrorCode properties, and data left in the socket's receive buffer. All other information is discarded.
>
> This example closes the <span class="title-ref">EasyTCPSocket</span> that were open. The sockets were added to the main window.
>
> ``` xojo
> Connector.Close
> Listener.Close
> ```

<div id="easytcpsocket.connect">

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

</div>

<div class="rst-class">

forsearch

</div>

EasyTCPSocket.Connect

**Connect**

> Attempts to connect.
>
> For `TCPSockets</api/networking/tcpsocket>`, the address and port properties must be set. For `UDPSockets</api/networking/udpsocket>`, the port property must be set. The Connect method binds a socket to a port. After calling Connect, the Port property will report the actual port you are bound to.

<div id="easytcpsocket.disconnect">

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

</div>

<div class="rst-class">

forsearch

</div>

EasyTCPSocket.Disconnect

**Disconnect**

> Disconnects the socket, resets it, and fires a `SocketCore</api/networking/socketcore>` Error event with a 102 error to let you know that the socket has been disconnected.
>
> This example disconnects the <span class="title-ref">EasyTCPSocket</span> that were opened.
>
> ``` xojo
> Connector.Disconnect
> Listener.Disconnect
> ```

<div id="easytcpsocket.endoffile">

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

</div>

<div class="rst-class">

forsearch

</div>

EasyTCPSocket.EndOfFile

**EndOfFile** As `Boolean</api/data_types/boolean>`

> Returns `True</api/language/true>` when there's no more data left to read.
>
> This code reads the rows and columns of data from a tab-delimited text file into a `ListBox</api/user_interface/desktop/desktoplistbox>`:
>
> ``` xojo
> Var f As FolderItem = FolderItem.ShowOpenFileDialog("text/plain") ' defined as a FileType
>
> If f <> Nil Then
>
>   Var textInput As TextInputStream
>   Var rowFromFile As String
>
>   textInput = TextInputStream.Open(f)
>   textInput.Encoding = Encodings.UTF8
>
>   Do
>
>     rowFromFile = textInput.ReadLine
>
>     Var values() As String = rowFromFile.ToArray(String.Chr(9))
>
>     ListBox1.ColumnCount = values.Count
>     ListBox1.AddRow("")
>
>     Var col As Integer
>
>     For Each value As String In values
>
>       ListBox1.CellTextAt(ListBox1.LastAddedRowIndex, col) = value
>       col = col + 1
>
>     Next
>
>   Loop Until textInput.EndOfFile
>
>   textInput.Close
>
> End If
> ```
>
> This example reads each pair of bytes from a file and writes them in reverse order to a new file. The user chooses the source file using the Open-file dialog box and saves the new file using the Save as dialog box. The EOF property is used to terminate the `Do...Loop</api/language/loops/do...loop>`.
>
> ``` xojo
> Var readFile As FolderItem = FolderItem.ShowOpenFileDialog("text")
>
> If readFile <> Nil Then
>
>   Var ReadStream As BinaryStream = BinaryStream.Open(readFile, False)
>   Var writeFile As FolderItem = FolderItem.ShowSaveFileDialog("", "")
>
>   ReadStream.LittleEndian = True
>
>   If writeFile <> Nil Then
>
>     Var writeStream As BinaryStream = BinaryStream.Create(writeFile, True)
>     writeStream.LittleEndian = True
>
>     Do Until ReadStream.EndOfFile
>       writeStream.WriteInt8(ReadStream.ReadInt8)
>     Loop
>
>     writeStream = Nil
>
>   End If
>
>   readStream = Nil
>
> End If
> ```

<div id="easytcpsocket.flush">

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

</div>

<div class="rst-class">

forsearch

</div>

EasyTCPSocket.Flush

**Flush**

> Immediately sends the contents of internal write buffers to disk or to the output stream.
>
> This function can be useful in point-to-point communication over sockets and similar connections: To optimize for transmission performance, some types of output streams try to collect small pieces of written data into one larger piece for sending instead of sending each piece out individually. By calling Flush, the data collection is stopped and the data is sent without further delay, reducing latency.
>
> When using this on a stream that ends up as a file on disk, it is useful, too: Any short parts of previously written data are written to disk right away, ensuring the data is actually on disk if the application terminates abruptly, e.g. due to a crash.
>
> Avoid calling this method too often. For example, do not call it between successive Write calls because you'll slow down performance without getting much benefit.
>
> A typical use case would look like this:
>
> ``` xojo
> mySocket.Write("you typed: ")
> mySocket.Write(key)
> mySocket.Write(".")
> mySocket.Flush
> ```

<div id="easytcpsocket.listen">

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

</div>

<div class="rst-class">

forsearch

</div>

EasyTCPSocket.Listen

**Listen**

> Attempts to listen for incoming connections on the currently specified port.
>
> After calling Listen, the Port property will report the actual port you are bound to.

<div id="easytcpsocket.lookahead">

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

</div>

<div class="rst-class">

forsearch

</div>

EasyTCPSocket.Lookahead

**Lookahead**(encoding As `TextEncoding</api/text/encoding_text/textencoding>` = `Nil</api/language/nil>`) As `String</api/data_types/string>`

> Returns a `String</api/data_types/string>`, containing the data that is available in the internal queue without removing it.
>
> The optional *encoding* parameter enables you to specify the text encoding of the data to be returned. The default is `Nil</api/language/nil>`. Use the `Encodings</api/text/encoding_text/encodings>` module to specify an encoding.
>
> This example adds the contents of the internal queue to a `TextArea</api/user_interface/desktop/desktoptextarea>`. The Listener <span class="title-ref">EasyTCPSocket</span> has been added to the window.
>
> ``` xojo
> TextArea1.AddText(listener.Lookahead)
> ```

<div id="easytcpsocket.poll">

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

</div>

<div class="rst-class">

forsearch

</div>

EasyTCPSocket.Poll

**Poll**

> Polls the socket manually, which allows a socket to be used synchronously.
>
> The following example polls the <span class="title-ref">EasyTCPSocket</span>.
>
> ``` xojo
> Listener.Poll
> ```

<div id="easytcpsocket.purge">

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

</div>

<div class="rst-class">

forsearch

</div>

EasyTCPSocket.Purge

**Purge**

> Removes all data from the socket's internal receive buffer. It does not affect the socket's internal send buffer.
>
> ``` xojo
> Listener.Purge
> ```

<div id="easytcpsocket.read">

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

</div>

<div class="rst-class">

forsearch

</div>

EasyTCPSocket.Read

**Read**(count As `Integer</api/data_types/integer>`) As `String</api/data_types/string>`

> Reads *count* bytes from the input stream and returns a `String</api/data_types/string>`.
>
> If *count* is higher than the amount of bytes currently available in the stream, all available bytes will be returned. Therefore, make sure to always consider the case that you get less than you requested. To see if you received all requested bytes, check the returned string's `String<string.bytes>` property (avoid using `Length<binarystream.length>` as it may give a different number if the encoding is not nil).
>
> If not enough memory is available, you get back an empty string.
>
> This example reads the first 1000 bytes from a `BinaryStream</api/files/binarystream>`.
>
> ``` xojo
> Var readFile As FolderItem = FolderItem.ShowOpenFileDialog("text/plain")
>
> If readFile <> Nil Then
>
>   Var ReadStream As BinaryStream = BinaryStream.Open(readFile, False)
>
>   ReadStream.LittleEndian = True
>   TextArea1.Text = ReadStream.Read(1000, Encodings.UTF8)
>
> End If
> ```

<div id="easytcpsocket.readall">

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

</div>

<div class="rst-class">

forsearch

</div>

EasyTCPSocket.ReadAll

**ReadAll** As `String</api/data_types/string>`

> Reads all the data from the internal buffer.
>
> This example reads all the data in the buffer into a `TextArea</api/user_interface/desktop/desktoptextarea>`.
>
> ``` xojo
> TextField1.AddText(listener.ReadAll)
> ```

<div id="easytcpsocket.readerror">

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

</div>

<div class="rst-class">

forsearch

</div>

EasyTCPSocket.ReadError

**ReadError** As `Boolean</api/data_types/boolean>`

> If `True</api/language/true>` then an error occurred during reading.

<div id="easytcpsocket.sendmessage">

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

</div>

<div class="rst-class">

forsearch

</div>

EasyTCPSocket.SendMessage

**SendMessage**(Command As `Int32</api/data_types/additional_types/int32>`, Data As `String</api/data_types/string>`)

> Sends a message, consisting of the code *command* and the text, *data*.
>
> Effective with 2017r3, the *command* parameter is Int32 instead of Integer to prevent incorrect behavior in 64-bit apps.

<div id="easytcpsocket.waitforconnection">

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

</div>

<div class="rst-class">

forsearch

</div>

EasyTCPSocket.WaitForConnection

**WaitForConnection**(Timeout As `Integer</api/data_types/integer>`) As `Boolean</api/data_types/boolean>`

> Waits for a connection until *Timeout* elapses. *Timeout* is in seconds.
>
> Returns `True</api/language/true>` if a connection is made; otherwise it returns `False</api/language/false>`.
>
> ``` xojo
> If EasyTCPSocket1.WaitForConnection(10) Then
>   ' execute communications
> Else
>   ' connection failed
> End If
> ```

<div id="easytcpsocket.waitformessage">

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

</div>

<div class="rst-class">

forsearch

</div>

EasyTCPSocket.WaitForMessage

**WaitForMessage**(Command As `Int32</api/data_types/additional_types/int32>`, Timeout As `Integer</api/data_types/integer>`) As `String</api/data_types/string>`

> Waits for a message identified by the value of *Command*.
>
> Effective with 2017r3, the *command* parameter is Int32 instead of Integer to prevent incorrect behavior in 64-bit apps.
>
> Returns a `String</api/data_types/string>`, containing the message text. The *timeout* is the amount of time in seconds that the socket will wait for a message before stopping.
>
> The *command* parameter can be used as a code to identify the type of data that is sent. For example, you could send a command ID of 100 to mean that the string data is actually a memory block containing a `FolderItem</api/files/folderitem>`. Or, you could define ID 101 as the username of a remote application. This message mode is enforced on you in that you cannot use an arbitrary Write command. If you'd like to send arbitrary data, then you can make up a miscellaneous command ID and send your arbitrary data.
>
> Command IDs less than 0 are reserved for internal use. When you are sending messages, you should not use a command ID less than 0, as it may very well cause issues with other classes.

<div id="easytcpsocket.write">

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

</div>

<div class="rst-class">

forsearch

</div>

EasyTCPSocket.Write

**Write**(Data As `String</api/data_types/string>`)

> Writes the passed data to the output stream.
>
> Note that in order to make sure that the data actually ends up on disk or gets sent to the socket it is connected to, the stream must either get closed or the `Flush<writeable.flush>` method be called. Otherwise, the data, if small, may end up temporarily in a write buffer before either a certain time has passed or more data is written. This buffering increases performance when writing lots of small pieces of data, but may be causing unwanted delays when another process, e.g. the other end of a socket connection, is waiting for the data. Consider calling the `Flush<writeable.flush>` method to reduce latencies that this buffering may cause in such cases.
>
> If Write fails, an `IOException</api/exceptions/ioexception>` will be raised.
>
> This example displays the Save As dialog box and writes the contents of the TextArea1 to a text file.
>
> ``` xojo
> Var f As FolderItem = FolderItem.ShowSaveFileDialog(FileTypes1.Text, "Untitled.txt")
>
> If f<> Nil Then
>
>   Var stream As BinaryStream
>
>   stream = BinaryStream.Create(f, True)
>   stream.Write(TextArea1.Text)
>   stream.Close
>
> End If
> ```

<div id="easytcpsocket.writeerror">

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

</div>

<div class="rst-class">

forsearch

</div>

EasyTCPSocket.WriteError

**WriteError** As `Boolean</api/data_types/boolean>`

> If `True</api/language/true>` then an error occurred during writing.

## Event descriptions

<div id="easytcpsocket.connected">

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

</div>

<div class="rst-class">

forsearch

</div>

EasyTCPSocket.Connected

**Connected**

> Executes when the connection is established with the server.

<div id="easytcpsocket.error">

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

</div>

<div class="rst-class">

forsearch

</div>

EasyTCPSocket.Error

**Error**(e As `RuntimeException</api/exceptions/runtimeexception>`)

> Occurs when an error occurs with the socket.
>
> These error codes provide you with key information about your socket, and it is not advisable to ignore them.
>
> When an error occurs, the `RuntimeException.ErrorNumber<runtimeexception.errornumber>` property will likely contain one of the following error codes:
>
> | Error Code | Description                                                                                                             |
> |------------|-------------------------------------------------------------------------------------------------------------------------|
> | 0          | No error occurred.                                                                                                      |
> | 100        | There was an error opening and initializing the drivers.                                                                |
> | 101        | This error code is no longer used.                                                                                      |
> | 102        | This code means that you lost your connection.                                                                          |
> | 103        | The socket was unable to resolve the address that was specified.                                                        |
> | 104        | This error code is no longer used.                                                                                      |
> | 105        | The address is currently in use.                                                                                        |
> | 106        | This is an invalid state error, which means that the socket is not in the proper state to be doing a certain operation. |
> | 107        | This error means that the port you specified is invalid.                                                                |
> | 108        | This error indicates that your application has run out of memory.                                                       |
>
> Information on `additional error codes</api/networking/socket_error_codes>` is available.
>
> The following example in the Error event handler displays the error code.
>
> ``` xojo
> MessageBox(e.ErrorNumber.ToString)
> ```

<div id="easytcpsocket.receivedmessage">

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

</div>

<div class="rst-class">

forsearch

</div>

EasyTCPSocket.ReceivedMessage

**ReceivedMessage**(Command As `Int32</api/data_types/additional_types/int32>`, Data As `String</api/data_types/string>`)

> A message, consisting of an identifying integer, *Command*, and the text *Data*, has been received.
>
> Effective with 2017r3, the *command* parameter is Int32 instead of Integer to prevent incorrect behavior in 64-bit apps.

<div id="easytcpsocket.sendcomplete">

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

</div>

<div class="rst-class">

forsearch

</div>

EasyTCPSocket.SendComplete

**SendComplete**(UserAborted As `Boolean</api/data_types/boolean>`)

> Occurs when a send has completed.
>
> Use this to determine when all your data has been sent. *UserAborted* will be `True</api/language/true>` if the user aborted the send by returning `True</api/language/true>` from the SendProgress event. You can use this information to update different status variables or to inform user about the success or failure of the transfer. If the send was completed, this value is `False</api/language/false>`. UserAborted will always be `False</api/language/false>` for UDP sockets.

<div id="easytcpsocket.sendprogress">

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

</div>

<div class="rst-class">

forsearch

</div>

EasyTCPSocket.SendProgress

**SendProgress**(BytesSent As `Integer</api/data_types/integer>`, BytesLeft As `Integer</api/data_types/integer>`) As `Boolean</api/data_types/boolean>`

> Occurs when your network provider queues your data in chunks and is about to send the next chunk.
>
> The parameters indicate the amount of progress that has been made during the send. Returns a `Boolean</api/data_types/boolean>`.
>
> Returning `True</api/language/true>` from this event causes the send to be cancelled. This does not close the socket's connection; it only clears the buffer. After all of the data has been transferred you will get a final SendProgress event followed by a `SendComplete<socketcore.sendcomplete>` event.
>
> *bytesSent* is the number of bytes that were sent in the chunk, not the total number of bytes sent.

## Interfaces

This class implements the `Readable</api/files/readable>` and `Writeable</api/files/writeable>` class interfaces.

## Notes

Even though you have access to the Write, Read and ReadAll methods of the `TCPSocket</api/networking/tcpsocket>` class, you should never call them. Doing so will cause a `RuntimeException</api/exceptions/runtimeexception>` to be raised (with an appropriate message set). This is so the internal protocol is enforced.

If you are subclassing a <span class="title-ref">EasyTCPSocket</span>, you must call the Super class's constructor in your own subclass's constructor. The subclass will not work or exhibit “strange” behavior unless this is done. Use the `Super</api/language/super>` keyword.

The *Command* parameter can be used as a code to identify the type of data that is sent. For example, you could send a command ID of 100 to mean that the string data is actually a memory block containing a `FolderItem</api/files/folderitem>`. Or, you could define ID 101 as the username of a remote application. This message mode is enforced on you in that you cannot use an arbitrary Write command. If you'd like to send arbitrary data, then you can make up a miscellaneous command ID and send your arbitrary data.

Command IDs less than 0 are reserved for internal use. When you are sending messages, you should not use a command ID less than 0, as it may very well cause issues with other classes.

The <span class="title-ref">EasyTCPSocket</span> class allows you to establish connections and communicate via the TCP protocol with a remote machine. The main difference between the <span class="title-ref">EasyTCPSocket</span> class and the regular `TCPSocket</api/networking/tcpsocket>` class is the message-based aspects of the protocol. The connection process is identical to a regular `TCPSocket</api/networking/tcpsocket>`. However, when you want to send data to a remote machine you must use the SendMessage method to do so.

When you receive data, you are not given a DataAvailable event, as is you are for `TCPSocket</api/networking/tcpsocket>`. Instead, the entire message is passed to you via the ReceivedMessage event. Because of this, we do not allow you to read in arbitrary data using the Read or ReadAll methods of the `TCPSocket</api/networking/tcpsocket>` class.When you receive a message sent via this protocol, you handle it via the ReceivedMessage event handler.

For synchronous communications, there is a WaitForConnection method which will synchronously wait a predetermined amount of time for a connection to be established. If the connection is made, it returns `True</api/language/true>`, otherwise, it returns `False</api/language/false>`.

For synchronous communications, use the WaitForMessage method. This method waits for a message to come in with the command ID you specify. Once that message comes in, it will return the string data portion of that message. If a message comes in with a command ID that is different from the one you are expecting, it will drop that message.

The <span class="title-ref">EasyTCPSocket</span> class is designed only for easy communication among Xojo applications on the network. It is not designed to be the basis for custom TCP-based communication protocols. It works only for other applications that implement the <span class="title-ref">EasyTCPSocket</span> protocol.

## Compatibility

|                       |                       |
|-----------------------|-----------------------|
| **Project Types**     | Console, Desktop, Web |
| **Operating Systems** | All                   |

<div class="seealso">

`TCPSocket</api/networking/tcpsocket>` parent class; `AutoDiscovery</api/networking/autodiscovery>`, `EasyUDPSocket</api/networking/easyudpsocket>`, `TCPSocket</api/networking/tcpsocket>`, `UDPSocket</api/networking/udpsocket>` classes.

</div>
