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 nsIAsyncGetClipboardData : 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 [scriptable, uuid(ce23c1c4-58fd-4c33-8579-fa0796d9652c)]
  83 interface nsIAsyncClipboardGetCallback : nsISupports
  84 {
  85   /**
  86    * Indicates that the clipboard get request has succeeded.
  87    */
  88   void onSuccess(in nsIAsyncGetClipboardData aAsyncGetClipboardData);
  89
  90   /**
  91    * Indicates that the clipboard get request has rejected.
  92    *
  93    * @param  aResult
  94    *         The reason for the rejection, can not be NS_OK.
  95    */
  96   void onError(in nsresult aResult);
  97 };
  98
  99 [scriptable, builtinclass, uuid(ceaa0047-647f-4b8e-ad1c-aff9fa62aa51)]
 100 interface nsIClipboard : nsISupports
 101 {
 102     const long kSelectionClipboard = 0;
 103     const long kGlobalClipboard = 1;
 104     const long kFindClipboard = 2;
 105     // Used to cache current selection on (nsClipboard) for macOS service menu.
 106     const long kSelectionCache = 3;
 107
 108 %{ C++
 109     static const uint32_t kClipboardTypeCount = kSelectionCache + 1;
 110 %}
 111
 112    /**
 113     * Given a transferable, set the data on the native clipboard
 114     *
 115     * @param  aTransferable The transferable
 116     * @param  anOwner The owner of the transferable
 117     * @param  aWhichClipboard Specifies the clipboard to which this operation applies.
 118     * @param  aSettingWindowContext [optional]
 119     *         The window context that is setting the clipboard, if any. This is used
 120     *         to possibly bypass Content Analysis if a set clipboard and get clipboard
 121     *         operation are done on the same page.
 122     * @result NS_OK if no errors
 123     */
 124
 125     void setData (in nsITransferable aTransferable, in nsIClipboardOwner anOwner,
 126                   in long aWhichClipboard, [optional] in WindowContext aSettingWindowContext);
 127
 128     /**
 129      * Requests setting data to the native clipboard. The actual set occurs
 130      * when the data is provided by calling nsIAsyncSetClipboardData::setData().
 131      * The result will be notified by nsIClipboardCallback. A new set request
 132      * will cancel any prior pending requests, if any exist.
 133      *
 134      * @param  aWhichClipboard
 135      *         Specifies the clipboard to which this operation applies.
 136      * @param  aSettingWindowContext [optional]
 137      *         The window context that is setting the clipboard, if any. This is used
 138      *         to possibly bypass Content Analysis if a set clipboard and get clipboard
 139      *         operation are done on the same page.
 140      * @param  aCallback [optional]
 141      *         The callback object that will be notified upon completion.
 142      * @return nsIAsyncSetClipboardData
 143      *         The write request object. The actual write will occur when the
 144      *         data is provided by calling nsIAsyncSetClipboardData::setData().
 145      */
 146     nsIAsyncSetClipboardData asyncSetData(in long aWhichClipboard,
 147                                           [optional] in WindowContext aSettingWindowContext,
 148                                           [optional] in nsIAsyncClipboardRequestCallback aCallback);
 149
 150    /**
 151     * Filters the flavors aTransferable can import (see
 152     * `nsITransferable::flavorsTransferableCanImport`) and gets the data for the
 153     * first flavor. That data is set for aTransferable.
 154     *
 155     * @param  aTransferable The transferable
 156     * @param  aWhichClipboard Specifies the clipboard to which this operation applies.
 157     * @param  aRequestingWindowContext [optional]
 158     *         The window context window that is requesting the clipboard, which is
 159     *         used for content analysis. Passing null means that the content is
 160     *         exempt from content analysis. (for example, scripted clipboard read by
 161     *         system code) This parameter should not be null when calling this from a
 162     *         content process.
 163     * @result NS_OK if no errors
 164     */
 165
 166     void getData ( in nsITransferable aTransferable, in long aWhichClipboard, [optional] in WindowContext aRequestingWindowContext) ;
 167
 168     /**
 169      * Requests getting data asynchronously from the native clipboard. This does
 170      * not actually retrieve the data, but returns a nsIAsyncGetClipboardData
 171      * contains current avaiable data formats. If the native clipboard is
 172      * updated, either by us or other application, the existing
 173      * nsIAsyncGetClipboardData becomes invalid.
 174      *
 175      * @param  aFlavorList
 176      *         Specific data formats ('flavors') that can be retrieved from the
 177      *         clipboard.
 178      * @param  aWhichClipboard
 179      *         Specifies the clipboard to which this operation applies.
 180      * @param  aCallback
 181      *         The callback object that will be notified upon completion.
 182      * @result NS_OK if no errors
 183      */
 184     void asyncGetData(in Array<ACString> aFlavorList,
 185                       in long aWhichClipboard,
 186                       in WindowContext aRequestingWindowContext,
 187                       in nsIPrincipal aRequestingPrincipal,
 188                       in nsIAsyncClipboardGetCallback aCallback);
 189
 190     /**
 191      * Requests getting data from the native clipboard. This does not actually
 192      * retreive the data, but returns a nsIAsyncGetClipboardData contains
 193      * current avaiable data formats. If the native clipboard is updated, either
 194      * by us or other application, the existing nsIAsyncGetClipboardData becomes
 195      * invalid.
 196      *
 197      * @param  aFlavorList
 198      *         Specific data formats ('flavors') that can be retrieved from the
 199      *         clipboard.
 200      * @param  aWhichClipboard
 201      *         Specifies the clipboard to which this operation applies.
 202      * @param  aRequestingWindowContext [optional]
 203      *         The window context window that is requesting the clipboard, which is
 204      *         used for content analysis. Passing null means that the content is
 205      *         exempt from content analysis. (for example, scripted clipboard read by
 206      *         system code) This parameter should not be null when calling this from a
 207      *         content process.
 208      * @return nsIAsyncSetClipboardData if successful.
 209      * @throws if the request can not be made.
 210      */
 211     nsIAsyncGetClipboardData getDataSnapshotSync(in Array<ACString> aFlavorList,
 212                                                  in long aWhichClipboard,
 213                                                  [optional] in WindowContext aRequestingWindowContext);
 214
 215    /**
 216     * This empties the clipboard and notifies the clipboard owner.
 217     * This empties the "logical" clipboard. It does not clear the native clipboard.
 218     *
 219     * @param  aWhichClipboard Specifies the clipboard to which this operation applies.
 220     * @result NS_OK if successful.
 221     */
 222
 223     void emptyClipboard ( in long aWhichClipboard ) ;
 224
 225    /**
 226     * This provides a way to give correct UI feedback about, for instance, a paste
 227     * should be allowed. It does _NOT_ actually retreive the data and should be a very
 228     * inexpensive call. All it does is check if there is data on the clipboard matching
 229     * any of the flavors in the given list.
 230     *
 231     * @param  aFlavorList     An array of ASCII strings.
 232     * @param  aWhichClipboard Specifies the clipboard to which this operation applies.
 233     * @outResult - if data is present matching one of
 234     * @result NS_OK if successful.
 235     */
 236     boolean hasDataMatchingFlavors ( in Array<ACString> aFlavorList,
 237                                      in long aWhichClipboard ) ;
 238
 239     /**
 240      * Allows clients to determine if the implementation supports the concept of a
 241      * separate clipboard.
 242      *
 243      * @param aWhichClipboard  Specifies the clipboard to which this operation applies.
 244      * @outResult  true if the implementaion supports specific clipboard type.
 245      * @result  NS_OK if successful.
 246      */
 247     [infallible]
 248     boolean isClipboardTypeSupported(in long aWhichClipboard);
 249 };