Class

# ServerSocket

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

## Description

Used to support multiple connections on the same port.

## Properties

<div class="rst-class">

table-centered_columns_3_and_4

</div>

| Name                                                            | Type                                                 | Read-Only | Shared |
|-----------------------------------------------------------------|------------------------------------------------------|-----------|--------|
| `Handle<serversocket.handle>`                                   | `Integer</api/data_types/integer>`                   | ✓         |        |
| `IsListening<serversocket.islistening>`                         | `Boolean</api/data_types/boolean>`                   | ✓         |        |
| `LocalAddress<serversocket.localaddress>`                       | `String</api/data_types/string>`                     | ✓         |        |
| `MaximumSocketsConnected<serversocket.maximumsocketsconnected>` | `Integer</api/data_types/integer>`                   |           |        |
| `MinimumSocketsAvailable<serversocket.minimumsocketsavailable>` | `Integer</api/data_types/integer>`                   |           |        |
| `NetworkInterface<serversocket.networkinterface>`               | `NetworkInterface</api/networking/networkinterface>` |           |        |
| `Port<serversocket.port>`                                       | `Integer</api/data_types/integer>`                   |           |        |

## Methods

<div class="rst-class">

table-centered_column_4

</div>

| Name                                                | Parameters | Returns                                  | Shared |
|-----------------------------------------------------|------------|------------------------------------------|--------|
| `ActiveConnections<serversocket.activeconnections>` |            | `TCPSocket()</api/networking/tcpsocket>` |        |
| `Listen<serversocket.listen>`                       |            |                                          |        |
| `StopListening<serversocket.stoplistening>`         |            |                                          |        |

## Events

<div class="rst-class">

table-centered_column_4

</div>

| Name                                | Parameters                                                                                                   | Returns                                |
|-------------------------------------|--------------------------------------------------------------------------------------------------------------|----------------------------------------|
| `AddSocket<serversocket.addsocket>` |                                                                                                              | `TCPSocket</api/networking/tcpsocket>` |
| `Error<serversocket.error>`         | errorCode As `Integer</api/data_types/integer>`, err As `RuntimeException</api/exceptions/runtimeexception>` |                                        |

## Property descriptions

<div id="serversocket.handle">

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

</div>

<div class="rst-class">

forsearch

</div>

ServerSocket.Handle

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

> This is the <span class="title-ref">ServerSocket</span>'s internal descriptor and it can be used with `Declare</api/language/declare>` statements.
>
> The descriptor is platform-specific. If *Handle* is less than zero, the descriptor is not available.
>
> This property is read-only.

<div id="serversocket.islistening">

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

</div>

<div class="rst-class">

forsearch

</div>

ServerSocket.IsListening

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

> `True</api/language/true>` when the <span class="title-ref">ServerSocket</span> is listening for incoming connections.
>
> This property is read-only.
>
> This example checks to see that the <span class="title-ref">ServerSocket</span> is listening.
>
> ``` xojo
> If mServerSocket.IsListening Then
> MessageBox(mServerSocket.NetworkInterface.IPAddress)
> Else
> MessageBox("Not listening")
> End If
> ```

<div id="serversocket.localaddress">

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

</div>

<div class="rst-class">

forsearch

</div>

ServerSocket.LocalAddress

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

> The local address that the <span class="title-ref">ServerSocket</span> is using.
>
> This property is read-only.
>
> This example gets the local address of the computer that is running the <span class="title-ref">ServerSocket</span>.
>
> ``` xojo
> TextField1.Text = mServerSocket.LocalAddress
> ```

<div id="serversocket.maximumsocketsconnected">

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

</div>

<div class="rst-class">

forsearch

</div>

ServerSocket.MaximumSocketsConnected

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

> The maximum number of connections the <span class="title-ref">ServerSocket</span> will allow to connect.
>
> When a socket disconnects from the <span class="title-ref">ServerSocket</span>, the server will allow one more connection.
>
> Default value:
>
> - When instantiated in code, this defaults to 1. Starting with 2017r2, this defaults to 10.
> - When a <span class="title-ref">ServerSocket</span> is dragged onto the Window, this defaults to 10.
>
> This example sets the MaximumSocketsConnected and MinimumSocketsAvailable properties.
>
> ``` xojo
> mServerSocket.MaximumSocketsConnected = 25
> mServerSocket.MinimumSocketsAvailable = 2
> ```

<div id="serversocket.minimumsocketsavailable">

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

</div>

<div class="rst-class">

forsearch

</div>

ServerSocket.MinimumSocketsAvailable

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

> The smallest number of sockets available in the server's pool of socket connections.
>
> If the <span class="title-ref">ServerSocket</span> falls below this number, it will call the AddSocket event to replenish its supply of sockets.
>
> Default value:
>
> - When instantiated in code, this defaults to 1. Starting with 2017r2, this defaults to 2.
> - When a <span class="title-ref">ServerSocket</span> is dragged onto the Window, this defaults to 2.
>
> This example sets the MaximumSocketsConnected and MinimumSocketsAvailable properties.
>
> ``` xojo
> mServerSocket.MaximumSocketsConnected = 25
> mServerSocket.MinimumSocketsAvailable = 2
> ```

<div id="serversocket.networkinterface">

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

</div>

<div class="rst-class">

forsearch

</div>

ServerSocket.NetworkInterface

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

> The `NetworkInterface</api/networking/networkinterface>` that the <span class="title-ref">ServerSocket</span> is bound to.
>
> See the examples for the `NetworkInterface</api/networking/networkinterface>`. This example gets the IPAddress that is being used.
>
> ``` xojo
> If mServerSocket.IsListening Then
> MessageBox(mServerSocket.NetworkInterface.IPAddress)
> Else
> MessageBox("Not listening")
> End If
> ```

<div id="serversocket.port">

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

</div>

<div class="rst-class">

forsearch

</div>

ServerSocket.Port

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

> The port to bind to for listening.
>
> This example gets the Port that is being used by the <span class="title-ref">ServerSocket</span>.
>
> ``` xojo
> TextField1.Text = mServerSocket.Port.ToString
> ```

## Method descriptions

<div id="serversocket.activeconnections">

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

</div>

<div class="rst-class">

forsearch

</div>

ServerSocket.ActiveConnections

**ActiveConnections** As `TCPSocket()</api/networking/tcpsocket>`

> Gets the array of active sockets managed by the <span class="title-ref">ServerSocket</span>. Returns an array of `TCPSockets</api/networking/tcpsocket>`. These are the `TCPSockets</api/networking/tcpsocket>` that were added via the AddSocket event and are now connected.
>
> This example gets the array of connections. The array was declared as a property of the window.
>
> ``` xojo
> Var ms() As TCPSocket
> ms = mServerSocket.ActiveConnections
> ```

<div id="serversocket.listen">

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

</div>

<div class="rst-class">

forsearch

</div>

ServerSocket.Listen

**Listen**

> Begins the listening process for the <span class="title-ref">ServerSocket</span> with the properties you specified.
>
> Start listening on a previously created \`ServerSocket\`:
>
> ``` xojo
> mServerSocket.Listen
> ```

<div id="serversocket.stoplistening">

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

</div>

<div class="rst-class">

forsearch

</div>

ServerSocket.StopListening

**StopListening**

> Terminates listening on the <span class="title-ref">ServerSocket</span>. It does not terminate any established connections.
>
> This example terminates listening.
>
> ``` xojo
> mServerSocket.StopListening
> ```

## Event descriptions

<div id="serversocket.addsocket">

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

</div>

<div class="rst-class">

forsearch

</div>

ServerSocket.AddSocket

**AddSocket** As `TCPSocket</api/networking/tcpsocket>`

> The <span class="title-ref">ServerSocket</span> is requesting that you add a socket to its internal pool.
>
> The TCPSocket instance returned by this event is associated with a single connection and is not reused.
>
> This is called when the <span class="title-ref">ServerSocket</span> first begins listening. This socket must stay resident (it cannot be a local variable) and must be non-`Nil</api/language/nil>`. It returns a `TCPSocket</api/networking/tcpsocket>`. Since UDP is a connectionless protocol, it does not make sense for a <span class="title-ref">ServerSocket</span> to deal with UDPSockets.

<div id="serversocket.error">

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

</div>

<div class="rst-class">

forsearch

</div>

ServerSocket.Error

**Error**(errorCode As `Integer</api/data_types/integer>`, err As `RuntimeException</api/exceptions/runtimeexception>`)

> Occurs when the socket has an error.
>
> Standard operating system error codes or Xojo-specific errors are returned.

## Notes

A <span class="title-ref">ServerSocket</span> is a permanent socket that listens on a single port for multiple connections. When a connection attempt is made on that port, the <span class="title-ref">ServerSocket</span> hands the connection off to another socket, and continues listening on the same port. Without the <span class="title-ref">ServerSocket</span>, it is difficult to implement this functionality due to the latency between a connection coming in, being handed off, creating a new listening socket, and restarting the listening process. If you had two connections coming in at about the same time, one of the connections may be dropped because there was no listening socket available on that port.

You can change the MinimumSocketsAvailable and MaximumSocketsConnected properties after establishing the listening socket. If you change the MaximumSocketsConnected property, it will not kill any existing connections (it just may not allow more connections until the existing connections have been released). If you change the MinimumSocketsAvailable property, it may fire the `AddSocket<serversocket.addsocket>` event to replenish its internal buffer.

Binding a <span class="title-ref">ServerSocket</span> to a port below 1024 requires the proper privileges on all operating systems.

## Sample code

The following example listens for connections from a client application. The interface has a DesktopListBox and a DesktopButton. A <span class="title-ref">ServerSocket</span>, mServerSocket, has been added to the window that has the following code in its `AddSocket<serversocket.addsocket>` event handler:

``` xojo
ListBox1.AddRow("Added Socket")
Var ret As TCPSocket = New ClientSocket(ListBox1, curSocket)
curSocket = curSocket + 1

Return ret
```

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

ClientSocket is a subclass of `TCPSocket</api/networking/tcpsocket>` and its constructor takes a `DesktopListBox</api/user_interface/desktop/desktoplistbox>` and an `Integer</api/data_types/integer>`.

ClientSocket's Connected event is:

``` xojo
ListBox1.AddRow("Socket " + mNum.ToString + " connected.")
Me.Write("From the server socket, I connected to you.")
```

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

Its DataAvailable event handler is:

``` xojo
ListBox1.AddRow("Socket " + mNum.ToString + " got: " + Me.ReadAll)
```

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

The SendComplete event handler is:

``` xojo
ListBox1.AddRow("Socket " + mNum.ToString + " send complete.")
```

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

The property mNum is the passed value of curSocket in its `Constructor</api/language/constructor>`.

The "Listen" button calls the Listen method.

``` xojo
mServerSocket.Listen
```

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

This triggers the `AddSocket<serversocket.addsocket>` event that creates the initial pool of sockets.

The client application has a "Connect" button to connect to the <span class="title-ref">ServerSocket</span> application, a `ListBox</api/user_interface/desktop/desktoplistbox>` to display status information, and an array of `TCPSockets</api/networking/tcpsocket>` to make connections.

The Connect button's Pressed event handler is:

``` xojo
TCPSocket1(curSocket).Port = 2002
TCPSocket1(curSocket).Address = "127.0.0.1"
TCPSocket1(curSocket).Connect
curSocket = curSocket + 1
```

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

CurSocket is an `Integer</api/data_types/integer>` property of the window and is initialized to 0.

The `TCPSocket</api/networking/tcpsocket>` has the following event handlers. The Connected event handler sends a message to the server application:

``` xojo
ListBox1.AddRow("Socket " + Index.ToString + " connected.")
Me.Write("Socket " + Index.ToString + "connected!")
```

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

The DataAvailable event handler reads the message and sends back a reply.

``` xojo
Listbox1.AddRow("Socket " + Index.ToString + ": " + Me.ReadAll)
Me.Write(" I got something from you.")
```

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

The Error event handler displays the error in the ListBox:

``` xojo
Listbox1.AddRow("Socket " + Index.ToString + ": Error = " + e.Message))
```

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

The SendComplete event handler reports that send is complete:

``` xojo
ListBox1.AddRow("Socket " + Index.ToString + " send complete.")
```

## Compatibility

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

<div class="seealso">

`Object</api/data_types/additional_types/object>` parent class; `SocketCore</api/networking/socketcore>`, `SSLSocket</api/networking/sslsocket>`, `TCPSocket</api/networking/tcpsocket>` classes.

</div>