| // 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.net.icmp; |
| |
| using fuchsia.net; |
| 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: fuchsia.net.IpAddress 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: fuchsia.net.IpAddress remote; |
| }; |
| |
| /// Provides clients access to ICMP echo sockets through EchoSockets. |
| [Discoverable] |
| 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; |
| }; |