chromium/chromeos/ash/services/cros_healthd/public/mojom/cros_healthd_exception.mojom

// Copyright 2023 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

// Definitions for the exception API exposed by the cros_healthd daemon.

// NOTE: This mojom should be kept in sync with the copy in Chromium OS's repo
// in src/platform2/diagnostics/mojom/public/cros_healthd_exception.mojom.
module ash.cros_healthd.mojom;

// A generic exception type for all HealthD public API.
//
// When we raise Exception through a mojo disconnection, we will encode it to a
// mojo disconnection error. A mojo disconnection error contains an uint32 error
// code and a string message. The error code is set to |reason| and the message
// is set to |debug_message|.
//
// NextMinVersion: 1, NextIndex: 2
[Stable]
struct Exception {
  // A specific reason for clients to handle exceptions (e.g. showing a specific
  // message to UI). Use this instead of parsing |debug_message|.
  // Only add a new reason if there is a client handling that reason. Don’t add
  // reasons like kServiceUnavailable, but something like
  // kFailedToCallFooService, to make it specific.
  // When we raise Exception through a mojo disconnection, this will be the mojo
  // error code.
  //
  // NextMinVersion: 2, NextIndex: 5
  [Stable, Extensible]
  enum Reason {
    // This is required for backwards compatibility. Don't raise this.
    // Set to 1 because 0 is reserved for kMojoDisconnectWithoutReason.
    [Default] kUnmappedEnumField = 1,
    // This is for compatibility with a mojo built-in disconnection error.
    // Don't raise this. Its value must be "0".
    kMojoDisconnectWithoutReason = 0,
    // Any other exceptions that we don't expect to happen. Clients should
    // simply report the error. If there is no client to handle this exception,
    // use this as the reason.
    kUnexpected = 2,
    // Raises this if clients try to run an unsupported feature. Note that
    // clients should use methods which return `SupportStatus` for support
    // status check.
    kUnsupported = 3,
    // Raises this if a camera frontend needs to be opened but it is actually
    // not opened.
    [MinVersion=1] kCameraFrontendNotOpened = 4,
  };
  Reason reason@0;
  // A human readable message for debugging. If a client want to handle a
  // specific exception, use |reason|. Don't rely on the content because it
  // could change anytime.
  string debug_message@1;
};

// The result type of support status check of HealthD API.
//
// NextMinVersion: 1
[Stable, Extensible]
union SupportStatus {
  // This is required for backwards compatibility. Don't use this.
  [Default]
  int8 unmapped_union_field;
  // This is set if any exception happens before we can determine whether the
  // feature is supported. Note that exception with reason `kUnsupported` is
  // never set here.
  Exception exception;
  // The feature is supported.
  Supported supported;
  // The feature is not supported.
  Unsupported unsupported;
};

// Empty struct for future extensibility.
//
// NextMinVersion: 1, NextIndex: 0
[Stable]
struct Supported {};

// Details about the unsupported reason.
//
// NextMinVersion: 1, NextIndex: 2
[Stable]
struct Unsupported {
  // A human readable message for debugging. If a client want to handle a
  // specific exception, use |reason|. Don't rely on the content because it
  // could change anytime.
  string debug_message@0;
  // A union for the detailed reason.
  UnsupportedReason? reason@1;
};

// Empty union for future extensibility. This can be used to pass the details
// about which config is missing or which policy is disabled. E.g. Add a field
// `PolicyEnum disabled_by_this_policy;`.
//
// NextMinVersion: 1
[Stable, Extensible]
union UnsupportedReason {
  // This is required for backwards compatibility. Don't use this.
  [Default]
  int8 unmapped_union_field;
};