chromeos: Add dbus MTPDClient.

chromeos/dbus/mtpd_client.h

+// Copyright (c) 2012 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.

[satorux1, 2012/08/03 05:26:07]

Could you write some brief description about MTPD, and what this D-Bus client is
used for?

[Lei Zhang, 2012/08/03 06:29:30]

Done.

+
+#ifndef CHROMEOS_DBUS_MTPD_CLIENT_H_
+#define CHROMEOS_DBUS_MTPD_CLIENT_H_
+
+#include <string>
+#include <vector>
+
+#include "base/basictypes.h"
+#include "base/callback.h"
+#include "base/time.h"
+#include "chromeos/chromeos_export.h"
+#include "chromeos/dbus/dbus_client_implementation_type.h"
+
+namespace dbus {
+class Bus;
+class Response;
+}
+
+namespace chromeos {
+
+// Mode to open a storage in.
+enum OpenStorageMode {
+  OPEN_STORAGE_MODE_READ_ONLY,
+};
+
+// Values match libmtp values unless noted below.
+// TODO(thestig) See if we can do better than this.
+enum FileType {
+  FILE_TYPE_FOLDER = 0,
+  FILE_TYPE_JPEG = 14,
+  FILE_TYPE_JFIF = 15,
+  FILE_TYPE_TIFF = 16,
+  FILE_TYPE_BMP = 17,
+  FILE_TYPE_GIF = 18,
+  FILE_TYPE_PICT = 19,
+  FILE_TYPE_PNG = 20,
+  FILE_TYPE_WINDOWSIMAGEFORMAT = 25,
+  FILE_TYPE_JP2 = 40,
+  FILE_TYPE_JPX = 41,
+  // Truly unknown file type.
+  FILE_TYPE_UNKNOWN = 44,
+  // There's more file types to map to, but right now they are not interesting.
+  // Just assign a dummy value for now.
+  FILE_TYPE_OTHER = 9999
+};
+
+// A class to represent information about a storage sent from mtpd.
+class StorageInfo {
+ public:
+  StorageInfo(const std::string& storage_name, dbus::Response* response);
+  ~StorageInfo();
+
+  // Storage name. (e.g. usb:1,5:65537)
+  std::string storage_name() const { return storage_name_; }

[satorux1, 2012/08/03 05:26:07]

const std::string&

ditto for elsewhere.

[Lei Zhang, 2012/08/03 06:29:30]

Done.

+
+  // Vendor. (e.g. Kodak)
+  std::string vendor() const { return vendor_; }
+
+  // Vendor ID. (e.g. 0x040a)
+  uint16 vendor_id() const { return vendor_id_; }
+
+  // Product. (e.g. DC4800)
+  std::string product() const { return product_; }
+
+  // Vendor ID. (e.g. 0x0160)
+  uint16 product_id() const { return product_id_; }
+
+  // Device flags as defined by libmtp.
+  uint32 device_flags() const { return device_flags_; }
+
+  // Storage type as defined in libmtp. (e.g. PTP_ST_FixedROM)
+  uint16 storage_type() const { return storage_type_; }
+
+  // File system type as defined in libmtp. (e.g. PTP_FST_DCF)
+  uint16 filesystem_type() const { return filesystem_type_; }
+
+  // Access capability as defined in libmtp. (e.g. PTP_AC_ReadWrite)
+  uint16 access_capability() const { return access_capability_; }
+
+  // Max capacity in bytes.
+  uint64 max_capacity() const { return max_capacity_; }
+
+  // Free space in byte.
+  uint64 free_space_in_bytes() const { return free_space_in_bytes_; }
+
+  // Free space in number of objects.
+  uint64 free_space_in_objects() const { return free_space_in_objects_; }
+
+  // Storage description. (e.g. internal memory)
+  std::string storage_description() const { return storage_description_; }
+
+  // Volume identifier. (e.g. the serial number, should be unique)
+  std::string volume_identifier() const { return volume_identifier_; }
+
+ private:
+  void InitializeFromResponse(dbus::Response* response);
+
+  // Device info. (A device can have multiple storages)
+  std::string vendor_;
+  uint16 vendor_id_;
+  std::string product_;
+  uint16 product_id_;
+  uint32 device_flags_;
+
+  // Storage info.
+  std::string storage_name_;
+  uint16 storage_type_;
+  uint16 filesystem_type_;
+  uint16 access_capability_;
+  uint64 max_capacity_;
+  uint64 free_space_in_bytes_;
+  uint64 free_space_in_objects_;
+  std::string storage_description_;
+  std::string volume_identifier_;
+};
+
+// A class to represent information about a file entry sent from mtpd.
+class FileEntry {
+ public:
+  explicit FileEntry(dbus::Response* response);
+  ~FileEntry();
+
+  // ID for the file.
+  uint32 item_id() const { return item_id_; }
+
+  // ID for the file's parent.
+  uint32 parent_id() const { return parent_id_; }
+
+  // Name of the file.
+  std::string filename() const { return filename_; }

[satorux1, 2012/08/03 05:26:07]

file_name() to be consistent with file_type()?

[Lei Zhang, 2012/08/03 06:29:30]

Done.

+
+  // Size of the file.
+  uint64 filesize() const { return filesize_; }

[satorux1, 2012/08/03 05:26:07]

file_size()?

[Lei Zhang, 2012/08/03 06:29:30]

Done.

+
+  // Modification time of the file.
+  base::Time modification_date() const { return modification_date_; }
+
+  // File type.
+  FileType file_type() const { return file_type_; }
+
+ private:
+  void InitializeFromResponse(dbus::Response* response);
+
+  // Storage info.
+  uint32 item_id_;
+  uint32 parent_id_;
+  std::string filename_;
+  uint64 filesize_;
+  base::Time modification_date_;
+  FileType file_type_;
+};
+
+// A class to make the actual DBus calls for mtpd service.
+// This class only makes calls, result/error handling should be done
+// by callbacks.
+class CHROMEOS_EXPORT MTPDClient {
+ public:
+  // A callback to be called when DBus method call fails.
+  typedef base::Callback<void()> ErrorCallback;
+
+  // A callback to handle the result of EnumerateAutoMountableDevices.
+  // The argument is the enumerated device paths.
+  typedef base::Callback<void(const std::vector<std::string>&)

[satorux1, 2012/08/03 05:26:07]

please add parameter name

typedef base::Callback<void(const std::vector<std::string>& device_paths)

as well as other places

[Lei Zhang, 2012/08/03 06:29:30]

Done.

+                         > EnumerateStorageCallback;
+
+  // A callback to handle the result of GetStorageInfo.
+  // The argument is the information about the specified storage.
+  typedef base::Callback<void(const StorageInfo&)> GetStorageInfoCallback;
+
+  // A callback to handle the result of OpenStorage.
+  // The argument is the returned handle.
+  typedef base::Callback<void(const std::string&)> OpenStorageCallback;
+
+  // A callback to handle the result of CloseStorage.
+  typedef base::Callback<void()> CloseStorageCallback;
+
+  // A callback to handle the result of ReadDirectoryByPath/Id.
+  // The argument is a vector of file entries.
+  typedef base::Callback<void(const std::vector<FileEntry>&)
+                         > ReadDirectoryCallback;
+
+  // A callback to handle the result of ReadFileByPath/Id.
+  // The argument is a string containing the file data.
+  typedef base::Callback<void(const std::string&)> ReadFileCallback;

[satorux1, 2012/08/03 05:37:10]

btw, this may be bad for large files, like a 2GB movie file. You might want to
pass a file descriptor instead.

[satorux1, 2012/08/03 05:41:57]

Oh you could just add a TODO here. :)

[Lei Zhang, 2012/08/03 06:29:30]

Yes, we have definitely considered this, but since we are limiting ourselves to
just photos for now, this is probably ok. I added a TODO.

+
+  // A callback to handle storage attach/detach events.
+  // The first argument is true for attach, false for detach.
+  // The second argument is the storage name.
+  typedef base::Callback<void(bool, const std::string&)> MTPStorageEventHandler;
+
+  virtual ~MTPDClient();
+
+  // Calls EnumerateStorage method. |callback| is called after the
+  // method call succeeds, otherwise, |error_callback| is called.
+  virtual void EnumerateStorage(
+      const EnumerateStorageCallback& callback,
+      const ErrorCallback& error_callback) = 0;
+
+  // Calls GetStorageInfo method. |callback| is called after the method call
+  // succeeds, otherwise, |error_callback| is called.
+  virtual void GetStorageInfo(const std::string& storage_name,
+                              const GetStorageInfoCallback& callback,
+                              const ErrorCallback& error_callback) = 0;
+
+  // Calls OpenStorage method. |callback| is called after the method call
+  // succeeds, otherwise, |error_callback| is called.
+  virtual void OpenStorage(const std::string& storage_name,
+                           OpenStorageMode mode,
+                           const OpenStorageCallback& callback,
+                           const ErrorCallback& error_callback) = 0;
+
+  // Calls CloseStorage method. |callback| is called after the method call
+  // succeeds, otherwise, |error_callback| is called.
+  virtual void CloseStorage(const std::string& handle,

[satorux1, 2012/08/03 05:26:07]

what is |handle|? Could you document?

[Lei Zhang, 2012/08/03 06:29:30]

Done.

+                            const CloseStorageCallback& callback,
+                            const ErrorCallback& error_callback) = 0;
+
+  // Calls ReadDirectoryByPath method. |callback| is called after the method
+  // call succeeds, otherwise, |error_callback| is called.
+  virtual void ReadDirectoryByPath(const std::string& handle,
+                                   const std::string& path,
+                                   const ReadDirectoryCallback& callback,
+                                   const ErrorCallback& error_callback) = 0;
+
+  // Calls ReadDirectoryById method. |callback| is called after the method
+  // call succeeds, otherwise, |error_callback| is called.

[satorux1, 2012/08/03 05:26:07]

what's |file_id|? I'm guessing this is FileEntry::item_id. Please document about
the parameter.

[Lei Zhang, 2012/08/03 06:29:30]

Added documentation, it's a MTP-ism.

+  virtual void ReadDirectoryById(const std::string& handle,
+                                 uint32 file_id,
+                                 const ReadDirectoryCallback& callback,
+                                 const ErrorCallback& error_callback) = 0;
+
+  // Calls ReadFileByPath method. |callback| is called after the method call
+  // succeeds, otherwise, |error_callback| is called.
+  virtual void ReadFileByPath(const std::string& handle,
+                              const std::string& path,
+                              const ReadFileCallback& callback,
+                              const ErrorCallback& error_callback) = 0;
+
+  // Calls ReadFileById method. |callback| is called after the method call
+  // succeeds, otherwise, |error_callback| is called.
+  virtual void ReadFileById(const std::string& handle,
+                            uint32 file_id,
+                            const ReadFileCallback& callback,
+                            const ErrorCallback& error_callback) = 0;
+
+  // Registers given callback for events.
+  // |storage_event_handler| is called when a mtp storage attach or detach
+  // signal is received.
+  virtual void SetUpConnections(const MTPStorageEventHandler& handler) = 0;
+
+  // Factory function, creates a new instance and returns ownership.
+  // For normal usage, access the singleton via DBusThreadManager::Get().
+  static MTPDClient* Create(DBusClientImplementationType type, dbus::Bus* bus);
+
+ protected:
+  // Create() should be used instead.
+  MTPDClient();
+
+ private:
+  DISALLOW_COPY_AND_ASSIGN(MTPDClient);
+};
+
+}  // namespace chromeos
+
+#endif  // CHROMEOS_DBUS_MTPD_CLIENT_H_