summaryrefslogtreecommitdiffstats
path: root/netwerk/mime/nsIMIMEService.idl
blob: 717f595c50eb8407c1dfb9f8d01f626dffa7f643 (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
/* -*- 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 nsIFile;
interface nsIMIMEInfo;
interface nsIURI;
interface nsIChannel;

/**
 * The MIME service is responsible for mapping file extensions to MIME-types
 * (see RFC 2045). It also provides access to nsIMIMEInfo interfaces and
 * acts as a general convenience wrapper of nsIMIMEInfo interfaces.
 *
 * The MIME service maintains a database with a <b>one</b> MIME type <b>to many</b>
 * file extensions rule. Adding the same file extension to multiple MIME types
 * is illegal and behavior is undefined.
 *
 * @see nsIMIMEInfo
 */
[scriptable, main_process_scriptable_only, uuid(5b3675a1-02db-4f8f-a560-b34736635f47)]
interface nsIMIMEService : nsISupports {
    /**
     * Retrieves an nsIMIMEInfo using both the extension
     * and the type of a file. The type is given preference
     * during the lookup. One of aMIMEType and aFileExt
     * can be an empty string. At least one of aMIMEType and aFileExt
     * must be nonempty.
     */
    nsIMIMEInfo getFromTypeAndExtension(in ACString aMIMEType, in AUTF8String aFileExt);

    /**
     * Retrieves a ACString representation of the MIME type
     * associated with this file extension.
     *
     * @param  A file extension (excluding the dot ('.')).
     * @return The MIME type, if any.
     */
    ACString getTypeFromExtension(in AUTF8String aFileExt);

    /**
     * Retrieves a ACString representation of the MIME type
     * associated with this URI. The association is purely
     * file extension to MIME type based. No attempt to determine
     * the type via server headers or byte scanning is made.
     *
     * @param  The URI the user wants MIME info on.
     * @return The MIME type, if any.
     */
    ACString getTypeFromURI(in nsIURI aURI);

    /**
     * Retrieves a ACString representation of the MIME type
     * associated with this file extension.  Only the default
     * builtin list is examined.  Unless you need a restricted
     * set use getTypeFromURI.
     *
     * @param  The URI the user wants MIME info on.
     * @return The MIME type, if any.
     */
    ACString getDefaultTypeFromURI(in nsIURI aURI);

    //
    ACString getTypeFromFile(in nsIFile aFile);

    /**
     * Given a Type/Extension combination, returns the default extension
     * for this type. This may be identical to the passed-in extension.
     *
     * @param aMIMEType The Type to get information on. Must not be empty.
     * @param aFileExt  File Extension. Can be empty.
     */
    AUTF8String getPrimaryExtension(in ACString aMIMEType, in AUTF8String aFileExt);

    /*
     * Returns an nsIMIMEInfo for the provided MIME type and extension
     * obtained from an OS lookup. If no handler is found for the type and
     * extension, returns a generic nsIMIMEInfo object. The MIME type and
     * extension can be the empty string. When the type and extension don't
     * map to the same handler, the semantics/resolution are platform
     * specific. See the platform implementations for details.
     *
     * @param aType           The MIME type to get handler information for.
     * @param aFileExtension  The filename extension to use either alone
     *                        or with the MIME type to get handler information
     *                        for. UTF-8 encoded.
     * @param [out] aFound    Out param indicating whether a MIMEInfo could
     *                        be found for the provided type and/or extension.
     *                        Set to false when neither extension nor the MIME
     *                        type are mapped to a handler.
     * @return                A nsIMIMEInfo object. This function must return
     *                        a MIMEInfo object if it can allocate one. The
     *                        only justifiable reason for not returning one is
     *                        an out-of-memory error.
     */
    nsIMIMEInfo getMIMEInfoFromOS(in ACString aType,
                                  in ACString aFileExtension,
                                  out boolean aFound);

    /**
     * Update the mime info's default app information based on OS
     * lookups.
     * Note: normally called automatically by nsIMIMEInfo. If you find
     * yourself needing to call this from elsewhere, file a bug instead.
     */
    void updateDefaultAppInfo(in nsIMIMEInfo aMIMEInfo);

    /**
     * Default filename validation for getValidFileName and
     * validateFileNameForSaving where other flags are not true.
     * That is, the extension is modified to fit the content type,
     * duplicate whitespace is collapsed, and long filenames are
     * truncated. A valid content type must be supplied. See the
     * description of getValidFileName for more details about how
     * the flags are used.
     */
    const long VALIDATE_DEFAULT = 0;

    /**
     * If true, then the filename is only validated to ensure that it is
     * acceptable for the file system. If false, then the extension is also
     * checked to ensure that it is valid for the content type. If the
     * extension is not valid, the filename is modified to have the proper
     * extension.
     */
    const long VALIDATE_SANITIZE_ONLY = 1;

    /**
     * Don't collapse strings of duplicate whitespace into a single string.
     */
    const long VALIDATE_DONT_COLLAPSE_WHITESPACE = 2;

    /**
     * Don't truncate long filenames.
     */
    const long VALIDATE_DONT_TRUNCATE = 4;

    /**
     * True to ignore the content type and guess the type from any existing
     * extension instead. "application/octet-stream" is used as the default
     * if there is no extension or there is no information available for
     * the extension.
     */
    const long VALIDATE_GUESS_FROM_EXTENSION = 8;

    /**
     * If the filename is empty, return the empty filename
     * without modification.
     */
    const long VALIDATE_ALLOW_EMPTY = 16;

    /**
     * Don't apply a default filename if the non-extension portion of the
     * filename is empty.
     */
    const long VALIDATE_NO_DEFAULT_FILENAME = 32;

    /**
     * When the filename has an invalid extension, force the the filename to
     * have a valid extension appended to the end of the filename when that
     * extension would normally be ignored for the given content type. This
     * primarily is used when saving pages to ensure that the html extension
     * is applied over any extension that might have been generated from a
     * page title.
     */
    const long VALIDATE_FORCE_APPEND_EXTENSION = 64;

    /**
     * Don't modify filenames or extensions that might be invalid or dangerous
     * on some platforms. If this flag is not used, these filenames will be
     * modified so that the operating system does not treat them specially.
     */
    const long VALIDATE_ALLOW_INVALID_FILENAMES = 128;

    /**
     * Generate a valid filename from the channel that can be used to save
     * the content of the channel to the local disk.
     *
     * The filename is determined from the content disposition, the filename
     * of the uri, or a default filename. The following modifications are
     * applied:
     *  - If the VALIDATE_SANITIZE_ONLY flag is not specified, then the
     *    extension of the filename is modified to suit the supplied content type.
     *  - Path separators (typically / and \) are replaced by underscores (_)
     *  - Characters that are not valid or would be confusing in filenames are
     *    replaced by spaces (*, :, etc)
     *  - Bidi related marks are replaced by underscores (_)
     *  - Whitespace and periods are removed from the beginning and end.
     *  - Unless VALIDATE_DONT_COLLAPSE_WHITESPACE is specified, multiple
     *    consecutive whitespace characters are collapsed to a single space
     *    character, either ' ' or an ideographic space 0x3000 if present.
     *  - Unless VALIDATE_DONT_TRUNCATE is specified, the filename is truncated
     *    to a maximum length, preserving the extension if possible.
     *  - Some filenames and extensions are invalid on certain platforms.
     *    These are replaced if possible unless VALIDATE_ALLOW_INVALID_FILENAMES
     *    is specified.
     *
     * If the VALIDATE_NO_DEFAULT_FILENAME flag is not specified, and after the
     * rules above are applied, the resulting filename is empty, a default
     * filename is used.
     *
     * If the VALIDATE_ALLOW_EMPTY flag is specified, an empty string may be
     * returned only if the filename could not be determined or was blank.
     *
     * If either the VALIDATE_SANITIZE_ONLY or VALIDATE_GUESS_FROM_EXTENSION flags
     * are specified, then the content type may be empty. Otherwise, the type must
     * not be empty.
     *
     * The aOriginalURI would be specified if the channel is for a local file but
     * it was originally sourced from a different uri.
     *
     * When saving an image, use validateFileNameForSaving instead and
     * pass the result of imgIRequest::GetFileName() as the filename to
     * check.
     *
     * @param aChannel The channel of the content to save.
     * @param aType The MIME type to use, which would usually be the
     *              same as the content type of the channel.
     * @param aOriginalURL the source url of the file, but may be null.
     * @param aFlags one or more of the flags above.
     * @returns The resulting filename.
     */
    AString getValidFileName(in nsIChannel aChannel,
                             in ACString aType,
                             in nsIURI aOriginalURI,
                             in unsigned long aFlags);

    /**
     * Similar to getValidFileName, but used when a specific filename needs
     * to be validated. The filename is modified as needed based on the
     * content type in the same manner as getValidFileName.
     *
     * If the filename came from a uri, it should not be escaped, that is,
     * any needed unescaping of the filename should happen before calling
     * this method.
     *
     * @param aType The MIME type to use.
     * @param aFlags one or more of the flags above.
     * @param aFileName The filename to validate.
     * @returns The validated filename.
     */
    AString validateFileNameForSaving(in AString aFileName,
                                      in ACString aType,
                                      in unsigned long aFlags);
};