sdk/fidl/fuchsia.cobalt/cobalt.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.
library fuchsia.cobalt;

/// Channels should not be longer than this.
///
/// # Deprecation
///
/// The SystemDataUpdater protocol is deprecated so this type is no longer needed.
@available(deprecated=18, note="SystemDataUpdater protocol is deprecated")
const MAX_CHANNEL_NAME_LENGTH uint32 = 256;

/// Response codes for Logger operations.
///
/// # Deprecation
///
/// The SystemDataUpdater protocol is deprecated so this type is no longer needed.
@available(deprecated=18, note="SystemDataUpdater protocol is deprecated")
type Status = strict enum : int32 {
    OK = 0;

    /// For example the supplied metric id is invalid.
    INVALID_ARGUMENTS = 1;

    /// An attempt was made to log an Event whose serialized size exceeds
    /// MAX_BYTES_PER_EVENT.
    EVENT_TOO_BIG = 2;

    /// Cobalt's local buffer is temporarily full and cannot handle any more
    /// Events at this time. Try again later. This condition should be rare
    BUFFER_FULL = 3;

    // Cobalt has received a ShutDown signal and will not accept any more
    // events.
    SHUT_DOWN = 4;

    /// Catch-all for unexpected errors.
    INTERNAL_ERROR = -1;
};

/////////////////////////////////////////////////////////////////////
// SystemProfileUpdater Interface
/////////////////////////////////////////////////////////////////////

/// A collection of fields describing a system's software distribution.
///
/// # Deprecation
///
/// The SystemDataUpdater protocol is deprecated so this type is no longer needed.
@available(deprecated=18, note="SystemDataUpdater protocol is deprecated")
type SoftwareDistributionInfo = table {
    /// The channel that the device last used as an update source. This value
    /// may be empty to indicate that the device is not currently associated
    /// with any channel.
    1: current_channel string:MAX_CHANNEL_NAME_LENGTH;
};

/// The SystemDataUpdater interface allows callers to update the state of
/// the SystemProfile in Cobalt. The changes are global and affect all loggers
/// running on the device.
///
/// # Deprecation
///
/// This protocol does not have any special properties compared to fuchsia.update.channel/Provider
/// other than requiring another component to push the current channel to Cobalt, rather than
/// having Cobalt pull the value. This protocol is deprecated and Cobalt is now retrieving the
/// channel via the standard fuchsia.update.channel/Provider::GetCurrent method.
@discoverable
@available(deprecated=18, note="channel retrieved through fuchsia.update.channel/Provider")
closed protocol SystemDataUpdater {
    /// Sets Cobalt's view of the system-wide distribution information replacing the
    /// existing values.
    ///
    /// `info` The specifications of the current system's software distribution.
    strict SetSoftwareDistributionInfo(struct {
        info SoftwareDistributionInfo;
    }) -> (struct {
        status Status;
    });
};

/////////////////////////////////////////////////////////////////////
// AggregateAndUpload Interface
/////////////////////////////////////////////////////////////////////

/// Locally aggregates all collected metrics and uploads generated
/// observations immediately. This is only to be used for Recovery, and
/// should only be called once per Recovery attempt.
///
/// If AggregateAndUpload completes, then the collected metrics were uploaded
/// to Cobalt successfully. Otherwise, AggregateAndUpload may continue to run
/// until the calling service cancels the process when long running operation
/// exceeds the specified timeout. The reason this may occur, is that
/// AggregateAndUpload has a retry policy, and will retry any failures until
/// the operation succeeds or is cancelled due to exceeding a specified
/// timeout.
@discoverable
closed protocol AggregateAndUpload {
    strict AggregateAndUploadMetricEvents() -> ();
};