sdk/fidl/fuchsia.developer.remotecontrol/remote-control.fidl

// 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.developer.remotecontrol;

using fuchsia.component as component;
using fuchsia.diagnostics as diagnostics;
using fuchsia.io as io;
using fuchsia.kernel as kernel;
using fuchsia.net as net;
using fuchsia.sys2 as sys2;
using zx;

const MAX_NUM_MATCHES uint16 = 250;
const MAX_CONNECT_MATCHES uint16 = 5;

type TunnelError = strict enum {
    // Couldn't connect to the address to forward.
    CONNECT_FAILED = 1;
    // Something was wrong with the socket which was being tunneled to.
    SOCKET_FAILED = 2;
    // Something was wrong with the ForwardCallback which was passed.
    CALLBACK_ERROR = 3;
};

@discoverable
open protocol RemoteControl {
    /// Returns the input.
    strict EchoString(struct {
        value string:255;
    }) -> (struct {
        response string:255;
    });

    /// Writes a string to the syslog on the device.
    strict LogMessage(struct {
        tag string:MAX;
        message string:MAX;
        severity diagnostics.Severity;
    }) -> ();

    /// Connects to the root [`fuchsia.sys2/RealmExplorer`] protocol.
    flexible RootRealmExplorer(resource struct {
        server server_end:sys2.RealmExplorer;
    }) -> () error zx.Status;

    /// Connects to the root [`fuchsia.sys2/RealmQuery`] protocol.
    @deprecated(
            "Please use `OpenCapability` to connect to `fuchsia.sys2.RealmQuery.root` in the namespace of `core/remote-control`")
    strict RootRealmQuery(resource struct {
        server server_end:sys2.RealmQuery;
    }) -> () error zx.Status;

    /// Connects to the root [`fuchsia.sys2/LifecycleController`] protocol.
    @deprecated(
            "Please use `OpenCapability` to connect to `fuchsia.sys2.LifecycleController.root` in the namespace of `core/remote-control`")
    flexible RootLifecycleController(resource struct {
        server server_end:sys2.LifecycleController;
    }) -> () error zx.Status;

    /// Connects to the root [`fuchsia.sys2/RouteValidator`] protocol.
    @deprecated(
            "Please use `OpenCapability` to connect to `fuchsia.sys2.RouteValidator.root` in the namespace of `core/remote-control`")
    flexible RootRouteValidator(resource struct {
        server server_end:sys2.RouteValidator;
    }) -> () error zx.Status;

    // Connects to the [`fuchsia.kernel/Stats`] protocol
    flexible KernelStats(resource struct {
        server server_end:kernel.Stats;
    }) -> () error zx.Status;

    flexible IdentifyHost() -> (struct {
        response IdentifyHostResponse;
    }) error IdentifyHostError;

    // Connects a channel to a service, given a moniker and a channel iff the
    // component identified by the given moniker exposes a capability of the
    // requested name.
    @deprecated("Please use `OpenCapability` with `OpenDirType::Exposed`")
    flexible ConnectCapability(resource struct {
        moniker string:component.MAX_MONIKER_LENGTH;
        capability_name component.name;
        server_chan zx.Handle:CHANNEL;
        flags io.OpenFlags;
    }) -> () error ConnectCapabilityError;

    // Connects a channel to a service, given a moniker and a channel iff the
    // component identified by the given moniker exposes a capability of the
    // requested name.
    flexible OpenCapability(resource struct {
        moniker string:component.MAX_MONIKER_LENGTH;
        capability_set sys2.OpenDirType;
        capability_name component.name;
        server_channel zx.Handle:CHANNEL;
        flags io.OpenFlags;
    }) -> () error ConnectCapabilityError;

    // Establishes a TCP connection to the given address and forwards traffic through the given
    // socket.
    flexible ForwardTcp(resource struct {
        addr net.SocketAddress;
        socket zx.Handle:SOCKET;
    }) -> () error TunnelError;

    // Listens on a TCP port and forwards any incoming connections to newly-created sockets which
    // are passed back via the callback.
    flexible ReverseTcp(resource struct {
        addr net.SocketAddress;
        client client_end:ForwardCallback;
    }) -> () error TunnelError;

    // Gets the current monotonic time in nanoseconds.
    strict GetTime() -> (struct {
        time int64;
    });
};

closed protocol ForwardCallback {
    strict Forward(resource struct {
        socket zx.Handle:SOCKET;
        addr net.SocketAddress;
    });
};