netwerk/mime/nsIMIMEInfo.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 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 };