nsIMIMEInfo.idl (13150B)
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 nsIURI; 9 interface nsIFile; 10 interface nsIUTF8StringEnumerator; 11 interface nsIHandlerApp; 12 interface nsIArray; 13 interface nsIMutableArray; 14 interface nsIInterfaceRequestor; 15 webidl BrowsingContext; 16 17 typedef long nsHandlerInfoAction; 18 19 /** 20 * nsIHandlerInfo gives access to the information about how a given protocol 21 * scheme or MIME-type is handled. 22 */ 23 [scriptable, uuid(325e56a7-3762-4312-aec7-f1fcf84b4145)] 24 interface nsIHandlerInfo : nsISupports { 25 /** 26 * The type of this handler info. For MIME handlers, this is the MIME type. 27 * For protocol handlers, it's the scheme. 28 * 29 * @return String representing the type. 30 */ 31 readonly attribute ACString type; 32 33 /** 34 * A human readable description of the handler type 35 */ 36 attribute AString description; 37 38 /** 39 * The application the user has said they want associated with this content 40 * type. This is not always guaranteed to be set!! 41 */ 42 attribute nsIHandlerApp preferredApplicationHandler; 43 44 /** 45 * Applications that can handle this content type. 46 * 47 * The list will include the preferred handler, if any. Elements of this 48 * array are nsIHandlerApp objects, and this attribute will always reference 49 * an array, whether or not there are any possible handlers. If there are 50 * no possible handlers, the array will contain no elements, so just check 51 * its length (nsIArray::length) to see if there are any possible handlers. 52 */ 53 readonly attribute nsIMutableArray possibleApplicationHandlers; 54 55 /** 56 * Indicates whether a default OS application handler exists, 57 * i.e. whether launchWithFile with action = useSystemDefault is possible 58 * and defaultDescription will contain usable information. 59 */ 60 readonly attribute boolean hasDefaultHandler; 61 62 /** 63 * A pretty name description of the associated default OS application. Only 64 * usable if hasDefaultHandler is true. 65 */ 66 readonly attribute AString defaultDescription; 67 68 /** 69 * The default OS application. Only usable if hasDefaultHandler is true. 70 */ 71 readonly attribute nsIFile defaultExecutable; 72 73 /** 74 * Launches the application with the specified URI, in a way that 75 * depends on the value of preferredAction. preferredAction must be 76 * useHelperApp or useSystemDefault. 77 * 78 * @note Only the URI scheme is used to determine how to launch. This is 79 * essentially a pass-by-value operation. This means that in the case of 80 * a file: URI, the handler that is registered for file: will be launched 81 * and our code will not make any decision based on the content-type or 82 * extension, though the invoked file: handler is free to do so. 83 * 84 * @param aURI 85 * The URI to launch this application with 86 * 87 * @param aBrowsingContext 88 * The window to parent the dialog against, and, if a web handler 89 * is chosen, it is loaded in this window as well. See 90 * nsIHandlerApp.launchWithURI for more details. 91 * 92 * @throw NS_ERROR_INVALID_ARG if preferredAction is not valid for this 93 * call. Other exceptions may be thrown. 94 */ 95 void launchWithURI(in nsIURI aURI, 96 [optional] in BrowsingContext aBrowsingContext); 97 98 /** 99 * preferredAction is how the user specified they would like to handle 100 * this content type: save to disk, use specified helper app, use OS 101 * default handler or handle using navigator; possible value constants 102 * listed below 103 */ 104 attribute nsHandlerInfoAction preferredAction; 105 106 const long saveToDisk = 0; 107 /** 108 * Used to indicate that we know nothing about what to do with this. You 109 * could consider this to be not initialized. 110 */ 111 const long alwaysAsk = 1; 112 const long useHelperApp = 2; 113 const long handleInternally = 3; 114 const long useSystemDefault = 4; 115 116 /** 117 * alwaysAskBeforeHandling: if true, we should always give the user a 118 * dialog asking how to dispose of this content. 119 */ 120 attribute boolean alwaysAskBeforeHandling; 121 }; 122 123 /** 124 * nsIMIMEInfo extends nsIHandlerInfo with a bunch of information specific to 125 * MIME content-types. There is a one-to-many relationship between MIME types 126 * and file extensions. This means that a MIMEInfo object may have multiple 127 * file extensions associated with it. However, the reverse is not true. 128 * 129 * MIMEInfo objects are generally retrieved from the MIME Service 130 * @see nsIMIMEService 131 */ 132 [scriptable, uuid(1c21acef-c7a1-40c6-9d40-a20480ee53a1)] 133 interface nsIMIMEInfo : nsIHandlerInfo { 134 /** 135 * Gives you an array of file types associated with this type. 136 * 137 * @return Number of elements in the array. 138 * @return Array of extensions. 139 */ 140 nsIUTF8StringEnumerator getFileExtensions(); 141 142 /** 143 * Set File Extensions. Input is a comma delimited list of extensions. 144 */ 145 void setFileExtensions(in AUTF8String aExtensions); 146 147 /** 148 * Returns whether or not the given extension is 149 * associated with this MIME info. 150 * 151 * @return TRUE if the association exists. 152 */ 153 boolean extensionExists(in AUTF8String aExtension); 154 155 /** 156 * Append a given extension to the set of extensions 157 */ 158 void appendExtension(in AUTF8String aExtension); 159 160 /** 161 * Returns the first extension association in 162 * the internal set of extensions. 163 * 164 * @return The first extension. 165 */ 166 attribute AUTF8String primaryExtension; 167 168 /** 169 * The MIME type of this MIMEInfo. 170 * 171 * @return String representing the MIME type. 172 * 173 * @deprecated use nsIHandlerInfo::type instead. 174 */ 175 readonly attribute ACString MIMEType; 176 177 /** 178 * Returns whether or not these two nsIMIMEInfos are logically 179 * equivalent. 180 * 181 * @returns PR_TRUE if the two are considered equal 182 */ 183 boolean equals(in nsIMIMEInfo aMIMEInfo); 184 185 /** 186 * Returns a list of nsILocalHandlerApp objects containing 187 * handlers associated with this mimeinfo. Implemented per 188 * platform using information in this object to generate the 189 * best list. Typically used for an "open with" style user 190 * option. 191 * 192 * @return nsIArray of nsILocalHandlerApp 193 */ 194 readonly attribute nsIArray possibleLocalHandlers; 195 196 /** 197 * Launches the application with the specified file, in a way that 198 * depends on the value of preferredAction. preferredAction must be 199 * useHelperApp or useSystemDefault. 200 * 201 * @param aFile The file to launch this application with. 202 * 203 * @throw NS_ERROR_INVALID_ARG if action is not valid for this function. 204 * Other exceptions may be thrown. 205 */ 206 void launchWithFile(in nsIFile aFile); 207 208 /** 209 * Check if we ourselves are registered as the OS default for this type. 210 */ 211 boolean isCurrentAppOSDefault(); 212 }; 213 214 /** 215 * nsIHandlerApp represents an external application that can handle content 216 * of some sort (either a MIME type or a protocol). 217 * 218 * FIXME: now that we've made nsIWebHandlerApp inherit from nsIHandlerApp, 219 * we should also try to make nsIWebContentHandlerInfo inherit from or possibly 220 * be replaced by nsIWebHandlerApp (bug 394710). 221 */ 222 [scriptable, uuid(8BDF20A4-9170-4548-AF52-78311A44F920)] 223 interface nsIHandlerApp : nsISupports { 224 225 /** 226 * Human readable name for the handler 227 */ 228 attribute AString name; 229 230 /** 231 * Detailed description for this handler. Suitable for 232 * a tooltip or short informative sentence. 233 */ 234 attribute AString detailedDescription; 235 236 /** 237 * Whether or not the given handler app is logically equivalent to the 238 * invokant (i.e. they represent the same app). 239 * 240 * Two apps are the same if they are both either local or web handlers 241 * and their executables/URI templates and command line parameters are 242 * the same. 243 * 244 * @param aHandlerApp the handler app to compare to the invokant 245 * 246 * @returns true if the two are logically equivalent, false otherwise 247 */ 248 boolean equals(in nsIHandlerApp aHandlerApp); 249 250 /** 251 * Launches the application with the specified URI. 252 * 253 * @param aURI 254 * The URI to launch this application with 255 * 256 * @param aBrowsingContext 257 * 258 * This represents the docshell to load the handler in and is passed 259 * through to nsIURILoader.openURI. If this parameter is null or 260 * not present, the web handler app implementation will attempt to 261 * find/create a place to load the handler and do so. As of this 262 * writing, it tries to load the web handler in a new window using 263 * nsIBrowserDOMWindow.openURI. In the future, it may attempt to 264 * have a more comprehensive strategy which could include handing 265 * off to the system default browser (bug 394479). 266 */ 267 void launchWithURI(in nsIURI aURI, 268 [optional] in BrowsingContext aBrowsingContext); 269 270 }; 271 272 /** 273 * nsILocalHandlerApp is a local OS-level executable 274 */ 275 [scriptable, uuid(D36B6329-52AE-4f45-80F4-B2536AE5F8B2)] 276 interface nsILocalHandlerApp : nsIHandlerApp { 277 278 /** 279 * Pointer to the executable file used to handle content 280 */ 281 attribute nsIFile executable; 282 283 /** 284 * Returns the current number of command line parameters. 285 */ 286 readonly attribute unsigned long parameterCount; 287 288 /** 289 * Asynchronously returns the pretty (user friendly) name of the 290 * executable. 291 * 292 * On Linux and Mac, this is the same as the name 293 * property. On Mac, that happens to be a nicer name than 294 * the executable's name without the file extension. 295 * 296 * On Windows, this name will be nicer, looked up from the 297 * registry when it exists and falling back to the FileDescription 298 * getVersionFieldInfo when the registry data doesn't exist. 299 * This has the side effect that the prettyName returned 300 * generally will match the text returned by defaultDescription in 301 * nsIHandlerInfo. 302 */ 303 [implicit_jscontext] 304 Promise prettyNameAsync(); 305 306 /** 307 * Clears the current list of command line parameters. 308 */ 309 void clearParameters(); 310 311 /** 312 * Appends a command line parameter to the command line 313 * parameter list. 314 * 315 * @param param the parameter to add. 316 */ 317 void appendParameter(in AString param); 318 319 /** 320 * Retrieves a specific command line parameter. 321 * 322 * @param param the index of the parameter to return. 323 * 324 * @return the parameter string. 325 * 326 * @throw NS_ERROR_INVALID_ARG if the index is out of range. 327 */ 328 AString getParameter(in unsigned long parameterIndex); 329 330 /** 331 * Checks to see if a parameter exists in the command line 332 * parameter list. 333 * 334 * @param param the parameter to search for. 335 * 336 * @return TRUE if the parameter exists in the current list. 337 */ 338 boolean parameterExists(in AString param); 339 }; 340 341 /** 342 * nsIWebHandlerApp is a web-based handler, as speced by the WhatWG HTML5 343 * draft. Currently, only GET-based handlers are supported. At some point, 344 * we probably want to work with WhatWG to spec out and implement POST-based 345 * handlers as well. 346 */ 347 [scriptable, uuid(7521a093-c498-45ce-b462-df7ba0d882f6)] 348 interface nsIWebHandlerApp : nsIHandlerApp { 349 350 /** 351 * Template used to construct the URI to GET. Template is expected to have 352 * a %s in it, and the escaped URI to be handled is inserted in place of 353 * that %s, as per the HTML5 spec. 354 */ 355 attribute AUTF8String uriTemplate; 356 }; 357 358 /** 359 * nsIDBusHandlerApp represents local applications launched by DBus a message 360 * invoking a method taking a single string argument descibing a URI 361 */ 362 [scriptable, uuid(1ffc274b-4cbf-4bb5-a635-05ad2cbb6534)] 363 interface nsIDBusHandlerApp : nsIHandlerApp { 364 365 /** 366 * Service defines the dbus service that should handle this protocol. 367 * If its not set, NS_ERROR_FAILURE will be returned by LaunchWithURI 368 */ 369 attribute AUTF8String service; 370 371 /** 372 * Objpath defines the object path of the dbus service that should handle 373 * this protocol. If its not set, NS_ERROR_FAILURE will be returned 374 * by LaunchWithURI 375 */ 376 attribute AUTF8String objectPath; 377 378 /** 379 * DBusInterface defines the interface of the dbus service that should 380 * handle this protocol. If its not set, NS_ERROR_FAILURE will be 381 * returned by LaunchWithURI 382 */ 383 attribute AUTF8String dBusInterface; 384 385 /** 386 * Method defines the dbus method that should be invoked to handle this 387 * protocol. If its not set, NS_ERROR_FAILURE will be returned by 388 * LaunchWithURI 389 */ 390 attribute AUTF8String method; 391 392 };