summaryrefslogtreecommitdiff
path: root/widget/nsITransferable.idl
blob: b128586dd1ea6fdc116edaf39b2c9623ab90ddd5 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
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;

};