uriloader/exthandler/nsIHandlerService.idl@925c144e1f1f (annotated)
uriloader/exthandler/nsIHandlerService.idl
Fri, 16 Jan 2015 18:13:44 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Fri, 16 Jan 2015 18:13:44 +0100
- branch
- TOR_BUG_9701
- changeset 14
- 925c144e1f1f
- permissions
- -rw-r--r--
Integrate suggestion from review to improve consistency with existing code.
| michael@0 | 1 | /* This Source Code Form is subject to the terms of the Mozilla Public |
| michael@0 | 2 | * License, v. 2.0. If a copy of the MPL was not distributed with this |
| michael@0 | 3 | * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ |
| michael@0 | 4 | |
| michael@0 | 5 | #include "nsISupports.idl" |
| michael@0 | 6 | |
| michael@0 | 7 | interface nsIHandlerInfo; |
| michael@0 | 8 | interface nsISimpleEnumerator; |
| michael@0 | 9 | |
| michael@0 | 10 | [scriptable, uuid(53f0ad17-ec62-46a1-adbc-efccc06babcd)] |
| michael@0 | 11 | interface nsIHandlerService : nsISupports |
| michael@0 | 12 | { |
| michael@0 | 13 | /** |
| michael@0 | 14 | * Retrieve a list of all handlers in the datastore. This list is not |
| michael@0 | 15 | * guaranteed to be in any particular order, and callers should not assume |
| michael@0 | 16 | * it will remain in the same order in the future. |
| michael@0 | 17 | * |
| michael@0 | 18 | * @returns a list of all handlers in the datastore |
| michael@0 | 19 | */ |
| michael@0 | 20 | nsISimpleEnumerator enumerate(); |
| michael@0 | 21 | |
| michael@0 | 22 | /** |
| michael@0 | 23 | * Fill a handler info object with information from the datastore. |
| michael@0 | 24 | * |
| michael@0 | 25 | * Note: because of the way the external helper app service currently mixes |
| michael@0 | 26 | * OS and user handler info in the same handler info object, this method |
| michael@0 | 27 | * takes an existing handler info object (probably retrieved from the OS) |
| michael@0 | 28 | * and "fills it in" with information from the datastore, overriding any |
| michael@0 | 29 | * existing properties on the object with properties from the datastore. |
| michael@0 | 30 | * |
| michael@0 | 31 | * Ultimately, however, we're going to separate OS and user handler info |
| michael@0 | 32 | * into separate objects, at which point this method should be renamed to |
| michael@0 | 33 | * something like "get" or "retrieve", take a class and type (or perhaps |
| michael@0 | 34 | * a type whose class can be determined by querying the type, for example |
| michael@0 | 35 | * an nsIContentType which is also an nsIMIMEType or an nsIProtocolScheme), |
| michael@0 | 36 | * and return a handler info object representing only the user info. |
| michael@0 | 37 | * |
| michael@0 | 38 | * Note: if you specify an override type, then the service will fill in |
| michael@0 | 39 | * the handler info object with information about that type instead of |
| michael@0 | 40 | * the type specified by the object's nsIHandlerInfo::type attribute. |
| michael@0 | 41 | * |
| michael@0 | 42 | * This is useful when you are trying to retrieve information about a MIME |
| michael@0 | 43 | * type that doesn't exist in the datastore, but you have a file extension |
| michael@0 | 44 | * for that type, and nsIHandlerService::getTypeFromExtension returns another |
| michael@0 | 45 | * MIME type that does exist in the datastore and can handle that extension. |
| michael@0 | 46 | * |
| michael@0 | 47 | * For example, the user clicks on a link, and the content has a MIME type |
| michael@0 | 48 | * that isn't in the datastore, but the link has a file extension, and that |
| michael@0 | 49 | * extension is associated with another MIME type in the datastore (perhaps |
| michael@0 | 50 | * an unofficial MIME type preceded an official one, like with image/x-png |
| michael@0 | 51 | * and image/png). |
| michael@0 | 52 | * |
| michael@0 | 53 | * In that situation, you can call this method to fill in the handler info |
| michael@0 | 54 | * object with information about that other type by passing the other type |
| michael@0 | 55 | * as the aOverrideType parameter. |
| michael@0 | 56 | * |
| michael@0 | 57 | * @param aHandlerInfo the handler info object |
| michael@0 | 58 | * @param aOverrideType a type to use instead of aHandlerInfo::type |
| michael@0 | 59 | * |
| michael@0 | 60 | * Note: if there is no information in the datastore about this type, |
| michael@0 | 61 | * this method throws NS_ERROR_NOT_AVAILABLE. Callers are encouraged to |
| michael@0 | 62 | * check exists() before calling fillHandlerInfo(), to prevent spamming the |
| michael@0 | 63 | * console with XPCOM exception errors. |
| michael@0 | 64 | */ |
| michael@0 | 65 | void fillHandlerInfo(in nsIHandlerInfo aHandlerInfo, |
| michael@0 | 66 | in ACString aOverrideType); |
| michael@0 | 67 | |
| michael@0 | 68 | /** |
| michael@0 | 69 | * Save the preferred action, preferred handler, possible handlers, and |
| michael@0 | 70 | * always ask properties of the given handler info object to the datastore. |
| michael@0 | 71 | * Updates an existing record or creates a new one if necessary. |
| michael@0 | 72 | * |
| michael@0 | 73 | * Note: if preferred action is undefined or invalid, then we assume |
| michael@0 | 74 | * the default value nsIHandlerInfo::useHelperApp. |
| michael@0 | 75 | * |
| michael@0 | 76 | * @param aHandlerInfo the handler info object |
| michael@0 | 77 | */ |
| michael@0 | 78 | void store(in nsIHandlerInfo aHandlerInfo); |
| michael@0 | 79 | |
| michael@0 | 80 | /** |
| michael@0 | 81 | * Whether or not a record for the given handler info object exists |
| michael@0 | 82 | * in the datastore. If the datastore is corrupt (or some other error |
| michael@0 | 83 | * is caught in the implementation), false will be returned. |
| michael@0 | 84 | * |
| michael@0 | 85 | * @param aHandlerInfo a handler info object |
| michael@0 | 86 | * |
| michael@0 | 87 | * @returns whether or not a record exists |
| michael@0 | 88 | */ |
| michael@0 | 89 | boolean exists(in nsIHandlerInfo aHandlerInfo); |
| michael@0 | 90 | |
| michael@0 | 91 | /** |
| michael@0 | 92 | * Remove the given handler info object from the datastore. Deletes all |
| michael@0 | 93 | * records associated with the object, including the preferred handler, info, |
| michael@0 | 94 | * and type records plus the entry in the list of types, if they exist. |
| michael@0 | 95 | * Otherwise, it does nothing and does not return an error. |
| michael@0 | 96 | * |
| michael@0 | 97 | * @param aHandlerInfo the handler info object |
| michael@0 | 98 | */ |
| michael@0 | 99 | void remove(in nsIHandlerInfo aHandlerInfo); |
| michael@0 | 100 | |
| michael@0 | 101 | /** |
| michael@0 | 102 | * Get the MIME type mapped to the given file extension in the datastore. |
| michael@0 | 103 | * |
| michael@0 | 104 | * XXX If we ever support extension -> protocol scheme mappings, then this |
| michael@0 | 105 | * method should work for those as well. |
| michael@0 | 106 | * |
| michael@0 | 107 | * Note: in general, you should use nsIMIMEService::getTypeFromExtension |
| michael@0 | 108 | * to get a MIME type from a file extension, as that method checks a variety |
| michael@0 | 109 | * of other sources besides just the datastore. Use this only when you want |
| michael@0 | 110 | * to specifically get only the mapping available in the datastore. |
| michael@0 | 111 | * |
| michael@0 | 112 | * @param aFileExtension the file extension |
| michael@0 | 113 | * |
| michael@0 | 114 | * @returns the MIME type, if any; otherwise returns an empty string (""). |
| michael@0 | 115 | */ |
| michael@0 | 116 | ACString getTypeFromExtension(in ACString aFileExtension); |
| michael@0 | 117 | }; |
