blob: 029fa03b7bec1e4f31223af03e12dc20de8fb723 [file] [log] [blame]
// Copyright 2019 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
library fuchsia.posix.socket;
using fuchsia.io;
using fuchsia.net;
using fuchsia.posix;
using zx;
/// Chosen to match `sizeof(struct sockaddr_storage)`.
using sockaddr = bytes:128;
/// Chosen to be large enough to hold whatever we might want to cram in it. So long as we support
/// socket options, we don't have a good sense of what we might want to send as payload.
// TODO(https://fxbug.dev/44347): replace C structures on the wire with FIDL types.
using sockopt = bytes:900;
/// The maximum length of an interface name.
// `sizeof((struct ifreq).ifr_name) == 16`; the last byte is reserved for the null terminator.
const uint8 INTERFACE_NAME_LENGTH = 15;
/// An interface name as a sequence of bytes.
using interface_name = string:INTERFACE_NAME_LENGTH;
/// A network socket.
///
/// Once a socket has been retrieved from a `Provider`, this interface is then used to further
/// configure and use the socket. This interface is essentially POSIX. Its implementation must
/// support Linux-specific arguments to {Get,Set}SockOpt.
///
/// All methods on this type are nonblocking; their exact behaviors match their Linux counterparts.
///
/// *Warning:* This protocol is not yet ready for direct use by clients. Instead, clients should
/// use the BSD sockets API to interact with sockets. We plan to change this protocol substantially
/// and clients that couple directly to this protocol will make those changes more difficult.
protocol BaseSocket {
compose fuchsia.io.Node;
/// Sets the local address used for the socket.
Bind(sockaddr addr) -> () error fuchsia.posix.Errno;
/// Initiates a connection to a remote address.
Connect(sockaddr addr) -> () error fuchsia.posix.Errno;
/// Retrieves the local socket address.
GetSockName() -> (sockaddr addr) error fuchsia.posix.Errno;
/// Retrieves the remote socket address.
GetPeerName() -> (sockaddr addr) error fuchsia.posix.Errno;
/// Sets the value of a socket option.
SetSockOpt(int16 level, int16 optname, sockopt optval) -> () error fuchsia.posix.Errno;
/// Retrieves the value of a socket option.
GetSockOpt(int16 level, int16 optname) -> (sockopt optval) error fuchsia.posix.Errno;
};
/// A datagram socket.
///
/// This type's [`fuchsia.io.Node/Describe`] method returns an eventpair which is used to signal
/// additional information about the state of the socket such as readiness or shutdown-ness.
///
/// All methods on this type are nonblocking; their exact behaviors match their Linux counterparts.
protocol DatagramSocket {
compose BaseSocket;
/// Shuts down part of the socket.
Shutdown(int16 how) -> () error fuchsia.posix.Errno;
/// Receives a message from the socket.
RecvMsg(uint32 addr_len, uint32 data_len, uint32 control_len, int16 flags) -> (sockaddr addr, bytes data, bytes control, uint32 truncated) error fuchsia.posix.Errno;
/// Sends a message on the socket.
SendMsg(sockaddr addr, vector<bytes>:MAX data, bytes control, int16 flags) -> (int64 len) error fuchsia.posix.Errno;
/// Sends a message on the socket.
SendMsg2(sockaddr addr, bytes:MAX data, bytes control, int16 flags) -> (int64 len) error fuchsia.posix.Errno;
};
/// A stream socket.
///
/// This type's [`fuchsia.io.Node/Describe`] method returns a socket which is used to transfer data
/// to and from the caller. Signals are used to communicate additional information about the state
/// of the socket such as connectedness and the presence of incoming connections in the case of a
/// listening socket.
///
/// All methods on this type are nonblocking; their exact behaviors match their Linux counterparts.
protocol StreamSocket {
compose BaseSocket;
/// Begins listening for new incoming connections. At most `backlog` connections will be
/// buffered.
Listen(int16 backlog) -> () error fuchsia.posix.Errno;
/// Accepts a buffered incoming connection.
Accept(int16 flags) -> (StreamSocket s) error fuchsia.posix.Errno;
};
/// Holds information about an interface and its addresses.
table InterfaceAddresses {
/// ID of the interface.
1: uint64 id;
/// Name of the interface.
2: interface_name name;
/// Contains the interface flags, as returned by the SIOCGIFFLAGS ioctl
/// operation.
3: uint32 flags;
/// All addresses currently assigned to the interface.
4: vector<fuchsia.net.Subnet>:MAX addresses;
};
/// A socket's domain.
///
/// Determines the addressing domain for a socket.
enum Domain : int16 {
/// An IPv4 socket. Equivalent to `AF_INET`.
IPV4 = 0;
/// An IPv6 socket. Equivalent to `AF_INET6`.
IPV6 = 1;
};
/// Protocols supported by [`fuchsia.posix.socket/DatagramSocket`].
///
/// `DatagramSocketProtocol` enumerates the protocols supported by the network stack over datagram
/// sockets.
// NOTE: This list can be expanded to accommodate other protocols should the need arise. Most
// notably, there exists the question on whether to support raw IP sockets and what the access model
// for those should be.
enum DatagramSocketProtocol {
/// UDP (User Datagram Protocol).
///
/// A UDP socket is equivalent to the POSIX API of `SOCK_DGRAM` with a protocol of 0 or
/// `IPPROTO_UDP`.
UDP = 1;
/// ICMP (Internet Control Message Protocol) echo.
///
/// An ICMP echo socket is equivalent to the POSIX API of `SOCK_DGRAM` with a protocol of
/// `IPPROTO_ICMP` `IPPROTO_ICMPV6` (depending on provided domain).
///
/// Datagrams sent over an ICMP echo socket *must* have a valid ICMP or ICMPv6 echo header.
ICMP_ECHO = 2;
};
/// Protocols supported by [`fuchsia.posix.socket/StreamSocket`].
///
/// `StreamSocketProtocol` enumerates the protocols supported by the network stack over stream
/// sockets.
enum StreamSocketProtocol {
/// TCP (Transmission Control Protocol).
///
/// A TCP socket is equivalent to the POSIX API of `SOCK_STREAM` with a protocol of 0 or
/// `IPPROTO_TCP`.
TCP = 0;
};
/// Provider implements the POSIX sockets API.
[Discoverable]
protocol Provider {
/// Requests a socket with the specified parameters.
// TODO(fxb/44347): Remove after soft transition.
[Deprecated = "Use StreamSocket or DatagramSocket instead"]
Socket2(int16 domain, int16 type, int16 protocol) -> (BaseSocket s) error fuchsia.posix.Errno;
/// Requests a stream socket with the specified parameters.
StreamSocket(Domain domain, StreamSocketProtocol proto) -> (StreamSocket s) error fuchsia.posix.Errno;
/// Requests a datagram socket with the specified parameters.
DatagramSocket(Domain domain, DatagramSocketProtocol proto) -> (DatagramSocket s) error fuchsia.posix.Errno;
/// Looks up an interface by its index and returns its name. Returns `ZX_ERR_NOT_FOUND` if the
/// specified index doesn't exist.
InterfaceIndexToName(uint64 index) -> (interface_name name) error zx.status;
/// Looks up an interface by its name and returns its index. Returns `ZX_ERR_NOT_FOUND` if the
/// specified name doesn't exist.
InterfaceNameToIndex(interface_name name) -> (uint64 index) error zx.status;
/// Requests a list of [`fuchsia.posix.socket.InterfaceAddresses`]
/// describing the network interfaces on the system.
GetInterfaceAddresses() -> (vector<InterfaceAddresses>:MAX interfaces);
};