sdk/fidl/fuchsia.vsock/connector.fidl

// Copyright 2018 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=HEAD)
library fuchsia.vsock;

using zx;
using fuchsia.hardware.vsock;

const USER_SIGNAL_0 uint32 = 0x01000000;

const SIGNAL_STREAM_INCOMING uint32 = USER_SIGNAL_0;

const VMADDR_CID_ANY uint32 = fuchsia.hardware.vsock.VMADDR_CID_ANY;
const VMADDR_CID_HYPERVISOR uint32 = fuchsia.hardware.vsock.VMADDR_CID_HYPERVISOR;
const VMADDR_CID_LOCAL uint32 = fuchsia.hardware.vsock.VMADDR_CID_LOCAL;
const VMADDR_CID_HOST uint32 = fuchsia.hardware.vsock.VMADDR_CID_HOST;

/// Collection of objects that represent an open connection.
type ConnectionTransport = resource struct {
    /// `data` socket that is ultimately given to the underlying vsock driver and
    /// is where all incoming data can be received from.
    data zx.Handle:SOCKET;
    /// `Connection` interface that is retained by a vsock service that can be
    /// used to manipulate the state of a connection or perform more complex
    /// operations than just sending and receiving on a socket.
    con server_end:Connection;
};

/// Interface for manipulating the state of an active connection.
closed protocol Connection {
    /// Trigger asynchronous shutdown. The underlying channel will be closed
    /// once shutdown is complete. Shutdown has an implicit barrier as any already
    /// queued sends will complete, but any additional sends will generate errors
    strict Shutdown();
};

/// Interface presented by a listener to accept or reject connections
closed protocol Acceptor {
    /// The response is either a `ConnectionTransport` to indicate that the connection
    /// is accepted, or none to indicate that it should be rejected.
    strict Accept(struct {
        addr fuchsia.hardware.vsock.Addr;
    }) -> (resource struct {
        con box<ConnectionTransport>;
    });
};

/// Interface presented by a listener to accept connections.
closed protocol Listener {
    /// Registers a listener for a local port. There can only be one listener for
    /// a single port at a time. The channel will have `SIGNAL_STREAM_INCOMING` asserted
    /// by the server when there is a connection ready to accept.
    strict Listen(struct {
        /// The maximum length to which the queue of pending connections waiting to
        /// be accepted.
        backlog uint32;
    }) -> () error zx.Status;
    /// Accept a pending connection from the queue after `Listen` was invoked and
    /// `SIGNAL_STREAM_INCOMING` was signaled.
    strict Accept(resource struct {
        con ConnectionTransport;
    }) -> (struct {
        addr fuchsia.hardware.vsock.Addr;
    }) error zx.Status;
};

/// Exposed by a service that can act as a bridge to the underlying vsock driver and
/// provides the ability for listeners to be multiplexed by port and manages dynamic
/// port allocation for outbound connections.
@discoverable
closed protocol Connector {
    /// Attempt to establish a connection to the specified remote cid/port pair.
    /// No local port is specified as an ephemeral one will automatically be allocated.
    strict Connect(resource struct {
        remote_cid uint32;
        remote_port uint32;
        con ConnectionTransport;
    }) -> (struct {
        local_port uint32;
    }) error zx.Status;
    /// Registers a listener for a local port. There can only be one listener for
    /// a single port at a time.
    strict Listen(resource struct {
        local_port uint32;
        acceptor client_end:Acceptor;
    }) -> () error zx.Status;
    /// Registers a listener for a local port. There can only be one listener for
    /// a single port at a time.
    strict Bind(resource struct {
        remote_cid uint32;
        local_port uint32;
        listener server_end:Listener;
    }) -> () error zx.Status;
    /// Query the current context id of the system. The local CID is should not
    /// necessary in interactions with the same device; instead you may pass
    /// `VMADDR_CID_LOCAL`, which will alias to local CID this returns. The cid returned
    /// by this method is useful for debugging or if you have some other communication
    /// channel to a different host and you would like to send them your CID to then
    /// establish a vsock connection on.
    strict GetCid() -> (struct {
        local_cid uint32;
    });
};