netwerk/mime/nsIMIMEService.idl

   1 /* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 #include "nsISupports.idl"
   7
   8 interface nsIFile;
   9 interface nsIMIMEInfo;
  10 interface nsIURI;
  11 interface nsIChannel;
  12
  13 %{C++
  14 #define NS_MIMESERVICE_CID                           \
  15 { /* 03af31da-3109-11d3-8cd0-0060b0fc14a3 */         \
  16     0x03af31da,                                      \
  17     0x3109,                                          \
  18     0x11d3,                                          \
  19     {0x8c, 0xd0, 0x00, 0x60, 0xb0, 0xfc, 0x14, 0xa3} \
  20 }
  21 %}
  22
  23 /**
  24  * The MIME service is responsible for mapping file extensions to MIME-types
  25  * (see RFC 2045). It also provides access to nsIMIMEInfo interfaces and
  26  * acts as a general convenience wrapper of nsIMIMEInfo interfaces.
  27  *
  28  * The MIME service maintains a database with a <b>one</b> MIME type <b>to many</b>
  29  * file extensions rule. Adding the same file extension to multiple MIME types
  30  * is illegal and behavior is undefined.
  31  *
  32  * @see nsIMIMEInfo
  33  */
  34 [scriptable, main_process_scriptable_only, uuid(5b3675a1-02db-4f8f-a560-b34736635f47)]
  35 interface nsIMIMEService : nsISupports {
  36     /**
  37      * Retrieves an nsIMIMEInfo using both the extension
  38      * and the type of a file. The type is given preference
  39      * during the lookup. One of aMIMEType and aFileExt
  40      * can be an empty string. At least one of aMIMEType and aFileExt
  41      * must be nonempty.
  42      */
  43     nsIMIMEInfo getFromTypeAndExtension(in ACString aMIMEType, in AUTF8String aFileExt);
  44
  45     /**
  46      * Retrieves a ACString representation of the MIME type
  47      * associated with this file extension.
  48      *
  49      * @param  A file extension (excluding the dot ('.')).
  50      * @return The MIME type, if any.
  51      */
  52     ACString getTypeFromExtension(in AUTF8String aFileExt);
  53
  54     /**
  55      * Retrieves a ACString representation of the MIME type
  56      * associated with this URI. The association is purely
  57      * file extension to MIME type based. No attempt to determine
  58      * the type via server headers or byte scanning is made.
  59      *
  60      * @param  The URI the user wants MIME info on.
  61      * @return The MIME type, if any.
  62      */
  63     ACString getTypeFromURI(in nsIURI aURI);
  64
  65     /**
  66      * Retrieves a ACString representation of the MIME type
  67      * associated with this file extension.  Only the default
  68      * builtin list is examined.  Unless you need a restricted
  69      * set use getTypeFromURI.
  70      *
  71      * @param  The URI the user wants MIME info on.
  72      * @return The MIME type, if any.
  73      */
  74     ACString getDefaultTypeFromURI(in nsIURI aURI);
  75
  76     //
  77     ACString getTypeFromFile(in nsIFile aFile);
  78
  79     /**
  80      * Given a Type/Extension combination, returns the default extension
  81      * for this type. This may be identical to the passed-in extension.
  82      *
  83      * @param aMIMEType The Type to get information on. Must not be empty.
  84      * @param aFileExt  File Extension. Can be empty.
  85      */
  86     AUTF8String getPrimaryExtension(in ACString aMIMEType, in AUTF8String aFileExt);
  87
  88     /*
  89      * Returns an nsIMIMEInfo for the provided MIME type and extension
  90      * obtained from an OS lookup. If no handler is found for the type and
  91      * extension, returns a generic nsIMIMEInfo object. The MIME type and
  92      * extension can be the empty string. When the type and extension don't
  93      * map to the same handler, the semantics/resolution are platform
  94      * specific. See the platform implementations for details.
  95      *
  96      * @param aType           The MIME type to get handler information for.
  97      * @param aFileExtension  The filename extension to use either alone
  98      *                        or with the MIME type to get handler information
  99      *                        for. UTF-8 encoded.
 100      * @param [out] aFound    Out param indicating whether a MIMEInfo could
 101      *                        be found for the provided type and/or extension.
 102      *                        Set to false when neither extension nor the MIME
 103      *                        type are mapped to a handler.
 104      * @return                A nsIMIMEInfo object. This function must return
 105      *                        a MIMEInfo object if it can allocate one. The
 106      *                        only justifiable reason for not returning one is
 107      *                        an out-of-memory error.
 108      */
 109     nsIMIMEInfo getMIMEInfoFromOS(in ACString aType,
 110                                   in ACString aFileExtension,
 111                                   out boolean aFound);
 112
 113     /**
 114      * Update the mime info's default app information based on OS
 115      * lookups.
 116      * Note: normally called automatically by nsIMIMEInfo. If you find
 117      * yourself needing to call this from elsewhere, file a bug instead.
 118      */
 119     void updateDefaultAppInfo(in nsIMIMEInfo aMIMEInfo);
 120
 121     /**
 122      * Default filename validation for getValidFileName and
 123      * validateFileNameForSaving where other flags are not true.
 124      * That is, the extension is modified to fit the content type,
 125      * duplicate whitespace is collapsed, and long filenames are
 126      * truncated. A valid content type must be supplied. See the
 127      * description of getValidFileName for more details about how
 128      * the flags are used.
 129      */
 130     const long VALIDATE_DEFAULT = 0;
 131
 132     /**
 133      * If true, then the filename is only validated to ensure that it is
 134      * acceptable for the file system. If false, then the extension is also
 135      * checked to ensure that it is valid for the content type. If the
 136      * extension is not valid, the filename is modified to have the proper
 137      * extension.
 138      */
 139     const long VALIDATE_SANITIZE_ONLY = 1;
 140
 141     /**
 142      * Don't collapse strings of duplicate whitespace into a single string.
 143      */
 144     const long VALIDATE_DONT_COLLAPSE_WHITESPACE = 2;
 145
 146     /**
 147      * Don't truncate long filenames.
 148      */
 149     const long VALIDATE_DONT_TRUNCATE = 4;
 150
 151     /**
 152      * True to ignore the content type and guess the type from any existing
 153      * extension instead. "application/octet-stream" is used as the default
 154      * if there is no extension or there is no information available for
 155      * the extension.
 156      */
 157     const long VALIDATE_GUESS_FROM_EXTENSION = 8;
 158
 159     /**
 160      * If the filename is empty, return the empty filename
 161      * without modification.
 162      */
 163     const long VALIDATE_ALLOW_EMPTY = 16;
 164
 165     /**
 166      * Don't apply a default filename if the non-extension portion of the
 167      * filename is empty.
 168      */
 169     const long VALIDATE_NO_DEFAULT_FILENAME = 32;
 170
 171     /**
 172      * When the filename has an invalid extension, force the the filename to
 173      * have a valid extension appended to the end of the filename when that
 174      * extension would normally be ignored for the given content type. This
 175      * primarily is used when saving pages to ensure that the html extension
 176      * is applied over any extension that might have been generated from a
 177      * page title.
 178      */
 179     const long VALIDATE_FORCE_APPEND_EXTENSION = 64;
 180
 181     /**
 182      * Don't modify filenames or extensions that might be invalid or dangerous
 183      * on some platforms. If this flag is not used, these filenames will be
 184      * modified so that the operating system does not treat them specially.
 185      */
 186     const long VALIDATE_ALLOW_INVALID_FILENAMES = 128;
 187
 188     /**
 189      * Generate a valid filename from the channel that can be used to save
 190      * the content of the channel to the local disk.
 191      *
 192      * The filename is determined from the content disposition, the filename
 193      * of the uri, or a default filename. The following modifications are
 194      * applied:
 195      *  - If the VALIDATE_SANITIZE_ONLY flag is not specified, then the
 196      *    extension of the filename is modified to suit the supplied content type.
 197      *  - Path separators (typically / and \) are replaced by underscores (_)
 198      *  - Characters that are not valid or would be confusing in filenames are
 199      *    replaced by spaces (*, :, etc)
 200      *  - Bidi related marks are replaced by underscores (_)
 201      *  - Whitespace and periods are removed from the beginning and end.
 202      *  - Unless VALIDATE_DONT_COLLAPSE_WHITESPACE is specified, multiple
 203      *    consecutive whitespace characters are collapsed to a single space
 204      *    character, either ' ' or an ideographic space 0x3000 if present.
 205      *  - Unless VALIDATE_DONT_TRUNCATE is specified, the filename is truncated
 206      *    to a maximum length, preserving the extension if possible.
 207      *  - Some filenames and extensions are invalid on certain platforms.
 208      *    These are replaced if possible unless VALIDATE_ALLOW_INVALID_FILENAMES
 209      *    is specified.
 210      *
 211      * If the VALIDATE_NO_DEFAULT_FILENAME flag is not specified, and after the
 212      * rules above are applied, the resulting filename is empty, a default
 213      * filename is used.
 214      *
 215      * If the VALIDATE_ALLOW_EMPTY flag is specified, an empty string may be
 216      * returned only if the filename could not be determined or was blank.
 217      *
 218      * If either the VALIDATE_SANITIZE_ONLY or VALIDATE_GUESS_FROM_EXTENSION flags
 219      * are specified, then the content type may be empty. Otherwise, the type must
 220      * not be empty.
 221      *
 222      * The aOriginalURI would be specified if the channel is for a local file but
 223      * it was originally sourced from a different uri.
 224      *
 225      * When saving an image, use validateFileNameForSaving instead and
 226      * pass the result of imgIRequest::GetFileName() as the filename to
 227      * check.
 228      *
 229      * @param aChannel The channel of the content to save.
 230      * @param aType The MIME type to use, which would usually be the
 231      *              same as the content type of the channel.
 232      * @param aOriginalURL the source url of the file, but may be null.
 233      * @param aFlags one or more of the flags above.
 234      * @returns The resulting filename.
 235      */
 236     AString getValidFileName(in nsIChannel aChannel,
 237                              in ACString aType,
 238                              in nsIURI aOriginalURI,
 239                              in unsigned long aFlags);
 240
 241     /**
 242      * Similar to getValidFileName, but used when a specific filename needs
 243      * to be validated. The filename is modified as needed based on the
 244      * content type in the same manner as getValidFileName.
 245      *
 246      * If the filename came from a uri, it should not be escaped, that is,
 247      * any needed unescaping of the filename should happen before calling
 248      * this method.
 249      *
 250      * @param aType The MIME type to use.
 251      * @param aFlags one or more of the flags above.
 252      * @param aFileName The filename to validate.
 253      * @returns The validated filename.
 254      */
 255     AString validateFileNameForSaving(in AString aFileName,
 256                                       in ACString aType,
 257                                       in unsigned long aFlags);
 258 };