DXR is a code search and navigation tool aimed at making sense of large projects. It supports full-text and regex searches as well as structural queries.

Mercurial (5b81998bb7ab)

VCS Links

Line Code
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365
/* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "nsISupports.idl"

interface nsIURI;
interface nsIFile;
interface nsIUTF8StringEnumerator;
interface nsIHandlerApp;
interface nsIArray;
interface nsIMutableArray;
interface nsIInterfaceRequestor;

typedef long nsHandlerInfoAction;

/**
 * nsIHandlerInfo gives access to the information about how a given protocol
 * scheme or MIME-type is handled.
 */
[scriptable, uuid(325e56a7-3762-4312-aec7-f1fcf84b4145)] 
interface nsIHandlerInfo : nsISupports {
    /**
     * The type of this handler info.  For MIME handlers, this is the MIME type.
     * For protocol handlers, it's the scheme.
     * 
     * @return String representing the type.
     */
    readonly attribute ACString type;

    /**
     * A human readable description of the handler type
     */
    attribute AString description;

    /**
     * The application the user has said they want associated with this content
     * type. This is not always guaranteed to be set!!
     */
    attribute nsIHandlerApp preferredApplicationHandler;

    /**
     * Applications that can handle this content type.
     *
     * The list will include the preferred handler, if any.  Elements of this
     * array are nsIHandlerApp objects, and this attribute will always reference
     * an array, whether or not there are any possible handlers.  If there are
     * no possible handlers, the array will contain no elements, so just check
     * its length (nsIArray::length) to see if there are any possible handlers.
     */
    readonly attribute nsIMutableArray possibleApplicationHandlers;

    /**
     * Indicates whether a default application handler exists,
     * i.e. whether launchWithFile with action = useSystemDefault is possible
     * and defaultDescription will contain usable information.
     */
    readonly attribute boolean hasDefaultHandler;

    /**
     * A pretty name description of the associated default application. Only
     * usable if hasDefaultHandler is true.
     */
    readonly attribute AString defaultDescription;

    /**
     * Launches the application with the specified URI, in a way that
     * depends on the value of preferredAction. preferredAction must be
     * useHelperApp or useSystemDefault.
     *  
     * @note Only the URI scheme is used to determine how to launch.  This is
     * essentially a pass-by-value operation.  This means that in the case of
     * a file: URI, the handler that is registered for file: will be launched
     * and our code will not make any decision based on the content-type or
     * extension, though the invoked file: handler is free to do so. 
     *
     * @param aURI
     *        The URI to launch this application with
     *
     * @param aWindowContext 
     *        The window to parent the dialog against, and, if a web handler
     *        is chosen, it is loaded in this window as well.  See 
     *        nsIHandlerApp.launchWithURI for more details.
     *
     * @throw NS_ERROR_INVALID_ARG if preferredAction is not valid for this
     * call. Other exceptions may be thrown.
     */
    void launchWithURI(in nsIURI aURI, 
                       [optional] in nsIInterfaceRequestor aWindowContext);

    /**
     * preferredAction is how the user specified they would like to handle
     * this content type: save to disk, use specified helper app, use OS
     * default handler or handle using navigator; possible value constants
     * listed below
     */
    attribute nsHandlerInfoAction preferredAction;

    const long saveToDisk = 0;
    /**
     * Used to indicate that we know nothing about what to do with this.  You
     * could consider this to be not initialized.
     */
    const long alwaysAsk = 1;
    const long useHelperApp = 2;
    const long handleInternally = 3;
    const long useSystemDefault = 4;

    /**
     * alwaysAskBeforeHandling: if true, we should always give the user a
     * dialog asking how to dispose of this content.
     */
    attribute boolean alwaysAskBeforeHandling;
};

/**
 * nsIMIMEInfo extends nsIHandlerInfo with a bunch of information specific to
 * MIME content-types. There is a one-to-many relationship between MIME types
 * and file extensions. This means that a MIMEInfo object may have multiple
 * file extensions associated with it.  However, the reverse is not true.
 *
 * MIMEInfo objects are generally retrieved from the MIME Service
 * @see nsIMIMEService
 */
[scriptable, uuid(1c21acef-c7a1-40c6-9d40-a20480ee53a1)]
interface nsIMIMEInfo : nsIHandlerInfo {
    /**
     * Gives you an array of file types associated with this type.
     *
     * @return Number of elements in the array.
     * @return Array of extensions.
     */
    nsIUTF8StringEnumerator getFileExtensions();

    /**
     * Set File Extensions. Input is a comma delimited list of extensions.
     */
    void setFileExtensions(in AUTF8String aExtensions);
 
    /**
     * Returns whether or not the given extension is
     * associated with this MIME info.
     *
     * @return TRUE if the association exists. 
     */
    boolean extensionExists(in AUTF8String aExtension);

    /**
     * Append a given extension to the set of extensions
     */
    void appendExtension(in AUTF8String aExtension);

    /**
     * Returns the first extension association in
     * the internal set of extensions.
     *
     * @return The first extension.
     */
    attribute AUTF8String primaryExtension;
    
    /**
     * The MIME type of this MIMEInfo.
     * 
     * @return String representing the MIME type.
     * 
     * @deprecated  use nsIHandlerInfo::type instead.
     */
    readonly attribute ACString MIMEType;

    /**
     * Returns whether or not these two nsIMIMEInfos are logically
     * equivalent.
     *
     * @returns PR_TRUE if the two are considered equal
     */
    boolean equals(in nsIMIMEInfo aMIMEInfo);

    /** 
     * Returns a list of nsILocalHandlerApp objects containing
     * handlers associated with this mimeinfo. Implemented per 
     * platform using information in this object to generate the
     * best list. Typically used for an "open with" style user 
     * option.
     * 
     * @return nsIArray of nsILocalHandlerApp
     */
    readonly attribute nsIArray possibleLocalHandlers;

    /**
     * Launches the application with the specified file, in a way that
     * depends on the value of preferredAction. preferredAction must be
     * useHelperApp or useSystemDefault.
     *
     * @param aFile The file to launch this application with.
     *
     * @throw NS_ERROR_INVALID_ARG if action is not valid for this function.
     * Other exceptions may be thrown.
     */
    void launchWithFile(in nsIFile aFile);
};

/**
 * nsIHandlerApp represents an external application that can handle content
 * of some sort (either a MIME type or a protocol).
 *
 * FIXME: now that we've made nsIWebHandlerApp inherit from nsIHandlerApp,
 * we should also try to make nsIWebContentHandlerInfo inherit from or possibly
 * be replaced by nsIWebHandlerApp (bug 394710).
 */
[scriptable, uuid(8BDF20A4-9170-4548-AF52-78311A44F920)]
interface nsIHandlerApp : nsISupports {

    /**
     * Human readable name for the handler
     */
    attribute AString name;

    /**
     * Detailed description for this handler. Suitable for
     * a tooltip or short informative sentence.
     */
    attribute AString detailedDescription;

    /**
     * Whether or not the given handler app is logically equivalent to the
     * invokant (i.e. they represent the same app).
     * 
     * Two apps are the same if they are both either local or web handlers
     * and their executables/URI templates and command line parameters are
     * the same.
     *
     * @param aHandlerApp the handler app to compare to the invokant
     *
     * @returns true if the two are logically equivalent, false otherwise
     */
    boolean equals(in nsIHandlerApp aHandlerApp);

    /**
     * Launches the application with the specified URI.
     *
     * @param aURI
     *        The URI to launch this application with
     *
     * @param aWindowContext 
     *
     *        Currently only relevant to web-handler apps.  If given, this
     *        represents the docshell to load the handler in and is passed
     *        through to nsIURILoader.openURI.  If this parameter is null or
     *        not present, the web handler app implementation will attempt to 
     *        find/create a place to load the handler and do so.  As of this
     *        writing, it tries to load the web handler in a new window using
     *        nsIBrowserDOMWindow.openURI.  In the future, it may attempt to 
     *        have a more comprehensive strategy which could include handing
     *        off to the system default browser (bug 394479).
     */
    void launchWithURI(in nsIURI aURI, 
                       [optional] in nsIInterfaceRequestor aWindowContext);

};

/**
 * nsILocalHandlerApp is a local OS-level executable
 */
[scriptable, uuid(D36B6329-52AE-4f45-80F4-B2536AE5F8B2)]
interface nsILocalHandlerApp : nsIHandlerApp {

    /**
     * Pointer to the executable file used to handle content
     */
    attribute nsIFile executable;

    /**
     * Returns the current number of command line parameters.
     */
    readonly attribute unsigned long parameterCount;

    /**
     * Clears the current list of command line parameters.
     */
    void clearParameters();

    /**
     * Appends a command line parameter to the command line
     * parameter list.
     *
     * @param param the parameter to add.
     */
    void appendParameter(in AString param);

    /**
     * Retrieves a specific command line parameter.
     *
     * @param param the index of the parameter to return.
     *
     * @return the parameter string.
     *
     * @throw NS_ERROR_INVALID_ARG if the index is out of range.
     */
    AString getParameter(in unsigned long parameterIndex);

    /**
     * Checks to see if a parameter exists in the command line
     * parameter list.
     *
     * @param param the parameter to search for.
     *
     * @return TRUE if the parameter exists in the current list. 
     */
    boolean parameterExists(in AString param);
};

/**
 * nsIWebHandlerApp is a web-based handler, as speced by the WhatWG HTML5
 * draft.  Currently, only GET-based handlers are supported.  At some point, 
 * we probably want to work with WhatWG to spec out and implement POST-based
 * handlers as well.
 */
[scriptable, uuid(7521a093-c498-45ce-b462-df7ba0d882f6)]
interface nsIWebHandlerApp : nsIHandlerApp {

    /**
     * Template used to construct the URI to GET.  Template is expected to have
     * a %s in it, and the escaped URI to be handled is inserted in place of 
     * that %s, as per the HTML5 spec.
     */
    attribute AUTF8String uriTemplate;
};

/**
 * nsIDBusHandlerApp represents local applications launched by DBus a message
 * invoking a method taking a single string argument descibing a URI
 */
[scriptable, uuid(1ffc274b-4cbf-4bb5-a635-05ad2cbb6534)]
interface nsIDBusHandlerApp : nsIHandlerApp {

    /**
     * Service defines the dbus service that should handle this protocol.
     * If its not set,  NS_ERROR_FAILURE will be returned by LaunchWithURI
     */
    attribute AUTF8String service;
    
    /**
     * Objpath defines the object path of the dbus service that should handle 
     * this protocol. If its not set,  NS_ERROR_FAILURE will be returned 
     * by LaunchWithURI
     */
    attribute AUTF8String objectPath;

    /**
     * DBusInterface defines the interface of the dbus service that should 
     * handle this protocol. If its not set,  NS_ERROR_FAILURE will be  
     * returned by LaunchWithURI
     */
    attribute AUTF8String dBusInterface;
    
    /**
     * Method defines the dbus method that should be invoked to handle this 
     * protocol. If its not set,  NS_ERROR_FAILURE will be returned by 
     * LaunchWithURI
     */
    attribute AUTF8String method;
    
};