image/imgICache.idl

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
   2  *
   3  * This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 #include "nsISupports.idl"
   8
   9 interface imgIRequest;
  10 interface nsIPrincipal;
  11 interface nsIProperties;
  12 interface nsIURI;
  13
  14 webidl Document;
  15
  16 %{ C++
  17 namespace mozilla {
  18 class OriginAttributes;
  19 } // mozilla namespace
  20 %}
  21
  22 [ptr] native OriginAttributesPtr(mozilla::OriginAttributes);
  23
  24 /**
  25  * imgICache interface
  26  *
  27  * @author Stuart Parmenter <pavlov@netscape.com>
  28  * @version 0.1
  29  * @see imagelib2
  30  */
  31 [scriptable, builtinclass, uuid(bfdf23ff-378e-402e-8a6c-840f0c82b6c3)]
  32 interface imgICache : nsISupports
  33 {
  34   /**
  35    * Evict images from the cache.
  36    *
  37    * @param chrome If TRUE,  evict only chrome images.
  38    *               If FALSE, evict everything except chrome images.
  39    */
  40   void clearCache(in boolean chrome);
  41
  42   /**
  43    * Evict images from the cache.
  44    *
  45    * @param uri The URI to remove.
  46    * @param doc The document to remove the cache entry for.
  47    * @throws NS_ERROR_NOT_AVAILABLE if \a uri was unable to be removed from
  48    * the cache.
  49    */
  50   [noscript] void removeEntry(in nsIURI uri, [optional] in Document doc);
  51
  52   /**
  53    * Evict images from the cache with the same origin and the same
  54    * originAttributes of the passed principal, across all processes. May only be
  55    * called from the parent process.
  56    *
  57    * @param aPrincipal The principal to clear cache entries for. The principals
  58    * origin attributes are used to determine whether the private or normal
  59    * browsing cache is cleared.
  60    * @throws NS_ERROR_NOT_AVAILABLE if not called in the parent process.
  61    */
  62   void removeEntriesFromPrincipalInAllProcesses(in nsIPrincipal aPrincipal);
  63
  64   /**
  65    * Evict images from the non-chrome cache which match the the given base
  66    * domain. Matching cache entries will be cleared across all origin attributes
  67    * and all processes.
  68    *
  69    * @param aBaseDomain base domain to delete cache entries for.
  70    * @throws NS_ERROR_NOT_AVAILABLE if not called in the parent process.
  71    */
  72   void removeEntriesFromBaseDomainInAllProcesses(in ACString aBaseDomain);
  73
  74   /**
  75    * Find Properties
  76    * Used to get properties such as 'type' and 'content-disposition'
  77    * 'type' is a nsISupportsCString containing the images' mime type such as
  78    * 'image/png'
  79    * 'content-disposition' will be a nsISupportsCString containing the header
  80    * If you call this before any data has been loaded from a URI, it will
  81    * succeed, but come back empty.
  82    *
  83    * Hopefully this will be removed with bug 805119
  84    *
  85    * @param uri The URI to look up.
  86    * @param doc Optional pointer to the document that the cache entry belongs to.
  87    * @returns NULL if the URL was not found in the cache
  88    */
  89   [must_use]
  90   nsIProperties findEntryProperties(in nsIURI uri,
  91                                     [optional] in Document doc);
  92
  93   /**
  94    * Make this cache instance respect private browsing notifications. This
  95    * entails clearing the chrome and content caches whenever the
  96    * last-pb-context-exited notification is observed.
  97    */
  98   void respectPrivacyNotifications();
  99
 100   /**
 101    * Clear the image cache for a document.  Controlled documents are responsible
 102    * for doing this manually when they get destroyed.
 103    */
 104   [noscript, notxpcom]
 105   void clearCacheForControlledDocument(in Document doc);
 106 };