cros: DBUS client to interact with fingerprint DBUS API.

chromeos/dbus/biod/biod_biometrics_manager_client.h

+// Copyright 2017 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+#ifndef CHROMEOS_DBUS_BIOD_BIOD_BIOMETRICS_MANAGER_CLIENT_H_
+#define CHROMEOS_DBUS_BIOD_BIOD_BIOMETRICS_MANAGER_CLIENT_H_
+
+#include <stdint.h>
+
+#include <unordered_map>
+#include <vector>
+
+#include "base/callback.h"
+#include "base/macros.h"
+#include "base/observer_list.h"
+#include "chromeos/chromeos_export.h"
+#include "chromeos/dbus/dbus_client.h"
+#include "chromeos/dbus/dbus_client_implementation_type.h"
+#include "chromeos/dbus/dbus_method_call_status.h"
+#include "third_party/cros_system_api/dbus/service_constants.h"
+
+namespace chromeos {
+
+// Each time the sensor detects a scan, an object containing all the users, each
+// with the labels of all the matched stored fingerprints is returned.
+using AuthScanMatches =
+    std::unordered_map<std::string, std::vector<std::string>>;
+
+// BiodBiometricsManagerClient is used to communicate with the biod D-Bus
+// interface.

[Daniel Erat, 2017/03/28 00:14:34]

biod exposes (or will expose) multiple biometrics managers, each is which has
its own d-bus object, right? this class appears to correspond to a single
manager, based on its RequestType() method. is there going to be another class
that communicates with a central biod d-bus object to get individual managers?

[sammiequon, 2017/03/28 01:31:05]

Yeah, I realized that after completing this CL and the following ones. I'll have
to add that later once I figure out how it is going to work.

[Daniel Erat, 2017/03/28 01:44:30]

i'm a bit hesitant for this to go in before you know how you'll be able to
instantiate it. :-) can you figure out that part of the design before proceeding
with this?

[sammiequon, 2017/03/28 03:17:54]

I looked at the biod code and if I read it correctly there is not a way to
choose a biometrics manager. It currently runs two managers, "fakefinger",
"fpcfinger". So I guess it would be either connect to the "fpcfinger" all the
time (ie. either side will change the interface") or there will be a biod
manager manager where I can query a list of biometrics manager in which I would
have to add a biod manager manager client. I don't think either will be
non-trivial.

[Daniel Erat, 2017/03/29 22:11:57]

this is why i suggested not having biod create multiple d-bus objects. :-(

i think that the right way to model the current interface would be by
introducing a BiodClient class that interfaces with
biod::kBiodServiceName/kBiodServicePath to enumerate BiometricsManager objects,
and then have it create and return BiodBiometricsManagerClient objects.

class BiodClient : public DBusClient {
  ...
  // you probably need something like WeakPtr here since these managers can
  // presumably disappear at any time. the calling code is going to need to
  // constantly check whether the pointer is still valid, too...
  std::vector<WeakPtr<BiodBiometricsManagerClient>> GetManagers();
  ...
 private:
  std::vector<std::unique_ptr<BiodBiometricsManagerClient>> managers_;
};

class BiodBiometricsManagerClient {
  ...
  biod::BiometricType type() const { return type_; }
  ...
 private:
  // if this can't change for a given manager, just initialize it when
  // you first see the manager instead of making the caller call RequestType
  biod::BiometricType type_;
  ...
};

BiodClient's Observer interface should contain BiodServiceRestarted, while
BiodBiometricsManagerClient's interface should contain
BiodEnrollScanDoneReceived and the rest of the methods.

+class CHROMEOS_EXPORT BiodBiometricsManagerClient : public DBusClient {
+ public:
+  // Interface for observing changes from the biometrics.

[Daniel Erat, 2017/03/28 00:14:35]

nit: "from the biometrics manager"

[sammiequon, 2017/03/28 01:31:05]

Done.

+  class Observer {
+   public:
+    // Called when biometrics manager powers up or is restarted.
+    virtual void BiodServiceRestarted() {}
+
+    // Called whenever a user attempts a scan. |scan_result| tells whether the
+    // scan was succesful. |is_complete| tells whether enrollment is complete
+    // and now over.
+    virtual void BiodEnrollScanDoneReceived(biod::ScanResult scan_result,
+                                            bool is_complete) {}

[Daniel Erat, 2017/03/28 00:14:35]

consider renaming |is_complete| to |enroll_session_complete| to make it clearer
what it's referring to (assuming that my understanding is correct)

[sammiequon, 2017/03/28 01:31:05]

Done.

+
+    // Called to indicate a bad scan of any kind, or a successful scan. If scan
+    // is successful, |matches| will equal all the enrollment IDs that match the
+    // scan, and the labels of the matched fingeprints.
+    virtual void BiodAuthScanDoneReceived(biod::ScanResult scan_result,
+                                          const AuthScanMatches& matches) {}
+
+    // Called during either session to indicate a failure. Any enrollment that
+    // was underway is thrown away and auth will no longer be happening.
+    virtual void BiodSessionFailedReceived() {}
+
+   protected:
+    virtual ~Observer() {}
+  };
+
+  ~BiodBiometricsManagerClient() override;
+
+  // Adds and removes the observer.
+  virtual void AddObserver(Observer* observer) = 0;
+  virtual void RemoveObserver(Observer* observer) = 0;
+
+  // Returns true if this object has the given observer.
+  virtual bool HasObserver(const Observer* observer) const = 0;
+
+  // UserRecordsCallback is used for the GetRecordsForUser method. It receives
+  // one argument which contains a list of the stored records object paths for
+  // a given user.
+  using UserRecordsCallback =
+      base::Callback<void(const std::vector<dbus::ObjectPath>&)>;
+
+  // BiometricTypeCallback is used for the GetType method. It receives
+  // one argument which states the type of biometric.
+  using BiometricTypeCallback = base::Callback<void(biod::BiometricType)>;
+
+  // Starts the biometric enroll session. |callback| is called with the object
+  // path of the current enroll session after the method succeeds.
+  virtual void StartEnrollSession(const std::string& user_id,
+                                  const std::string& label,
+                                  const ObjectPathCallback& callback) = 0;
+
+  // Gets all the records registered with this biometric. |callback| is called
+  // with all the object paths of the records after this method succeeds.
+  virtual void GetRecordsForUser(const std::string& user_id,
+                                 const UserRecordsCallback& callback) = 0;
+
+  // Irreversibly destroys all records registered with this biometric.
+  virtual void DestroyAllRecords() = 0;
+
+  // Starts the biometric auth session. |callback| is called with the object
+  // path of the auth session after the method succeeds.
+  virtual void StartAuthSession(const ObjectPathCallback& callback) = 0;
+
+  // Requests the type of biometric. |callback| is called with the biometric
+  // type after the method succeeds.
+  virtual void RequestType(const BiometricTypeCallback& callback) = 0;
+
+  // Creates the instance.
+  static BiodBiometricsManagerClient* Create(DBusClientImplementationType type);
+
+ protected:
+  friend class BiodBiometricsManagerClientTest;
+
+  // Create() should be used instead.
+  BiodBiometricsManagerClient();
+
+ private:
+  DISALLOW_COPY_AND_ASSIGN(BiodBiometricsManagerClient);
+};
+
+}  // namespace chromeos
+
+#endif  // CHROMEOS_DBUS_BIOD_BIOD_BIOMETRICS_MANAGER_CLIENT_H_