1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/netwerk/mime/nsIMIMEInfo.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,365 @@
1.4 +/* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +#include "nsISupports.idl"
1.10 +
1.11 +interface nsIURI;
1.12 +interface nsIFile;
1.13 +interface nsIUTF8StringEnumerator;
1.14 +interface nsIHandlerApp;
1.15 +interface nsIArray;
1.16 +interface nsIMutableArray;
1.17 +interface nsIInterfaceRequestor;
1.18 +
1.19 +typedef long nsHandlerInfoAction;
1.20 +
1.21 +/**
1.22 + * nsIHandlerInfo gives access to the information about how a given protocol
1.23 + * scheme or MIME-type is handled.
1.24 + */
1.25 +[scriptable, uuid(325e56a7-3762-4312-aec7-f1fcf84b4145)]
1.26 +interface nsIHandlerInfo : nsISupports {
1.27 + /**
1.28 + * The type of this handler info. For MIME handlers, this is the MIME type.
1.29 + * For protocol handlers, it's the scheme.
1.30 + *
1.31 + * @return String representing the type.
1.32 + */
1.33 + readonly attribute ACString type;
1.34 +
1.35 + /**
1.36 + * A human readable description of the handler type
1.37 + */
1.38 + attribute AString description;
1.39 +
1.40 + /**
1.41 + * The application the user has said they want associated with this content
1.42 + * type. This is not always guaranteed to be set!!
1.43 + */
1.44 + attribute nsIHandlerApp preferredApplicationHandler;
1.45 +
1.46 + /**
1.47 + * Applications that can handle this content type.
1.48 + *
1.49 + * The list will include the preferred handler, if any. Elements of this
1.50 + * array are nsIHandlerApp objects, and this attribute will always reference
1.51 + * an array, whether or not there are any possible handlers. If there are
1.52 + * no possible handlers, the array will contain no elements, so just check
1.53 + * its length (nsIArray::length) to see if there are any possible handlers.
1.54 + */
1.55 + readonly attribute nsIMutableArray possibleApplicationHandlers;
1.56 +
1.57 + /**
1.58 + * Indicates whether a default application handler exists,
1.59 + * i.e. whether launchWithFile with action = useSystemDefault is possible
1.60 + * and defaultDescription will contain usable information.
1.61 + */
1.62 + readonly attribute boolean hasDefaultHandler;
1.63 +
1.64 + /**
1.65 + * A pretty name description of the associated default application. Only
1.66 + * usable if hasDefaultHandler is true.
1.67 + */
1.68 + readonly attribute AString defaultDescription;
1.69 +
1.70 + /**
1.71 + * Launches the application with the specified URI, in a way that
1.72 + * depends on the value of preferredAction. preferredAction must be
1.73 + * useHelperApp or useSystemDefault.
1.74 + *
1.75 + * @note Only the URI scheme is used to determine how to launch. This is
1.76 + * essentially a pass-by-value operation. This means that in the case of
1.77 + * a file: URI, the handler that is registered for file: will be launched
1.78 + * and our code will not make any decision based on the content-type or
1.79 + * extension, though the invoked file: handler is free to do so.
1.80 + *
1.81 + * @param aURI
1.82 + * The URI to launch this application with
1.83 + *
1.84 + * @param aWindowContext
1.85 + * The window to parent the dialog against, and, if a web handler
1.86 + * is chosen, it is loaded in this window as well. See
1.87 + * nsIHandlerApp.launchWithURI for more details.
1.88 + *
1.89 + * @throw NS_ERROR_INVALID_ARG if preferredAction is not valid for this
1.90 + * call. Other exceptions may be thrown.
1.91 + */
1.92 + void launchWithURI(in nsIURI aURI,
1.93 + [optional] in nsIInterfaceRequestor aWindowContext);
1.94 +
1.95 + /**
1.96 + * preferredAction is how the user specified they would like to handle
1.97 + * this content type: save to disk, use specified helper app, use OS
1.98 + * default handler or handle using navigator; possible value constants
1.99 + * listed below
1.100 + */
1.101 + attribute nsHandlerInfoAction preferredAction;
1.102 +
1.103 + const long saveToDisk = 0;
1.104 + /**
1.105 + * Used to indicate that we know nothing about what to do with this. You
1.106 + * could consider this to be not initialized.
1.107 + */
1.108 + const long alwaysAsk = 1;
1.109 + const long useHelperApp = 2;
1.110 + const long handleInternally = 3;
1.111 + const long useSystemDefault = 4;
1.112 +
1.113 + /**
1.114 + * alwaysAskBeforeHandling: if true, we should always give the user a
1.115 + * dialog asking how to dispose of this content.
1.116 + */
1.117 + attribute boolean alwaysAskBeforeHandling;
1.118 +};
1.119 +
1.120 +/**
1.121 + * nsIMIMEInfo extends nsIHandlerInfo with a bunch of information specific to
1.122 + * MIME content-types. There is a one-to-many relationship between MIME types
1.123 + * and file extensions. This means that a MIMEInfo object may have multiple
1.124 + * file extensions associated with it. However, the reverse is not true.
1.125 + *
1.126 + * MIMEInfo objects are generally retrieved from the MIME Service
1.127 + * @see nsIMIMEService
1.128 + */
1.129 +[scriptable, uuid(1c21acef-c7a1-40c6-9d40-a20480ee53a1)]
1.130 +interface nsIMIMEInfo : nsIHandlerInfo {
1.131 + /**
1.132 + * Gives you an array of file types associated with this type.
1.133 + *
1.134 + * @return Number of elements in the array.
1.135 + * @return Array of extensions.
1.136 + */
1.137 + nsIUTF8StringEnumerator getFileExtensions();
1.138 +
1.139 + /**
1.140 + * Set File Extensions. Input is a comma delimited list of extensions.
1.141 + */
1.142 + void setFileExtensions(in AUTF8String aExtensions);
1.143 +
1.144 + /**
1.145 + * Returns whether or not the given extension is
1.146 + * associated with this MIME info.
1.147 + *
1.148 + * @return TRUE if the association exists.
1.149 + */
1.150 + boolean extensionExists(in AUTF8String aExtension);
1.151 +
1.152 + /**
1.153 + * Append a given extension to the set of extensions
1.154 + */
1.155 + void appendExtension(in AUTF8String aExtension);
1.156 +
1.157 + /**
1.158 + * Returns the first extension association in
1.159 + * the internal set of extensions.
1.160 + *
1.161 + * @return The first extension.
1.162 + */
1.163 + attribute AUTF8String primaryExtension;
1.164 +
1.165 + /**
1.166 + * The MIME type of this MIMEInfo.
1.167 + *
1.168 + * @return String representing the MIME type.
1.169 + *
1.170 + * @deprecated use nsIHandlerInfo::type instead.
1.171 + */
1.172 + readonly attribute ACString MIMEType;
1.173 +
1.174 + /**
1.175 + * Returns whether or not these two nsIMIMEInfos are logically
1.176 + * equivalent.
1.177 + *
1.178 + * @returns PR_TRUE if the two are considered equal
1.179 + */
1.180 + boolean equals(in nsIMIMEInfo aMIMEInfo);
1.181 +
1.182 + /**
1.183 + * Returns a list of nsILocalHandlerApp objects containing
1.184 + * handlers associated with this mimeinfo. Implemented per
1.185 + * platform using information in this object to generate the
1.186 + * best list. Typically used for an "open with" style user
1.187 + * option.
1.188 + *
1.189 + * @return nsIArray of nsILocalHandlerApp
1.190 + */
1.191 + readonly attribute nsIArray possibleLocalHandlers;
1.192 +
1.193 + /**
1.194 + * Launches the application with the specified file, in a way that
1.195 + * depends on the value of preferredAction. preferredAction must be
1.196 + * useHelperApp or useSystemDefault.
1.197 + *
1.198 + * @param aFile The file to launch this application with.
1.199 + *
1.200 + * @throw NS_ERROR_INVALID_ARG if action is not valid for this function.
1.201 + * Other exceptions may be thrown.
1.202 + */
1.203 + void launchWithFile(in nsIFile aFile);
1.204 +};
1.205 +
1.206 +/**
1.207 + * nsIHandlerApp represents an external application that can handle content
1.208 + * of some sort (either a MIME type or a protocol).
1.209 + *
1.210 + * FIXME: now that we've made nsIWebHandlerApp inherit from nsIHandlerApp,
1.211 + * we should also try to make nsIWebContentHandlerInfo inherit from or possibly
1.212 + * be replaced by nsIWebHandlerApp (bug 394710).
1.213 + */
1.214 +[scriptable, uuid(8BDF20A4-9170-4548-AF52-78311A44F920)]
1.215 +interface nsIHandlerApp : nsISupports {
1.216 +
1.217 + /**
1.218 + * Human readable name for the handler
1.219 + */
1.220 + attribute AString name;
1.221 +
1.222 + /**
1.223 + * Detailed description for this handler. Suitable for
1.224 + * a tooltip or short informative sentence.
1.225 + */
1.226 + attribute AString detailedDescription;
1.227 +
1.228 + /**
1.229 + * Whether or not the given handler app is logically equivalent to the
1.230 + * invokant (i.e. they represent the same app).
1.231 + *
1.232 + * Two apps are the same if they are both either local or web handlers
1.233 + * and their executables/URI templates and command line parameters are
1.234 + * the same.
1.235 + *
1.236 + * @param aHandlerApp the handler app to compare to the invokant
1.237 + *
1.238 + * @returns true if the two are logically equivalent, false otherwise
1.239 + */
1.240 + boolean equals(in nsIHandlerApp aHandlerApp);
1.241 +
1.242 + /**
1.243 + * Launches the application with the specified URI.
1.244 + *
1.245 + * @param aURI
1.246 + * The URI to launch this application with
1.247 + *
1.248 + * @param aWindowContext
1.249 + *
1.250 + * Currently only relevant to web-handler apps. If given, this
1.251 + * represents the docshell to load the handler in and is passed
1.252 + * through to nsIURILoader.openURI. If this parameter is null or
1.253 + * not present, the web handler app implementation will attempt to
1.254 + * find/create a place to load the handler and do so. As of this
1.255 + * writing, it tries to load the web handler in a new window using
1.256 + * nsIBrowserDOMWindow.openURI. In the future, it may attempt to
1.257 + * have a more comprehensive strategy which could include handing
1.258 + * off to the system default browser (bug 394479).
1.259 + */
1.260 + void launchWithURI(in nsIURI aURI,
1.261 + [optional] in nsIInterfaceRequestor aWindowContext);
1.262 +
1.263 +};
1.264 +
1.265 +/**
1.266 + * nsILocalHandlerApp is a local OS-level executable
1.267 + */
1.268 +[scriptable, uuid(D36B6329-52AE-4f45-80F4-B2536AE5F8B2)]
1.269 +interface nsILocalHandlerApp : nsIHandlerApp {
1.270 +
1.271 + /**
1.272 + * Pointer to the executable file used to handle content
1.273 + */
1.274 + attribute nsIFile executable;
1.275 +
1.276 + /**
1.277 + * Returns the current number of command line parameters.
1.278 + */
1.279 + readonly attribute unsigned long parameterCount;
1.280 +
1.281 + /**
1.282 + * Clears the current list of command line parameters.
1.283 + */
1.284 + void clearParameters();
1.285 +
1.286 + /**
1.287 + * Appends a command line parameter to the command line
1.288 + * parameter list.
1.289 + *
1.290 + * @param param the parameter to add.
1.291 + */
1.292 + void appendParameter(in AString param);
1.293 +
1.294 + /**
1.295 + * Retrieves a specific command line parameter.
1.296 + *
1.297 + * @param param the index of the parameter to return.
1.298 + *
1.299 + * @return the parameter string.
1.300 + *
1.301 + * @throw NS_ERROR_INVALID_ARG if the index is out of range.
1.302 + */
1.303 + AString getParameter(in unsigned long parameterIndex);
1.304 +
1.305 + /**
1.306 + * Checks to see if a parameter exists in the command line
1.307 + * parameter list.
1.308 + *
1.309 + * @param param the parameter to search for.
1.310 + *
1.311 + * @return TRUE if the parameter exists in the current list.
1.312 + */
1.313 + boolean parameterExists(in AString param);
1.314 +};
1.315 +
1.316 +/**
1.317 + * nsIWebHandlerApp is a web-based handler, as speced by the WhatWG HTML5
1.318 + * draft. Currently, only GET-based handlers are supported. At some point,
1.319 + * we probably want to work with WhatWG to spec out and implement POST-based
1.320 + * handlers as well.
1.321 + */
1.322 +[scriptable, uuid(7521a093-c498-45ce-b462-df7ba0d882f6)]
1.323 +interface nsIWebHandlerApp : nsIHandlerApp {
1.324 +
1.325 + /**
1.326 + * Template used to construct the URI to GET. Template is expected to have
1.327 + * a %s in it, and the escaped URI to be handled is inserted in place of
1.328 + * that %s, as per the HTML5 spec.
1.329 + */
1.330 + attribute AUTF8String uriTemplate;
1.331 +};
1.332 +
1.333 +/**
1.334 + * nsIDBusHandlerApp represents local applications launched by DBus a message
1.335 + * invoking a method taking a single string argument descibing a URI
1.336 + */
1.337 +[scriptable, uuid(1ffc274b-4cbf-4bb5-a635-05ad2cbb6534)]
1.338 +interface nsIDBusHandlerApp : nsIHandlerApp {
1.339 +
1.340 + /**
1.341 + * Service defines the dbus service that should handle this protocol.
1.342 + * If its not set, NS_ERROR_FAILURE will be returned by LaunchWithURI
1.343 + */
1.344 + attribute AUTF8String service;
1.345 +
1.346 + /**
1.347 + * Objpath defines the object path of the dbus service that should handle
1.348 + * this protocol. If its not set, NS_ERROR_FAILURE will be returned
1.349 + * by LaunchWithURI
1.350 + */
1.351 + attribute AUTF8String objectPath;
1.352 +
1.353 + /**
1.354 + * DBusInterface defines the interface of the dbus service that should
1.355 + * handle this protocol. If its not set, NS_ERROR_FAILURE will be
1.356 + * returned by LaunchWithURI
1.357 + */
1.358 + attribute AUTF8String dBusInterface;
1.359 +
1.360 + /**
1.361 + * Method defines the dbus method that should be invoked to handle this
1.362 + * protocol. If its not set, NS_ERROR_FAILURE will be returned by
1.363 + * LaunchWithURI
1.364 + */
1.365 + attribute AUTF8String method;
1.366 +
1.367 +};
1.368 +
