diff options
Diffstat (limited to 'widget/nsITransferable.idl')
| -rw-r--r-- | widget/nsITransferable.idl | 212 |
1 files changed, 212 insertions, 0 deletions
diff --git a/widget/nsITransferable.idl b/widget/nsITransferable.idl new file mode 100644 index 000000000..b128586dd --- /dev/null +++ b/widget/nsITransferable.idl @@ -0,0 +1,212 @@ +/* -*- 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 "nsIArray.idl" +#include "nsISupports.idl" +#include "nsIFormatConverter.idl" +#include "nsIContentPolicyBase.idl" + +interface nsIPrincipal; + +%{ C++ + +// these probably shouldn't live here, but in some central repository shared +// by the entire app. +#define kTextMime "text/plain" +#define kRTFMime "text/rtf" +#define kUnicodeMime "text/unicode" +#define kMozTextInternal "text/x-moz-text-internal" // text data which isn't suppoed to be parsed by other apps. +#define kHTMLMime "text/html" +#define kAOLMailMime "AOLMAIL" +#define kPNGImageMime "image/png" +#define kJPEGImageMime "image/jpeg" +#define kJPGImageMime "image/jpg" +#define kGIFImageMime "image/gif" +#define kFileMime "application/x-moz-file" + +#define kURLMime "text/x-moz-url" // data contains url\ntitle +#define kURLDataMime "text/x-moz-url-data" // data contains url only +#define kURLDescriptionMime "text/x-moz-url-desc" // data contains description +#define kURLPrivateMime "text/x-moz-url-priv" // same as kURLDataMime but for private uses +#define kNativeImageMime "application/x-moz-nativeimage" +#define kNativeHTMLMime "application/x-moz-nativehtml" + +// These are used to indicate the context for a fragment of HTML source, such +// that some parent structure and style can be preserved. kHTMLContext +// contains the serialized ancestor elements, whereas kHTMLInfo are numbers +// identifying where in the context the fragment was from. +#define kHTMLContext "text/_moz_htmlcontext" +#define kHTMLInfo "text/_moz_htmlinfo" + +// the source URL for a file promise +#define kFilePromiseURLMime "application/x-moz-file-promise-url" +// the destination filename for a file promise +#define kFilePromiseDestFilename "application/x-moz-file-promise-dest-filename" +// a dataless flavor used to interact with the OS during file drags +#define kFilePromiseMime "application/x-moz-file-promise" +// a synthetic flavor, put into the transferable once we know the destination directory of a file drag +#define kFilePromiseDirectoryMime "application/x-moz-file-promise-dir" + +#define kCustomTypesMime "application/x-moz-custom-clipdata" + +%} + + +/** + * nsIFlavorDataProvider allows a flavor to 'promise' data later, + * supplying the data lazily. + * + * To use it, call setTransferData, passing the flavor string, + * a nsIFlavorDataProvider QI'd to nsISupports, and a data size of 0. + * + * When someone calls getTransferData later, if the data size is + * stored as 0, the nsISupports will be QI'd to nsIFlavorDataProvider, + * and its getFlavorData called. + * + */ +interface nsITransferable; +interface nsILoadContext; + +[scriptable, uuid(7E225E5F-711C-11D7-9FAE-000393636592)] +interface nsIFlavorDataProvider : nsISupports +{ + + /** + * Retrieve the data from this data provider. + * + * @param aTransferable (in parameter) the transferable we're being called for. + * @param aFlavor (in parameter) the flavor of data to retrieve + * @param aData the data. Some variant of class in nsISupportsPrimitives.idl + * @param aDataLen the length of the data + */ + void getFlavorData(in nsITransferable aTransferable, in string aFlavor, out nsISupports aData, out unsigned long aDataLen); +}; + + +[scriptable, uuid(97e0c418-1c1e-4106-bad1-9fcb11dff2fe)] +interface nsITransferable : nsISupports +{ + const long kFlavorHasDataProvider = 0; + + /** + * Initializes a transferable object. This should be called on all + * transferable objects. Failure to do so will result in fatal assertions in + * debug builds. + * + * The load context is used to track whether the transferable is storing privacy- + * sensitive information. For example, we try to delete data that you copy + * to the clipboard when you close a Private Browsing window. + * + * To get the appropriate load context in Javascript callers, one needs to get + * to the document that the transferable corresponds to, and then get the load + * context from the document like this: + * + * var loadContext = doc.defaultView.QueryInterface(Ci.nsIInterfaceRequestor) + * .getInterface(Ci.nsIWebNavigation) + * .QueryInterface(Ci.nsILoadContext); + * + * In C++ callers, if you have the corresponding document, you can just call + * nsIDocument::GetLoadContext to get to the load context object. + * + * @param aContext the load context associated with the transferable object. + * This can be set to null if a load context is not available. + */ + void init(in nsILoadContext aContext); + + /** + * Computes a list of flavors (mime types as nsISupportsCString) that the transferable + * can export, either through intrinsic knowledge or output data converters. + * + * @param aDataFlavorList fills list with supported flavors. This is a copy of + * the internal list, so it may be edited w/out affecting the transferable. + */ + nsIArray flavorsTransferableCanExport ( ) ; + + /** + * Given a flavor retrieve the data. + * + * @param aFlavor (in parameter) the flavor of data to retrieve + * @param aData the data. Some variant of class in nsISupportsPrimitives.idl + * @param aDataLen the length of the data + */ + void getTransferData ( in string aFlavor, out nsISupports aData, out unsigned long aDataLen ) ; + + /** + * Returns the best flavor in the transferable, given those that have + * been added to it with |AddFlavor()| + * + * @param aFlavor (out parameter) the flavor of data that was retrieved + * @param aData the data. Some variant of class in nsISupportsPrimitives.idl + * @param aDataLen the length of the data + */ + void getAnyTransferData ( out ACString aFlavor, out nsISupports aData, + out unsigned long aDataLen ) ; + + /** + * Returns true if the data is large. + */ + boolean isLargeDataSet ( ) ; + + + /////////////////////////////// + // Setter part of interface + /////////////////////////////// + + /** + * Computes a list of flavors (mime types as nsISupportsCString) that the transferable can + * accept into it, either through intrinsic knowledge or input data converters. + * + * @param outFlavorList fills list with supported flavors. This is a copy of + * the internal list, so it may be edited w/out affecting the transferable. + */ + nsIArray flavorsTransferableCanImport ( ) ; + + /** + * Sets the data in the transferable with the specified flavor. The transferable + * will maintain its own copy the data, so it is not necessary to do that beforehand. + * + * @param aFlavor the flavor of data that is being set + * @param aData the data, either some variant of class in nsISupportsPrimitives.idl, + * an nsIFile, or an nsIFlavorDataProvider (see above) + * @param aDataLen the length of the data, or 0 if passing a nsIFlavorDataProvider + */ + void setTransferData ( in string aFlavor, in nsISupports aData, in unsigned long aDataLen ) ; + + /** + * Add the data flavor, indicating that this transferable + * can receive this type of flavor + * + * @param aDataFlavor a new data flavor to handle + */ + void addDataFlavor ( in string aDataFlavor ) ; + + /** + * Removes the data flavor matching the given one (string compare) and the data + * that goes along with it. + * + * @param aDataFlavor a data flavor to remove + */ + void removeDataFlavor ( in string aDataFlavor ) ; + + attribute nsIFormatConverter converter; + + /** + * Use of the SetIsPrivateData() method generated by isPrivateData attribute should + * be avoided as much as possible because the value set may not reflect the status + * of the context in which the transferable was created. + */ + [noscript] attribute boolean isPrivateData; + + /** + * The principal of the source dom node this transferable was + * created from and the contentPolicyType for the transferable. + * Note, currently only used on Windows for network principal and + * contentPolicyType information in clipboard and drag operations. + */ + [noscript] attribute nsIPrincipal requestingPrincipal; + [noscript] attribute nsContentPolicyType contentPolicyType; + +}; |