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