summaryrefslogtreecommitdiffstats
path: root/netwerk/mime/nsIMIMEInfo.idl
blob: 64172e14e98fbd7e021eec9f3ff5aa98c37a4e4b (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
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
/* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/* 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 "nsISupports.idl"

interface nsIURI;
interface nsIFile;
interface nsIUTF8StringEnumerator;
interface nsIHandlerApp;
interface nsIArray;
interface nsIMutableArray;
interface nsIInterfaceRequestor;

typedef long nsHandlerInfoAction;

/**
 * nsIHandlerInfo gives access to the information about how a given protocol
 * scheme or MIME-type is handled.
 */
[scriptable, uuid(325e56a7-3762-4312-aec7-f1fcf84b4145)] 
interface nsIHandlerInfo : nsISupports {
    /**
     * The type of this handler info.  For MIME handlers, this is the MIME type.
     * For protocol handlers, it's the scheme.
     * 
     * @return String representing the type.
     */
    readonly attribute ACString type;

    /**
     * A human readable description of the handler type
     */
    attribute AString description;

    /**
     * The application the user has said they want associated with this content
     * type. This is not always guaranteed to be set!!
     */
    attribute nsIHandlerApp preferredApplicationHandler;

    /**
     * Applications that can handle this content type.
     *
     * The list will include the preferred handler, if any.  Elements of this
     * array are nsIHandlerApp objects, and this attribute will always reference
     * an array, whether or not there are any possible handlers.  If there are
     * no possible handlers, the array will contain no elements, so just check
     * its length (nsIArray::length) to see if there are any possible handlers.
     */
    readonly attribute nsIMutableArray possibleApplicationHandlers;

    /**
     * Indicates whether a default application handler exists,
     * i.e. whether launchWithFile with action = useSystemDefault is possible
     * and defaultDescription will contain usable information.
     */
    readonly attribute boolean hasDefaultHandler;

    /**
     * A pretty name description of the associated default application. Only
     * usable if hasDefaultHandler is true.
     */
    readonly attribute AString defaultDescription;

    /**
     * Launches the application with the specified URI, in a way that
     * depends on the value of preferredAction. preferredAction must be
     * useHelperApp or useSystemDefault.
     *  
     * @note Only the URI scheme is used to determine how to launch.  This is
     * essentially a pass-by-value operation.  This means that in the case of
     * a file: URI, the handler that is registered for file: will be launched
     * and our code will not make any decision based on the content-type or
     * extension, though the invoked file: handler is free to do so. 
     *
     * @param aURI
     *        The URI to launch this application with
     *
     * @param aWindowContext 
     *        The window to parent the dialog against, and, if a web handler
     *        is chosen, it is loaded in this window as well.  See 
     *        nsIHandlerApp.launchWithURI for more details.
     *
     * @throw NS_ERROR_INVALID_ARG if preferredAction is not valid for this
     * call. Other exceptions may be thrown.
     */
    void launchWithURI(in nsIURI aURI, 
                       [optional] in nsIInterfaceRequestor aWindowContext);

    /**
     * preferredAction is how the user specified they would like to handle
     * this content type: save to disk, use specified helper app, use OS
     * default handler or handle using navigator; possible value constants
     * listed below
     */
    attribute nsHandlerInfoAction preferredAction;

    const long saveToDisk = 0;
    /**
     * Used to indicate that we know nothing about what to do with this.  You
     * could consider this to be not initialized.
     */
    const long alwaysAsk = 1;
    const long useHelperApp = 2;
    const long handleInternally = 3;
    const long useSystemDefault = 4;

    /**
     * alwaysAskBeforeHandling: if true, we should always give the user a
     * dialog asking how to dispose of this content.
     */
    attribute boolean alwaysAskBeforeHandling;
};

/**
 * nsIMIMEInfo extends nsIHandlerInfo with a bunch of information specific to
 * MIME content-types. There is a one-to-many relationship between MIME types
 * and file extensions. This means that a MIMEInfo object may have multiple
 * file extensions associated with it.  However, the reverse is not true.
 *
 * MIMEInfo objects are generally retrieved from the MIME Service
 * @see nsIMIMEService
 */
[scriptable, uuid(1c21acef-c7a1-40c6-9d40-a20480ee53a1)]
interface nsIMIMEInfo : nsIHandlerInfo {
    /**
     * Gives you an array of file types associated with this type.
     *
     * @return Number of elements in the array.
     * @return Array of extensions.
     */
    nsIUTF8StringEnumerator getFileExtensions();

    /**
     * Set File Extensions. Input is a comma delimited list of extensions.
     */
    void setFileExtensions(in AUTF8String aExtensions);
 
    /**
     * Returns whether or not the given extension is
     * associated with this MIME info.
     *
     * @return TRUE if the association exists. 
     */
    boolean extensionExists(in AUTF8String aExtension);

    /**
     * Append a given extension to the set of extensions
     */
    void appendExtension(in AUTF8String aExtension);

    /**
     * Returns the first extension association in
     * the internal set of extensions.
     *
     * @return The first extension.
     */
    attribute AUTF8String primaryExtension;
    
    /**
     * The MIME type of this MIMEInfo.
     * 
     * @return String representing the MIME type.
     * 
     * @deprecated  use nsIHandlerInfo::type instead.
     */
    readonly attribute ACString MIMEType;

    /**
     * Returns whether or not these two nsIMIMEInfos are logically
     * equivalent.
     *
     * @returns PR_TRUE if the two are considered equal
     */
    boolean equals(in nsIMIMEInfo aMIMEInfo);

    /** 
     * Returns a list of nsILocalHandlerApp objects containing
     * handlers associated with this mimeinfo. Implemented per 
     * platform using information in this object to generate the
     * best list. Typically used for an "open with" style user 
     * option.
     * 
     * @return nsIArray of nsILocalHandlerApp
     */
    readonly attribute nsIArray possibleLocalHandlers;

    /**
     * Launches the application with the specified file, in a way that
     * depends on the value of preferredAction. preferredAction must be
     * useHelperApp or useSystemDefault.
     *
     * @param aFile The file to launch this application with.
     *
     * @throw NS_ERROR_INVALID_ARG if action is not valid for this function.
     * Other exceptions may be thrown.
     */
    void launchWithFile(in nsIFile aFile);
};

/**
 * nsIHandlerApp represents an external application that can handle content
 * of some sort (either a MIME type or a protocol).
 *
 * FIXME: now that we've made nsIWebHandlerApp inherit from nsIHandlerApp,
 * we should also try to make nsIWebContentHandlerInfo inherit from or possibly
 * be replaced by nsIWebHandlerApp (bug 394710).
 */
[scriptable, uuid(8BDF20A4-9170-4548-AF52-78311A44F920)]
interface nsIHandlerApp : nsISupports {

    /**
     * Human readable name for the handler
     */
    attribute AString name;

    /**
     * Detailed description for this handler. Suitable for
     * a tooltip or short informative sentence.
     */
    attribute AString detailedDescription;

    /**
     * Whether or not the given handler app is logically equivalent to the
     * invokant (i.e. they represent the same app).
     * 
     * Two apps are the same if they are both either local or web handlers
     * and their executables/URI templates and command line parameters are
     * the same.
     *
     * @param aHandlerApp the handler app to compare to the invokant
     *
     * @returns true if the two are logically equivalent, false otherwise
     */
    boolean equals(in nsIHandlerApp aHandlerApp);

    /**
     * Launches the application with the specified URI.
     *
     * @param aURI
     *        The URI to launch this application with
     *
     * @param aWindowContext 
     *
     *        Currently only relevant to web-handler apps.  If given, this
     *        represents the docshell to load the handler in and is passed
     *        through to nsIURILoader.openURI.  If this parameter is null or
     *        not present, the web handler app implementation will attempt to 
     *        find/create a place to load the handler and do so.  As of this
     *        writing, it tries to load the web handler in a new window using
     *        nsIBrowserDOMWindow.openURI.  In the future, it may attempt to 
     *        have a more comprehensive strategy which could include handing
     *        off to the system default browser (bug 394479).
     */
    void launchWithURI(in nsIURI aURI, 
                       [optional] in nsIInterfaceRequestor aWindowContext);

};

/**
 * nsILocalHandlerApp is a local OS-level executable
 */
[scriptable, uuid(D36B6329-52AE-4f45-80F4-B2536AE5F8B2)]
interface nsILocalHandlerApp : nsIHandlerApp {

    /**
     * Pointer to the executable file used to handle content
     */
    attribute nsIFile executable;

    /**
     * Returns the current number of command line parameters.
     */
    readonly attribute unsigned long parameterCount;

    /**
     * Clears the current list of command line parameters.
     */
    void clearParameters();

    /**
     * Appends a command line parameter to the command line
     * parameter list.
     *
     * @param param the parameter to add.
     */
    void appendParameter(in AString param);

    /**
     * Retrieves a specific command line parameter.
     *
     * @param param the index of the parameter to return.
     *
     * @return the parameter string.
     *
     * @throw NS_ERROR_INVALID_ARG if the index is out of range.
     */
    AString getParameter(in unsigned long parameterIndex);

    /**
     * Checks to see if a parameter exists in the command line
     * parameter list.
     *
     * @param param the parameter to search for.
     *
     * @return TRUE if the parameter exists in the current list. 
     */
    boolean parameterExists(in AString param);
};

/**
 * nsIWebHandlerApp is a web-based handler, as speced by the WhatWG HTML5
 * draft.  Currently, only GET-based handlers are supported.  At some point, 
 * we probably want to work with WhatWG to spec out and implement POST-based
 * handlers as well.
 */
[scriptable, uuid(7521a093-c498-45ce-b462-df7ba0d882f6)]
interface nsIWebHandlerApp : nsIHandlerApp {

    /**
     * Template used to construct the URI to GET.  Template is expected to have
     * a %s in it, and the escaped URI to be handled is inserted in place of 
     * that %s, as per the HTML5 spec.
     */
    attribute AUTF8String uriTemplate;
};

/**
 * nsIDBusHandlerApp represents local applications launched by DBus a message
 * invoking a method taking a single string argument descibing a URI
 */
[scriptable, uuid(1ffc274b-4cbf-4bb5-a635-05ad2cbb6534)]
interface nsIDBusHandlerApp : nsIHandlerApp {

    /**
     * Service defines the dbus service that should handle this protocol.
     * If its not set,  NS_ERROR_FAILURE will be returned by LaunchWithURI
     */
    attribute AUTF8String service;
    
    /**
     * Objpath defines the object path of the dbus service that should handle 
     * this protocol. If its not set,  NS_ERROR_FAILURE will be returned 
     * by LaunchWithURI
     */
    attribute AUTF8String objectPath;

    /**
     * DBusInterface defines the interface of the dbus service that should 
     * handle this protocol. If its not set,  NS_ERROR_FAILURE will be  
     * returned by LaunchWithURI
     */
    attribute AUTF8String dBusInterface;
    
    /**
     * Method defines the dbus method that should be invoked to handle this 
     * protocol. If its not set,  NS_ERROR_FAILURE will be returned by 
     * LaunchWithURI
     */
    attribute AUTF8String method;
    
};