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