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
  16 typedef long nsHandlerInfoAction;
  17
  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;
  31
  32     /**
  33      * A human readable description of the handler type
  34      */
  35     attribute AString description;
  36
  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;
  42
  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;
  53
  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;
  60
  61     /**
  62      * A pretty name description of the associated default application. Only
  63      * usable if hasDefaultHandler is true.
  64      */
  65     readonly attribute AString defaultDescription;
  66
  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);
  91
  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;
  99
 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;
 109
 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 };
 116
 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();
 135
 136     /**
 137      * Set File Extensions. Input is a comma delimited list of extensions.
 138      */
 139     void setFileExtensions(in AUTF8String aExtensions);
 140
 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);
 148
 149     /**
 150      * Append a given extension to the set of extensions
 151      */
 152     void appendExtension(in AUTF8String aExtension);
 153
 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;
 161
 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;
 170
 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);
 178
 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;
 189
 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 };
 202
 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 {
 213
 214     /**
 215      * Human readable name for the handler
 216      */
 217     attribute AString name;
 218
 219     /**
 220      * Detailed description for this handler. Suitable for
 221      * a tooltip or short informative sentence.
 222      */
 223     attribute AString detailedDescription;
 224
 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);
 238
 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);
 259
 260 };
 261
 262 /**
 263  * nsILocalHandlerApp is a local OS-level executable
 264  */
 265 [scriptable, uuid(D36B6329-52AE-4f45-80F4-B2536AE5F8B2)]
 266 interface nsILocalHandlerApp : nsIHandlerApp {
 267
 268     /**
 269      * Pointer to the executable file used to handle content
 270      */
 271     attribute nsIFile executable;
 272
 273     /**
 274      * Returns the current number of command line parameters.
 275      */
 276     readonly attribute unsigned long parameterCount;
 277
 278     /**
 279      * Clears the current list of command line parameters.
 280      */
 281     void clearParameters();
 282
 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);
 290
 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);
 301
 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 };
 312
 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 {
 321
 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 };
 329
 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 {
 336
 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;
 342
 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;
 349
 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;
 356
 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;
 363
 364 };
 365