src/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::Callback<void()> 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::Callback<void()> CloseStorageCallback;
  56
  57   // A callback to handle the result of ReadDirectoryByPath/Id.
  58   // The argument is a vector of file entries.
  59   typedef base::Callback<void(const std::vector<MtpFileEntry>& file_entries)
  60                          > ReadDirectoryCallback;
  61
  62   // A callback to handle the result of ReadFileChunkByPath/Id.
  63   // The argument is a string containing the file data.
  64   typedef base::Callback<void(const std::string& data)> ReadFileCallback;
  65
  66   // A callback to handle the result of GetFileInfoByPath/Id.
  67   // The argument is a file entry.
  68   typedef base::Callback<void(const MtpFileEntry& file_entry)
  69                          > GetFileInfoCallback;
  70
  71   // A callback to handle storage attach/detach events.
  72   // The first argument is true for attach, false for detach.
  73   // The second argument is the storage name.
  74   typedef base::Callback<void(bool is_attach,
  75                               const std::string& storage_name)
  76                          > MTPStorageEventHandler;
  77
  78   virtual ~MediaTransferProtocolDaemonClient();
  79
  80   // Calls EnumerateStorages method. |callback| is called after the
  81   // method call succeeds, otherwise, |error_callback| is called.
  82   virtual void EnumerateStorages(
  83       const EnumerateStoragesCallback& callback,
  84       const ErrorCallback& error_callback) = 0;
  85
  86   // Calls GetStorageInfo method. |callback| is called after the method call
  87   // succeeds, otherwise, |error_callback| is called.
  88   virtual void GetStorageInfo(const std::string& storage_name,
  89                               const GetStorageInfoCallback& callback,
  90                               const ErrorCallback& error_callback) = 0;
  91
  92   // Calls OpenStorage method. |callback| is called after the method call
  93   // succeeds, otherwise, |error_callback| is called.
  94   // OpenStorage returns a handle in |callback|.
  95   virtual void OpenStorage(const std::string& storage_name,
  96                            const std::string& mode,
  97                            const OpenStorageCallback& callback,
  98                            const ErrorCallback& error_callback) = 0;
  99
 100   // Calls CloseStorage method. |callback| is called after the method call
 101   // succeeds, otherwise, |error_callback| is called.
 102   // |handle| comes from a OpenStorageCallback.
 103   virtual void CloseStorage(const std::string& handle,
 104                             const CloseStorageCallback& callback,
 105                             const ErrorCallback& error_callback) = 0;
 106
 107   // Calls ReadDirectoryByPath method. |callback| is called after the method
 108   // call succeeds, otherwise, |error_callback| is called.
 109   virtual void ReadDirectoryByPath(const std::string& handle,
 110                                    const std::string& path,
 111                                    const ReadDirectoryCallback& callback,
 112                                    const ErrorCallback& error_callback) = 0;
 113
 114   // Calls ReadDirectoryById method. |callback| is called after the method
 115   // call succeeds, otherwise, |error_callback| is called.
 116   // |file_id| is a MTP-device specific id for a file.
 117   virtual void ReadDirectoryById(const std::string& handle,
 118                                  uint32 file_id,
 119                                  const ReadDirectoryCallback& callback,
 120                                  const ErrorCallback& error_callback) = 0;
 121
 122   // Calls ReadFileChunkByPath method. |callback| is called after the method
 123   // call succeeds, otherwise, |error_callback| is called.
 124   // |bytes_to_read| cannot exceed 1 MiB.
 125   virtual void ReadFileChunkByPath(const std::string& handle,
 126                                    const std::string& path,
 127                                    uint32 offset,
 128                                    uint32 bytes_to_read,
 129                                    const ReadFileCallback& callback,
 130                                    const ErrorCallback& error_callback) = 0;
 131
 132   // TODO(thestig) Remove this in the near future if we don't see anyone using
 133   // it.
 134   // Calls ReadFilePathById method. |callback| is called after the method call
 135   // succeeds, otherwise, |error_callback| is called.
 136   // |file_id| is a MTP-device specific id for a file.
 137   // |bytes_to_read| cannot exceed 1 MiB.
 138   virtual void ReadFileChunkById(const std::string& handle,
 139                                  uint32 file_id,
 140                                  uint32 offset,
 141                                  uint32 bytes_to_read,
 142                                  const ReadFileCallback& callback,
 143                                  const ErrorCallback& error_callback) = 0;
 144
 145   // Calls GetFileInfoByPath method. |callback| is called after the method
 146   // call succeeds, otherwise, |error_callback| is called.
 147   virtual void GetFileInfoByPath(const std::string& handle,
 148                                  const std::string& path,
 149                                  const GetFileInfoCallback& callback,
 150                                  const ErrorCallback& error_callback) = 0;
 151
 152   // Calls GetFileInfoById method. |callback| is called after the method
 153   // call succeeds, otherwise, |error_callback| is called.
 154   // |file_id| is a MTP-device specific id for a file.
 155   virtual void GetFileInfoById(const std::string& handle,
 156                                uint32 file_id,
 157                                const GetFileInfoCallback& callback,
 158                                const ErrorCallback& error_callback) = 0;
 159
 160   // Registers given callback for events.
 161   // |storage_event_handler| is called when a mtp storage attach or detach
 162   // signal is received.
 163   virtual void SetUpConnections(const MTPStorageEventHandler& handler) = 0;
 164
 165   // Factory function, creates a new instance and returns ownership.
 166   // For normal usage, set |is_stub| to false.
 167   static MediaTransferProtocolDaemonClient* Create(dbus::Bus* bus,
 168                                                    bool is_stub);
 169
 170  protected:
 171   // Create() should be used instead.
 172   MediaTransferProtocolDaemonClient();
 173
 174  private:
 175   DISALLOW_COPY_AND_ASSIGN(MediaTransferProtocolDaemonClient);
 176 };
 177
 178 }  // namespace device
 179
 180 #endif  // DEVICE_MEDIA_TRANSFER_PROTOCOL_MEDIA_TRANSFER_PROTOCOL_DAEMON_CLIENT_H_