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.
@available(added=16)
library fuchsia.developer.remotecontrol;

using fuchsia.component as component;
using fuchsia.diagnostics.types as diagnostics_types;
using fuchsia.diagnostics as diagnostics;

// TODO(https://fxbug.dev/324081103): Remove the dependency on fuchsia.io when the OpenCapability
// method is removed from the RemoteControl protocol.
using fuchsia.io as io;
using fuchsia.sys2 as sys2;
using zx;

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

type TunnelError = flexible 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;
};

// Strict methods in this protocol are due to them predating the introduction of
// API levels and being hard to migrate.
@discoverable(server="platform")
open protocol RemoteControl {
    /// Returns the input.
    strict EchoString(struct {
        value string:255;
    }) -> (struct {
        response string:255;
    });

    @available(replaced=27)
    strict LogMessage(struct {
        tag string:MAX;
        message string:MAX;
        severity diagnostics.Severity;
    }) -> ();

    /// Writes a string to the syslog on the device.
    @available(added=27)
    strict LogMessage(struct {
        tag string:MAX;
        message string:MAX;
        severity diagnostics_types.Severity;
    }) -> ();

    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.
    @available(added=25)
    flexible ConnectCapability(resource struct {
        moniker string:component.MAX_MONIKER_LENGTH;
        capability_set sys2.OpenDirType;
        capability_name component.name;
        server_channel zx.Handle:CHANNEL;
    }) -> () error ConnectCapabilityError;

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

    // Gets the current boot time in nanoseconds.
    @available(added=26)
    strict GetBootTime() -> (struct {
        time zx.InstantBoot;
    });

    /// [DEPRECATED - Use ConnectCapability instead.]
    ///
    /// 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.
    @available(
            deprecated=25,
            replaced=26,
            renamed="DeprecatedOpenCapability",
            note="Use ConnectCapability instead.")
    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;

    /// [DEPRECATED - Use ConnectCapability instead.]
    ///
    /// 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.
    //
    // TODO(https://fxbug.dev/384994764): In an ideal world, we'd be able to say
    // `removed=26, renamed="DeprecatedOpenCapability"` on `OpenCapability` to
    // get this for free, but unfortunately that doesn't work.
    //
    // TODO(https://fxbug.dev/324081103): Once all in-tree calls to
    // `DeprecatedOpenCapability` have been removed, delete this method and
    // change the annotation on `OpenCapability` to:
    //
    //     @available(
    //         deprecated=25,
    //         removed=26,
    //         note="Use ConnectCapability instead.")
    @available(added=26)
    @selector("OpenCapability")
    flexible DeprecatedOpenCapability(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;
};