From Xojo Documentation

Revision as of 19:59, 2 April 2021 by Gperlman (talk | contribs) (See Also)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
You are currently browsing the old Xojo documentation site. It will go offline as of October 2, 2023. Please visit the new Xojo documentation site! - you will be redirected shortly...

Class (inherits from SocketCore)

Used for TCP/IP communication. For secure communications, use SSLSocket instead.

Connected Error SendProgress
DataAvailable SendComplete
Address Handle fa-lock-32.png NetworkInterface
BytesAvailable fa-lock-32.png IsConnected fa-lock-32.png Port
BytesLeftToSend fa-lock-32.png LocalAddress fa-lock-32.png RemoteAddress fa-lock-32.png
Close Flush Purge
Connect Listen Read
Disconnect Lookahead ReadAll
EndOfFile Poll Write


The TCPSocket class implements the Readable and Writeable class interfaces.


The Transmission Control Protocol, or TCP, is the basis for most internet traffic. It is a connection-oriented protocol that provides a reliable way to transfer data across a network.

To establish a connection between two computers using TCPSockets, one computer must be set up to listen on a specific port. The other computer (called the client) then attempts to connect by specifying the network address (or IP address) of the remote machine and the port on which to attempt the connection. In order to send and receive data with a remote machine, both machines must have some indication that this connection will be established.That happens by either picking a well-defined port for the listener (or server) to listen on, or by some prior arrangement (e.g., you are the author of both the server and the client program).

When a server receives a connection attempt on the port it is listening on, it accepts the incoming connection, and sends an acknowledgement back to the remote machine. Once both machines have reached an agreement (or are "connected"), then you can begin sending and receiving data. When you close your connection with the remote machine, there is a similar handshake process that goes on, so both computers know that the connection is being terminated.

Because of the amount of error checking and handshakes, TCP is an extremely reliable protocol. When you send a packet of information, it is guaranteed to make it to the remote machine unless you have been disconnected, either abortive or orderly. But this feature comes at the cost of high overhead. A typical TCP packet that is sent over the network has around a 40-byte header that goes with it. This header is checked, and changed by all the various machines en route to its destination. This overhead makes TCP a slower protocol to use. The trade-off is speed versus security, in favor of security. If it is speed you are looking for (for example to support a networked game), then you should look into the UDP protocol.

The TCPSocket handles the disconnection process more gracefully. It tries to do an orderly disconnect when possible (which allows for all data transfers to finish), and will only fall back on an abortive disconnect when it is not possible to do an orderly one. TCPSockets handle flow control, so sending large amount of data will not drop data during the send or the receive process.

It is possible for packets of data to come in before the socket has finished the connection process. If this happens, the TCPSocket is prepared to handle this, so your initial packets will not be lost. This is a Macintosh-only feature; Windows sockets were already prepared to handle these situations.

The SendProgress event allows you to determine send speeds, and tells you how many bytes of data you have sent since your last SendProgress event, as well as how many bytes are left to send. If you return True from the SendProgress event, you cancel the current transfer. This does not close the socket's connection; it only clears the send buffer. You can use this event to determine if a connection is too slow, and cancel it. Once all of the data has been transferred, you will get a last SendProgress event, followed by a SendComplete event.

The RemoteAddress property for a connecting socket returns the IP address of the remote host connection for Windows sockets. One useful thing you can do with the RemoteAddress property is to test to make sure the IP address you wanted to connect to is the same as the IP address you are currently connected to.

TCPSockets can be orphaned. An orphaned socket will keep a lock on itself after you call either the Connect or Listen methods. The socket gets unlocked when it has been disconnected. This means that an orphaned socket will continue to work so long as it is connected. This also means that you need to call the Close method before its lock will be released.

If you orphan a socket, you need to be certain that the socket will get a disconnect message from its connection at some point. For example, some web servers will not release a socket once the data has been transferred to it (for efficiency reasons). When you are done with the socket, it will remain active and connected unless you explicitly call the Close method of the SocketCore class. If you think your socket could be in a state in which it is left open, keep a reference to the socket around somewhere and use the Close method to terminate the connection. Calling the Disconnect method also applies instead of calls to the Close method.

If you use a constructor in a subclass of TCPSocket, you must call the Super class's constructor in your subclass's constructor. The subclass will not work unless this is done.

Binding a TCPSocket to well-known ports below 1024 requires proper privileges on all operating systems.

The TCPSocket class implements the Readable and Writable class interfaces. If you implement either or both of these interfaces, you must provide the methods and parameters specified by these class interfaces.

For more information about class interfaces and how to implement them, see the section "Class Interfaces" in the User's Guide.

Xojo Cloud

Web apps running on Xojo Cloud first have to use the FirewallPort class to open the port used to connect to to TCP externally.

Sample Code

This code uses a TCPSocket to establish an internet connection.

Var socket1 As New TCPSocket

// set its port and address
// TextField1 contains a valid url, such as ""
socket1.Address = ""
socket1.Port = 80

// connect the socket

// while the socket isn't connected
While Not socket1.IsConnected
// poll the socket to let it do its thing
// if an error occurs, the Error event will fire

// if we broke the loop because we're connected
If socket1.IsConnected Then
// here would be a great place to do a synchronous read operation...
// if an error occurs, the Error event will fire
End if

// close the socket

See Also

EasyTCPSocket, ServerSocket, SocketCore, SSLSocket, UDPSocket classes; Readable, Writeable class interfaces.