src/cobalt/site/docs/reference/starboard/modules/socket.md

---
layout: doc
title: "Starboard Module Reference: socket.h"
---

Defines Starboard socket I/O functions. Starboard supports IPv4 and IPv6, TCP
and UDP, server and client sockets. Some platforms may not support IPv6, some
may not support listening sockets, and some may not support any kind of sockets
at all (or only allow them in debug builds).

Starboard ONLY supports non-blocking socket I/O, so all sockets are non-blocking
at creation time.

Note that, on some platforms, API calls on one end of a socket connection may
not be instantaneously aware of manipulations on the socket at the other end of
the connection, thus requiring use of either an SbSocketWaiter or spin-polling.

TODO: For platforms that do not support sockets at all, they must support at
least a high-level HTTP client API (to be defined later).

## Macros ##

### kSbSocketInvalid ###

Well-defined value for an invalid socket handle.

## Enums ##

### SbSocketAddressType ###

All possible address types.

#### Values ####

*   `kSbSocketAddressTypeIpv4`

    An IPv4 address, using only the first 4 entries of the address buffer.
*   `kSbSocketAddressTypeIpv6`

    An IPv6 address, which uses 16 entries of the address buffer.

### SbSocketError ###

Enumeration of all Starboard socket operation results. Despite the enum name,
note that the value actually describes the outcome of an operation, which is not
always an error.

#### Values ####

*   `kSbSocketOk`

    The operation succeeded.
*   `kSbSocketPending`

    The operation is blocked on I/O. Either try again "later," or be very clever
    and wait on it with a SbSocketWaiter.
*   `kSbSocketErrorConnectionReset`

    This socket error is generated when the connection is reset unexpectedly and
    the connection is now invalid. This might happen for example if an read
    packet has the "TCP RST" bit set.
*   `kSbSocketErrorFailed`

    The operation failed for some other reason not specified above.

### SbSocketProtocol ###

All possible IP socket types.

#### Values ####

*   `kSbSocketProtocolTcp`

    The TCP/IP protocol, a reliable, stateful, streaming protocol.
*   `kSbSocketProtocolUdp`

    The UDP/IP protocol, an unreliable, connectionless, discrete packet
    (datagram) protocol.

### SbSocketResolveFilter ###

Bits that can be set when calling SbSocketResolve to filter the results.

#### Values ####

*   `kSbSocketResolveFilterNone`

    No filters, include everything.
*   `kSbSocketResolveFilterIpv4`

    Include Ipv4 addresses.
*   `kSbSocketResolveFilterIpv6`

    Include Ipv6 addresses.

## Typedefs ##

### SbSocket ###

A handle to a socket.

#### Definition ####

```
typedef SbSocketPrivate* SbSocket
```

## Structs ##

### SbSocketAddress ###

A representation of any possible supported address type.

#### Members ####

*   `uint8_t address`

    The storage for the address. For IPv4, only the first 4 bytes make up the
    address. For IPv6, the entire buffer of 16 bytes is meaningful. An address
    of all zeros means that the address is unspecified.
*   `SbSocketAddressType type`

    The type of address this represents (IPv4 vs IPv6).
*   `int port`

    The port component of this socket address. If not specified, it will be
    zero, which is officially undefined.

### SbSocketResolution ###

The result of a host name resolution.

#### Members ####

*   `SbSocketAddress* addresses`

    An array of addresses associated with the host name.
*   `int address_count`

    The length of the `addresses` array.

## Functions ##

### SbSocketAccept ###

Accepts a pending connection on `socket` and returns a new SbSocket representing
that connection. This function sets the error on `socket` and returns
`kSbSocketInvalid` if it is unable to accept a new connection.

`socket`: The SbSocket that is accepting a pending connection.

#### Declaration ####

```
SbSocket SbSocketAccept(SbSocket socket)
```

### SbSocketBind ###

Binds `socket` to a specific local interface and port specified by
`local_address`. This function sets and returns the socket error if it is unable
to bind to `local_address`.

`socket`: The SbSocket to be bound to the local interface. `local_address`: The
local address to which the socket is to be bound. This value must not be `NULL`.

*   Setting the local address to port `0` (or not specifying a port) indicates
    that the function should choose a port for you.

*   Setting the IP address to `0.0.0.0` means that the socket should be bound to
    all interfaces.

#### Declaration ####

```
SbSocketError SbSocketBind(SbSocket socket, const SbSocketAddress *local_address)
```

### SbSocketClearLastError ###

Clears the last error set on `socket`. The return value indicates whether the
socket error was cleared.

#### Declaration ####

```
bool SbSocketClearLastError(SbSocket socket)
```

### SbSocketConnect ###

Opens a connection of `socket`'s type to the host and port specified by
`address`. This function sets and returns the socket error if it is unable to
connect to `address`. (It returns `kSbSocketOk` if it creates the connection
successfully.)

`socket`: The type of connection that should be opened. `address`: The host and
port to which the socket should connect.

#### Declaration ####

```
SbSocketError SbSocketConnect(SbSocket socket, const SbSocketAddress *address)
```

### SbSocketCreate ###

Creates a new non-blocking socket for protocol `protocol` using address family
`address_type`.

*   If successful, this function returns the newly created handle.

*   If unsuccessful, this function returns `kSbSocketInvalid` and also sets the
    last system error appropriately.

`address_type`: The type of IP address to use for the socket. `protocol`: The
protocol to use for the socket.

#### Declaration ####

```
SbSocket SbSocketCreate(SbSocketAddressType address_type, SbSocketProtocol protocol)
```

### SbSocketDestroy ###

Destroys the `socket` by flushing it, closing any connection that may be active
on it, and reclaiming any resources associated with it, including any
registration with an `SbSocketWaiter`.

The return value indicates whether the destruction was successful. However, even
if this function returns `false`, you should not be able to use the socket any
more.

`socket`: The SbSocket to be destroyed.

#### Declaration ####

```
bool SbSocketDestroy(SbSocket socket)
```

### SbSocketFreeResolution ###

Frees a resolution allocated by SbSocketResolve.

`resolution`: The resolution to be freed.

#### Declaration ####

```
void SbSocketFreeResolution(SbSocketResolution *resolution)
```

### SbSocketGetInterfaceAddress ###

Gets the source address and the netmask that would be used to connect to the
destination. The netmask parameter is optional, and only populated if a non-NULL
parameter is passed in. To determine which source IP will be used, the kernel
takes into account the protocol, routes, destination ip, etc. The subnet mask,
aka netmask, is used to find the routing prefix. In IPv6, this should be derived
from the prefix value.

Returns whether it was possible to determine the source address and the netmask
(if non-NULL value is passed) to be used to connect to the destination. This
function could fail if the destination is not reachable, if it an invalid
address, etc.

`destination`: The destination IP to be connected to. If IP addresses is not
0.0.0.0 or ::, then temporary addresses may be returned.

If the destination address is 0.0.0.0, and its `type` is
`kSbSocketAddressTypeIpv4`, then any IPv4 local interface that is up and not a
loopback interface is a valid return value.

If the destination address is ::, and its `type` is `kSbSocketAddressTypeIpv6`
then any IPv6 local interface that is up and not loopback or a link-local IP is
a valid return value. However, in the case of IPv6, the address with the biggest
scope must be returned. E.g., a globally scoped and routable IP is prefered over
a unique local address (ULA). Also, the IP address that is returned must be
permanent.

If destination address is NULL, then any IP address that is valid for
`destination` set to 0.0.0.0 (IPv4) or :: (IPv6) can be returned.

`out_source_address`: This function places the address of the local interface in
this output variable. `out_netmask`: This parameter is optional. If a non-NULL
value is passed in, this function places the netmask associated with the source
address in this output variable.

#### Declaration ####

```
bool SbSocketGetInterfaceAddress(const SbSocketAddress *const destination, SbSocketAddress *out_source_address, SbSocketAddress *out_netmask)
```

### SbSocketGetLastError ###

Returns the last error set on `socket`. If `socket` is not valid, this function
returns `kSbSocketErrorFailed`.

`socket`: The SbSocket that the last error is returned for.

#### Declaration ####

```
SbSocketError SbSocketGetLastError(SbSocket socket)
```

### SbSocketGetLocalAddress ###

Gets the address that this socket is bound to locally, if the socket is
connected. The return value indicates whether the address was retrieved
successfully.

`socket`: The SbSocket for which the local address is retrieved. `out_address`:
The SbSocket's local address.

#### Declaration ####

```
bool SbSocketGetLocalAddress(SbSocket socket, SbSocketAddress *out_address)
```

### SbSocketIsConnected ###

Indicates whether `socket` is connected to anything. Invalid sockets are not
connected.

`socket`: The SbSocket to be checked.

#### Declaration ####

```
bool SbSocketIsConnected(SbSocket socket)
```

### SbSocketIsConnectedAndIdle ###

Returns whether `socket` is connected to anything, and, if so, whether it is
receiving any data.

`socket`: The SbSocket to be checked.

#### Declaration ####

```
bool SbSocketIsConnectedAndIdle(SbSocket socket)
```

### SbSocketIsValid ###

Returns whether the given socket handle is valid.

#### Declaration ####

```
static bool SbSocketIsValid(SbSocket socket)
```

### SbSocketJoinMulticastGroup ###

Joins `socket` to an IP multicast group identified by `address`. The equivalent
of IP_ADD_MEMBERSHIP. The return value indicates whether the socket was joined
to the group successfully.

`socket`: The SbSocket to be joined to the IP multicast group. `address`: The
location of the IP multicast group.

#### Declaration ####

```
bool SbSocketJoinMulticastGroup(SbSocket socket, const SbSocketAddress *address)
```

### SbSocketListen ###

Causes `socket` to listen on the local address that `socket` was previously
bound to by SbSocketBind. This function sets and returns the socket error if it
is unable to listen for some reason. (It returns `kSbSocketOk` if it creates the
connection successfully.)

`socket`: The SbSocket on which the function operates.

#### Declaration ####

```
SbSocketError SbSocketListen(SbSocket socket)
```

### SbSocketReceiveFrom ###

Reads up to `data_size` bytes from `socket` into `out_data` and places the
source address of the packet in `out_source` if out_source is not NULL. Returns
the number of bytes read, or a negative number if there is an error, in which
case SbSocketGetLastError can provide the precise error encountered.

Note that this function is NOT specified to make a best effort to read all data
on all platforms, but it MAY still do so. It is specified to read however many
bytes are available conveniently, meaning that it should avoid blocking until
there is data. It can be run in a loop until SbSocketGetLastError returns
`kSbSocketPending` to make it a best-effort read (but still only up to not
blocking, unless you want to spin).

The primary use of `out_source` is to receive datagram packets from multiple
sources on a UDP server socket. TCP has two endpoints connected persistently, so
the address is unnecessary, but allowed.

`socket`: The SbSocket from which data is read. `out_data`: The data read from
the socket. `data_size`: The number of bytes to read. `out_source`: The source
address of the packet.

#### Declaration ####

```
int SbSocketReceiveFrom(SbSocket socket, char *out_data, int data_size, SbSocketAddress *out_source)
```

### SbSocketResolve ###

Synchronously resolves `hostname` into the returned SbSocketResolution , which
must be freed with SbSocketFreeResolution. The function returns `NULL` if it is
unable to resolve `hostname`.

`hostname`: The hostname to be resolved. `filters`: A mask of
SbSocketResolveFilter values used to filter the resolution. If `filters` does
not specify an IP address family filter, all address families are included.
However, if one IP address family filter is specified, only that address family
is included. The function ignores unrecognized filter bits.

#### Declaration ####

```
SbSocketResolution* SbSocketResolve(const char *hostname, int filters)
```

### SbSocketSendTo ###

Writes up to `data_size` bytes of `data` to `destination` via `socket`. Returns
the number of bytes written, or a negative number if there is an error, in which
case `SbSocketGetLastError` can provide the precise error encountered.

Note that this function is NOT specified to make a best effort to write all data
on all platforms, but it MAY still do so. It is specified to write however many
bytes are available conveniently. It can be run in a loop until
SbSocketGetLastError returns `kSbSocketPending` to make it a best-effort write
(but still only up to not blocking, unless you want to spin).

`socket`: The SbSocket to use to write data. `data`: The data read from the
socket. `data_size`: The number of bytes of `data` to write. `destination`: The
location to which data is written. This value must be `NULL` for TCP
connections, which can only have a single endpoint.

The primary use of `destination` is to send datagram packets, which can go out
to multiple sources from a single UDP server socket. TCP has two endpoints
connected persistently, so setting `destination` when sending to a TCP socket
will cause an error.

#### Declaration ####

```
int SbSocketSendTo(SbSocket socket, const char *data, int data_size, const SbSocketAddress *destination)
```

### SbSocketSetBroadcast ###

Sets the `SO_BROADCAST`, or equivalent, option to `value` on `socket`. The
return value indicates whether the option was actually set.

This option is only meaningful for UDP sockets and allows the socket to send to
the broadcast address.

`socket`: The SbSocket for which the option is set. `value`: The new value for
the option.

#### Declaration ####

```
bool SbSocketSetBroadcast(SbSocket socket, bool value)
```

### SbSocketSetReceiveBufferSize ###

Sets the `SO_RCVBUF`, or equivalent, option to `size` on `socket`. The return
value indicates whether the option was actually set.

`socket`: The SbSocket for which the option is set. `size`: The value for the
option.

#### Declaration ####

```
bool SbSocketSetReceiveBufferSize(SbSocket socket, int32_t size)
```

### SbSocketSetReuseAddress ###

Sets the `SO_REUSEADDR`, or equivalent, option to `value` on `socket`. The
return value indicates whether the option was actually set.

This option allows a bound address to be reused if a socket isn't actively bound
to it.

`socket`: The SbSocket for which the option is set. `value`: The new value for
the option.

#### Declaration ####

```
bool SbSocketSetReuseAddress(SbSocket socket, bool value)
```

### SbSocketSetSendBufferSize ###

Sets the `SO_SNDBUF`, or equivalent, option to `size` on `socket`. The return
value indicates whether the option was actually set.

`socket`: The SbSocket for which the option is set. `size`: The value for the
option.

#### Declaration ####

```
bool SbSocketSetSendBufferSize(SbSocket socket, int32_t size)
```

### SbSocketSetTcpKeepAlive ###

Sets the `SO_KEEPALIVE`, or equivalent, option to `value` on `socket`. The
return value indicates whether the option was actually set.

`socket`: The SbSocket for which the option is set. `value`: If set to `true`,
then `period` specifies the minimum time (SbTime) is always in microseconds)
between keep-alive packets. If set to `false`, `period` is ignored. `period`:
The time between keep-alive packets. This value is only relevant if `value` is
`true`.

#### Declaration ####

```
bool SbSocketSetTcpKeepAlive(SbSocket socket, bool value, SbTime period)
```

### SbSocketSetTcpNoDelay ###

Sets the `TCP_NODELAY`, or equivalent, option to `value` on `socket`. The return
value indicates whether the option was actually set.

This function disables the Nagle algorithm for reducing the number of packets
sent when converting from a stream to packets. Disabling Nagle generally puts
the data for each Send call into its own packet, but does not guarantee that
behavior.

`socket`: The SbSocket for which the option is set. `value`: Indicates whether
the Nagle algorithm should be disabled (`value`=`true`).

#### Declaration ####

```
bool SbSocketSetTcpNoDelay(SbSocket socket, bool value)
```

### SbSocketSetTcpWindowScaling ###

Sets the `SO_WINSCALE`, or equivalent, option to `value` on `socket`. The return
value indicates whether the option was actually set.

`socket`: The SbSocket for which the option is set. `value`: The value for the
option.

#### Declaration ####

```
bool SbSocketSetTcpWindowScaling(SbSocket socket, bool value)
```