The Tor Browser: netwerk/mime/nsIMIMEInfo.idl@b8a032363ba2

Incorporate requested changes from Mozilla in review:
https://bugzilla.mozilla.org/show_bug.cgi?id=1123480#c6

     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/. */

     6 #include "nsISupports.idl"

     8 interface nsIURI;

     9 interface nsIFile;

    10 interface nsIUTF8StringEnumerator;

    11 interface nsIHandlerApp;

    12 interface nsIArray;

    13 interface nsIMutableArray;

    14 interface nsIInterfaceRequestor;

    16 typedef long nsHandlerInfoAction;

    18 /**

    19  * nsIHandlerInfo gives access to the information about how a given protocol

    20  * scheme or MIME-type is handled.

    21  */

    22 [scriptable, uuid(325e56a7-3762-4312-aec7-f1fcf84b4145)]

    23 interface nsIHandlerInfo : nsISupports {

    24     /**

    25      * The type of this handler info.  For MIME handlers, this is the MIME type.

    26      * For protocol handlers, it's the scheme.

    27      *

    28      * @return String representing the type.

    29      */

    30     readonly attribute ACString type;

    32     /**

    33      * A human readable description of the handler type

    34      */

    35     attribute AString description;

    37     /**

    38      * The application the user has said they want associated with this content

    39      * type. This is not always guaranteed to be set!!

    40      */

    41     attribute nsIHandlerApp preferredApplicationHandler;

    43     /**

    44      * Applications that can handle this content type.

    45      *

    46      * The list will include the preferred handler, if any.  Elements of this

    47      * array are nsIHandlerApp objects, and this attribute will always reference

    48      * an array, whether or not there are any possible handlers.  If there are

    49      * no possible handlers, the array will contain no elements, so just check

    50      * its length (nsIArray::length) to see if there are any possible handlers.

    51      */

    52     readonly attribute nsIMutableArray possibleApplicationHandlers;

    54     /**

    55      * Indicates whether a default application handler exists,

    56      * i.e. whether launchWithFile with action = useSystemDefault is possible

    57      * and defaultDescription will contain usable information.

    58      */

    59     readonly attribute boolean hasDefaultHandler;

    61     /**

    62      * A pretty name description of the associated default application. Only

    63      * usable if hasDefaultHandler is true.

    64      */

    65     readonly attribute AString defaultDescription;

    67     /**

    68      * Launches the application with the specified URI, in a way that

    69      * depends on the value of preferredAction. preferredAction must be

    70      * useHelperApp or useSystemDefault.

    71      *

    72      * @note Only the URI scheme is used to determine how to launch.  This is

    73      * essentially a pass-by-value operation.  This means that in the case of

    74      * a file: URI, the handler that is registered for file: will be launched

    75      * and our code will not make any decision based on the content-type or

    76      * extension, though the invoked file: handler is free to do so.

    77      *

    78      * @param aURI

    79      *        The URI to launch this application with

    80      *

    81      * @param aWindowContext

    82      *        The window to parent the dialog against, and, if a web handler

    83      *        is chosen, it is loaded in this window as well.  See

    84      *        nsIHandlerApp.launchWithURI for more details.

    85      *

    86      * @throw NS_ERROR_INVALID_ARG if preferredAction is not valid for this

    87      * call. Other exceptions may be thrown.

    88      */

    89     void launchWithURI(in nsIURI aURI,

    90                        [optional] in nsIInterfaceRequestor aWindowContext);

    92     /**

    93      * preferredAction is how the user specified they would like to handle

    94      * this content type: save to disk, use specified helper app, use OS

    95      * default handler or handle using navigator; possible value constants

    96      * listed below

    97      */

    98     attribute nsHandlerInfoAction preferredAction;

   100     const long saveToDisk = 0;

   101     /**

   102      * Used to indicate that we know nothing about what to do with this.  You

   103      * could consider this to be not initialized.

   104      */

   105     const long alwaysAsk = 1;

   106     const long useHelperApp = 2;

   107     const long handleInternally = 3;

   108     const long useSystemDefault = 4;

   110     /**

   111      * alwaysAskBeforeHandling: if true, we should always give the user a

   112      * dialog asking how to dispose of this content.

   113      */

   114     attribute boolean alwaysAskBeforeHandling;

   115 };

   117 /**

   118  * nsIMIMEInfo extends nsIHandlerInfo with a bunch of information specific to

   119  * MIME content-types. There is a one-to-many relationship between MIME types

   120  * and file extensions. This means that a MIMEInfo object may have multiple

   121  * file extensions associated with it.  However, the reverse is not true.

   122  *

   123  * MIMEInfo objects are generally retrieved from the MIME Service

   124  * @see nsIMIMEService

   125  */

   126 [scriptable, uuid(1c21acef-c7a1-40c6-9d40-a20480ee53a1)]

   127 interface nsIMIMEInfo : nsIHandlerInfo {

   128     /**

   129      * Gives you an array of file types associated with this type.

   130      *

   131      * @return Number of elements in the array.

   132      * @return Array of extensions.

   133      */

   134     nsIUTF8StringEnumerator getFileExtensions();

   136     /**

   137      * Set File Extensions. Input is a comma delimited list of extensions.

   138      */

   139     void setFileExtensions(in AUTF8String aExtensions);

   141     /**

   142      * Returns whether or not the given extension is

   143      * associated with this MIME info.

   144      *

   145      * @return TRUE if the association exists.

   146      */

   147     boolean extensionExists(in AUTF8String aExtension);

   149     /**

   150      * Append a given extension to the set of extensions

   151      */

   152     void appendExtension(in AUTF8String aExtension);

   154     /**

   155      * Returns the first extension association in

   156      * the internal set of extensions.

   157      *

   158      * @return The first extension.

   159      */

   160     attribute AUTF8String primaryExtension;

   162     /**

   163      * The MIME type of this MIMEInfo.

   164      *

   165      * @return String representing the MIME type.

   166      *

   167      * @deprecated  use nsIHandlerInfo::type instead.

   168      */

   169     readonly attribute ACString MIMEType;

   171     /**

   172      * Returns whether or not these two nsIMIMEInfos are logically

   173      * equivalent.

   174      *

   175      * @returns PR_TRUE if the two are considered equal

   176      */

   177     boolean equals(in nsIMIMEInfo aMIMEInfo);

   179     /**

   180      * Returns a list of nsILocalHandlerApp objects containing

   181      * handlers associated with this mimeinfo. Implemented per

   182      * platform using information in this object to generate the

   183      * best list. Typically used for an "open with" style user

   184      * option.

   185      *

   186      * @return nsIArray of nsILocalHandlerApp

   187      */

   188     readonly attribute nsIArray possibleLocalHandlers;

   190     /**

   191      * Launches the application with the specified file, in a way that

   192      * depends on the value of preferredAction. preferredAction must be

   193      * useHelperApp or useSystemDefault.

   194      *

   195      * @param aFile The file to launch this application with.

   196      *

   197      * @throw NS_ERROR_INVALID_ARG if action is not valid for this function.

   198      * Other exceptions may be thrown.

   199      */

   200     void launchWithFile(in nsIFile aFile);

   201 };

   203 /**

   204  * nsIHandlerApp represents an external application that can handle content

   205  * of some sort (either a MIME type or a protocol).

   206  *

   207  * FIXME: now that we've made nsIWebHandlerApp inherit from nsIHandlerApp,

   208  * we should also try to make nsIWebContentHandlerInfo inherit from or possibly

   209  * be replaced by nsIWebHandlerApp (bug 394710).

   210  */

   211 [scriptable, uuid(8BDF20A4-9170-4548-AF52-78311A44F920)]

   212 interface nsIHandlerApp : nsISupports {

   214     /**

   215      * Human readable name for the handler

   216      */

   217     attribute AString name;

   219     /**

   220      * Detailed description for this handler. Suitable for

   221      * a tooltip or short informative sentence.

   222      */

   223     attribute AString detailedDescription;

   225     /**

   226      * Whether or not the given handler app is logically equivalent to the

   227      * invokant (i.e. they represent the same app).

   228      *

   229      * Two apps are the same if they are both either local or web handlers

   230      * and their executables/URI templates and command line parameters are

   231      * the same.

   232      *

   233      * @param aHandlerApp the handler app to compare to the invokant

   234      *

   235      * @returns true if the two are logically equivalent, false otherwise

   236      */

   237     boolean equals(in nsIHandlerApp aHandlerApp);

   239     /**

   240      * Launches the application with the specified URI.

   241      *

   242      * @param aURI

   243      *        The URI to launch this application with

   244      *

   245      * @param aWindowContext

   246      *

   247      *        Currently only relevant to web-handler apps.  If given, this

   248      *        represents the docshell to load the handler in and is passed

   249      *        through to nsIURILoader.openURI.  If this parameter is null or

   250      *        not present, the web handler app implementation will attempt to

   251      *        find/create a place to load the handler and do so.  As of this

   252      *        writing, it tries to load the web handler in a new window using

   253      *        nsIBrowserDOMWindow.openURI.  In the future, it may attempt to

   254      *        have a more comprehensive strategy which could include handing

   255      *        off to the system default browser (bug 394479).

   256      */

   257     void launchWithURI(in nsIURI aURI,

   258                        [optional] in nsIInterfaceRequestor aWindowContext);

   260 };

   262 /**

   263  * nsILocalHandlerApp is a local OS-level executable

   264  */

   265 [scriptable, uuid(D36B6329-52AE-4f45-80F4-B2536AE5F8B2)]

   266 interface nsILocalHandlerApp : nsIHandlerApp {

   268     /**

   269      * Pointer to the executable file used to handle content

   270      */

   271     attribute nsIFile executable;

   273     /**

   274      * Returns the current number of command line parameters.

   275      */

   276     readonly attribute unsigned long parameterCount;

   278     /**

   279      * Clears the current list of command line parameters.

   280      */

   281     void clearParameters();

   283     /**

   284      * Appends a command line parameter to the command line

   285      * parameter list.

   286      *

   287      * @param param the parameter to add.

   288      */

   289     void appendParameter(in AString param);

   291     /**

   292      * Retrieves a specific command line parameter.

   293      *

   294      * @param param the index of the parameter to return.

   295      *

   296      * @return the parameter string.

   297      *

   298      * @throw NS_ERROR_INVALID_ARG if the index is out of range.

   299      */

   300     AString getParameter(in unsigned long parameterIndex);

   302     /**

   303      * Checks to see if a parameter exists in the command line

   304      * parameter list.

   305      *

   306      * @param param the parameter to search for.

   307      *

   308      * @return TRUE if the parameter exists in the current list.

   309      */

   310     boolean parameterExists(in AString param);

   311 };

   313 /**

   314  * nsIWebHandlerApp is a web-based handler, as speced by the WhatWG HTML5

   315  * draft.  Currently, only GET-based handlers are supported.  At some point,

   316  * we probably want to work with WhatWG to spec out and implement POST-based

   317  * handlers as well.

   318  */

   319 [scriptable, uuid(7521a093-c498-45ce-b462-df7ba0d882f6)]

   320 interface nsIWebHandlerApp : nsIHandlerApp {

   322     /**

   323      * Template used to construct the URI to GET.  Template is expected to have

   324      * a %s in it, and the escaped URI to be handled is inserted in place of

   325      * that %s, as per the HTML5 spec.

   326      */

   327     attribute AUTF8String uriTemplate;

   328 };

   330 /**

   331  * nsIDBusHandlerApp represents local applications launched by DBus a message

   332  * invoking a method taking a single string argument descibing a URI

   333  */

   334 [scriptable, uuid(1ffc274b-4cbf-4bb5-a635-05ad2cbb6534)]

   335 interface nsIDBusHandlerApp : nsIHandlerApp {

   337     /**

   338      * Service defines the dbus service that should handle this protocol.

   339      * If its not set,  NS_ERROR_FAILURE will be returned by LaunchWithURI

   340      */

   341     attribute AUTF8String service;

   343     /**

   344      * Objpath defines the object path of the dbus service that should handle

   345      * this protocol. If its not set,  NS_ERROR_FAILURE will be returned

   346      * by LaunchWithURI

   347      */

   348     attribute AUTF8String objectPath;

   350     /**

   351      * DBusInterface defines the interface of the dbus service that should

   352      * handle this protocol. If its not set,  NS_ERROR_FAILURE will be

   353      * returned by LaunchWithURI

   354      */

   355     attribute AUTF8String dBusInterface;

   357     /**

   358      * Method defines the dbus method that should be invoked to handle this

   359      * protocol. If its not set,  NS_ERROR_FAILURE will be returned by

   360      * LaunchWithURI

   361      */

   362     attribute AUTF8String method;

   364 };

The Tor Browser / file revision

netwerk/mime/nsIMIMEInfo.idl@b8a032363ba2

netwerk/mime/nsIMIMEInfo.idl