/* -*- 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 nsIClipboardDataSnapshot : 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 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); /** * 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. * @result NS_OK if no errors */ void getDataSync(in nsITransferable aTransferable); }; [scriptable, uuid(ce23c1c4-58fd-4c33-8579-fa0796d9652c)] interface nsIClipboardGetDataSnapshotCallback : nsISupports { /** * Indicates that the clipboard get request has succeeded. */ void onSuccess(in nsIClipboardDataSnapshot aClipboardDataSnapshot); /** * 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 { cenum ClipboardType : 32 { kSelectionClipboard = 0, kGlobalClipboard = 1, kFindClipboard = 2, // Used to cache current selection on (nsClipboard) for macOS service menu. 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 nsIClipboard_ClipboardType 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 nsIClipboard_ClipboardType 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 nsIClipboard_ClipboardType 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 getDataSnapshot(in Array aFlavorList, in nsIClipboard_ClipboardType aWhichClipboard, in WindowContext aRequestingWindowContext, in nsIPrincipal aRequestingPrincipal, in nsIClipboardGetDataSnapshotCallback 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. */ nsIClipboardDataSnapshot getDataSnapshotSync(in Array aFlavorList, in nsIClipboard_ClipboardType 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 nsIClipboard_ClipboardType 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 aFlavorList, in nsIClipboard_ClipboardType 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 nsIClipboard_ClipboardType aWhichClipboard); };