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
36namespace base {
37class FilePath;
38
39namespace win {
40class MessageWindow;
41}  // namespace win
42}  // namespace base
43
44// TODO(dcheng): Temporary until the IPC layer doesn't use WriteObjects().
45namespace content {
46class ClipboardMessageFilter;
47}
48
49namespace gfx {
50class Size;
51}
52
53class SkBitmap;
54
55#ifdef __OBJC__
56@class NSString;
57#else
58class NSString;
59#endif
60
61namespace ui {
62class ClipboardTest;
63class ScopedClipboardWriter;
64
65class 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_
375