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