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

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 veryclever and wait on it with a SbSocketWaiter.
  • kSbSocketErrorFailed - The operation failed for some reason.
    TODO: It's unclear if we actually care about why, so leaving the restof this enumeration blank until it becomes clear that we do.

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.

Structs

SbSocketAddress

A representation of any possible supported address type.

Members

Members
uint8_t
address[16]
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.

SbSocketPrivate

Private structure representing a socket, which may or may not be connected or listening.

SbSocketResolution

The result of a host name resolution.

Members

Members
int
address_count
The length of the addresses array.

Functions

SbSocketAccept

Description

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.

Declaration and definitions

SB_EXPORT SbSocket SbSocketAccept(SbSocket socket);

#include "starboard/socket.h"

SbSocket SbSocketAccept(SbSocket /*socket*/) {
  return kSbSocketInvalid;
}

Parameters

Parameters
SbSocket
socket
The SbSocket that is accepting a pending connection.

SbSocketBind

Description

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.

Declaration and definitions

SB_EXPORT SbSocketError SbSocketBind(SbSocket socket,
                                     const SbSocketAddress* local_address);

#include "starboard/socket.h"

SbSocketError SbSocketBind(SbSocket /*socket*/,
                           const SbSocketAddress* /*local_address*/) {
  return kSbSocketErrorFailed;
}

Parameters

Parameters
SbSocket
socket
The SbSocket to be bound to the local interface.
const SbSocketAddress*
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.

SbSocketClearLastError

Description

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

Declaration and definitions

SB_EXPORT bool SbSocketClearLastError(SbSocket socket);

#include "starboard/socket.h"

bool SbSocketClearLastError(SbSocket /*socket*/) {
  return false;
}

Parameters

Parameters
SbSocket
socket

SbSocketConnect

Description

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

Declaration and definitions

SB_EXPORT SbSocketError SbSocketConnect(SbSocket socket,
                                        const SbSocketAddress* address);

#include "starboard/socket.h"

SbSocketError SbSocketConnect(SbSocket /*socket*/,
                              const SbSocketAddress* /*address*/) {
  return kSbSocketErrorFailed;
}

Parameters

Parameters
SbSocket
socket
The type of connection that should be opened.
const SbSocketAddress*
address
The host and port to which the socket should connect.

SbSocketCreate

Description

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.

Declaration and definitions

SB_EXPORT SbSocket SbSocketCreate(SbSocketAddressType address_type,
                                  SbSocketProtocol protocol);

#include "starboard/socket.h"

SbSocket SbSocketCreate(SbSocketAddressType /*address_type*/,
                        SbSocketProtocol /*protocol*/) {
  return kSbSocketInvalid;
}

Parameters

Parameters
SbSocketAddressType
address_type
The type of IP address to use for the socket.
SbSocketProtocol
protocol
The protocol to use for the socket.

SbSocketDestroy

Description

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.

Declaration and definitions

SB_EXPORT bool SbSocketDestroy(SbSocket socket);

#include "starboard/socket.h"

bool SbSocketDestroy(SbSocket /*socket*/) {
  return false;
}

Parameters

Parameters
SbSocket
socket
The SbSocket to be destroyed.

SbSocketFreeResolution

Description

Frees a resolution allocated by SbSocketResolve.

Declaration and definitions

SB_EXPORT void SbSocketFreeResolution(SbSocketResolution* resolution);

#include "starboard/socket.h"

void SbSocketFreeResolution(SbSocketResolution* /*resolution*/) {
}

Parameters

Parameters
SbSocketResolution*
resolution
The resolution to be freed.

SbSocketGetLastError

Description

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

Declaration and definitions

SB_EXPORT SbSocketError SbSocketGetLastError(SbSocket socket);

#include "starboard/socket.h"

SbSocketError SbSocketGetLastError(SbSocket /*socket*/) {
  return kSbSocketErrorFailed;
}

Parameters

Parameters
SbSocket
socket
The SbSocket that the last error is returned for.

SbSocketGetLocalAddress

Description

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.

Declaration and definitions

SB_EXPORT bool SbSocketGetLocalAddress(SbSocket socket,
                                       SbSocketAddress* out_address);

#include "starboard/socket.h"

bool SbSocketGetLocalAddress(SbSocket /*socket*/,
                             SbSocketAddress* /*out_address*/) {
  return false;
}

Parameters

Parameters
SbSocket
socket
The SbSocket for which the local address is retrieved.
SbSocketAddress*
out_address
The SbSocket's local address.

SbSocketGetLocalInterfaceAddress

Description

Gets the address of the local IPv4 network interface. The return value indicates whether the address was retrieved successfully.

Declaration and definitions

SB_EXPORT bool SbSocketGetLocalInterfaceAddress(SbSocketAddress* out_address);

#include "starboard/socket.h"

bool SbSocketGetLocalInterfaceAddress(SbSocketAddress* /*out_address*/) {
  return false;
}

#include "starboard/socket.h"

#include <arpa/inet.h>
#include <ifaddrs.h>

#include "starboard/log.h"
#include "starboard/shared/posix/socket_internal.h"

namespace sbposix = starboard::shared::posix;

bool SbSocketGetLocalInterfaceAddress(SbSocketAddress* out_address) {
  if (!out_address) {
    return false;
  }

  // Get a list of the local network interfaces.
  struct ifaddrs* ifaddr;
  if (getifaddrs(&ifaddr) == -1) {
    return false;
  }

  // Scan the returned interfaces for a non-loopback IPv4 interface.
  for (struct ifaddrs* it = ifaddr; it != NULL; it = it->ifa_next) {
    if (it->ifa_addr == NULL) {
      continue;
    }

    // Filter out anything but IPv4.
    if (it->ifa_addr->sa_family != AF_INET) {
      continue;
    }

    // We know it is IPV4, so let's cast it over.
    struct sockaddr_in* if_addr =
        reinterpret_cast<struct sockaddr_in*>(it->ifa_addr);

    // Filter out the loopback adapter.
    if (if_addr->sin_addr.s_addr == htonl(INADDR_LOOPBACK)) {
      continue;
    }

    // Copy the address to the destination.
    sbposix::SockAddr sock_addr;
    sock_addr.FromSockaddr(it->ifa_addr);
    if (!sock_addr.ToSbSocketAddress(out_address)) {
      continue;
    }

    freeifaddrs(ifaddr);
    return true;
  }

  freeifaddrs(ifaddr);
  return false;
}

Parameters

Parameters
SbSocketAddress*
out_address
The retrieved address. The address does not include loopback (or IPv6) addresses.

SbSocketIsConnected

Description

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

Declaration and definitions

SB_EXPORT bool SbSocketIsConnected(SbSocket socket);

#include "starboard/socket.h"

bool SbSocketIsConnected(SbSocket /*socket*/) {
  return false;
}

Parameters

Parameters
SbSocket
socket
The SbSocket to be checked.

SbSocketIsConnectedAndIdle

Description

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

Declaration and definitions

SB_EXPORT bool SbSocketIsConnectedAndIdle(SbSocket socket);

#include "starboard/socket.h"

bool SbSocketIsConnectedAndIdle(SbSocket /*socket*/) {
  return false;
}

Parameters

Parameters
SbSocket
socket
The SbSocket to be checked.

SbSocketIsValid

Description

Returns whether the given socket handle is valid.

Declaration

static SB_C_INLINE bool SbSocketIsValid(SbSocket socket) {
  return socket != kSbSocketInvalid;
}

Parameters

Parameters
SbSocket
socket

SbSocketJoinMulticastGroup

Description

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.

Declaration and definitions

SB_EXPORT bool SbSocketJoinMulticastGroup(SbSocket socket,
                                          const SbSocketAddress* address);

#include "starboard/socket.h"

bool SbSocketJoinMulticastGroup(SbSocket /*socket*/,
                                const SbSocketAddress* /*address*/) {
  return false;
}

Parameters

Parameters
SbSocket
socket
The SbSocket to be joined to the IP multicast group.
const SbSocketAddress*
address
The location of the IP multicast group.

SbSocketListen

Description

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

Declaration and definitions

SB_EXPORT SbSocketError SbSocketListen(SbSocket socket);

#include "starboard/socket.h"

SbSocketError SbSocketListen(SbSocket /*socket*/) {
  return kSbSocketErrorFailed;
}

Parameters

Parameters
SbSocket
socket
The SbSocket on which the function operates.

SbSocketReceiveFrom

Description

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.

Declaration and definitions

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

#include "starboard/socket.h"

int SbSocketReceiveFrom(SbSocket /*socket*/,
                        char* /*out_data*/,
                        int /*data_size*/,
                        SbSocketAddress* /*out_source*/) {
  return -1;
}

Parameters

Parameters
SbSocket
socket
The SbSocket from which data is read.
char*
out_data
The data read from the socket.
int
data_size
The number of bytes to read.
SbSocketAddress*
out_source
The source address of the packet.

SbSocketResolve

Description

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

Declaration and definitions

SB_EXPORT SbSocketResolution* SbSocketResolve(const char* hostname,
                                              int filters);

#include "starboard/socket.h"

SbSocketResolution* SbSocketResolve(const char* /*hostname*/, int /*filters*/) {
  return NULL;
}

Parameters

Parameters
const char*
hostname
The hostname to be resolved.
int
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.

SbSocketSendTo

Description

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).
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 and definitions

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

#include "starboard/socket.h"

int SbSocketSendTo(SbSocket /*socket*/,
                   const char* /*data*/,
                   int /*data_size*/,
                   const SbSocketAddress* /*destination*/) {
  return -1;
}

Parameters

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

SbSocketSetBroadcast

Description

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.

Declaration and definitions

SB_EXPORT bool SbSocketSetBroadcast(SbSocket socket, bool value);

#include "starboard/socket.h"

bool SbSocketSetBroadcast(SbSocket /*socket*/, bool /*value*/) {
  return false;
}

Parameters

Parameters
SbSocket
socket
The SbSocket for which the option is set.
bool
value
The new value for the option.

SbSocketSetReceiveBufferSize

Description

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

Declaration and definitions

SB_EXPORT bool SbSocketSetReceiveBufferSize(SbSocket socket, int32_t size);

#include "starboard/socket.h"

bool SbSocketSetReceiveBufferSize(SbSocket /*socket*/, int32_t /*size*/) {
  return false;
}

Parameters

Parameters
SbSocket
socket
The SbSocket for which the option is set.
int32_t
size
The value for the option.

SbSocketSetReuseAddress

Description

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.

Declaration and definitions

SB_EXPORT bool SbSocketSetReuseAddress(SbSocket socket, bool value);

#include "starboard/socket.h"

bool SbSocketSetReuseAddress(SbSocket /*socket*/, bool /*value*/) {
  return false;
}

Parameters

Parameters
SbSocket
socket
The SbSocket for which the option is set.
bool
value
The new value for the option.

SbSocketSetSendBufferSize

Description

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

Declaration and definitions

SB_EXPORT bool SbSocketSetSendBufferSize(SbSocket socket, int32_t size);

#include "starboard/socket.h"

bool SbSocketSetSendBufferSize(SbSocket /*socket*/, int32_t /*size*/) {
  return false;
}

Parameters

Parameters
SbSocket
socket
The SbSocket for which the option is set.
int32_t
size
The value for the option.

SbSocketSetTcpKeepAlive

Description

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

Declaration and definitions

SB_EXPORT bool SbSocketSetTcpKeepAlive(SbSocket socket,
                                       bool value,
                                       SbTime period);

#include "starboard/socket.h"

bool SbSocketSetTcpKeepAlive(SbSocket /*socket*/,
                             bool /*value*/,
                             SbTime /*period*/) {
  return false;
}

Parameters

Parameters
SbSocket
socket
The SbSocket for which the option is set.
bool
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.
SbTime
period
The time between keep-alive packets. This value is only relevant if value is true.

SbSocketSetTcpNoDelay

Description

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.

Declaration and definitions

SB_EXPORT bool SbSocketSetTcpNoDelay(SbSocket socket, bool value);

#include "starboard/socket.h"

bool SbSocketSetTcpNoDelay(SbSocket /*socket*/, bool /*value*/) {
  return false;
}

Parameters

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

SbSocketSetTcpWindowScaling

Description

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

Declaration and definitions

SB_EXPORT bool SbSocketSetTcpWindowScaling(SbSocket socket, bool value);

#include "starboard/socket.h"

bool SbSocketSetTcpWindowScaling(SbSocket /*socket*/, bool /*value*/) {
  return false;
}

Parameters

Parameters
SbSocket
socket
The SbSocket for which the option is set.
bool
value
The value for the option.