1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/uriloader/exthandler/nsIHandlerService.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,117 @@
1.4 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.5 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.6 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.7 +
1.8 +#include "nsISupports.idl"
1.9 +
1.10 +interface nsIHandlerInfo;
1.11 +interface nsISimpleEnumerator;
1.12 +
1.13 +[scriptable, uuid(53f0ad17-ec62-46a1-adbc-efccc06babcd)]
1.14 +interface nsIHandlerService : nsISupports
1.15 +{
1.16 + /**
1.17 + * Retrieve a list of all handlers in the datastore. This list is not
1.18 + * guaranteed to be in any particular order, and callers should not assume
1.19 + * it will remain in the same order in the future.
1.20 + *
1.21 + * @returns a list of all handlers in the datastore
1.22 + */
1.23 + nsISimpleEnumerator enumerate();
1.24 +
1.25 + /**
1.26 + * Fill a handler info object with information from the datastore.
1.27 + *
1.28 + * Note: because of the way the external helper app service currently mixes
1.29 + * OS and user handler info in the same handler info object, this method
1.30 + * takes an existing handler info object (probably retrieved from the OS)
1.31 + * and "fills it in" with information from the datastore, overriding any
1.32 + * existing properties on the object with properties from the datastore.
1.33 + *
1.34 + * Ultimately, however, we're going to separate OS and user handler info
1.35 + * into separate objects, at which point this method should be renamed to
1.36 + * something like "get" or "retrieve", take a class and type (or perhaps
1.37 + * a type whose class can be determined by querying the type, for example
1.38 + * an nsIContentType which is also an nsIMIMEType or an nsIProtocolScheme),
1.39 + * and return a handler info object representing only the user info.
1.40 + *
1.41 + * Note: if you specify an override type, then the service will fill in
1.42 + * the handler info object with information about that type instead of
1.43 + * the type specified by the object's nsIHandlerInfo::type attribute.
1.44 + *
1.45 + * This is useful when you are trying to retrieve information about a MIME
1.46 + * type that doesn't exist in the datastore, but you have a file extension
1.47 + * for that type, and nsIHandlerService::getTypeFromExtension returns another
1.48 + * MIME type that does exist in the datastore and can handle that extension.
1.49 + *
1.50 + * For example, the user clicks on a link, and the content has a MIME type
1.51 + * that isn't in the datastore, but the link has a file extension, and that
1.52 + * extension is associated with another MIME type in the datastore (perhaps
1.53 + * an unofficial MIME type preceded an official one, like with image/x-png
1.54 + * and image/png).
1.55 + *
1.56 + * In that situation, you can call this method to fill in the handler info
1.57 + * object with information about that other type by passing the other type
1.58 + * as the aOverrideType parameter.
1.59 + *
1.60 + * @param aHandlerInfo the handler info object
1.61 + * @param aOverrideType a type to use instead of aHandlerInfo::type
1.62 + *
1.63 + * Note: if there is no information in the datastore about this type,
1.64 + * this method throws NS_ERROR_NOT_AVAILABLE. Callers are encouraged to
1.65 + * check exists() before calling fillHandlerInfo(), to prevent spamming the
1.66 + * console with XPCOM exception errors.
1.67 + */
1.68 + void fillHandlerInfo(in nsIHandlerInfo aHandlerInfo,
1.69 + in ACString aOverrideType);
1.70 +
1.71 + /**
1.72 + * Save the preferred action, preferred handler, possible handlers, and
1.73 + * always ask properties of the given handler info object to the datastore.
1.74 + * Updates an existing record or creates a new one if necessary.
1.75 + *
1.76 + * Note: if preferred action is undefined or invalid, then we assume
1.77 + * the default value nsIHandlerInfo::useHelperApp.
1.78 + *
1.79 + * @param aHandlerInfo the handler info object
1.80 + */
1.81 + void store(in nsIHandlerInfo aHandlerInfo);
1.82 +
1.83 + /**
1.84 + * Whether or not a record for the given handler info object exists
1.85 + * in the datastore. If the datastore is corrupt (or some other error
1.86 + * is caught in the implementation), false will be returned.
1.87 + *
1.88 + * @param aHandlerInfo a handler info object
1.89 + *
1.90 + * @returns whether or not a record exists
1.91 + */
1.92 + boolean exists(in nsIHandlerInfo aHandlerInfo);
1.93 +
1.94 + /**
1.95 + * Remove the given handler info object from the datastore. Deletes all
1.96 + * records associated with the object, including the preferred handler, info,
1.97 + * and type records plus the entry in the list of types, if they exist.
1.98 + * Otherwise, it does nothing and does not return an error.
1.99 + *
1.100 + * @param aHandlerInfo the handler info object
1.101 + */
1.102 + void remove(in nsIHandlerInfo aHandlerInfo);
1.103 +
1.104 + /**
1.105 + * Get the MIME type mapped to the given file extension in the datastore.
1.106 + *
1.107 + * XXX If we ever support extension -> protocol scheme mappings, then this
1.108 + * method should work for those as well.
1.109 + *
1.110 + * Note: in general, you should use nsIMIMEService::getTypeFromExtension
1.111 + * to get a MIME type from a file extension, as that method checks a variety
1.112 + * of other sources besides just the datastore. Use this only when you want
1.113 + * to specifically get only the mapping available in the datastore.
1.114 + *
1.115 + * @param aFileExtension the file extension
1.116 + *
1.117 + * @returns the MIME type, if any; otherwise returns an empty string ("").
1.118 + */
1.119 + ACString getTypeFromExtension(in ACString aFileExtension);
1.120 +};
