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).
Well-defined value for an invalid socket handle.
All possible address types.
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.
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.
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.
All possible IP socket types.
kSbSocketProtocolTcp
The TCP/IP protocol, a reliable, stateful, streaming protocol.
kSbSocketProtocolUdp
The UDP/IP protocol, an unreliable, connectionless, discrete packet (datagram) protocol.
Bits that can be set when calling SbSocketResolve to filter the results.
kSbSocketResolveFilterNone
No filters, include everything.
kSbSocketResolveFilterIpv4
Include Ipv4 addresses.
kSbSocketResolveFilterIpv6
Include Ipv6 addresses.
A handle to a socket.
typedef SbSocketPrivate* SbSocket
A representation of any possible supported address type.
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.
The result of a host name resolution.
SbSocketAddress* addresses
An array of addresses associated with the host name.
int address_count
The length of the addresses array.
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.
SbSocket SbSocketAccept(SbSocket socket)
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.
SbSocketError SbSocketBind(SbSocket socket, const SbSocketAddress *local_address)
Clears the last error set on socket. The return value indicates whether the socket error was cleared.
bool SbSocketClearLastError(SbSocket socket)
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.
SbSocketError SbSocketConnect(SbSocket socket, const SbSocketAddress *address)
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.
SbSocket SbSocketCreate(SbSocketAddressType address_type, SbSocketProtocol protocol)
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.
bool SbSocketDestroy(SbSocket socket)
Frees a resolution allocated by SbSocketResolve.
resolution: The resolution to be freed.
void SbSocketFreeResolution(SbSocketResolution *resolution)
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.
bool SbSocketGetInterfaceAddress(const SbSocketAddress *const destination, SbSocketAddress *out_source_address, SbSocketAddress *out_netmask)
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.
SbSocketError SbSocketGetLastError(SbSocket socket)
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.
bool SbSocketGetLocalAddress(SbSocket socket, SbSocketAddress *out_address)
Indicates whether socket is connected to anything. Invalid sockets are not connected.
socket: The SbSocket to be checked.
bool SbSocketIsConnected(SbSocket socket)
Returns whether socket is connected to anything, and, if so, whether it is receiving any data.
socket: The SbSocket to be checked.
bool SbSocketIsConnectedAndIdle(SbSocket socket)
Returns whether the given socket handle is valid.
static bool SbSocketIsValid(SbSocket socket)
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.
bool SbSocketJoinMulticastGroup(SbSocket socket, const SbSocketAddress *address)
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.
SbSocketError SbSocketListen(SbSocket socket)
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.
int SbSocketReceiveFrom(SbSocket socket, char *out_data, int data_size, SbSocketAddress *out_source)
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.
SbSocketResolution* SbSocketResolve(const char *hostname, int filters)
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.
int SbSocketSendTo(SbSocket socket, const char *data, int data_size, const SbSocketAddress *destination)
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.
bool SbSocketSetBroadcast(SbSocket socket, bool value)
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.
bool SbSocketSetReceiveBufferSize(SbSocket socket, int32_t size)
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.
bool SbSocketSetReuseAddress(SbSocket socket, bool value)
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.
bool SbSocketSetSendBufferSize(SbSocket socket, int32_t size)
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.
bool SbSocketSetTcpKeepAlive(SbSocket socket, bool value, SbTime period)
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).
bool SbSocketSetTcpNoDelay(SbSocket socket, bool value)
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.
bool SbSocketSetTcpWindowScaling(SbSocket socket, bool value)