blob: 4eac2ec21a26c3373c7849f7ced0595e3b0b870d [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.
using zx;
/// Configuration for an ICMP echo socket.
table EchoSocketConfig {
/// Local IPv4 or IPv6 address used as the source for ICMP echo requests
/// sent through this EchoSocket.
/// This field is currently ignored and has no effect, but may have an
/// effect in the future for source-based routing. It is highly encouraged
/// to specify this field, if possible.
1: local;
/// Remote IPv4 or IPv6 address used as the destination for ICMP echo
/// requests sent through this EchoSocket.
/// The version of IP used for `remote` needs to match the version used
/// by `source`. If this criterion is not met, an `EchoSocket.OnOpen` event
/// will be sent with status `INVALID_ARGUMENT`.
/// In other words, `source` and `remote` can either both be IPv4 or IPv6.
/// Having `source` as IPv4 and `remote` as IPv6, or vice versa, will result
/// in error.
2: remote;
/// Provides clients access to ICMP echo sockets through EchoSockets.
protocol Provider {
/// Open an ICMP socket soley for sending ICMP echo requests and receiving
/// ICMP echo replies. A protocol request `socket` provides an interface to
/// the EchoSocket for the new ICMP echo socket.
OpenEchoSocket(EchoSocketConfig config, request<EchoSocket> socket);
/// EchoSocket is a socket that allows sending ICMP echo requests and receiving
/// ICMP echo replies.
/// Other ICMP operations, such as sending and receiving error messages, are
/// handled by the network stack itself and not exposed by this API.
/// The OnOpen event will trigger with a status code once opened.
protocol EchoSocket {
/// Send an ICMP echo request.
/// The source address on the packet is chosen purely based on the remote
/// address for the time being. The configured local address from
/// `EchoSocketConfig` is ignored.
SendRequest(EchoPacket request);
/// Watch for an ICMP echo reply or error. If a reply or error hasn't been
/// received yet, block until one arrives; otherwise, return immediately.
/// Any incoming echo replies from the configured remote address will be
/// received, regardless of their destination address. This is due to the
/// ignored local address from `EchoSocketConfig`.
/// Returns status:
/// - `ADDRESS_UNREACHABLE` when the remote host is unreachable
/// - `OUT_OF_RANGE` when the packet is larger than the MTU
Watch() -> (EchoPacket reply) error zx.status;
/// Triggers when the socket opens. Indicates the success or failure of the
/// open operation.
/// Returns status `INVALID_ARUGMENT` when the `local` and `remote` IP
/// addresses do not match IP versions.
-> OnOpen(zx.status s);
/// EchoPacket specifies ICMP fields for an echo request or reply. IP fields
/// are set and verified upon `OpenEchoSocket`.
struct EchoPacket {
/// Sequence numbers are used to match requests and replies.
uint16 sequence_num;
/// The payload can be of arbitrary length and content. The size, including IP
/// and ICMP headers, must be less than the Maximum Transmission Limit (MTU)
/// of the network to avoid being fragmented.
bytes payload;