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 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 ReadDirectoryEntryIds method. |callback| is called after the method
 108   // call succeeds, otherwise, |error_callback| is called.
 109   // |file_id| is a MTP-device specific id for a file.
 110   virtual void ReadDirectoryEntryIds(
 111       const std::string& handle,
 112       uint32 file_id,
 113       const ReadDirectoryEntryIdsCallback& callback,
 114       const ErrorCallback& error_callback) = 0;
 115
 116   // Calls GetFileInfo method. |callback| is called after the method
 117   // call succeeds, otherwise, |error_callback| is called.
 118   // |file_ids| is a list of MTP-device specific file ids.
 119   // |offset| is the index into |file_ids| to read from.
 120   // |entries_to_read| is the maximum number of file entries to read.
 121   virtual void GetFileInfo(const std::string& handle,
 122                            const std::vector<uint32>& file_ids,
 123                            size_t offset,
 124                            size_t entries_to_read,
 125                            const GetFileInfoCallback& callback,
 126                            const ErrorCallback& error_callback) = 0;
 127
 128   // Calls ReadFileChunk method. |callback| is called after the method call
 129   // succeeds, otherwise, |error_callback| is called.
 130   // |file_id| is a MTP-device specific id for a file.
 131   // |offset| is the offset into the file.
 132   // |bytes_to_read| cannot exceed 1 MiB.
 133   virtual void ReadFileChunk(const std::string& handle,
 134                              uint32 file_id,
 135                              uint32 offset,
 136                              uint32 bytes_to_read,
 137                              const ReadFileCallback& callback,
 138                              const ErrorCallback& error_callback) = 0;
 139
 140   // Registers given callback for events. Should only be called once.
 141   // |storage_event_handler| is called when a mtp storage attach or detach
 142   // signal is received.
 143   virtual void ListenForChanges(const MTPStorageEventHandler& handler) = 0;
 144
 145   // Factory function, creates a new instance and returns ownership.
 146   static MediaTransferProtocolDaemonClient* Create(dbus::Bus* bus);
 147
 148  protected:
 149   // Create() should be used instead.
 150   MediaTransferProtocolDaemonClient();
 151
 152  private:
 153   DISALLOW_COPY_AND_ASSIGN(MediaTransferProtocolDaemonClient);
 154 };
 155
 156 }  // namespace device
 157
 158 #endif  // DEVICE_MEDIA_TRANSFER_PROTOCOL_MEDIA_TRANSFER_PROTOCOL_DAEMON_CLIENT_H_