// Copyright 2024 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.session.power;

using zx;

/// Lets the session manager handoff a power lease to a session component.
///
/// As an example, `session_manager` may take a lease on the
/// `ApplicationActivity` power element, and offer [`Handoff`] to the
/// session component. The session component can then take the lease from
/// `session_manager` when it is started. This way a constant dependency
/// is maintained on `ApplicationActivity` as the session is restarted.
@available(added=HEAD)
@discoverable
open protocol Handoff {
    /// Take the lease.
    flexible Take() -> (resource struct {
        /// A lease on the power element.
        ///
        /// This is secretly a `fuchsia.power.broker.LeaseControl` channel
        /// but we'd like to avoid exposing that to `ffx`. When that protocol
        /// is stabilized, we can replace the channel with that here.
        ///
        /// TODO(https://fxbug.dev/339474151): This may also become an
        /// eventpair as the linked bug tracks migrating lease control channel
        /// to eventpair.
        lease zx.Handle;
    }) error HandoffError;
};

/// Error when taking the power lease.
@available(added=HEAD)
type HandoffError = flexible enum {
    /// The lease is already taken.
    ALREADY_TAKEN = 1;

    /// The lease is not available due to errors or configuration.
    UNAVAILABLE = 2;
};