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