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/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     // Custom copy and assignment constructor to handle NSString.
     95     FormatType(const FormatType& other);
     96     FormatType& operator=(const FormatType& other);
     97 #endif
     98 
     99     bool Equals(const FormatType& other) const;
    100 
    101    private:
    102     friend class Clipboard;
    103 
    104     // Platform-specific glue used internally by the Clipboard class. Each
    105     // plaform should define,at least one of each of the following:
    106     // 1. A constructor that wraps that native clipboard format descriptor.
    107     // 2. An accessor to retrieve the wrapped descriptor.
    108     // 3. A data member to hold the wrapped descriptor.
    109     //
    110     // Note that in some cases, the accessor for the wrapped descriptor may be
    111     // public, as these format types can be used by drag and drop code as well.
    112 #if defined(OS_WIN)
    113     explicit FormatType(UINT native_format);
    114     FormatType(UINT native_format, LONG index);
    115     UINT ToUINT() const { return data_.cfFormat; }
    116     FORMATETC data_;
    117 #elif defined(USE_AURA)
    118     explicit FormatType(const std::string& native_format);
    119     const std::string& data() const { return data_; }
    120     std::string data_;
    121 #elif defined(OS_MACOSX)
    122     explicit FormatType(NSString* native_format);
    123     NSString* ToNSString() const { return data_; }
    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_
    375