widget/nsIClipboard.idl

   1 /* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
   2  *
   3  * This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7
   8 #include "nsISupports.idl"
   9 #include "nsITransferable.idl"
  10 #include "nsIClipboardOwner.idl"
  11
  12 interface nsIArray;
  13
  14 webidl WindowContext;
  15
  16 [scriptable, builtinclass, uuid(801e2318-c8fa-11ed-afa1-0242ac120002)]
  17 interface nsIAsyncSetClipboardData : nsISupports {
  18   /**
  19    * Provide the data for the set request.
  20    *
  21    * @param  aTransferable
  22    *         The transferable contains the data to be written.
  23    * @param  aOwner [optional]
  24    *         The owner of the transferable.
  25    */
  26   void setData(in nsITransferable aTransferable, [optional] in nsIClipboardOwner aOwner);
  27
  28   /**
  29    * Abort the request to set data.
  30    *
  31    * @param  aReason
  32    *         The reason for the abort, can not be NS_OK.
  33    */
  34   void abort(in nsresult aReason);
  35 };
  36
  37 [scriptable, function, uuid(78f7c18e-c8fa-11ed-afa1-0242ac120002)]
  38 interface nsIAsyncClipboardRequestCallback : nsISupports
  39 {
  40   /**
  41    * Indicates that the clipboard request has either succeeded, been canceled or
  42    * rejected.
  43    *
  44    * @param  aResult
  45    *         The result of the request. NS_OK if successful, or another value
  46    *         that indicates the reason for failure or cancellation.
  47    */
  48   void onComplete(in nsresult aResult);
  49 };
  50
  51 [scriptable, builtinclass, uuid(c18ea2f7-6b6f-4a38-9ab3-a8781fdfcc39)]
  52 interface nsIClipboardDataSnapshot : nsISupports {
  53   /**
  54    * Determines whether this request is still valid (e.g., the clipboard content
  55    * associated with this request is not stale).
  56    */
  57   readonly attribute boolean valid;
  58
  59   /**
  60    * The available flavors in the clipboard.
  61    */
  62   readonly attribute Array<ACString> flavorList;
  63
  64   /**
  65    * Filters the flavors that `aTransferable` can import (see
  66    * `nsITransferable::flavorsTransferableCanImport`). Every specified flavors
  67    * must exist in `flavorList`, or the request will be rejected. If the request
  68    * remains valid, it retrieves the data for the first flavor. The data is then
  69    * set for `aTransferable`.
  70    *
  71    * @param  aTransferable
  72    *         The transferable which contains the flavors to be read.
  73    * @param  aCallback
  74    *         The nsIAsyncClipboardRequestCallback to be invoked once the get
  75    *         request is either successfully completed or rejected.
  76    * @result NS_OK if no errors
  77    */
  78   void getData(in nsITransferable aTransferable,
  79                in nsIAsyncClipboardRequestCallback aCallback);
  80
  81   /**
  82    * Filters the flavors that `aTransferable` can import (see
  83    * `nsITransferable::flavorsTransferableCanImport`). Every specified flavors
  84    * must exist in `flavorList`, or the request will be rejected. If the request
  85    * remains valid, it retrieves the data for the first flavor. The data is then
  86    * set for `aTransferable`.
  87    *
  88    * @param  aTransferable
  89    *         The transferable which contains the flavors to be read.
  90    * @result NS_OK if no errors
  91    */
  92   void getDataSync(in nsITransferable aTransferable);
  93 };
  94
  95 [scriptable, uuid(ce23c1c4-58fd-4c33-8579-fa0796d9652c)]
  96 interface nsIClipboardGetDataSnapshotCallback : nsISupports
  97 {
  98   /**
  99    * Indicates that the clipboard get request has succeeded.
 100    */
 101   void onSuccess(in nsIClipboardDataSnapshot aClipboardDataSnapshot);
 102
 103   /**
 104    * Indicates that the clipboard get request has rejected.
 105    *
 106    * @param  aResult
 107    *         The reason for the rejection, can not be NS_OK.
 108    */
 109   void onError(in nsresult aResult);
 110 };
 111
 112 [scriptable, builtinclass, uuid(ceaa0047-647f-4b8e-ad1c-aff9fa62aa51)]
 113 interface nsIClipboard : nsISupports
 114 {
 115   cenum ClipboardType : 32 {
 116     kSelectionClipboard = 0,
 117     kGlobalClipboard = 1,
 118     kFindClipboard = 2,
 119     // Used to cache current selection on (nsClipboard) for macOS service menu.
 120     kSelectionCache = 3,
 121   };
 122
 123 %{ C++
 124     static const uint32_t kClipboardTypeCount = kSelectionCache + 1;
 125 %}
 126
 127    /**
 128     * Given a transferable, set the data on the native clipboard
 129     *
 130     * @param  aTransferable The transferable
 131     * @param  anOwner The owner of the transferable
 132     * @param  aWhichClipboard Specifies the clipboard to which this operation applies.
 133     * @param  aSettingWindowContext [optional]
 134     *         The window context that is setting the clipboard, if any. This is used
 135     *         to possibly bypass Content Analysis if a set clipboard and get clipboard
 136     *         operation are done on the same page.
 137     * @result NS_OK if no errors
 138     */
 139
 140     void setData (in nsITransferable aTransferable, in nsIClipboardOwner anOwner,
 141                   in nsIClipboard_ClipboardType aWhichClipboard, [optional] in WindowContext aSettingWindowContext);
 142
 143     /**
 144      * Requests setting data to the native clipboard. The actual set occurs
 145      * when the data is provided by calling nsIAsyncSetClipboardData::setData().
 146      * The result will be notified by nsIClipboardCallback. A new set request
 147      * will cancel any prior pending requests, if any exist.
 148      *
 149      * @param  aWhichClipboard
 150      *         Specifies the clipboard to which this operation applies.
 151      * @param  aSettingWindowContext [optional]
 152      *         The window context that is setting the clipboard, if any. This is used
 153      *         to possibly bypass Content Analysis if a set clipboard and get clipboard
 154      *         operation are done on the same page.
 155      * @param  aCallback [optional]
 156      *         The callback object that will be notified upon completion.
 157      * @return nsIAsyncSetClipboardData
 158      *         The write request object. The actual write will occur when the
 159      *         data is provided by calling nsIAsyncSetClipboardData::setData().
 160      */
 161     nsIAsyncSetClipboardData asyncSetData(in nsIClipboard_ClipboardType aWhichClipboard,
 162                                           [optional] in WindowContext aSettingWindowContext,
 163                                           [optional] in nsIAsyncClipboardRequestCallback aCallback);
 164
 165    /**
 166     * Filters the flavors aTransferable can import (see
 167     * `nsITransferable::flavorsTransferableCanImport`) and gets the data for the
 168     * first flavor. That data is set for aTransferable.
 169     *
 170     * @param  aTransferable The transferable
 171     * @param  aWhichClipboard Specifies the clipboard to which this operation applies.
 172     * @param  aRequestingWindowContext [optional]
 173     *         The window context window that is requesting the clipboard, which is
 174     *         used for content analysis. Passing null means that the content is
 175     *         exempt from content analysis. (for example, scripted clipboard read by
 176     *         system code) This parameter should not be null when calling this from a
 177     *         content process.
 178     * @result NS_OK if no errors
 179     */
 180
 181     void getData ( in nsITransferable aTransferable, in nsIClipboard_ClipboardType aWhichClipboard, [optional] in WindowContext aRequestingWindowContext) ;
 182
 183     /**
 184      * Requests getting data asynchronously from the native clipboard. This does
 185      * not actually retrieve the data, but returns a nsIAsyncGetClipboardData
 186      * contains current avaiable data formats. If the native clipboard is
 187      * updated, either by us or other application, the existing
 188      * nsIAsyncGetClipboardData becomes invalid.
 189      *
 190      * @param  aFlavorList
 191      *         Specific data formats ('flavors') that can be retrieved from the
 192      *         clipboard.
 193      * @param  aWhichClipboard
 194      *         Specifies the clipboard to which this operation applies.
 195      * @param  aCallback
 196      *         The callback object that will be notified upon completion.
 197      * @result NS_OK if no errors
 198      */
 199     void getDataSnapshot(in Array<ACString> aFlavorList,
 200                          in nsIClipboard_ClipboardType aWhichClipboard,
 201                          in WindowContext aRequestingWindowContext,
 202                          in nsIPrincipal aRequestingPrincipal,
 203                          in nsIClipboardGetDataSnapshotCallback aCallback);
 204
 205     /**
 206      * Requests getting data from the native clipboard. This does not actually
 207      * retreive the data, but returns a nsIAsyncGetClipboardData contains
 208      * current avaiable data formats. If the native clipboard is updated, either
 209      * by us or other application, the existing nsIAsyncGetClipboardData becomes
 210      * invalid.
 211      *
 212      * @param  aFlavorList
 213      *         Specific data formats ('flavors') that can be retrieved from the
 214      *         clipboard.
 215      * @param  aWhichClipboard
 216      *         Specifies the clipboard to which this operation applies.
 217      * @param  aRequestingWindowContext [optional]
 218      *         The window context window that is requesting the clipboard, which is
 219      *         used for content analysis. Passing null means that the content is
 220      *         exempt from content analysis. (for example, scripted clipboard read by
 221      *         system code) This parameter should not be null when calling this from a
 222      *         content process.
 223      * @return nsIAsyncSetClipboardData if successful.
 224      * @throws if the request can not be made.
 225      */
 226     nsIClipboardDataSnapshot getDataSnapshotSync(in Array<ACString> aFlavorList,
 227                                                  in nsIClipboard_ClipboardType aWhichClipboard,
 228                                                  [optional] in WindowContext aRequestingWindowContext);
 229
 230    /**
 231     * This empties the clipboard and notifies the clipboard owner.
 232     * This empties the "logical" clipboard. It does not clear the native clipboard.
 233     *
 234     * @param  aWhichClipboard Specifies the clipboard to which this operation applies.
 235     * @result NS_OK if successful.
 236     */
 237
 238     void emptyClipboard ( in nsIClipboard_ClipboardType aWhichClipboard ) ;
 239
 240    /**
 241     * This provides a way to give correct UI feedback about, for instance, a paste
 242     * should be allowed. It does _NOT_ actually retreive the data and should be a very
 243     * inexpensive call. All it does is check if there is data on the clipboard matching
 244     * any of the flavors in the given list.
 245     *
 246     * @param  aFlavorList     An array of ASCII strings.
 247     * @param  aWhichClipboard Specifies the clipboard to which this operation applies.
 248     * @outResult - if data is present matching one of
 249     * @result NS_OK if successful.
 250     */
 251     boolean hasDataMatchingFlavors ( in Array<ACString> aFlavorList,
 252                                      in nsIClipboard_ClipboardType aWhichClipboard ) ;
 253
 254     /**
 255      * Allows clients to determine if the implementation supports the concept of a
 256      * separate clipboard.
 257      *
 258      * @param aWhichClipboard  Specifies the clipboard to which this operation applies.
 259      * @outResult  true if the implementaion supports specific clipboard type.
 260      * @result  NS_OK if successful.
 261      */
 262     [infallible]
 263     boolean isClipboardTypeSupported(in nsIClipboard_ClipboardType aWhichClipboard);
 264 };