device/media_transfer_protocol/media_transfer_protocol_daemon_client.h

   1 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 // Client code to talk to the Media Transfer Protocol daemon. The MTP daemon is
   6 // responsible for communicating with PTP / MTP capable devices like cameras
   7 // and smartphones.
   8
   9 #ifndef DEVICE_MEDIA_TRANSFER_PROTOCOL_MEDIA_TRANSFER_PROTOCOL_DAEMON_CLIENT_H_
  10 #define DEVICE_MEDIA_TRANSFER_PROTOCOL_MEDIA_TRANSFER_PROTOCOL_DAEMON_CLIENT_H_
  11
  12 #include <string>
  13 #include <vector>
  14
  15 #include "base/basictypes.h"
  16 #include "base/callback.h"
  17 #include "build/build_config.h"
  18
  19 #if !defined(OS_LINUX)
  20 #error "Only used on Linux and ChromeOS"
  21 #endif
  22
  23 class MtpFileEntry;
  24 class MtpStorageInfo;
  25
  26 namespace dbus {
  27 class Bus;
  28 }
  29
  30 namespace device {
  31
  32 // A class to make the actual DBus calls for mtpd service.
  33 // This class only makes calls, result/error handling should be done
  34 // by callbacks.
  35 class MediaTransferProtocolDaemonClient {
  36  public:
  37   // A callback to be called when DBus method call fails.
  38   typedef base::Closure ErrorCallback;
  39
  40   // A callback to handle the result of EnumerateAutoMountableDevices.
  41   // The argument is the enumerated storage names.
  42   typedef base::Callback<void(const std::vector<std::string>& storage_names)
  43                          > EnumerateStoragesCallback;
  44
  45   // A callback to handle the result of GetStorageInfo.
  46   // The argument is the information about the specified storage.
  47   typedef base::Callback<void(const MtpStorageInfo& storage_info)
  48                          > GetStorageInfoCallback;
  49
  50   // A callback to handle the result of OpenStorage.
  51   // The argument is the returned handle.
  52   typedef base::Callback<void(const std::string& handle)> OpenStorageCallback;
  53
  54   // A callback to handle the result of CloseStorage.
  55   typedef base::Closure CloseStorageCallback;
  56
  57   // A callback to handle the result of ReadDirectoryEntryIds.
  58   // The argument is a vector of file ids.
  59   typedef base::Callback<void(const std::vector<uint32>& file_ids)
  60                          > ReadDirectoryEntryIdsCallback;
  61
  62   // A callback to handle the result of GetFileInfo.
  63   // The argument is a vector of file entries.
  64   typedef base::Callback<void(const std::vector<MtpFileEntry>& file_entries)
  65                          > GetFileInfoCallback;
  66
  67   // A callback to handle the result of ReadFileChunkById.
  68   // The argument is a string containing the file data.
  69   typedef base::Callback<void(const std::string& data)> ReadFileCallback;
  70
  71   // A callback to handle the result of RenameObject.
  72   typedef base::Closure RenameObjectCallback;
  73
  74   // A callback to handle the result of CopyFileFromLocal.
  75   typedef base::Closure CopyFileFromLocalCallback;
  76
  77   // A callback to handle the result of DeleteObject.
  78   typedef base::Closure DeleteObjectCallback;
  79
  80   // A callback to handle storage attach/detach events.
  81   // The first argument is true for attach, false for detach.
  82   // The second argument is the storage name.
  83   typedef base::Callback<void(bool is_attach,
  84                               const std::string& storage_name)
  85                          > MTPStorageEventHandler;
  86
  87   virtual ~MediaTransferProtocolDaemonClient();
  88
  89   // Calls EnumerateStorages method. |callback| is called after the
  90   // method call succeeds, otherwise, |error_callback| is called.
  91   virtual void EnumerateStorages(
  92       const EnumerateStoragesCallback& callback,
  93       const ErrorCallback& error_callback) = 0;
  94
  95   // Calls GetStorageInfo method. |callback| is called after the method call
  96   // succeeds, otherwise, |error_callback| is called.
  97   virtual void GetStorageInfo(const std::string& storage_name,
  98                               const GetStorageInfoCallback& callback,
  99                               const ErrorCallback& error_callback) = 0;
 100
 101   // Calls OpenStorage method. |callback| is called after the method call
 102   // succeeds, otherwise, |error_callback| is called.
 103   // OpenStorage returns a handle in |callback|.
 104   virtual void OpenStorage(const std::string& storage_name,
 105                            const std::string& mode,
 106                            const OpenStorageCallback& callback,
 107                            const ErrorCallback& error_callback) = 0;
 108
 109   // Calls CloseStorage method. |callback| is called after the method call
 110   // succeeds, otherwise, |error_callback| is called.
 111   // |handle| comes from a OpenStorageCallback.
 112   virtual void CloseStorage(const std::string& handle,
 113                             const CloseStorageCallback& callback,
 114                             const ErrorCallback& error_callback) = 0;
 115
 116   // Calls ReadDirectoryEntryIds method. |callback| is called after the method
 117   // call succeeds, otherwise, |error_callback| is called.
 118   // |file_id| is a MTP-device specific id for a file.
 119   virtual void ReadDirectoryEntryIds(
 120       const std::string& handle,
 121       uint32 file_id,
 122       const ReadDirectoryEntryIdsCallback& callback,
 123       const ErrorCallback& error_callback) = 0;
 124
 125   // Calls GetFileInfo method. |callback| is called after the method
 126   // call succeeds, otherwise, |error_callback| is called.
 127   // |file_ids| is a list of MTP-device specific file ids.
 128   // |offset| is the index into |file_ids| to read from.
 129   // |entries_to_read| is the maximum number of file entries to read.
 130   virtual void GetFileInfo(const std::string& handle,
 131                            const std::vector<uint32>& file_ids,
 132                            size_t offset,
 133                            size_t entries_to_read,
 134                            const GetFileInfoCallback& callback,
 135                            const ErrorCallback& error_callback) = 0;
 136
 137   // Calls ReadFileChunk method. |callback| is called after the method call
 138   // succeeds, otherwise, |error_callback| is called.
 139   // |file_id| is a MTP-device specific id for a file.
 140   // |offset| is the offset into the file.
 141   // |bytes_to_read| cannot exceed 1 MiB.
 142   virtual void ReadFileChunk(const std::string& handle,
 143                              uint32 file_id,
 144                              uint32 offset,
 145                              uint32 bytes_to_read,
 146                              const ReadFileCallback& callback,
 147                              const ErrorCallback& error_callback) = 0;
 148
 149   // Calls RenameObject method. |callback| is called after the method call
 150   // succeeds, otherwise, |error_callback| is called.
 151   // |object_is| is an id of object to be renamed.
 152   // |new_name| is new name of the object.
 153   virtual void RenameObject(const std::string& handle,
 154                             const uint32 object_id,
 155                             const std::string& new_name,
 156                             const RenameObjectCallback& callback,
 157                             const ErrorCallback& error_callback) = 0;
 158
 159   // Calls CopyFileFromLocal method. |callback| is called after the method call
 160   // succeeds, otherwise, |error_callback| is called.
 161   // |source_file_descriptor| is a file descriptor of source file.
 162   // |parent_id| is a object id of a target directory.
 163   // |file_name| is a file name of a target file.
 164   virtual void CopyFileFromLocal(const std::string& handle,
 165                                  const int source_file_descriptor,
 166                                  const uint32 parent_id,
 167                                  const std::string& file_name,
 168                                  const CopyFileFromLocalCallback& callback,
 169                                  const ErrorCallback& error_callback) = 0;
 170
 171   // Calls DeleteObject method. |callback| is called after the method call
 172   // succeeds, otherwise, |error_callback| is called.
 173   // |object_id| is an object id of a file or directory which is deleted.
 174   virtual void DeleteObject(const std::string& handle,
 175                             const uint32 object_id,
 176                             const DeleteObjectCallback& callback,
 177                             const ErrorCallback& error_callback) = 0;
 178
 179   // Registers given callback for events. Should only be called once.
 180   // |storage_event_handler| is called when a mtp storage attach or detach
 181   // signal is received.
 182   virtual void ListenForChanges(const MTPStorageEventHandler& handler) = 0;
 183
 184   // Factory function, creates a new instance and returns ownership.
 185   static MediaTransferProtocolDaemonClient* Create(dbus::Bus* bus);
 186
 187  protected:
 188   // Create() should be used instead.
 189   MediaTransferProtocolDaemonClient();
 190
 191  private:
 192   DISALLOW_COPY_AND_ASSIGN(MediaTransferProtocolDaemonClient);
 193 };
 194
 195 }  // namespace device
 196
 197 #endif  // DEVICE_MEDIA_TRANSFER_PROTOCOL_MEDIA_TRANSFER_PROTOCOL_DAEMON_CLIENT_H_