// Copyright (c) 2012 The Chromium OS Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

syntax = "proto2";

option optimize_for = LITE_RUNTIME;

package power_manager;

// Included in powerd's SuspendImminent signal, sent when the system is about to
// suspend.  If any clients previously called RegisterSuspendDelay, suspending
// will be deferred until they've called powerd's HandleSuspendReadiness method.
//
// The general flow is as follows:
//
// 1. A client that needs to perform some work before the system can be
//    suspended listens for SuspendImminent and SuspendDone signals from powerd.
// 2. The client passes a RegisterSuspendDelayRequest to powerd's
//    RegisterSuspendDelay method and receives a RegisterSuspendDelayReply in
//    response.  The client saves the |delay_id| field from the response.
// 3. When the power manager is about to suspend the system, it emits a
//    SuspendImminent signal containing this message.
// 4. Upon receipt of the signal, the client performs any last minute work
//    that it needs to do and then calls powerd's HandleSuspendReadiness method,
//    including its |delay_id| and the |suspend_id| field from the signal.
// 5. Once powerd has received notification that all registered clients are
//    ready to suspend, the system will be suspended.
// 6. After the system resumes (or the suspend attempt fails or is canceled),
//    powerd emits a SuspendDone signal. The client may undo any pre-suspend
//    work that was done in response to the SuspendImminent signal.
// 7. Before the client exits, it calls UnregisterSuspendDelayRequest with its
//    delay ID.
message SuspendImminent {
  // Next ID to use: 2

  // Unique ID corresponding to this suspend attempt.  This is included in the
  // SuspendReadinessInfo message passed via HandleSuspendReadiness.
  optional int32 suspend_id = 1;
}

// Included in powerd's SuspendDone signal, sent after the system has completed
// a suspend attempt (either by suspending and resuming or by failing to
// suspend). Each SuspendImminent signal will be followed by a SuspendDone
// signal.
message SuspendDone {
  // Next ID to use: 3

  // Unique ID corresponding to the suspend attempt.
  optional int32 suspend_id = 1;

  // Wall time that the system was suspended, as given by
  // base::TimeDelta::ToInternalValue().
  optional int64 suspend_duration = 2;
}

// Included in calls to powerd's RegisterSuspendDelay method.
message RegisterSuspendDelayRequest {
  // Next ID to use: 3

  // Upper bound on the amount of time that the power manager will wait for this
  // client to call HandleSuspendReadiness before suspending the system, as
  // given by base::TimeDelta::ToInternalValue().
  optional int64 timeout = 1;

  // Human-readable description of the delay's purpose (e.g. the name of
  // the daemon that requested the delay).  Only used for debugging.
  optional string description = 2;
}

// Included in responses to powerd's RegisterSuspendDelay method.
message RegisterSuspendDelayReply {
  // Next ID to use: 2

  // Unique ID assigned to the client that registered this suspend delay.  This
  // is included in later HandleSuspendReadiness and UnregisterSuspendDelay
  // calls.
  optional int32 delay_id = 1;
}

// Included in calls to powerd's UnregisterSuspendDelay method.
message UnregisterSuspendDelayRequest {
  // Next ID to use: 2

  // ID that was returned in response to the original RegisterSuspendDelay call.
  optional int32 delay_id = 1;
}

// Included in calls to powerd's HandleSuspendReadiness method.
message SuspendReadinessInfo {
  // Next ID to use: 3

  // ID that was returned to the client in response to its invocation of
  // RegisterSuspendDelay.
  optional int32 delay_id = 1;

  // ID that was included in the SuspendImminent signal that provoked this
  // readiness call.
  optional int32 suspend_id = 2;
}