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