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/gtest_prod_util.h"
  14 #include "base/memory/scoped_ptr.h"
  15 #include "base/memory/shared_memory.h"
  16 #include "base/process/process.h"
  17 #include "base/strings/string16.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(TOOLKIT_GTK)
  24 #include <gdk/gdk.h>
  25 #endif
  26
  27 #if defined(OS_WIN)
  28 #include <objidl.h>
  29 #elif defined(OS_ANDROID)
  30 #include <jni.h>
  31
  32 #include "base/android/jni_android.h"
  33 #include "base/android/scoped_java_ref.h"
  34 #endif
  35
  36 #if defined(USE_AURA) && defined(USE_X11)
  37 #include "base/memory/scoped_ptr.h"
  38 #endif
  39
  40 namespace base {
  41 class FilePath;
  42
  43 namespace win {
  44 class MessageWindow;
  45 }  // namespace win
  46 }  // namespace base
  47
  48 namespace gfx {
  49 class Size;
  50 }
  51
  52 class SkBitmap;
  53
  54 #if defined(TOOLKIT_GTK)
  55 typedef struct _GtkClipboard GtkClipboard;
  56 #endif
  57
  58 #ifdef __OBJC__
  59 @class NSString;
  60 #else
  61 class NSString;
  62 #endif
  63
  64 namespace ui {
  65 class ClipboardTest;
  66
  67 class UI_BASE_EXPORT Clipboard : NON_EXPORTED_BASE(public base::ThreadChecker) {
  68  public:
  69   // MIME type constants.
  70   static const char kMimeTypeText[];
  71   static const char kMimeTypeURIList[];
  72   static const char kMimeTypeDownloadURL[];
  73   static const char kMimeTypeHTML[];
  74   static const char kMimeTypeRTF[];
  75   static const char kMimeTypePNG[];
  76
  77   // Platform neutral holder for native data representation of a clipboard type.
  78   struct UI_BASE_EXPORT FormatType {
  79     FormatType();
  80     ~FormatType();
  81
  82     // Serializes and deserializes a FormatType for use in IPC messages.
  83     std::string Serialize() const;
  84     static FormatType Deserialize(const std::string& serialization);
  85
  86 #if defined(OS_WIN) || defined(USE_AURA)
  87     // FormatType can be used in a set on some platforms.
  88     bool operator<(const FormatType& other) const;
  89 #endif
  90
  91 #if defined(OS_WIN)
  92     const FORMATETC& ToFormatEtc() const { return data_; }
  93 #elif defined(USE_AURA)
  94     const std::string& ToString() const { return data_; }
  95 #elif defined(OS_MACOSX)
  96     // Custom copy and assignment constructor to handle NSString.
  97     FormatType(const FormatType& other);
  98     FormatType& operator=(const FormatType& other);
  99 #endif
 100
 101    private:
 102     friend class Clipboard;
 103
 104     bool Equals(const FormatType& other) const;
 105
 106     // Platform-specific glue used internally by the Clipboard class. Each
 107     // plaform should define,at least one of each of the following:
 108     // 1. A constructor that wraps that native clipboard format descriptor.
 109     // 2. An accessor to retrieve the wrapped descriptor.
 110     // 3. A data member to hold the wrapped descriptor.
 111     //
 112     // Note that in some cases, the accessor for the wrapped descriptor may be
 113     // public, as these format types can be used by drag and drop code as well.
 114 #if defined(OS_WIN)
 115     explicit FormatType(UINT native_format);
 116     FormatType(UINT native_format, LONG index);
 117     UINT ToUINT() const { return data_.cfFormat; }
 118     FORMATETC data_;
 119 #elif defined(USE_AURA)
 120     explicit FormatType(const std::string& native_format);
 121     const std::string& data() const { return data_; }
 122     std::string data_;
 123 #elif defined(OS_MACOSX)
 124     explicit FormatType(NSString* native_format);
 125     NSString* ToNSString() const { return data_; }
 126     NSString* data_;
 127 #elif defined(TOOLKIT_GTK)
 128     explicit FormatType(const std::string& native_format);
 129     explicit FormatType(const GdkAtom& native_format);
 130     const GdkAtom& ToGdkAtom() const { return data_; }
 131     GdkAtom data_;
 132 #elif defined(OS_ANDROID)
 133     explicit FormatType(const std::string& native_format);
 134     const std::string& data() const { return data_; }
 135     std::string data_;
 136 #else
 137 #error No FormatType definition.
 138 #endif
 139
 140     // Copyable and assignable, since this is essentially an opaque value type.
 141   };
 142
 143   // ObjectType designates the type of data to be stored in the clipboard. This
 144   // designation is shared across all OSes. The system-specific designation
 145   // is defined by FormatType. A single ObjectType might be represented by
 146   // several system-specific FormatTypes. For example, on Linux the CBF_TEXT
 147   // ObjectType maps to "text/plain", "STRING", and several other formats. On
 148   // windows it maps to CF_UNICODETEXT.
 149   enum ObjectType {
 150     CBF_TEXT,
 151     CBF_HTML,
 152     CBF_RTF,
 153     CBF_BOOKMARK,
 154     CBF_WEBKIT,
 155     CBF_SMBITMAP,  // Bitmap from shared memory.
 156     CBF_DATA,  // Arbitrary block of bytes.
 157   };
 158
 159   // ObjectMap is a map from ObjectType to associated data.
 160   // The data is organized differently for each ObjectType. The following
 161   // table summarizes what kind of data is stored for each key.
 162   // * indicates an optional argument.
 163   //
 164   // Key           Arguments    Type
 165   // -------------------------------------
 166   // CBF_TEXT      text         char array
 167   // CBF_HTML      html         char array
 168   //               url*         char array
 169   // CBF_RTF       data         byte array
 170   // CBF_BOOKMARK  html         char array
 171   //               url          char array
 172   // CBF_WEBKIT    none         empty vector
 173   // CBF_SMBITMAP  shared_mem   A pointer to an unmapped base::SharedMemory
 174   //                            object containing the bitmap data. The bitmap
 175   //                            data should be premultiplied.
 176   //               size         gfx::Size struct
 177   // CBF_DATA      format       char array
 178   //               data         byte array
 179   typedef std::vector<char> ObjectMapParam;
 180   typedef std::vector<ObjectMapParam> ObjectMapParams;
 181   typedef std::map<int /* ObjectType */, ObjectMapParams> ObjectMap;
 182
 183   static bool IsSupportedClipboardType(int32 type) {
 184     switch (type) {
 185       case CLIPBOARD_TYPE_COPY_PASTE:
 186         return true;
 187 #if defined(USE_X11) && !defined(OS_CHROMEOS)
 188       case CLIPBOARD_TYPE_SELECTION:
 189         return true;
 190 #endif
 191     }
 192     return false;
 193   }
 194
 195   static ClipboardType FromInt(int32 type) {
 196     return static_cast<ClipboardType>(type);
 197   }
 198
 199   // Sets the list of threads that are allowed to access the clipboard.
 200   static void SetAllowedThreads(
 201       const std::vector<base::PlatformThreadId>& allowed_threads);
 202
 203   // Returns the clipboard object for the current thread.
 204   //
 205   // Most implementations will have at most one clipboard which will live on
 206   // the main UI thread, but Windows has tricky semantics where there have to
 207   // be two clipboards: one that lives on the UI thread and one that lives on
 208   // the IO thread.
 209   static Clipboard* GetForCurrentThread();
 210
 211   // Destroys the clipboard for the current thread. Usually, this will clean up
 212   // all clipboards, except on Windows. (Previous code leaks the IO thread
 213   // clipboard, so it shouldn't be a problem.)
 214   static void DestroyClipboardForCurrentThread();
 215
 216   // Write a bunch of objects to the system clipboard. Copies are made of the
 217   // contents of |objects|.
 218   // Note: If you're thinking about calling this, you should probably be using
 219   // ScopedClipboardWriter instead.
 220   void WriteObjects(ClipboardType type, const ObjectMap& objects);
 221
 222   // Returns a sequence number which uniquely identifies clipboard state.
 223   // This can be used to version the data on the clipboard and determine
 224   // whether it has changed.
 225   uint64 GetSequenceNumber(ClipboardType type);
 226
 227   // Tests whether the clipboard contains a certain format
 228   bool IsFormatAvailable(const FormatType& format, ClipboardType type) const;
 229
 230   // Clear the clipboard data.
 231   void Clear(ClipboardType type);
 232
 233   void ReadAvailableTypes(ClipboardType type,
 234                           std::vector<base::string16>* types,
 235                           bool* contains_filenames) const;
 236
 237   // Reads UNICODE text from the clipboard, if available.
 238   void ReadText(ClipboardType type, base::string16* result) const;
 239
 240   // Reads ASCII text from the clipboard, if available.
 241   void ReadAsciiText(ClipboardType type, std::string* result) const;
 242
 243   // Reads HTML from the clipboard, if available. If the HTML fragment requires
 244   // context to parse, |fragment_start| and |fragment_end| are indexes into
 245   // markup indicating the beginning and end of the actual fragment. Otherwise,
 246   // they will contain 0 and markup->size().
 247   void ReadHTML(ClipboardType type,
 248                 base::string16* markup,
 249                 std::string* src_url,
 250                 uint32* fragment_start,
 251                 uint32* fragment_end) const;
 252
 253   // Reads RTF from the clipboard, if available. Stores the result as a byte
 254   // vector.
 255   void ReadRTF(ClipboardType type, std::string* result) const;
 256
 257   // Reads an image from the clipboard, if available.
 258   SkBitmap ReadImage(ClipboardType type) const;
 259
 260   void ReadCustomData(ClipboardType clipboard_type,
 261                       const base::string16& type,
 262                       base::string16* result) const;
 263
 264   // Reads a bookmark from the clipboard, if available.
 265   void ReadBookmark(base::string16* title, std::string* url) const;
 266
 267   // Reads raw data from the clipboard with the given format type. Stores result
 268   // as a byte vector.
 269   void ReadData(const FormatType& format, std::string* result) const;
 270
 271   // Gets the FormatType corresponding to an arbitrary format string,
 272   // registering it with the system if needed. Due to Windows/Linux
 273   // limitiations, |format_string| must never be controlled by the user.
 274   static FormatType GetFormatType(const std::string& format_string);
 275
 276   // Get format identifiers for various types.
 277   static const FormatType& GetUrlFormatType();
 278   static const FormatType& GetUrlWFormatType();
 279   static const FormatType& GetMozUrlFormatType();
 280   static const FormatType& GetPlainTextFormatType();
 281   static const FormatType& GetPlainTextWFormatType();
 282   static const FormatType& GetFilenameFormatType();
 283   static const FormatType& GetFilenameWFormatType();
 284   static const FormatType& GetWebKitSmartPasteFormatType();
 285   // Win: MS HTML Format, Other: Generic HTML format
 286   static const FormatType& GetHtmlFormatType();
 287   static const FormatType& GetRtfFormatType();
 288   static const FormatType& GetBitmapFormatType();
 289   // TODO(raymes): Unify web custom data and pepper custom data:
 290   // crbug.com/158399.
 291   static const FormatType& GetWebCustomDataFormatType();
 292   static const FormatType& GetPepperCustomDataFormatType();
 293
 294   // Embeds a pointer to a SharedMemory object pointed to by |bitmap_handle|
 295   // belonging to |process| into a shared bitmap [CBF_SMBITMAP] slot in
 296   // |objects|.  The pointer is deleted by DispatchObjects().
 297   //
 298   // On non-Windows platforms, |process| is ignored.
 299   static bool ReplaceSharedMemHandle(ObjectMap* objects,
 300                                      base::SharedMemoryHandle bitmap_handle,
 301                                      base::ProcessHandle process)
 302       WARN_UNUSED_RESULT;
 303 #if defined(OS_WIN)
 304   // Firefox text/html
 305   static const FormatType& GetTextHtmlFormatType();
 306   static const FormatType& GetCFHDropFormatType();
 307   static const FormatType& GetFileDescriptorFormatType();
 308   static const FormatType& GetFileContentZeroFormatType();
 309   static const FormatType& GetIDListFormatType();
 310 #endif
 311
 312  private:
 313   FRIEND_TEST_ALL_PREFIXES(ClipboardTest, SharedBitmapTest);
 314   FRIEND_TEST_ALL_PREFIXES(ClipboardTest, EmptyHTMLTest);
 315   friend class ClipboardTest;
 316
 317   Clipboard();
 318   ~Clipboard();
 319
 320   void DispatchObject(ObjectType type, const ObjectMapParams& params);
 321
 322   void WriteText(const char* text_data, size_t text_len);
 323
 324   void WriteHTML(const char* markup_data,
 325                  size_t markup_len,
 326                  const char* url_data,
 327                  size_t url_len);
 328
 329   void WriteRTF(const char* rtf_data, size_t data_len);
 330
 331   void WriteBookmark(const char* title_data,
 332                      size_t title_len,
 333                      const char* url_data,
 334                      size_t url_len);
 335
 336   void WriteWebSmartPaste();
 337
 338   void WriteBitmap(const SkBitmap& bitmap);
 339
 340   void WriteData(const FormatType& format,
 341                  const char* data_data,
 342                  size_t data_len);
 343 #if defined(OS_WIN)
 344   void WriteBitmapFromHandle(HBITMAP source_hbitmap,
 345                              const gfx::Size& size);
 346
 347   // Safely write to system clipboard. Free |handle| on failure.
 348   void WriteToClipboard(unsigned int format, HANDLE handle);
 349
 350   static void ParseBookmarkClipboardFormat(const base::string16& bookmark,
 351                                            base::string16* title,
 352                                            std::string* url);
 353
 354   // Free a handle depending on its type (as intuited from format)
 355   static void FreeData(unsigned int format, HANDLE data);
 356
 357   // Return the window that should be the clipboard owner, creating it
 358   // if neccessary.  Marked const for lazily initialization by const methods.
 359   HWND GetClipboardWindow() const;
 360
 361   // Mark this as mutable so const methods can still do lazy initialization.
 362   mutable scoped_ptr<base::win::MessageWindow> clipboard_owner_;
 363
 364 #elif defined(TOOLKIT_GTK)
 365   // The public API is via WriteObjects() which dispatches to multiple
 366   // Write*() calls, but on GTK we must write all the clipboard types
 367   // in a single GTK call.  To support this we store the current set
 368   // of data we intend to put on the clipboard on clipboard_data_ as
 369   // WriteObjects is running, and then at the end call SetGtkClipboard
 370   // which replaces whatever is on the system clipboard with the
 371   // contents of clipboard_data_.
 372
 373  public:
 374   typedef std::map<std::string, std::pair<char*, size_t> > TargetMap;
 375
 376  private:
 377   // Write changes to gtk clipboard.
 378   void SetGtkClipboard(ClipboardType type);
 379   // Insert a mapping into clipboard_data_.
 380   void InsertMapping(const char* key, char* data, size_t data_len);
 381
 382   // Find the gtk clipboard for the passed type enum.
 383   GtkClipboard* LookupBackingClipboard(ClipboardType type) const;
 384
 385   TargetMap* clipboard_data_;
 386   GtkClipboard* clipboard_;
 387   GtkClipboard* primary_selection_;
 388 #elif defined(USE_CLIPBOARD_AURAX11)
 389  private:
 390   // We keep our implementation details private because otherwise we bring in
 391   // the X11 headers and break chrome compile.
 392   class AuraX11Details;
 393   scoped_ptr<AuraX11Details> aurax11_details_;
 394 #endif
 395
 396   DISALLOW_COPY_AND_ASSIGN(Clipboard);
 397 };
 398
 399 }  // namespace ui
 400
 401 #endif  // UI_BASE_CLIPBOARD_CLIPBOARD_H_