uriloader/exthandler/nsIHandlerService.idl

   1 /* This Source Code Form is subject to the terms of the Mozilla Public
   2  * License, v. 2.0. If a copy of the MPL was not distributed with this
   3  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   4
   5 #include "nsISupports.idl"
   6
   7 interface nsIHandlerInfo;
   8 interface nsISimpleEnumerator;
   9 interface nsIMIMEInfo;
  10
  11 [scriptable, uuid(53f0ad17-ec62-46a1-adbc-efccc06babcd)]
  12 interface nsIHandlerService : nsISupports
  13 {
  14   /**
  15    * Asynchronously performs any IO that the nsIHandlerService needs to do
  16    * before it can be of use.
  17    */
  18   void asyncInit();
  19
  20   /**
  21    * Retrieve a list of all handlers in the datastore.  This list is not
  22    * guaranteed to be in any particular order, and callers should not assume
  23    * it will remain in the same order in the future.
  24    *
  25    * @returns a list of all handlers in the datastore
  26    */
  27   nsISimpleEnumerator enumerate();
  28
  29   /**
  30    * Fill a handler info object with information from the datastore.
  31    *
  32    * Note: because of the way the external helper app service currently mixes
  33    * OS and user handler info in the same handler info object, this method
  34    * takes an existing handler info object (probably retrieved from the OS)
  35    * and "fills it in" with information from the datastore, overriding any
  36    * existing properties on the object with properties from the datastore.
  37    *
  38    * Ultimately, however, we're going to separate OS and user handler info
  39    * into separate objects, at which point this method should be renamed to
  40    * something like "get" or "retrieve", take a class and type (or perhaps
  41    * a type whose class can be determined by querying the type, for example
  42    * an nsIContentType which is also an nsIMIMEType or an nsIProtocolScheme),
  43    * and return a handler info object representing only the user info.
  44    *
  45    * Note: if you specify an override type, then the service will fill in
  46    * the handler info object with information about that type instead of
  47    * the type specified by the object's nsIHandlerInfo::type attribute.
  48    *
  49    * This is useful when you are trying to retrieve information about a MIME
  50    * type that doesn't exist in the datastore, but you have a file extension
  51    * for that type, and nsIHandlerService::getTypeFromExtension returns another
  52    * MIME type that does exist in the datastore and can handle that extension.
  53    *
  54    * For example, the user clicks on a link, and the content has a MIME type
  55    * that isn't in the datastore, but the link has a file extension, and that
  56    * extension is associated with another MIME type in the datastore (perhaps
  57    * an unofficial MIME type preceded an official one, like with image/x-png
  58    * and image/png).
  59    *
  60    * In that situation, you can call this method to fill in the handler info
  61    * object with information about that other type by passing the other type
  62    * as the aOverrideType parameter.
  63    *
  64    * @param aHandlerInfo   the handler info object
  65    * @param aOverrideType  a type to use instead of aHandlerInfo::type
  66    *
  67    * Note: if there is no information in the datastore about this type,
  68    * this method throws NS_ERROR_NOT_AVAILABLE. Callers are encouraged to
  69    * check exists() before calling fillHandlerInfo(), to prevent spamming the
  70    * console with XPCOM exception errors.
  71    */
  72   void fillHandlerInfo(in nsIHandlerInfo aHandlerInfo,
  73                        in ACString aOverrideType);
  74
  75   /**
  76    * Save the preferred action, preferred handler, possible handlers, and
  77    * always ask properties of the given handler info object to the datastore.
  78    * Updates an existing record or creates a new one if necessary.
  79    *
  80    * Note: if preferred action is undefined or invalid, then we assume
  81    * the default value nsIHandlerInfo::useHelperApp.
  82    *
  83    * @param aHandlerInfo  the handler info object
  84    */
  85   void store(in nsIHandlerInfo aHandlerInfo);
  86
  87   /**
  88    * Whether or not a record for the given handler info object exists
  89    * in the datastore. If the datastore is corrupt (or some other error
  90    * is caught in the implementation), false will be returned.
  91    *
  92    * @param aHandlerInfo  a handler info object
  93    *
  94    * @returns whether or not a record exists
  95    */
  96   boolean exists(in nsIHandlerInfo aHandlerInfo);
  97
  98   /**
  99    * Remove the given handler info object from the datastore.  Deletes all
 100    * records associated with the object, including the preferred handler, info,
 101    * and type records plus the entry in the list of types, if they exist.
 102    * Otherwise, it does nothing and does not return an error.
 103    *
 104    * @param aHandlerInfo  the handler info object
 105    */
 106   void remove(in nsIHandlerInfo aHandlerInfo);
 107
 108   /**
 109    * Get the MIME type mapped to the given file extension in the datastore.
 110    *
 111    * XXX If we ever support extension -> protocol scheme mappings, then this
 112    * method should work for those as well.
 113    *
 114    * Note: in general, you should use nsIMIMEService::getTypeFromExtension
 115    * to get a MIME type from a file extension, as that method checks a variety
 116    * of other sources besides just the datastore.  Use this only when you want
 117    * to specifically get only the mapping available in the datastore.
 118    *
 119    * @param aFileExtension  the file extension
 120    *
 121    * @returns the MIME type, if any; otherwise returns an empty string ("").
 122    */
 123   ACString getTypeFromExtension(in ACString aFileExtension);
 124
 125   /**
 126    * Whether or not there is a handler known to the OS for the
 127    * specified protocol type.
 128    *
 129    * @param aProtocolScheme scheme to check for support
 130    *
 131    * @returns whether or not a handler exists
 132    */
 133   boolean existsForProtocolOS(in ACString aProtocolScheme);
 134
 135   /**
 136    * Whether or not there is a handler in the datastore or OS for
 137    * the specified protocol type. If there is no handler in the datastore,
 138    * falls back to a check for an OS handler.
 139    *
 140    * @param aProtocolScheme scheme to check for support
 141    *
 142    * @returns whether or not a handler exists
 143    */
 144   boolean existsForProtocol(in ACString aProtocolScheme);
 145
 146   /*
 147    * This method only exists for nsOSHelperAppServiceChild using
 148    * the ContentHandlerService implementation.
 149    *
 150    * Returns an nsIMIMEInfo for the provided MIME type and extension
 151    * obtained from an OS lookup. If no handler is found for the type and
 152    * extension, returns a generic nsIMIMEInfo object. The MIME type and
 153    * extension can be the empty string. When the type and extension don't
 154    * map to the same handler, the semantics/resolution are platform
 155    * specific. See the platform implementations for details.
 156    *
 157    * @param aType           The MIME type to get handler information for.
 158    * @param aFileExtension  The filename extension to use either alone
 159    *                        or with the MIME type to get handler information
 160    *                        for. UTF-8 encoded.
 161    * @param [out] aFound    Out param indicating whether a MIMEInfo could
 162    *                        be found for the provided type and/or extension.
 163    *                        Set to false when neither extension nor the MIME
 164    *                        type are mapped to a handler.
 165    * @return                A nsIMIMEInfo object. This function must return
 166    *                        a MIMEInfo object if it can allocate one. The
 167    *                        only justifiable reason for not returning one is
 168    *                        an out-of-memory error.
 169    */
 170   [noscript] nsIMIMEInfo getMIMEInfoFromOS(in ACString aType,
 171                                            in ACString aFileExtension,
 172                                            out boolean aFound);
 173
 174   /*
 175    * Get a description for the application responsible for handling
 176    * the provided protocol.
 177    */
 178   AString getApplicationDescription(in ACString aProtocolScheme);
 179 };