| <link rel="stylesheet" href="../style.css" /> |
| |
| [TOC] |
| # fuchsia.net.interfaces |
| |
| <div class="fidl-version-div"><span class="fidl-attribute fidl-version">Added: 7</span></div> |
| |
| |
| ## **PROTOCOLS** |
| |
| ## State {#State} |
| *Defined in [fuchsia.net.interfaces/interfaces.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.net.interfaces/interfaces.fidl;l=113)* |
| <p>Network interface state inspection and observation.</p> |
| |
| |
| ### GetWatcher {#State.GetWatcher} |
| |
| <p>Initialize a watcher for interface state.</p> |
| <p>The server enqueues interface addition, deletion and property changes as |
| they occur, which can then be retrieved via the pipelined protocol.</p> |
| <ul> |
| <li>request <code>options</code> specifies the behavior of the <a class='link' href='#Watcher'>Watcher</a>.</li> |
| <li>request <code>watcher</code> grants access to a <a class='link' href='#Watcher'>Watcher</a>. Closed if the queue |
| cannot be allocated or if the queue is full when the server attempts |
| to enqueue an event.</li> |
| </ul> |
| |
| |
| |
| #### Request {#State.GetWatcher_Request} |
| |
| <table> |
| <tr><th>Name</th><th>Type</th></tr> |
| <tr> |
| <td><code>options</code></td> |
| <td> |
| <code><a class='link' href='#WatcherOptions'>WatcherOptions</a></code> |
| </td> |
| </tr> |
| <tr> |
| <td><code>watcher</code></td> |
| <td> |
| <code>server_end<<a class='link' href='#Watcher'>Watcher</a>></code> |
| </td> |
| </tr> |
| </table> |
| |
| |
| ## Watcher {#Watcher} |
| *Defined in [fuchsia.net.interfaces/interfaces.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.net.interfaces/interfaces.fidl;l=148)* |
| <p>Observer protocol for changes to network interfaces (addition, deletion, and |
| interface property changes).</p> |
| |
| |
| ### Watch {#Watcher.Watch} |
| |
| <p>Hanging get for an interface addition/deletion change.</p> |
| <p>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.</p> |
| <p>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 <a class='link' href='#Event.existing'>Event.existing</a> followed by a single <a class='link' href='#Event.idle'>Event.idle</a> |
| 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.</p> |
| <p>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.</p> |
| <ul> |
| <li>response <code>event</code> the interface change event.</li> |
| </ul> |
| |
| |
| |
| #### Request {#Watcher.Watch_Request} |
| |
| <EMPTY> |
| |
| |
| #### Response {#Watcher.Watch_Response} |
| |
| <table> |
| <tr><th>Name</th><th>Type</th></tr> |
| <tr> |
| <td><code>event</code></td> |
| <td> |
| <code><a class='link' href='#Event'>Event</a></code> |
| </td> |
| </tr> |
| </table> |
| |
| |
| ## **STRUCTS** |
| |
| ### Empty {#Empty data-text="Empty"} |
| *Defined in [fuchsia.net.interfaces/interfaces.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.net.interfaces/interfaces.fidl;l=20)* |
| |
| <EMPTY> |
| |
| |
| |
| ## **TABLES** |
| |
| ### Address {#Address data-text="Address"} |
| |
| |
| *Defined in [fuchsia.net.interfaces/interfaces.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.net.interfaces/interfaces.fidl;l=68)* |
| |
| <table> |
| <tr><th>Ordinal</th><th>Field</th><th>Type</th><th>Description</th></tr> |
| <tr id="Address.addr"> |
| <td><h3 id="Address.addr" class="add-link hide-from-toc">1</h3></td> |
| <td><code>addr</code></td> |
| <td> |
| <code><a class='link' href='../fuchsia.net/'>fuchsia.net</a>/<a class='link' href='../fuchsia.net/#Subnet'>Subnet</a></code> |
| </td> |
| <td><p>The address and prefix length.</p> |
| <p>Required.</p> |
| </td> |
| </tr> |
| <tr id="Address.valid_until"> |
| <td><h3 id="Address.valid_until" class="add-link hide-from-toc">2</h3></td> |
| <td><code>valid_until</code></td> |
| <td> |
| <code><a class='link' href='../zx/'>zx</a>/<a class='link' href='../zx/#time'>time</a></code> |
| </td> |
| <td><p>The time after which the address will no longer be valid.</p> |
| <p>Its value must be greater than 0. A value of <code>ZX_TIME_INFINITE</code> |
| indicates that the address will always be valid. The value is |
| derived from the monotonic clock.</p> |
| <p>As a <code>zx.time</code>, the value has |
| <a href="https://fuchsia.dev/fuchsia-src/concepts/time/monotonic">monotonic clock semantics</a>, |
| which implies that it has no meaning outside of the host on which it |
| was generated and no meaning across host restarts.</p> |
| <p>Optional; may be omitted due to disinterest.</p> |
| </td> |
| </tr> |
| <tr id="Address.preferred_lifetime_info"> |
| <td><h3 id="Address.preferred_lifetime_info" class="add-link hide-from-toc">3</h3></td> |
| <td><code>preferred_lifetime_info</code></td> |
| <td> |
| <code><a class='link' href='#PreferredLifetimeInfo'>PreferredLifetimeInfo</a></code> |
| </td> |
| <td><p>Preferred lifetime information.</p> |
| <p>Optional; may be omitted due to disinterest.</p> |
| <div class="fidl-version-div"><span class="fidl-attribute fidl-version">Added: 9</span></div> |
| </td> |
| </tr> |
| </table> |
| |
| ### Properties {#Properties data-text="Properties"} |
| |
| |
| *Defined in [fuchsia.net.interfaces/interfaces.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.net.interfaces/interfaces.fidl;l=60)* |
| <p>Properties of a network interface.</p> |
| |
| <table> |
| <tr><th>Ordinal</th><th>Field</th><th>Type</th><th>Description</th></tr> |
| <tr id="Properties.id"> |
| <td><h3 id="Properties.id" class="add-link hide-from-toc">1</h3></td> |
| <td><code>id</code></td> |
| <td> |
| <code><a class='link' href='../fuchsia.net/'>fuchsia.net</a>/<a class='link' href='../fuchsia.net/#InterfaceId'>InterfaceId</a></code> |
| </td> |
| <td><p>An opaque identifier for the interface. Its value will not be reused |
| even if the device is removed and subsequently re-added. Immutable.</p> |
| </td> |
| </tr> |
| <tr id="Properties.addresses"> |
| <td><h3 id="Properties.addresses" class="add-link hide-from-toc">2</h3></td> |
| <td><code>addresses</code></td> |
| <td> |
| <code>vector<<a class='link' href='#Address'>Address</a>></code> |
| </td> |
| <td><p>The addresses currently assigned to the interface.</p> |
| <p>Addresses are sorted on <a class='link' href='#Address.addr'>Address.addr</a>, and no two addresses can |
| have the same <code>Address.addr</code> value.</p> |
| </td> |
| </tr> |
| <tr id="Properties.online"> |
| <td><h3 id="Properties.online" class="add-link hide-from-toc">3</h3></td> |
| <td><code>online</code></td> |
| <td> |
| <code>bool</code> |
| </td> |
| <td><p>The device is enabled and its physical state is online.</p> |
| </td> |
| </tr> |
| <tr id="Properties.device_class"> |
| <td><h3 id="Properties.device_class" class="add-link hide-from-toc">4</h3></td> |
| <td><code>device_class</code></td> |
| <td> |
| <code><a class='link' href='#DeviceClass'>DeviceClass</a></code> |
| </td> |
| <td><p>The device class of the interface. Immutable.</p> |
| </td> |
| </tr> |
| <tr id="Properties.has_default_ipv4_route"> |
| <td><h3 id="Properties.has_default_ipv4_route" class="add-link hide-from-toc">5</h3></td> |
| <td><code>has_default_ipv4_route</code></td> |
| <td> |
| <code>bool</code> |
| </td> |
| <td><p>Whether there is a default IPv4 route through this interface.</p> |
| </td> |
| </tr> |
| <tr id="Properties.has_default_ipv6_route"> |
| <td><h3 id="Properties.has_default_ipv6_route" class="add-link hide-from-toc">6</h3></td> |
| <td><code>has_default_ipv6_route</code></td> |
| <td> |
| <code>bool</code> |
| </td> |
| <td><p>Whether there is a default IPv6 route through this interface.</p> |
| </td> |
| </tr> |
| <tr id="Properties.name"> |
| <td><h3 id="Properties.name" class="add-link hide-from-toc">7</h3></td> |
| <td><code>name</code></td> |
| <td> |
| <code><a class='link' href='#Name'>Name</a></code> |
| </td> |
| <td><p>The name of the interface. Immutable.</p> |
| </td> |
| </tr> |
| </table> |
| |
| ### WatcherOptions {#WatcherOptions data-text="WatcherOptions"} |
| |
| |
| *Defined in [fuchsia.net.interfaces/interfaces.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.net.interfaces/interfaces.fidl;l=125)* |
| |
| <table> |
| <tr><th>Ordinal</th><th>Field</th><th>Type</th><th>Description</th></tr> |
| <tr id="WatcherOptions.address_properties_interest"> |
| <td><h3 id="WatcherOptions.address_properties_interest" class="add-link hide-from-toc">1</h3></td> |
| <td><code>address_properties_interest</code></td> |
| <td> |
| <code><a class='link' href='#AddressPropertiesInterest'>AddressPropertiesInterest</a></code> |
| </td> |
| <td><p>Bitfield for registering interest in address properties.</p> |
| <p>Optional; interpreted as all bits set to 0 if not present.</p> |
| <div class="fidl-version-div"><span class="fidl-attribute fidl-version">Added: HEAD</span></div> |
| </td> |
| </tr> |
| </table> |
| |
| |
| ## **UNIONS** |
| |
| ### DeviceClass [strict](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute} {#DeviceClass data-text="DeviceClass"} |
| *Defined in [fuchsia.net.interfaces/interfaces.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.net.interfaces/interfaces.fidl;l=96)* |
| <table> |
| <tr><th>Ordinal</th><th>Variant</th><th>Type</th><th>Description</th></tr> |
| <tr id="DeviceClass.loopback"> |
| <td><h3 id="DeviceClass.loopback" class="add-link hide-from-toc">1</h3></td> |
| <td><code>loopback</code></td> |
| <td> |
| <code><a class='link' href='#Empty'>Empty</a></code> |
| </td> |
| <td><p>The interface is loopback.</p> |
| </td> |
| </tr> |
| <tr id="DeviceClass.device"> |
| <td><h3 id="DeviceClass.device" class="add-link hide-from-toc">2</h3></td> |
| <td><code>device</code></td> |
| <td> |
| <code><a class='link' href='../fuchsia.hardware.network/'>fuchsia.hardware.network</a>/<a class='link' href='../fuchsia.hardware.network/#DeviceClass'>DeviceClass</a></code> |
| </td> |
| <td><p>The interface's network device class.</p> |
| </td> |
| </tr> |
| </table> |
| |
| ### Event [strict](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute} {#Event data-text="Event"} |
| *Defined in [fuchsia.net.interfaces/interfaces.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.net.interfaces/interfaces.fidl;l=169)* |
| <table> |
| <tr><th>Ordinal</th><th>Variant</th><th>Type</th><th>Description</th></tr> |
| <tr id="Event.existing"> |
| <td><h3 id="Event.existing" class="add-link hide-from-toc">1</h3></td> |
| <td><code>existing</code></td> |
| <td> |
| <code><a class='link' href='#Properties'>Properties</a></code> |
| </td> |
| <td><p>Properties of an interface that existed when watching started.</p> |
| <p>All interested fields and <a class='link' href='#Properties.id'>Properties.id</a> are set.</p> |
| </td> |
| </tr> |
| <tr id="Event.added"> |
| <td><h3 id="Event.added" class="add-link hide-from-toc">2</h3></td> |
| <td><code>added</code></td> |
| <td> |
| <code><a class='link' href='#Properties'>Properties</a></code> |
| </td> |
| <td><p>Properties of an interface that was added while watching.</p> |
| <p>All interested fields and <a class='link' href='#Properties.id'>Properties.id</a> are set.</p> |
| </td> |
| </tr> |
| <tr id="Event.removed"> |
| <td><h3 id="Event.removed" class="add-link hide-from-toc">3</h3></td> |
| <td><code>removed</code></td> |
| <td> |
| <code><a class='link' href='../fuchsia.net/'>fuchsia.net</a>/<a class='link' href='../fuchsia.net/#InterfaceId'>InterfaceId</a></code> |
| </td> |
| <td><p>ID of an interface that was removed while watching.</p> |
| </td> |
| </tr> |
| <tr id="Event.changed"> |
| <td><h3 id="Event.changed" class="add-link hide-from-toc">4</h3></td> |
| <td><code>changed</code></td> |
| <td> |
| <code><a class='link' href='#Properties'>Properties</a></code> |
| </td> |
| <td><p>Properties of an interface that changed while watching.</p> |
| <p>Only <a class='link' href='#Properties.id'>Properties.id</a> and interested fields which have changed |
| are set with the new values.</p> |
| </td> |
| </tr> |
| <tr id="Event.idle"> |
| <td><h3 id="Event.idle" class="add-link hide-from-toc">5</h3></td> |
| <td><code>idle</code></td> |
| <td> |
| <code><a class='link' href='#Empty'>Empty</a></code> |
| </td> |
| <td><p>Sentinel value indicating no more <a class='link' href='#existing'>existing</a> events will be |
| sent.</p> |
| </td> |
| </tr> |
| </table> |
| |
| ### PreferredLifetimeInfo [strict](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute} {#PreferredLifetimeInfo data-text="PreferredLifetimeInfo"} |
| *Defined in [fuchsia.net.interfaces/interfaces.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.net.interfaces/interfaces.fidl;l=25)* |
| <p>Information about the preferred lifetime of an IP address or delegated |
| prefix.</p> |
| <div class="fidl-version-div"><span class="fidl-attribute fidl-version">Added: 9</span></div> |
| <table> |
| <tr><th>Ordinal</th><th>Variant</th><th>Type</th><th>Description</th></tr> |
| <tr id="PreferredLifetimeInfo.preferred_until"> |
| <td><h3 id="PreferredLifetimeInfo.preferred_until" class="add-link hide-from-toc">1</h3></td> |
| <td><code>preferred_until</code></td> |
| <td> |
| <code><a class='link' href='../zx/'>zx</a>/<a class='link' href='../zx/#time'>time</a></code> |
| </td> |
| <td><p>The end of the preferred lifetime.</p> |
| <p>The address/prefix should <em>not</em> be considered deprecated if <code>zx.time</code> |
| is in the past. <code>preferred_until</code> is exchanged as a means to inform |
| the deadline where deprecation is expected to happen.</p> |
| <p>The preferred lifetime of addresses is defined in |
| <a href="https://tools.ietf.org/html/rfc4862#section-2">RFC 4862, section 2</a>.</p> |
| <p>Addresses configured using a delegated prefix must have a preferred |
| lifetime no longer than that of the prefix according to |
| <a href="https://datatracker.ietf.org/doc/html/rfc8415#section-6.3">RFC 8415, section 6.3</a>.</p> |
| <p>Must be greater than 0. If <code>zx.time.INFINITE</code>, the preferred lifetime |
| does not expire.</p> |
| </td> |
| </tr> |
| <tr id="PreferredLifetimeInfo.deprecated"> |
| <td><h3 id="PreferredLifetimeInfo.deprecated" class="add-link hide-from-toc">2</h3></td> |
| <td><code>deprecated</code></td> |
| <td> |
| <code><a class='link' href='#Empty'>Empty</a></code> |
| </td> |
| <td><p>The address/prefix is deprecated.</p> |
| <p>Deprecated addresses should no longer be used for initiating |
| new connections unless explicitly requested, or if no other |
| non-deprecated addresses are assigned (as described in |
| <a href="https://tools.ietf.org/html/rfc4862#section-1">RFC 4862, section 1</a>).</p> |
| <p>Addresses configured using a deprecated delegated prefix must also be |
| deprecated according to |
| <a href="https://datatracker.ietf.org/doc/html/rfc8415#section-6.3">RFC 8415, section 6.3</a>.</p> |
| <p>An address/prefix can become undeprecated if its preferred lifetime is |
| extended.</p> |
| </td> |
| </tr> |
| </table> |
| |
| |
| ## **BITS** |
| |
| ### AddressPropertiesInterest [flexible](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute} {#AddressPropertiesInterest} |
| Type: <code>uint64</code> |
| |
| *Defined in [fuchsia.net.interfaces/interfaces.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.net.interfaces/interfaces.fidl;l=135)* |
| |
| <table> |
| <tr><th>Name</th><th>Value</th><th>Description</th></tr> |
| <tr id="AddressPropertiesInterest.VALID_UNTIL"> |
| <td><h3 id="AddressPropertiesInterest.VALID_UNTIL" class="add-link hide-from-toc">VALID_UNTIL</h3></td> |
| <td>1</td> |
| <td></td> |
| </tr> |
| <tr id="AddressPropertiesInterest.PREFERRED_LIFETIME_INFO"> |
| <td><h3 id="AddressPropertiesInterest.PREFERRED_LIFETIME_INFO" class="add-link hide-from-toc">PREFERRED_LIFETIME_INFO</h3></td> |
| <td>2</td> |
| <td></td> |
| </tr> |
| </table> |
| |
| |
| ## **CONSTANTS** |
| |
| <table> |
| <tr><th>Name</th><th>Value</th><th>Type</th><th>Description</th></tr> |
| <tr id="INTERFACE_NAME_LENGTH"> |
| <td><a href="https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.net.interfaces/interfaces.fidl;l=14">INTERFACE_NAME_LENGTH</a></td> |
| <td> |
| <code>15</code> |
| </td> |
| <td><code>uint8</code></td> |
| <td><p>The maximum length of an interface name.</p> |
| </td> |
| </tr> |
| </table> |
| |
| ## **ALIASES** |
| |
| <table> |
| <tr><th>Name</th><th>Value</th><th>Description</th></tr> |
| <tr id="Name"> |
| <td><a href="https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.net.interfaces/interfaces.fidl;l=17">Name</a></td> |
| <td> |
| <code>string</code>[<code><a class='link' href='#INTERFACE_NAME_LENGTH'>INTERFACE_NAME_LENGTH</a></code>]</td> |
| <td><p>An interface name as a sequence of bytes.</p> |
| </td> |
| </tr> |
| </table> |
