sdk/fidl/fuchsia.developer.bridge/daemon.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.bridge;
using fuchsia.developer.remotecontrol as rc;
using fuchsia.device;
using zx;

const MAX_SERVICE_NAME_SIZE uint8 = 255;

type DaemonError = strict enum {
    TARGET_CACHE_ERROR = 1;
    TARGET_STATE_ERROR = 2;
    RCS_CONNECTION_ERROR = 3;
    /// A generic timeout error.
    TIMEOUT = 4;

    /// When querying for a target, the cache was empty.
    TARGET_CACHE_EMPTY = 5;
    /// When querying for a target (specified or not), there were
    /// too many matches to be clear on which target was the intent
    /// of the query.
    TARGET_AMBIGUOUS = 6;
    /// When querying for a target, no matches were found.
    TARGET_NOT_FOUND = 7;
    /// When attempting to connect to RCS on a Fastboot device.
    TARGET_IN_FASTBOOT = 8;
    /// Fastboot device expected.
    NON_FASTBOOT_DEVICE = 9;
    /// When attempting to connect to a service that does not exist on the
    /// daemon.
    SERVICE_NOT_FOUND = 10;
    /// An error was encountered when attempting to open a service stream.
    SERVICE_OPEN_ERROR = 11;
    /// An error encountered when the daemon's service register is in a bad
    /// state internally. This is primarily caused by trying to open a service
    /// while the daaemon is actively shutting down, and should be extremely
    /// rare.
    BAD_SERVICE_REGISTER_STATE = 12;
    /// When attempting to connect to RCS on a Fastboot device.
    TARGET_IN_ZEDBOOT = 13;
};

@discoverable
protocol Daemon {
    /// Crashes the daemon. Primarily used for testing.
    Crash() -> ();

    /// Returns the input.
    EchoString(struct {
        value string:256;
    }) -> (struct {
        response string:256;
    });

    /// Hang the daemon. Primarily used for testing.
    Hang() -> ();

    /// Make the daemon exit.
    Quit() -> (struct {
        success bool;
    });

    // Retrieves version information about this daemon instance.
    GetVersionInfo() -> (struct {
        info VersionInfo;
    });

    // Retrieves a hash of the current binary.
    GetHash() -> (struct {
        response string:64;
    });

    /// Creates an iterator over diagnostics data. At present, this means cached log data.
    ///
    /// Note that there is some duplication in this API and the StreamDiagnostics API in RCS.
    /// This is because the surface for the daemon API needs to be slightly different:
    /// 1) It needs to accomodate specifying a target.
    /// 2) The error surface is accordingly slightly different.
    /// 3) The parameters surface is currently different (SNAPSHOT_RECENT_THEN_SUBSCRIBE has no meaning
    ///    in the diagnostics bridge) and have different evolution paths - for example, the daemon may
    ///    eventually support multi-target log streaming.
    ///
    /// If the target field is a nodename or log session identifier (e.g. "ffx_daemon"),
    /// then cached logs will be returned for that target even if the target is
    /// currently offline.
    StreamDiagnostics(resource struct {
        target string:<fuchsia.device.DEVICE_NAME_MAX, optional>;
        parameters DaemonDiagnosticsStreamParameters;
        iterator server_end:rc.ArchiveIterator;
    }) -> (struct {
        session LogSession;
    }) error DiagnosticsStreamError;

    /// Connects to a deamon service.
    ///
    /// Takes a service name under which the channel will be connected (the
    /// caller is intended to know the type of the channel a priori).
    ///
    /// Developers are not intended to use this directly. Instead this should
    /// be invoked automatically through the FFX plugin/service framework.
    ///
    /// Again for emphasis: if you are a developer and you are invoking this
    /// function directly, you should reconsider your actions.
    ConnectToService(resource struct {
        name string:MAX_SERVICE_NAME_SIZE;
        server_channel zx.handle:CHANNEL;
    }) -> (struct {}) error DaemonError;
};