ui/base/clipboard/clipboard.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 #ifndef UI_BASE_CLIPBOARD_CLIPBOARD_H_
   6 #define UI_BASE_CLIPBOARD_CLIPBOARD_H_
   7
   8 #include <map>
   9 #include <string>
  10 #include <vector>
  11
  12 #include "base/compiler_specific.h"
  13 #include "base/lazy_instance.h"
  14 #include "base/process/process.h"
  15 #include "base/strings/string16.h"
  16 #include "base/synchronization/lock.h"
  17 #include "base/threading/platform_thread.h"
  18 #include "base/threading/thread_checker.h"
  19 #include "ui/base/clipboard/clipboard_types.h"
  20 #include "ui/base/ui_base_export.h"
  21
  22 #if defined(OS_WIN)
  23 #include <objidl.h>
  24 #endif
  25
  26 namespace base {
  27 class FilePath;
  28
  29 namespace win {
  30 class MessageWindow;
  31 }  // namespace win
  32 }  // namespace base
  33
  34 namespace gfx {
  35 class Size;
  36 }
  37
  38 class SkBitmap;
  39
  40 #ifdef __OBJC__
  41 @class NSString;
  42 #else
  43 class NSString;
  44 #endif
  45
  46 namespace ui {
  47 template <typename T>
  48 class ClipboardTest;
  49 class TestClipboard;
  50 class ScopedClipboardWriter;
  51
  52 class UI_BASE_EXPORT Clipboard : NON_EXPORTED_BASE(public base::ThreadChecker) {
  53  public:
  54   // MIME type constants.
  55   static const char kMimeTypeText[];
  56   static const char kMimeTypeURIList[];
  57   static const char kMimeTypeDownloadURL[];
  58   static const char kMimeTypeHTML[];
  59   static const char kMimeTypeRTF[];
  60   static const char kMimeTypePNG[];
  61
  62   // Platform neutral holder for native data representation of a clipboard type.
  63   struct UI_BASE_EXPORT FormatType {
  64     FormatType();
  65     ~FormatType();
  66
  67     // Serializes and deserializes a FormatType for use in IPC messages.
  68     std::string Serialize() const;
  69     static FormatType Deserialize(const std::string& serialization);
  70
  71     // FormatType can be used in a set on some platforms.
  72     bool operator<(const FormatType& other) const;
  73
  74 #if defined(OS_WIN)
  75     const FORMATETC& ToFormatEtc() const { return data_; }
  76 #elif defined(USE_AURA) || defined(OS_ANDROID)
  77     const std::string& ToString() const { return data_; }
  78 #elif defined(OS_MACOSX)
  79     NSString* ToNSString() const { return data_; }
  80     // Custom copy and assignment constructor to handle NSString.
  81     FormatType(const FormatType& other);
  82     FormatType& operator=(const FormatType& other);
  83 #endif
  84
  85     bool Equals(const FormatType& other) const;
  86
  87    private:
  88     friend class Clipboard;
  89
  90     // Platform-specific glue used internally by the Clipboard class. Each
  91     // plaform should define,at least one of each of the following:
  92     // 1. A constructor that wraps that native clipboard format descriptor.
  93     // 2. An accessor to retrieve the wrapped descriptor.
  94     // 3. A data member to hold the wrapped descriptor.
  95     //
  96     // Note that in some cases, the accessor for the wrapped descriptor may be
  97     // public, as these format types can be used by drag and drop code as well.
  98 #if defined(OS_WIN)
  99     explicit FormatType(UINT native_format);
 100     FormatType(UINT native_format, LONG index);
 101     FORMATETC data_;
 102 #elif defined(USE_AURA) || defined(OS_ANDROID)
 103     explicit FormatType(const std::string& native_format);
 104     std::string data_;
 105 #elif defined(OS_MACOSX)
 106     explicit FormatType(NSString* native_format);
 107     NSString* data_;
 108 #else
 109 #error No FormatType definition.
 110 #endif
 111
 112     // Copyable and assignable, since this is essentially an opaque value type.
 113   };
 114
 115   static bool IsSupportedClipboardType(int32 type) {
 116     switch (type) {
 117       case CLIPBOARD_TYPE_COPY_PASTE:
 118         return true;
 119 #if !defined(OS_WIN) && !defined(OS_MACOSX) && !defined(OS_CHROMEOS)
 120       case CLIPBOARD_TYPE_SELECTION:
 121         return true;
 122 #endif
 123     }
 124     return false;
 125   }
 126
 127   static ClipboardType FromInt(int32 type) {
 128     return static_cast<ClipboardType>(type);
 129   }
 130
 131   // Sets the list of threads that are allowed to access the clipboard.
 132   static void SetAllowedThreads(
 133       const std::vector<base::PlatformThreadId>& allowed_threads);
 134
 135   // Returns the clipboard object for the current thread.
 136   //
 137   // Most implementations will have at most one clipboard which will live on
 138   // the main UI thread, but Windows has tricky semantics where there have to
 139   // be two clipboards: one that lives on the UI thread and one that lives on
 140   // the IO thread.
 141   static Clipboard* GetForCurrentThread();
 142
 143   // Destroys the clipboard for the current thread. Usually, this will clean up
 144   // all clipboards, except on Windows. (Previous code leaks the IO thread
 145   // clipboard, so it shouldn't be a problem.)
 146   static void DestroyClipboardForCurrentThread();
 147
 148   // Returns a sequence number which uniquely identifies clipboard state.
 149   // This can be used to version the data on the clipboard and determine
 150   // whether it has changed.
 151   virtual uint64 GetSequenceNumber(ClipboardType type) const = 0;
 152
 153   // Tests whether the clipboard contains a certain format
 154   virtual bool IsFormatAvailable(const FormatType& format,
 155                                  ClipboardType type) const = 0;
 156
 157   // Clear the clipboard data.
 158   virtual void Clear(ClipboardType type) = 0;
 159
 160   virtual void ReadAvailableTypes(ClipboardType type,
 161                                   std::vector<base::string16>* types,
 162                                   bool* contains_filenames) const = 0;
 163
 164   // Reads UNICODE text from the clipboard, if available.
 165   virtual void ReadText(ClipboardType type, base::string16* result) const = 0;
 166
 167   // Reads ASCII text from the clipboard, if available.
 168   virtual void ReadAsciiText(ClipboardType type, std::string* result) const = 0;
 169
 170   // Reads HTML from the clipboard, if available. If the HTML fragment requires
 171   // context to parse, |fragment_start| and |fragment_end| are indexes into
 172   // markup indicating the beginning and end of the actual fragment. Otherwise,
 173   // they will contain 0 and markup->size().
 174   virtual void ReadHTML(ClipboardType type,
 175                         base::string16* markup,
 176                         std::string* src_url,
 177                         uint32* fragment_start,
 178                         uint32* fragment_end) const = 0;
 179
 180   // Reads RTF from the clipboard, if available. Stores the result as a byte
 181   // vector.
 182   virtual void ReadRTF(ClipboardType type, std::string* result) const = 0;
 183
 184   // Reads an image from the clipboard, if available.
 185   virtual SkBitmap ReadImage(ClipboardType type) const = 0;
 186
 187   virtual void ReadCustomData(ClipboardType clipboard_type,
 188                               const base::string16& type,
 189                               base::string16* result) const = 0;
 190
 191   // Reads a bookmark from the clipboard, if available.
 192   virtual void ReadBookmark(base::string16* title, std::string* url) const = 0;
 193
 194   // Reads raw data from the clipboard with the given format type. Stores result
 195   // as a byte vector.
 196   virtual void ReadData(const FormatType& format,
 197                         std::string* result) const = 0;
 198
 199   // Gets the FormatType corresponding to an arbitrary format string,
 200   // registering it with the system if needed. Due to Windows/Linux
 201   // limitiations, |format_string| must never be controlled by the user.
 202   static FormatType GetFormatType(const std::string& format_string);
 203
 204   // Get format identifiers for various types.
 205   static const FormatType& GetUrlFormatType();
 206   static const FormatType& GetUrlWFormatType();
 207   static const FormatType& GetMozUrlFormatType();
 208   static const FormatType& GetPlainTextFormatType();
 209   static const FormatType& GetPlainTextWFormatType();
 210   static const FormatType& GetFilenameFormatType();
 211   static const FormatType& GetFilenameWFormatType();
 212   static const FormatType& GetWebKitSmartPasteFormatType();
 213   // Win: MS HTML Format, Other: Generic HTML format
 214   static const FormatType& GetHtmlFormatType();
 215   static const FormatType& GetRtfFormatType();
 216   static const FormatType& GetBitmapFormatType();
 217   // TODO(raymes): Unify web custom data and pepper custom data:
 218   // crbug.com/158399.
 219   static const FormatType& GetWebCustomDataFormatType();
 220   static const FormatType& GetPepperCustomDataFormatType();
 221
 222 #if defined(OS_WIN)
 223   // Firefox text/html
 224   static const FormatType& GetTextHtmlFormatType();
 225   static const FormatType& GetCFHDropFormatType();
 226   static const FormatType& GetFileDescriptorFormatType();
 227   static const FormatType& GetFileContentZeroFormatType();
 228   static const FormatType& GetIDListFormatType();
 229 #endif
 230
 231  protected:
 232   static Clipboard* Create();
 233
 234   Clipboard() {}
 235   virtual ~Clipboard() {}
 236
 237   // ObjectType designates the type of data to be stored in the clipboard. This
 238   // designation is shared across all OSes. The system-specific designation
 239   // is defined by FormatType. A single ObjectType might be represented by
 240   // several system-specific FormatTypes. For example, on Linux the CBF_TEXT
 241   // ObjectType maps to "text/plain", "STRING", and several other formats. On
 242   // windows it maps to CF_UNICODETEXT.
 243   enum ObjectType {
 244     CBF_TEXT,
 245     CBF_HTML,
 246     CBF_RTF,
 247     CBF_BOOKMARK,
 248     CBF_WEBKIT,
 249     CBF_SMBITMAP,  // Bitmap from shared memory.
 250     CBF_DATA,      // Arbitrary block of bytes.
 251   };
 252
 253   // ObjectMap is a map from ObjectType to associated data.
 254   // The data is organized differently for each ObjectType. The following
 255   // table summarizes what kind of data is stored for each key.
 256   // * indicates an optional argument.
 257   //
 258   // Key           Arguments    Type
 259   // -------------------------------------
 260   // CBF_TEXT      text         char array
 261   // CBF_HTML      html         char array
 262   //               url*         char array
 263   // CBF_RTF       data         byte array
 264   // CBF_BOOKMARK  html         char array
 265   //               url          char array
 266   // CBF_WEBKIT    none         empty vector
 267   // CBF_SMBITMAP  bitmap       A pointer to a SkBitmap. The caller must ensure
 268   //                            the SkBitmap remains live for the duration of
 269   //                            the WriteObjects call.
 270   // CBF_DATA      format       char array
 271   //               data         byte array
 272   typedef std::vector<char> ObjectMapParam;
 273   typedef std::vector<ObjectMapParam> ObjectMapParams;
 274   typedef std::map<int /* ObjectType */, ObjectMapParams> ObjectMap;
 275
 276   // Write a bunch of objects to the system clipboard. Copies are made of the
 277   // contents of |objects|.
 278   virtual void WriteObjects(ClipboardType type, const ObjectMap& objects) = 0;
 279
 280   void DispatchObject(ObjectType type, const ObjectMapParams& params);
 281
 282   virtual void WriteText(const char* text_data, size_t text_len) = 0;
 283
 284   virtual void WriteHTML(const char* markup_data,
 285                          size_t markup_len,
 286                          const char* url_data,
 287                          size_t url_len) = 0;
 288
 289   virtual void WriteRTF(const char* rtf_data, size_t data_len) = 0;
 290
 291   virtual void WriteBookmark(const char* title_data,
 292                              size_t title_len,
 293                              const char* url_data,
 294                              size_t url_len) = 0;
 295
 296   virtual void WriteWebSmartPaste() = 0;
 297
 298   virtual void WriteBitmap(const SkBitmap& bitmap) = 0;
 299
 300   virtual void WriteData(const FormatType& format,
 301                          const char* data_data,
 302                          size_t data_len) = 0;
 303
 304  private:
 305   // For access to WriteObjects().
 306   friend class ScopedClipboardWriter;
 307   friend class TestClipboard;
 308
 309   // A list of allowed threads. By default, this is empty and no thread checking
 310   // is done (in the unit test case), but a user (like content) can set which
 311   // threads are allowed to call this method.
 312   typedef std::vector<base::PlatformThreadId> AllowedThreadsVector;
 313   static base::LazyInstance<AllowedThreadsVector> allowed_threads_;
 314
 315   // Mapping from threads to clipboard objects.
 316   typedef std::map<base::PlatformThreadId, Clipboard*> ClipboardMap;
 317   static base::LazyInstance<ClipboardMap> clipboard_map_;
 318
 319   // Mutex that controls access to |g_clipboard_map|.
 320   static base::LazyInstance<base::Lock>::Leaky clipboard_map_lock_;
 321
 322   DISALLOW_COPY_AND_ASSIGN(Clipboard);
 323 };
 324
 325 }  // namespace ui
 326
 327 #endif  // UI_BASE_CLIPBOARD_CLIPBOARD_H_