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

module device.mojom;

// Note: this needs to stay in sync with
// src/platform2/system_api/dbus/biod/constants.proto in the ChromeOS repo.
// Please modify tools/metrics/histograms/enums.xml when changing this.
// These values are persisted to logs. Entries should not be renumbered and
// numeric values should never be reused (See FingerprintScanResult metrics
// enum).
enum ScanResult {
  SUCCESS = 0,
  PARTIAL = 1,
  INSUFFICIENT = 2,
  SENSOR_DIRTY = 3,
  TOO_SLOW = 4,
  TOO_FAST = 5,
  IMMOBILE = 6,
  NO_MATCH = 7,
};

// Note: this needs to stay in sync with
// src/platform2/system_api/dbus/biod/constants.proto in the ChromeOS repo.
// Protobuf enum starts with 1 (0 is not used for compatibility with android),
// but in this enum we add 'catch all' field at 0. It is required by enum
// histogram guidelines.
// Please modify tools/metrics/histograms/enums.xml when changing this.
// These values are persisted to logs. Entries should not be renumbered and
// numeric values should never be reused.
enum FingerprintError {
  UNKNOWN = 0,
  HW_UNAVAILABLE = 1,
  UNABLE_TO_PROCESS = 2,
  TIMEOUT = 3,
  NO_SPACE = 4,
  CANCELED = 5,
  UNABLE_TO_REMOVE = 6,
  LOCKOUT = 7,
  NO_TEMPLATES = 8,
};

// Note: this needs to stay in sync with
// src/platform2/system_api/dbus/biod/dbus-constants.proto in the ChromeOS
// repro.
enum BiometricType {
  UNKNOWN = 0,
  FINGERPRINT = 1,
};

// Note: this needs to stay in sync with
// src/platform2/system_api/dbus/biod/messages.proto in the ChromeOS repo.
union FingerprintMessage {
  FingerprintError fingerprint_error;
  ScanResult scan_result;
};

// Note: this needs to stay in sync with
// src/platform2/system_api/dbus/biod/constants.proto in the ChromeOS repo.
enum BiometricsManagerStatus {
  UNKNOWN = 0,
  INITIALIZED = 1,
};

// This interface is ChromeOS-specific. If it is ever desired to support a more
// general fingerprint service across more platforms, the interface would need
// to be generalized. Interface for observing fingerprint daemon signals.
interface FingerprintObserver {
  // Called when biometrics device powers up or is restarted.
  OnRestarted();

  // Called when BiometricsManager Status changed.
  // e.g Primary profile initialized.
  OnStatusChanged(BiometricsManagerStatus status);

  // Called whenever a user attempts a scan. |scan_result| tells whether the
  // scan was successful. |is_complete| tells whether record is complete and now
  // over.
  //
  // |percent_complete| within [0, 100] represents the percent of enrollment
  // completion and -1 means unknown percentage.
  OnEnrollScanDone(ScanResult scan_result,
                   bool is_complete,
                   int32 percent_complete);

  // Called to indicate a bad scan of any kind, or a successful scan. If scan is
  // successful, |matches| is a map of user id keys to a vector of object path
  // values.
  OnAuthScanDone(FingerprintMessage msg, map<string, array<string>> matches);

  // Called during either mode to indicate a failure. Any EnrollSession record
  // that was underway is thrown away and AuthSession will no longer be
  // happening.
  OnSessionFailed();
};

// Interface for communicating with fingerprint deamon through dbus.
interface Fingerprint {
  // Gets all the records of this user registered with this biometric manager.
  // |records| is a map of record path keys to record label values.
  GetRecordsForUser(string user_id) => (map<string, string> records, bool success);

  // Starts the biometric enroll session.
  StartEnrollSession(string user_id, string label);

  // Ends the current enroll session.
  CancelCurrentEnrollSession() => (bool success);

  // Requests the label of the record at |record_path|.
  RequestRecordLabel(string record_path) => (string label);

  // Changes the label of the record at |record_path| to |new_label|.
  SetRecordLabel(string record_path, string new_label) => (bool success);

  // Removes the record. This record will no longer
  // be able to used for authentication.
  RemoveRecord(string record_path) => (bool success);

  // Starts the biometric authentication session.
  StartAuthSession();

  // Ends the current authentication session.
  EndCurrentAuthSession() => (bool success);

  // Irreversibly destroys all records registered with this biometric manager.
  DestroyAllRecords() => (bool success);

  // Adds fingerprint observers and notifies them when receiving signals.
  AddFingerprintObserver(pending_remote<FingerprintObserver> observer);

  // Requests the type of biometric.
  RequestType() => (BiometricType type);
};