# fuchsia.net.interfaces

<br />

Added: 7

## **PROTOCOLS**

## State

*Defined in [fuchsia.net.interfaces/interfaces.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.net.interfaces/interfaces.fidl;l=164)*

Network interface state inspection and observation.

<br />

### GetWatcher

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](https://fuchsia.dev/reference/fidl/fuchsia.net.interfaces#Watcher).
- request `watcher` grants access to a [Watcher](https://fuchsia.dev/reference/fidl/fuchsia.net.interfaces#Watcher). Closed if the queue cannot be allocated or if the queue is full when the server attempts to enqueue an event.

#### Request

| Name | Type |
|---|---|
| `options` | `https://fuchsia.dev/reference/fidl/fuchsia.net.interfaces#WatcherOptions` |
| `watcher` | `server_end:https://fuchsia.dev/reference/fidl/fuchsia.net.interfaces#Watcher` |

## Watcher

*Defined in [fuchsia.net.interfaces/interfaces.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.net.interfaces/interfaces.fidl;l=208)*

Observer protocol for changes to network interfaces (addition, deletion, and
interface property changes).

<br />

### Watch

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](https://fuchsia.dev/reference/fidl/fuchsia.net.interfaces#Event.existing) followed by a single [Event.idle](https://fuchsia.dev/reference/fidl/fuchsia.net.interfaces#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.

#### Request

\<EMPTY\>

#### Response

| Name | Type |
|---|---|
| `event` | `https://fuchsia.dev/reference/fidl/fuchsia.net.interfaces#Event` |

## **STRUCTS**

### 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\>

## **ENUMS**

### AddressAssignmentState [strict](https://fuchsia.dev/fuchsia-src/reference/fidl/language/language#strict-vs-flexible)

Type: `uint32`

*Defined in [fuchsia.net.interfaces/interfaces.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.net.interfaces/interfaces.fidl;l=62)*

Assignment state of an IP address.
Added: HEAD

<br />

| Name | Value | Description |
|---|---|---|
| ### TENTATIVE | `1` | Address assignment is in progress, e.g. Duplicate Address Detection is being performed. The address cannot be used when in this state (cannot bind to it yet or receive packets destined to it). The Duplicate Address Detection mechanism is described in [RFC 4862, section 5.4](https://tools.ietf.org/html/rfc4862#section-5.4) |
| ### ASSIGNED | `2` | The address is assigned to an interface. |
| ### UNAVAILABLE | `3` | The address is unavailable, e.g. if the interface holding the address is offline. |

## **TABLES**

### Address

*Defined in [fuchsia.net.interfaces/interfaces.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.net.interfaces/interfaces.fidl;l=98)*

| Ordinal | Field | Type | Description |
|---|---|---|---|
| ### 1 | `addr` | `https://fuchsia.dev/reference/fuchsia.net//https://fuchsia.dev/reference/fuchsia.net#Subnet` | The address and prefix length. Required. |
| ### 2 | `valid_until` | `https://fuchsia.dev/reference/zx//https://fuchsia.dev/reference/zx#Time` | 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. Optional; may be omitted due to disinterest. |
| ### 3 | `preferred_lifetime_info` | `https://fuchsia.dev/reference/fidl/fuchsia.net.interfaces#PreferredLifetimeInfo` | Preferred lifetime information. Optional; may be omitted due to disinterest. Added: 9 |
| ### 4 | `assignment_state` | `https://fuchsia.dev/reference/fidl/fuchsia.net.interfaces#AddressAssignmentState` | The address's assignment state. Required. Added: HEAD |

### Properties

*Defined in [fuchsia.net.interfaces/interfaces.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.net.interfaces/interfaces.fidl;l=87)*

Properties of a network interface.

<br />

| Ordinal | Field | Type | Description |
|---|---|---|---|
| ### 1 | `id` | `https://fuchsia.dev/reference/fuchsia.net//https://fuchsia.dev/reference/fuchsia.net#InterfaceId` | An opaque identifier for the interface. Its value will not be reused even if the device is removed and subsequently re-added. Immutable. |
| ### 2 | `addresses` | `vector<https://fuchsia.dev/reference/fidl/fuchsia.net.interfaces#Address>` | The addresses currently installed on the interface. Addresses are sorted on [Address.addr](https://fuchsia.dev/reference/fidl/fuchsia.net.interfaces#Address.addr), and no two addresses can have the same `Address.addr` value. Only assigned addresses are included unless the watcher was created with [WatcherOptions.include_non_assigned_addresses](https://fuchsia.dev/reference/fidl/fuchsia.net.interfaces#WatcherOptions.include_non_assigned_addresses) set to `true`. |
| ### 3 | `online` | `bool` | The device is enabled and its physical state is online. |
| ### 5 | `has_default_ipv4_route` | `bool` | Whether there is a default IPv4 route through this interface. |
| ### 6 | `has_default_ipv6_route` | `bool` | Whether there is a default IPv6 route through this interface. |
| ### 7 | `name` | `https://fuchsia.dev/reference/fidl/fuchsia.net.interfaces#Name` | The name of the interface. Immutable. |
| ### 8 | `port_class` | `https://fuchsia.dev/reference/fidl/fuchsia.net.interfaces#PortClass` | The port class of the interface. Immutable. Added: 22 |
| ### 9 | `port_identity_koid` | `https://fuchsia.dev/reference/zx//https://fuchsia.dev/reference/zx#Koid` | The KOID of the identity event vended out by the interface's backing [fuchsia.hardware.network](https://fuchsia.dev/reference/fuchsia.hardware.network/)/[Port](https://fuchsia.dev/reference/fuchsia.hardware.network/#Port). Callers may use this identifier to correlate port instances to installed interfaces. Immutable. Present for interfaces backed by a [fuchsia.hardware.network](https://fuchsia.dev/reference/fuchsia.hardware.network/)/[Port](https://fuchsia.dev/reference/fuchsia.hardware.network/#Port), absent otherwise. Added: HEAD |

### WatcherOptions

*Defined in [fuchsia.net.interfaces/interfaces.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.net.interfaces/interfaces.fidl;l=176)*

| Ordinal | Field | Type | Description |
|---|---|---|---|
| ### 1 | `address_properties_interest` | `https://fuchsia.dev/reference/fidl/fuchsia.net.interfaces#AddressPropertiesInterest` | Bitfield for registering interest in address properties. Optional; interpreted as all bits set to 0 if not present. Added: HEAD |
| ### 2 | `include_non_assigned_addresses` | `bool` | Flag to determine if only assigned addresses are returned (where the assignment state is [AddressAssignmentState::Assigned](https://fuchsia.dev/reference/fidl/fuchsia.net.interfaces#AddressAssignmentState::Assigned)) or all addresses are returned. Optional; interpreted as false if not present. Added: HEAD |
| ### 3 | `port_identity_koid_filter` | `https://fuchsia.dev/reference/zx//https://fuchsia.dev/reference/zx#Koid` | If specified, only events pertaining the interface whose port identity event matches the provided `port_identity_koid_filter` are yielded. Optional; no port identity filtering is performed if absent. Added: HEAD |

## **UNIONS**

### Event [strict](https://fuchsia.dev/fuchsia-src/reference/fidl/language/language#strict-vs-flexible)

*Defined in [fuchsia.net.interfaces/interfaces.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.net.interfaces/interfaces.fidl;l=231)*

| Ordinal | Variant | Type | Description |
|---|---|---|---|
| ### 1 | `existing` | `https://fuchsia.dev/reference/fidl/fuchsia.net.interfaces#Properties` | Properties of an interface that existed when watching started. All interested fields and [Properties.id](https://fuchsia.dev/reference/fidl/fuchsia.net.interfaces#Properties.id) are set. |
| ### 2 | `added` | `https://fuchsia.dev/reference/fidl/fuchsia.net.interfaces#Properties` | Properties of an interface that was added while watching. All interested fields and [Properties.id](https://fuchsia.dev/reference/fidl/fuchsia.net.interfaces#Properties.id) are set. |
| ### 3 | `removed` | `https://fuchsia.dev/reference/fuchsia.net//https://fuchsia.dev/reference/fuchsia.net#InterfaceId` | ID of an interface that was removed while watching. |
| ### 4 | `changed` | `https://fuchsia.dev/reference/fidl/fuchsia.net.interfaces#Properties` | Properties of an interface that changed while watching. Only [Properties.id](https://fuchsia.dev/reference/fidl/fuchsia.net.interfaces#Properties.id) and interested fields which have changed are set with the new values. |
| ### 5 | `idle` | `https://fuchsia.dev/reference/fidl/fuchsia.net.interfaces#Empty` | Sentinel value indicating no more [existing](https://fuchsia.dev/reference/fidl/fuchsia.net.interfaces#existing) events will be sent. |

<br />

### PortClass [flexible](https://fuchsia.dev/fuchsia-src/reference/fidl/language/language#strict-vs-flexible)

*Defined in [fuchsia.net.interfaces/interfaces.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.net.interfaces/interfaces.fidl;l=152)*

The port class of an interface.
Added: 22

| Ordinal | Variant | Type | Description |
|---|---|---|---|
| ### 1 | `loopback` | `https://fuchsia.dev/reference/fidl/fuchsia.net.interfaces#Empty` | The interface is loopback. |
| ### 2 | `device` | `https://fuchsia.dev/reference/fuchsia.hardware.network//https://fuchsia.dev/reference/fuchsia.hardware.network#PortClass` | The interface's network device port class. |
| ### 3 | `blackhole` | `https://fuchsia.dev/reference/fidl/fuchsia.net.interfaces#Empty` | The interface is a blackhole interface. Added: HEAD |

<br />

### PreferredLifetimeInfo [strict](https://fuchsia.dev/fuchsia-src/reference/fidl/language/language#strict-vs-flexible)

*Defined in [fuchsia.net.interfaces/interfaces.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.net.interfaces/interfaces.fidl;l=26)*

Information about the preferred lifetime of an IP address or delegated
prefix.
Added: 9

| Ordinal | Variant | Type | Description |
|---|---|---|---|
| ### 1 | `preferred_until` | `https://fuchsia.dev/reference/zx//https://fuchsia.dev/reference/zx#Time` | The end of the preferred lifetime. The address/prefix should *not* be considered deprecated if `zx.Time` is in the past. `preferred_until` is exchanged as a means to inform the deadline where deprecation is expected to happen. The preferred lifetime of addresses is defined in [RFC 4862, section 2](https://tools.ietf.org/html/rfc4862#section-2). Addresses configured using a delegated prefix must have a preferred lifetime no longer than that of the prefix according to [RFC 8415, section 6.3](https://datatracker.ietf.org/doc/html/rfc8415#section-6.3). Must be greater than 0. If `zx.Time.INFINITE`, the preferred lifetime does not expire. |
| ### 2 | `deprecated` | `https://fuchsia.dev/reference/fidl/fuchsia.net.interfaces#Empty` | The address/prefix is deprecated. 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 [RFC 4862, section 1](https://tools.ietf.org/html/rfc4862#section-1)). Addresses configured using a deprecated delegated prefix must also be deprecated according to [RFC 8415, section 6.3](https://datatracker.ietf.org/doc/html/rfc8415#section-6.3). An address/prefix can become undeprecated if its preferred lifetime is extended. |

<br />

## **BITS**

### AddressPropertiesInterest [flexible](https://fuchsia.dev/fuchsia-src/reference/fidl/language/language#strict-vs-flexible)

Type: `uint64`

*Defined in [fuchsia.net.interfaces/interfaces.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.net.interfaces/interfaces.fidl;l=181)*

| Name | Value | Description |
|---|---|---|
| ### VALID_UNTIL | 1 |   |
| ### PREFERRED_LIFETIME_INFO | 2 |   |

## **CONSTANTS**

| Name | Value | Type | Description |
|---|---|---|---|
| [INTERFACE_NAME_LENGTH](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.net.interfaces/interfaces.fidl;l=14) | `15` | `uint8` | The maximum length of an interface name. |

## **ALIASES**

| Name | Value | Description |
|---|---|---|
| [Name](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.net.interfaces/interfaces.fidl;l=17) | `string`\[`https://fuchsia.dev/reference/fidl/fuchsia.net.interfaces#INTERFACE_NAME_LENGTH`\] | An interface name as a sequence of bytes. |