Class

# SocketCore

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

## Description

The base class for `TCPSocket</api/networking/tcpsocket>` and `UDPSocket</api/networking/udpsocket>`. The `SSLSocket</api/networking/sslsocket>` class is derived from `TCPSocket</api/networking/tcpsocket>`. <span class="title-ref">SocketCore</span> is an abstract class and cannot be instantiated directly.

## Properties

<div class="rst-class">

table-centered_columns_3_and_4

</div>

| Name                                            | Type                                                 | Read-Only | Shared |
|-------------------------------------------------|------------------------------------------------------|-----------|--------|
| `Handle<socketcore.handle>`                     | `Integer</api/data_types/integer>`                   | ✓         |        |
| `IsConnected<socketcore.isconnected>`           | `Boolean</api/data_types/boolean>`                   | ✓         |        |
| `LocalAddress<socketcore.localaddress>`         | `String</api/data_types/string>`                     | ✓         |        |
| `NetworkInterface<socketcore.networkinterface>` | `NetworkInterface</api/networking/networkinterface>` |           |        |
| `Port<socketcore.port>`                         | `Integer</api/data_types/integer>`                   |           |        |

## Methods

<div class="rst-class">

table-centered_column_4

</div>

| Name                          | Parameters | Returns | Shared |
|-------------------------------|------------|---------|--------|
| `Close<socketcore.close>`     |            |         |        |
| `Connect<socketcore.connect>` |            |         |        |
| `Poll<socketcore.poll>`       |            |         |        |
| `Purge<socketcore.purge>`     |            |         |        |

## Events

<div class="rst-class">

table-centered_column_4

</div>

| Name                                      | Parameters                                                | Returns |
|-------------------------------------------|-----------------------------------------------------------|---------|
| `DataAvailable<socketcore.dataavailable>` |                                                           |         |
| `Error<socketcore.error>`                 | e As `RuntimeException</api/exceptions/runtimeexception>` |         |
| `SendComplete<socketcore.sendcomplete>`   | userAborted As `Boolean</api/data_types/boolean>`         |         |

## Property descriptions

<div id="socketcore.handle">

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

</div>

<div class="rst-class">

forsearch

</div>

SocketCore.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.
>
> <div class="important">
>
> <div class="title">
>
> Important
>
> </div>
>
> This property is not supported for Android.
>
> </div>
>
> - 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="socketcore.isconnected">

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

</div>

<div class="rst-class">

forsearch

</div>

SocketCore.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 Socket1.IsConnected Then
>   ' proceed using the connection
> Else
>   MessageBox("Connection failed!")
> End If
> ```

<div id="socketcore.localaddress">

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

</div>

<div class="rst-class">

forsearch

</div>

SocketCore.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 = Socket1.LocalAddress
> ```

<div id="socketcore.networkinterface">

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

</div>

<div class="rst-class">

forsearch

</div>

SocketCore.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.
>
> <div class="important">
>
> <div class="title">
>
> Important
>
> </div>
>
> This property is not supported for Android.
>
> </div>
>
> This example specifies that the `TCPSocket</api/networking/tcpsocket>` will use the first Network Interface on the user's computer.
>
> ``` xojo
> Socket1.NetworkInterface = System.NetworkInterface(0)
> ```

<div id="socketcore.port">

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

</div>

<div class="rst-class">

forsearch

</div>

SocketCore.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
> Socket1.Port = 8080
> ```

## Method descriptions

<div id="socketcore.close">

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

</div>

<div class="rst-class">

forsearch

</div>

SocketCore.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>`), and data left in the socket's receive buffer. All other information is discarded.
>
> This example closes the `EasyTCPSockets</api/networking/easytcpsocket>` that were open. The sockets were added to the main window.
>
> ``` xojo
> Connector.Close
> Listener.Close
> ```

<div id="socketcore.connect">

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

</div>

<div class="rst-class">

forsearch

</div>

SocketCore.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="socketcore.poll">

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

</div>

<div class="rst-class">

forsearch

</div>

SocketCore.Poll

**Poll**

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

<div id="socketcore.purge">

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

</div>

<div class="rst-class">

forsearch

</div>

SocketCore.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
> ```

## Event descriptions

<div id="socketcore.dataavailable">

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

</div>

<div class="rst-class">

forsearch

</div>

SocketCore.DataAvailable

**DataAvailable**

> Occurs when additional data has come into the internal receive buffer.

<div id="socketcore.error">

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

</div>

<div class="rst-class">

forsearch

</div>

SocketCore.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<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.                                                       |
>
> These are not the only errors that are returned. For Windows, additional error codes are usually positive numbers in the range \[10004, 11004\]. For Windows error codes, see WinSock.h. MacOS and Linux use POSIX error codes. For a description of macOS and Linux error codes, see <http://www.ioplex.com/~miallen/errcmp.html>.
>
> e.g. error 64 is for "host is down".
>
> The following example in the Error event handler displays the error code.
>
> ``` xojo
> MessageBox(Me.e.ErrorNumber.ToString)
> ```

<div id="socketcore.sendcomplete">

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

</div>

<div class="rst-class">

forsearch

</div>

SocketCore.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.

## Notes

There are some instances where you would like the system to pick a port for you. These needs can range from needing a port for passive FTP file transfers, or perhaps you wrote a class to auto-discover other applications on the network and you would like to negotiate a port to connect over using TCP/IP. If you specify a Port of 0 and then call `TCPSocket<tcpsocket.listen>` or `UDPSocket.Connect<socketcore.connect>`, a random port will be picked for you. Most often, these ports will be in the range of 49512 to 65535 (inclusive).

If you use this method to obtain an open port, then you probably need to use the following procedure to determine which port was chosen. After calling the `Connect<socketcore.connect>` method or the `Listen<tcpsocket.listen>` method of the `TCPSocket</api/networking/tcpsocket>` class, you can check the `Port<socketcore.port>` property to see which port was assigned. This means that the port number will change from 0 to the port number that you are bound to.

There's another benefit checking the Port property. There is a hacking technique called port hijacking where the hacker steals a port out from under you. If this happens, checking the Port property will tell you if someone has hijacked the port. It can be a good idea (though paranoid) to periodically check to make sure the Port property returns a port that you expect to see. For instance, if you were listening on port 80 for HTTP connections, but the Port property says you're listening on port 2113, then something may be wrong.

The `SendComplete<socketcore.sendcomplete>` event's parameter lets you know whether the transfer has completed or has been cancelled by returning `True</api/language/true>` from the SendProgress event of the `TCPSocket</api/networking/tcpsocket>` class. You can use this information to update different status variables, or alert the user of transfer success or failure. If the user aborted, this parameter is `True</api/language/true>`, and if the send was completed, this value is `False</api/language/false>`. The `SendComplete<socketcore.sendcomplete>` event's parameter is always `False</api/language/false>` for UDPSockets since there is not a SendProgress event for that class.

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

### Endianness

There are two different endian standards. Intel, Apple and ARM CPUs use "little" [endianness](http://en.wikipedia.org/wiki/Endianness). Sockets work with streams of data and do not change the endianness of the data you are transferring. This is fine in most cases, but if you are transferring binary data, such as from a `BinaryStream</api/files/binarystream>` or a `MemoryBlock</api/language/memoryblock>`, you will want to ensure that the endianness matches from server to client regardless of what platform you are on. You can do this by setting the LittleEndian property on `MemoryBlocks</api/language/memoryblock>` or `BinaryStreams</api/files/binarystream>` to the same value for your client and your server. Failure to ensure that the endianness is consistent will result in a possible byte-order conflict in your application. You can use the `TargetBigEndian</api/compiler_directives/targetbigendian>` and `TargetLittleEndian</api/compiler_directives/targetlittleendian>` constants to determine the endian standard for the platform on which your app is running.

## Compatibility

|                       |     |
|-----------------------|-----|
| **Project Types**     | All |
| **Operating Systems** | All |

<div class="seealso">

`Object</api/data_types/additional_types/object>` parent class; `Datagram</api/networking/datagram>`, `AutoDiscovery</api/networking/autodiscovery>`, `ServerSocket</api/networking/serversocket>`, `TCPSocket</api/networking/tcpsocket>`, `UDPSocket</api/networking/udpsocket>`, `EasyUDPSocket</api/networking/easyudpsocket>` classes.

</div>