| // Copyright 2020 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. |
| @available(added=7) |
| library fuchsia.net.interfaces; |
| |
| using fuchsia.hardware.network; |
| using fuchsia.net; |
| using zx; |
| |
| /// The maximum length of an interface name. |
| // `sizeof((struct ifreq).ifr_name) == 16`; the last byte is reserved for the |
| // null terminator. |
| const INTERFACE_NAME_LENGTH uint8 = 15; |
| |
| /// An interface name as a sequence of bytes. |
| alias name = string:INTERFACE_NAME_LENGTH; |
| |
| // TODO(https://fxbug.dev/7913): Use built-in empty struct when available. |
| type Empty = struct {}; |
| |
| /// Properties of a network interface. |
| type Properties = table { |
| /// An opaque identifier for the interface. Its value will not be reused |
| /// even if the device is removed and subsequently re-added. Immutable. |
| 1: id fuchsia.net.interface_id; |
| /// The addresses currently assigned to the interface. |
| 2: addresses vector<@generated_name("Address") table { |
| /// The address and prefix length. |
| @deprecated("incorrectly implies subnet membership; use `value` instead") |
| 1: addr fuchsia.net.Subnet; |
| /// The time after which the address will no longer be valid. |
| /// |
| /// Its value must be greater than 0. A value of `ZX_TIME_INFINITE` |
| /// indicates that the address will always be valid. The value is |
| /// derived from the monotonic clock. |
| /// |
| /// As a `zx.time`, the value has |
| /// [monotonic clock semantics](https://fuchsia.dev/fuchsia-src/concepts/time/monotonic), |
| /// which implies that it has no meaning outside of the host on which it |
| /// was generated and no meaning across host restarts. |
| 2: valid_until zx.time; |
| /// The interface address. |
| 3: value fuchsia.net.InterfaceAddress; |
| }>:MAX; |
| /// The device is enabled and its physical state is online. |
| 3: online bool; |
| /// The device class of the interface. Immutable. |
| 4: device_class strict union { |
| /// The interface is loopback. |
| 1: loopback Empty; |
| /// The interface's network device class. |
| 2: device fuchsia.hardware.network.DeviceClass; |
| }; |
| |
| /// Whether there is a default IPv4 route through this interface. |
| 5: has_default_ipv4_route bool; |
| /// Whether there is a default IPv6 route through this interface. |
| 6: has_default_ipv6_route bool; |
| /// The name of the interface. Immutable. |
| 7: name name; |
| }; |
| |
| /// Network interface state inspection and observation. |
| @discoverable |
| protocol State { |
| /// Initialize a watcher for interface state. |
| /// |
| /// The server enqueues interface addition, deletion and property changes as |
| /// they occur, which can then be retrieved via the pipelined protocol. |
| /// |
| /// + request `options` specifies the behavior of the [`Watcher`]. |
| /// + request `watcher` grants access to a [`Watcher`]. Closed if the queue |
| /// cannot be allocated or if the queue is full when the server attempts |
| /// to enqueue an event. |
| GetWatcher(resource struct { |
| /// Options for configuring the interface state watcher. |
| // This type is currently empty, but may grow to allow behavior tuning |
| // of the watcher, e.g. allow subscribing to a subset of the available |
| // events. |
| options @generated_name("WatcherOptions") table {}; |
| watcher server_end:Watcher; |
| }); |
| }; |
| |
| /// Observer protocol for changes to network interfaces (addition, deletion, and |
| /// interface property changes). |
| protocol Watcher { |
| /// Hanging get for an interface addition/deletion change. |
| /// |
| /// Clients should only have one call of this method at a time; a second |
| /// call to this method while a call is already pending will cause the |
| /// server end of the protocol to be closed. |
| /// |
| /// If there are N interfaces present at the time the server end of the |
| /// protocol is initialized, then the first N invocations of this method |
| /// will return [`Event.existing`] followed by a single [`Event.idle`] |
| /// indicating that all existing interfaces have been sent. Subsequent calls |
| /// will immediately return if there is a change to be reported, or block |
| /// until a change occurs. |
| /// |
| /// The server may choose to coalesce property change events, e.g. when |
| /// multiple independent property changes occur. As a result, clients cannot |
| /// assume that the order in which they observe the interface changes is the |
| /// order in which the changes occurred. |
| /// |
| /// - response `event` the interface change event. Properties of an added or |
| /// existing interface will have all fields present. Property change |
| /// events will always have the interface ID field present (the ID never |
| /// changes); while other fields will only be present with the new value |
| /// if the property has changed. |
| Watch() -> (struct { |
| event strict union { |
| /// Properties of an interface that existed when watching started. |
| /// |
| /// All fields are set. |
| 1: existing Properties; |
| /// Properties of an interface that was added while watching. |
| /// |
| /// All fields are set. |
| 2: added Properties; |
| /// ID of an interface that was removed while watching. |
| 3: removed fuchsia.net.interface_id; |
| /// Properties of an interface that changed while watching. |
| /// |
| /// Only [`Properties.id`] and changed fields are set. |
| 4: changed Properties; |
| /// Sentinel value indicating no more [`existing`] events will be |
| /// sent. |
| 5: idle Empty; |
| }; |
| }); |
| }; |