summaryrefslogtreecommitdiffstats
path: root/widget/nsIClipboard.idl
blob: fc1f8bf8c358a3d053ff73d363dd1c89300463d0 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
/* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
 *
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */


#include "nsISupports.idl"
#include "nsITransferable.idl"
#include "nsIClipboardOwner.idl"

interface nsIArray;

webidl WindowContext;

[scriptable, builtinclass, uuid(801e2318-c8fa-11ed-afa1-0242ac120002)]
interface nsIAsyncSetClipboardData : nsISupports {
  /**
   * Provide the data for the set request.
   *
   * @param  aTransferable
   *         The transferable contains the data to be written.
   * @param  aOwner [optional]
   *         The owner of the transferable.
   */
  void setData(in nsITransferable aTransferable, [optional] in nsIClipboardOwner aOwner);

  /**
   * Abort the request to set data.
   *
   * @param  aReason
   *         The reason for the abort, can not be NS_OK.
   */
  void abort(in nsresult aReason);
};

[scriptable, function, uuid(78f7c18e-c8fa-11ed-afa1-0242ac120002)]
interface nsIAsyncClipboardRequestCallback : nsISupports
{
  /**
   * Indicates that the clipboard request has either succeeded, been canceled or
   * rejected.
   *
   * @param  aResult
   *         The result of the request. NS_OK if successful, or another value
   *         that indicates the reason for failure or cancellation.
   */
  void onComplete(in nsresult aResult);
};

[scriptable, builtinclass, uuid(c18ea2f7-6b6f-4a38-9ab3-a8781fdfcc39)]
interface nsIAsyncGetClipboardData : nsISupports {
  /**
   * Determines whether this request is still valid (e.g., the clipboard content
   * associated with this request is not stale).
   */
  readonly attribute boolean valid;

  /**
   * The available flavors in the clipboard.
   */
  readonly attribute Array<ACString> flavorList;

  /**
   * Filters the flavors that `aTransferable` can import (see
   * `nsITransferable::flavorsTransferableCanImport`). Every specified flavors
   * must exist in `flavorList`, or the request will be rejected. If the request
   * remains valid, it retrieves the data for the first flavor. The data is then
   * set for `aTransferable`.
   *
   * @param  aTransferable
   *         The transferable which contains the flavors to be read.
   * @param  aCallback
   *         The nsIAsyncClipboardRequestCallback to be invoked once the get
   *         request is either successfully completed or rejected.
   * @result NS_OK if no errors
   */
  void getData(in nsITransferable aTransferable,
               in nsIAsyncClipboardRequestCallback aCallback);
};

[scriptable, uuid(ce23c1c4-58fd-4c33-8579-fa0796d9652c)]
interface nsIAsyncClipboardGetCallback : nsISupports
{
  /**
   * Indicates that the clipboard get request has succeeded.
   */
  void onSuccess(in nsIAsyncGetClipboardData aAsyncGetClipboardData);

  /**
   * Indicates that the clipboard get request has rejected.
   *
   * @param  aResult
   *         The reason for the rejection, can not be NS_OK.
   */
  void onError(in nsresult aResult);
};

[scriptable, builtinclass, uuid(ceaa0047-647f-4b8e-ad1c-aff9fa62aa51)]
interface nsIClipboard : nsISupports
{
    const long kSelectionClipboard = 0;
    const long kGlobalClipboard = 1;
    const long kFindClipboard = 2;
    // Used to cache current selection on (nsClipboard) for macOS service menu.
    const long kSelectionCache = 3;

%{ C++
    static const uint32_t kClipboardTypeCount = kSelectionCache + 1;
%}

   /**
    * Given a transferable, set the data on the native clipboard
    *
    * @param  aTransferable The transferable
    * @param  anOwner The owner of the transferable
    * @param  aWhichClipboard Specifies the clipboard to which this operation applies.
    * @param  aSettingWindowContext [optional]
    *         The window context that is setting the clipboard, if any. This is used
    *         to possibly bypass Content Analysis if a set clipboard and get clipboard
    *         operation are done on the same page.
    * @result NS_OK if no errors
    */

    void setData (in nsITransferable aTransferable, in nsIClipboardOwner anOwner,
                  in long aWhichClipboard, [optional] in WindowContext aSettingWindowContext);

    /**
     * Requests setting data to the native clipboard. The actual set occurs
     * when the data is provided by calling nsIAsyncSetClipboardData::setData().
     * The result will be notified by nsIClipboardCallback. A new set request
     * will cancel any prior pending requests, if any exist.
     *
     * @param  aWhichClipboard
     *         Specifies the clipboard to which this operation applies.
     * @param  aSettingWindowContext [optional]
     *         The window context that is setting the clipboard, if any. This is used
     *         to possibly bypass Content Analysis if a set clipboard and get clipboard
     *         operation are done on the same page.
     * @param  aCallback [optional]
     *         The callback object that will be notified upon completion.
     * @return nsIAsyncSetClipboardData
     *         The write request object. The actual write will occur when the
     *         data is provided by calling nsIAsyncSetClipboardData::setData().
     */
    nsIAsyncSetClipboardData asyncSetData(in long aWhichClipboard,
                                          [optional] in WindowContext aSettingWindowContext,
                                          [optional] in nsIAsyncClipboardRequestCallback aCallback);

   /**
    * Filters the flavors aTransferable can import (see
    * `nsITransferable::flavorsTransferableCanImport`) and gets the data for the
    * first flavor. That data is set for aTransferable.
    *
    * @param  aTransferable The transferable
    * @param  aWhichClipboard Specifies the clipboard to which this operation applies.
    * @param  aRequestingWindowContext [optional]
    *         The window context window that is requesting the clipboard, which is
    *         used for content analysis. Passing null means that the content is
    *         exempt from content analysis. (for example, scripted clipboard read by
    *         system code) This parameter should not be null when calling this from a
    *         content process.
    * @result NS_OK if no errors
    */

    void getData ( in nsITransferable aTransferable, in long aWhichClipboard, [optional] in WindowContext aRequestingWindowContext) ;

    /**
     * Requests getting data asynchronously from the native clipboard. This does
     * not actually retrieve the data, but returns a nsIAsyncGetClipboardData
     * contains current avaiable data formats. If the native clipboard is
     * updated, either by us or other application, the existing
     * nsIAsyncGetClipboardData becomes invalid.
     *
     * @param  aFlavorList
     *         Specific data formats ('flavors') that can be retrieved from the
     *         clipboard.
     * @param  aWhichClipboard
     *         Specifies the clipboard to which this operation applies.
     * @param  aCallback
     *         The callback object that will be notified upon completion.
     * @result NS_OK if no errors
     */
    void asyncGetData(in Array<ACString> aFlavorList,
                      in long aWhichClipboard,
                      in WindowContext aRequestingWindowContext,
                      in nsIPrincipal aRequestingPrincipal,
                      in nsIAsyncClipboardGetCallback aCallback);

    /**
     * Requests getting data from the native clipboard. This does not actually
     * retreive the data, but returns a nsIAsyncGetClipboardData contains
     * current avaiable data formats. If the native clipboard is updated, either
     * by us or other application, the existing nsIAsyncGetClipboardData becomes
     * invalid.
     *
     * @param  aFlavorList
     *         Specific data formats ('flavors') that can be retrieved from the
     *         clipboard.
     * @param  aWhichClipboard
     *         Specifies the clipboard to which this operation applies.
     * @param  aRequestingWindowContext [optional]
     *         The window context window that is requesting the clipboard, which is
     *         used for content analysis. Passing null means that the content is
     *         exempt from content analysis. (for example, scripted clipboard read by
     *         system code) This parameter should not be null when calling this from a
     *         content process.
     * @return nsIAsyncSetClipboardData if successful.
     * @throws if the request can not be made.
     */
    nsIAsyncGetClipboardData getDataSnapshotSync(in Array<ACString> aFlavorList,
                                                 in long aWhichClipboard,
                                                 [optional] in WindowContext aRequestingWindowContext);

   /**
    * This empties the clipboard and notifies the clipboard owner.
    * This empties the "logical" clipboard. It does not clear the native clipboard.
    *
    * @param  aWhichClipboard Specifies the clipboard to which this operation applies.
    * @result NS_OK if successful.
    */

    void emptyClipboard ( in long aWhichClipboard ) ;

   /**
    * This provides a way to give correct UI feedback about, for instance, a paste
    * should be allowed. It does _NOT_ actually retreive the data and should be a very
    * inexpensive call. All it does is check if there is data on the clipboard matching
    * any of the flavors in the given list.
    *
    * @param  aFlavorList     An array of ASCII strings.
    * @param  aWhichClipboard Specifies the clipboard to which this operation applies.
    * @outResult - if data is present matching one of
    * @result NS_OK if successful.
    */
    boolean hasDataMatchingFlavors ( in Array<ACString> aFlavorList,
                                     in long aWhichClipboard ) ;

    /**
     * Allows clients to determine if the implementation supports the concept of a
     * separate clipboard.
     *
     * @param aWhichClipboard  Specifies the clipboard to which this operation applies.
     * @outResult  true if the implementaion supports specific clipboard type.
     * @result  NS_OK if successful.
     */
    [infallible]
    boolean isClipboardTypeSupported(in long aWhichClipboard);
};