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