widget/nsITransferable.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 #include "nsIArray.idl"
   8 #include "nsISupports.idl"
   9 #include "nsIFormatConverter.idl"
  10 #include "nsIContentPolicy.idl"
  11
  12 interface nsICookieJarSettings;
  13 interface nsIPrincipal;
  14 interface nsIReferrerInfo;
  15
  16 %{ C++
  17
  18 // Internal formats must have their second part starting with 'x-moz-',
  19 // for example text/x-moz-internaltype. These cannot be assigned by
  20 // unprivileged content but all other types can.
  21 #define kInternal_Mimetype_Prefix   u"/x-moz-"_ns
  22
  23 // these probably shouldn't live here, but in some central repository shared
  24 // by the entire app.
  25 #define kTextMime                   "text/plain"
  26 #define kRTFMime                    "text/rtf"
  27 #define kMozTextInternal            "text/x-moz-text-internal"  // text data which isn't suppoed to be parsed by other apps.
  28 #define kHTMLMime                   "text/html"
  29 #define kAOLMailMime                "AOLMAIL"
  30 #define kPNGImageMime               "image/png"
  31 #define kJPEGImageMime              "image/jpeg"
  32 #define kJPGImageMime               "image/jpg"
  33 #define kGIFImageMime               "image/gif"
  34 #define kFileMime                   "application/x-moz-file"
  35
  36 #define kURLMime                    "text/x-moz-url"        // data contains url\ntitle
  37 #define kURLDataMime                "text/x-moz-url-data"   // data contains url only
  38 #define kURLDescriptionMime         "text/x-moz-url-desc"   // data contains description
  39 #define kURLPrivateMime             "text/x-moz-url-priv"   // same as kURLDataMime but for private uses
  40 #define kNativeImageMime            "application/x-moz-nativeimage"
  41 #define kNativeHTMLMime             "application/x-moz-nativehtml"
  42
  43 // These are used to indicate the context for a fragment of HTML source, such
  44 // that some parent structure and style can be preserved. kHTMLContext
  45 // contains the serialized ancestor elements, whereas kHTMLInfo are numbers
  46 // identifying where in the context the fragment was from.
  47 #define kHTMLContext   "text/_moz_htmlcontext"
  48 #define kHTMLInfo      "text/_moz_htmlinfo"
  49
  50 // Holds the MIME type from the image request. This is used to ensure the
  51 // local application handler for the request's MIME type accepts images with
  52 // the given filename extension (from kFilePromiseDestFilename). When the
  53 // image is dragged out, we replace the extension with a compatible extension.
  54 #define kImageRequestMime           "text/x-moz-requestmime"
  55
  56 // the source URL for a file promise
  57 #define kFilePromiseURLMime         "application/x-moz-file-promise-url"
  58 // the destination filename for a file promise
  59 #define kFilePromiseDestFilename    "application/x-moz-file-promise-dest-filename"
  60 // a dataless flavor used to interact with the OS during file drags
  61 #define kFilePromiseMime            "application/x-moz-file-promise"
  62 // a synthetic flavor, put into the transferable once we know the destination directory of a file drag
  63 #define kFilePromiseDirectoryMime   "application/x-moz-file-promise-dir"
  64
  65 #define kCustomTypesMime "application/x-moz-custom-clipdata"
  66
  67 #define kPDFJSMime "application/pdfjs"
  68
  69 %}
  70
  71
  72 /**
  73   * nsIFlavorDataProvider allows a flavor to 'promise' data later,
  74   * supplying the data lazily.
  75   *
  76   * To use it, call setTransferData, passing the flavor string and
  77   * a nsIFlavorDataProvider QI'd to nsISupports.
  78   *
  79   * When someone calls getTransferData later, if the data size is
  80   * stored as 0, the nsISupports will be QI'd to nsIFlavorDataProvider,
  81   * and its getFlavorData called.
  82   *
  83   */
  84 interface nsITransferable;
  85 interface nsILoadContext;
  86
  87 [scriptable, uuid(7E225E5F-711C-11D7-9FAE-000393636592)]
  88 interface nsIFlavorDataProvider : nsISupports
  89 {
  90
  91   /**
  92     * Retrieve the data from this data provider.
  93     *
  94     * @param  aTransferable (in parameter) the transferable we're being called for.
  95     * @param  aFlavor (in parameter) the flavor of data to retrieve
  96     * @param  aData the data. Some variant of class in nsISupportsPrimitives.idl
  97     */
  98   void getFlavorData(in nsITransferable aTransferable, in string aFlavor, out nsISupports aData);
  99 };
 100
 101
 102 [scriptable, builtinclass, uuid(97e0c418-1c1e-4106-bad1-9fcb11dff2fe)]
 103 interface nsITransferable : nsISupports
 104 {
 105   /**
 106    * Initializes a transferable object.  This should be called on all
 107    * transferable objects.  Failure to do so will result in fatal assertions in
 108    * debug builds.
 109    *
 110    * The load context is used to track whether the transferable is storing privacy-
 111    * sensitive information.
 112    *
 113    * To get the appropriate load context in Javascript callers, one needs to get
 114    * to the document that the transferable corresponds to, and then get the load
 115    * context from the document like this:
 116    *
 117    * var loadContext = doc.defaultView.docShell
 118    *                                  .QueryInterface(Ci.nsILoadContext);
 119    *
 120    * In C++ callers, if you have the corresponding document, you can just call
 121    * Document::GetLoadContext to get to the load context object.
 122    *
 123    * @param aContext the load context associated with the transferable object.
 124    *        This can be set to null if a load context is not available.
 125    */
 126   void init(in nsILoadContext aContext);
 127
 128   /**
 129     * Computes a list of flavors that the transferable can export, either
 130     * through intrinsic knowledge or output data converters.
 131     */
 132   Array<ACString> flavorsTransferableCanExport();
 133
 134   /**
 135     * Given a flavor retrieve the data.
 136     *
 137     * @param  aFlavor (in parameter) the flavor of data to retrieve
 138     * @param  aData the data. Some variant of class in nsISupportsPrimitives.idl
 139     */
 140   [must_use] void getTransferData(in string aFlavor, out nsISupports aData);
 141
 142   /**
 143     * Returns the first flavor which has data.
 144     *
 145     * @param  aFlavor (out parameter) the flavor of data that was retrieved
 146     * @param  aData the data. Some variant of class in nsISupportsPrimitives.idl
 147     */
 148   void getAnyTransferData(out ACString aFlavor, out nsISupports aData);
 149
 150     ///////////////////////////////
 151     // Setter part of interface
 152     ///////////////////////////////
 153
 154   /**
 155     * Computes a list of flavors that the transferable can
 156     * accept into it, either through intrinsic knowledge or input data converters.
 157     *
 158     */
 159   Array<ACString> flavorsTransferableCanImport();
 160
 161   /**
 162     * Sets the data in the transferable with the specified flavor. The transferable
 163     * will maintain its own copy the data, so it is not necessary to do that beforehand.
 164     *
 165     * @param  aFlavor the flavor of data that is being set
 166     * @param  aData the data, either some variant of class in nsISupportsPrimitives.idl,
 167     *         an nsIFile, or an nsIFlavorDataProvider (see above)
 168     */
 169   void setTransferData(in string aFlavor, in nsISupports aData);
 170
 171   /**
 172     * Add the data flavor, indicating that this transferable
 173     * can receive this type of flavor
 174     *
 175     * @param  aDataFlavor a new data flavor to handle
 176     */
 177   void addDataFlavor ( in string aDataFlavor ) ;
 178
 179   /**
 180     * Removes the data flavor matching the given one (string compare) and the data
 181     * that goes along with it.
 182     *
 183     * @param  aDataFlavor a data flavor to remove
 184     */
 185   void removeDataFlavor ( in string aDataFlavor ) ;
 186
 187   attribute nsIFormatConverter converter;
 188
 189   /**
 190    * Use of the SetIsPrivateData() method generated by isPrivateData attribute should
 191    * be avoided as much as possible because the value set may not reflect the status
 192    * of the context in which the transferable was created.
 193    */
 194   [notxpcom, nostdcall] attribute boolean isPrivateData;
 195
 196   /**
 197    * The principal associated with this transferable. This could be either the
 198    * node principal of the source DOM node from which this transferable was
 199    * created, or the principal of the global from which this transferable was
 200    * created.
 201    * XXXedgar: Rename it to something more generic, bug 1867636.
 202    */
 203   [notxpcom, nostdcall] attribute nsIPrincipal requestingPrincipal;
 204
 205   /**
 206    * the contentPolicyType for this transferable.
 207    */
 208   [notxpcom, nostdcall] attribute nsContentPolicyType contentPolicyType;
 209
 210   /**
 211    * The cookieJarSettings of the source dom node this transferable was created
 212    * from.
 213    */
 214   [notxpcom, nostdcall] attribute nsICookieJarSettings cookieJarSettings;
 215
 216   /**
 217    * Used for initializing the referrer when downloading a file promise.
 218    */
 219   [notxpcom, nostdcall] attribute nsIReferrerInfo referrerInfo;
 220 };