1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/widget/nsITransferable.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,198 @@
1.4 +/* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
1.5 + *
1.6 + * This Source Code Form is subject to the terms of the Mozilla Public
1.7 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.8 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.9 +
1.10 +#include "nsISupports.idl"
1.11 +#include "nsISupportsArray.idl"
1.12 +#include "nsIFormatConverter.idl"
1.13 +
1.14 +
1.15 +%{ C++
1.16 +
1.17 +// these probably shouldn't live here, but in some central repository shared
1.18 +// by the entire app.
1.19 +#define kTextMime "text/plain"
1.20 +#define kUnicodeMime "text/unicode"
1.21 +#define kMozTextInternal "text/x-moz-text-internal" // text data which isn't suppoed to be parsed by other apps.
1.22 +#define kHTMLMime "text/html"
1.23 +#define kAOLMailMime "AOLMAIL"
1.24 +#define kPNGImageMime "image/png"
1.25 +#define kJPEGImageMime "image/jpeg"
1.26 +#define kJPGImageMime "image/jpg"
1.27 +#define kGIFImageMime "image/gif"
1.28 +#define kFileMime "application/x-moz-file"
1.29 +
1.30 +#define kURLMime "text/x-moz-url" // data contains url\ntitle
1.31 +#define kURLDataMime "text/x-moz-url-data" // data contains url only
1.32 +#define kURLDescriptionMime "text/x-moz-url-desc" // data contains description
1.33 +#define kURLPrivateMime "text/x-moz-url-priv" // same as kURLDataMime but for private uses
1.34 +#define kNativeImageMime "application/x-moz-nativeimage"
1.35 +#define kNativeHTMLMime "application/x-moz-nativehtml"
1.36 +
1.37 +// These are used to indicate the context for a fragment of HTML source, such
1.38 +// that some parent structure and style can be preserved. kHTMLContext
1.39 +// contains the serialized ancestor elements, whereas kHTMLInfo are numbers
1.40 +// identifying where in the context the fragment was from.
1.41 +#define kHTMLContext "text/_moz_htmlcontext"
1.42 +#define kHTMLInfo "text/_moz_htmlinfo"
1.43 +
1.44 +// the source URL for a file promise
1.45 +#define kFilePromiseURLMime "application/x-moz-file-promise-url"
1.46 +// the destination filename for a file promise
1.47 +#define kFilePromiseDestFilename "application/x-moz-file-promise-dest-filename"
1.48 +// a dataless flavor used to interact with the OS during file drags
1.49 +#define kFilePromiseMime "application/x-moz-file-promise"
1.50 +// a synthetic flavor, put into the transferable once we know the destination directory of a file drag
1.51 +#define kFilePromiseDirectoryMime "application/x-moz-file-promise-dir"
1.52 +
1.53 +%}
1.54 +
1.55 +
1.56 +/**
1.57 + * nsIFlavorDataProvider allows a flavor to 'promise' data later,
1.58 + * supplying the data lazily.
1.59 + *
1.60 + * To use it, call setTransferData, passing the flavor string,
1.61 + * a nsIFlavorDataProvider QI'd to nsISupports, and a data size of 0.
1.62 + *
1.63 + * When someone calls getTransferData later, if the data size is
1.64 + * stored as 0, the nsISupports will be QI'd to nsIFlavorDataProvider,
1.65 + * and its getFlavorData called.
1.66 + *
1.67 + */
1.68 +interface nsITransferable;
1.69 +interface nsILoadContext;
1.70 +
1.71 +[scriptable, uuid(7E225E5F-711C-11D7-9FAE-000393636592)]
1.72 +interface nsIFlavorDataProvider : nsISupports
1.73 +{
1.74 +
1.75 + /**
1.76 + * Retrieve the data from this data provider.
1.77 + *
1.78 + * @param aTransferable (in parameter) the transferable we're being called for.
1.79 + * @param aFlavor (in parameter) the flavor of data to retrieve
1.80 + * @param aData the data. Some variant of class in nsISupportsPrimitives.idl
1.81 + * @param aDataLen the length of the data
1.82 + */
1.83 + void getFlavorData(in nsITransferable aTransferable, in string aFlavor, out nsISupports aData, out unsigned long aDataLen);
1.84 +};
1.85 +
1.86 +
1.87 +[scriptable, uuid(5a611a60-e5b5-11e1-aff1-0800200c9a66)]
1.88 +interface nsITransferable : nsISupports
1.89 +{
1.90 + const long kFlavorHasDataProvider = 0;
1.91 +
1.92 + /**
1.93 + * Initializes a transferable object. This should be called on all
1.94 + * transferable objects. Failure to do so will result in fatal assertions in
1.95 + * debug builds.
1.96 + *
1.97 + * The load context is used to track whether the transferable is storing privacy-
1.98 + * sensitive information. For example, we try to delete data that you copy
1.99 + * to the clipboard when you close a Private Browsing window.
1.100 + *
1.101 + * To get the appropriate load context in Javascript callers, one needs to get
1.102 + * to the document that the transferable corresponds to, and then get the load
1.103 + * context from the document like this:
1.104 + *
1.105 + * var loadContext = doc.defaultView.QueryInterface(Ci.nsIInterfaceRequestor)
1.106 + * .getInterface(Ci.nsIWebNavigation)
1.107 + * .QueryInterface(Ci.nsILoadContext);
1.108 + *
1.109 + * In C++ callers, if you have the corresponding document, you can just call
1.110 + * nsIDocument::GetLoadContext to get to the load context object.
1.111 + *
1.112 + * @param aContext the load context associated with the transferable object.
1.113 + * This can be set to null if a load context is not available.
1.114 + */
1.115 + void init(in nsILoadContext aContext);
1.116 +
1.117 + /**
1.118 + * Computes a list of flavors (mime types as nsISupportsCString) that the transferable
1.119 + * can export, either through intrinsic knowledge or output data converters.
1.120 + *
1.121 + * @param aDataFlavorList fills list with supported flavors. This is a copy of
1.122 + * the internal list, so it may be edited w/out affecting the transferable.
1.123 + */
1.124 + nsISupportsArray flavorsTransferableCanExport ( ) ;
1.125 +
1.126 + /**
1.127 + * Given a flavor retrieve the data.
1.128 + *
1.129 + * @param aFlavor (in parameter) the flavor of data to retrieve
1.130 + * @param aData the data. Some variant of class in nsISupportsPrimitives.idl
1.131 + * @param aDataLen the length of the data
1.132 + */
1.133 + void getTransferData ( in string aFlavor, out nsISupports aData, out unsigned long aDataLen ) ;
1.134 +
1.135 + /**
1.136 + * Returns the best flavor in the transferable, given those that have
1.137 + * been added to it with |AddFlavor()|
1.138 + *
1.139 + * @param aFlavor (out parameter) the flavor of data that was retrieved
1.140 + * @param aData the data. Some variant of class in nsISupportsPrimitives.idl
1.141 + * @param aDataLen the length of the data
1.142 + */
1.143 + void getAnyTransferData ( out string aFlavor, out nsISupports aData, out unsigned long aDataLen ) ;
1.144 +
1.145 + /**
1.146 + * Returns true if the data is large.
1.147 + */
1.148 + boolean isLargeDataSet ( ) ;
1.149 +
1.150 +
1.151 + ///////////////////////////////
1.152 + // Setter part of interface
1.153 + ///////////////////////////////
1.154 +
1.155 + /**
1.156 + * Computes a list of flavors (mime types as nsISupportsCString) that the transferable can
1.157 + * accept into it, either through intrinsic knowledge or input data converters.
1.158 + *
1.159 + * @param outFlavorList fills list with supported flavors. This is a copy of
1.160 + * the internal list, so it may be edited w/out affecting the transferable.
1.161 + */
1.162 + nsISupportsArray flavorsTransferableCanImport ( ) ;
1.163 +
1.164 + /**
1.165 + * Sets the data in the transferable with the specified flavor. The transferable
1.166 + * will maintain its own copy the data, so it is not necessary to do that beforehand.
1.167 + *
1.168 + * @param aFlavor the flavor of data that is being set
1.169 + * @param aData the data, either some variant of class in nsISupportsPrimitives.idl,
1.170 + * an nsIFile, or an nsIFlavorDataProvider (see above)
1.171 + * @param aDataLen the length of the data, or 0 if passing a nsIFlavorDataProvider
1.172 + */
1.173 + void setTransferData ( in string aFlavor, in nsISupports aData, in unsigned long aDataLen ) ;
1.174 +
1.175 + /**
1.176 + * Add the data flavor, indicating that this transferable
1.177 + * can receive this type of flavor
1.178 + *
1.179 + * @param aDataFlavor a new data flavor to handle
1.180 + */
1.181 + void addDataFlavor ( in string aDataFlavor ) ;
1.182 +
1.183 + /**
1.184 + * Removes the data flavor matching the given one (string compare) and the data
1.185 + * that goes along with it.
1.186 + *
1.187 + * @param aDataFlavor a data flavor to remove
1.188 + */
1.189 + void removeDataFlavor ( in string aDataFlavor ) ;
1.190 +
1.191 + attribute nsIFormatConverter converter;
1.192 +
1.193 + /**
1.194 + * Use of the SetIsPrivateData() method generated by isPrivateData attribute should
1.195 + * be avoided as much as possible because the value set may not reflect the status
1.196 + * of the context in which the transferable was created.
1.197 + */
1.198 + [noscript] attribute boolean isPrivateData;
1.199 +
1.200 +};
1.201 +
