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