Home | History | Annotate | Download | only in Interfaces 
      1 /*
      2  * Copyright (C) 2006, 2007, 2008, 2009 Apple Inc. All rights reserved.
      3  *
      4  * Redistribution and use in source and binary forms, with or without
      5  * modification, are permitted provided that the following conditions
      6  * are met:
      7  * 1. Redistributions of source code must retain the above copyright
      8  *    notice, this list of conditions and the following disclaimer.
      9  * 2. Redistributions in binary form must reproduce the above copyright
     10  *    notice, this list of conditions and the following disclaimer in the
     11  *    documentation and/or other materials provided with the distribution.
     12  *
     13  * THIS SOFTWARE IS PROVIDED BY APPLE COMPUTER, INC. ``AS IS'' AND ANY
     14  * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
     15  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
     16  * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL APPLE COMPUTER, INC. OR
     17  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
     18  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
     19  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
     20  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
     21  * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
     22  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
     23  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
     24  */
     25 
     26 cpp_quote("#define WebIconDatabaseDidAddIconNotification TEXT(\"WebIconDatabaseDidAddIconNotification\")")
     27 cpp_quote("#define WebIconNotificationUserInfoURLKey TEXT(\"WebIconNotificationUserInfoURLKey\")")
     28 cpp_quote("#define WebIconDatabaseDidRemoveAllIconsNotification TEXT(\"WebIconDatabaseDidRemoveAllIconsNotification\")")
     29 
     30 #ifndef DO_NO_IMPORTS
     31 import "oaidl.idl";
     32 import "ocidl.idl";
     33 #endif
     34 
     35 /*!
     36     @class WebIconDatabase
     37     @discussion Features:
     38         - memory cache icons at different sizes
     39         - disk storage
     40         - icon update notification
     41 
     42         Uses:
     43         - WebIconLoader to cache icon images
     44         - UI elements to retrieve icons that represent site URLs.
     45         - Save icons to disk for later use.
     46 
     47     Every icon in the database has a retain count.  If an icon has a retain count greater than 0, it will be written to disk for later use. If an icon's retain count equals zero it will be removed from disk.  The retain count is not persistent across launches. If the WebKit client wishes to retain an icon it should retain the icon once for every launch.  This is best done at initialization time before the database begins removing icons.  To make sure that the database does not remove unretained icons prematurely, call delayDatabaseCleanup until all desired icons are retained.  Once all are retained, call allowDatabaseCleanup.
     48 
     49     Note that an icon can be retained after the database clean-up has begun. This just has to be done before the icon is removed. Icons are removed from the database whenever new icons are added to it.
     50 
     51     Retention methods can be called for icons that are not yet in the database.
     52 
     53     @interface WebIconDatabase : NSObject
     54 */
     55 [
     56     object,
     57     oleautomation,
     58     hidden,
     59     uuid(E93F2616-2560-47d9-BD4D-6E2F1E1D3174),
     60     pointer_default(unique)
     61 ]
     62 interface IWebIconDatabase : IUnknown
     63 {
     64     /*!
     65         @method sharedIconDatabase
     66         @abstract Returns a shared instance of the icon database
     67         + (WebIconDatabase *)sharedIconDatabase;
     68     */
     69     HRESULT sharedIconDatabase([out, retval] IWebIconDatabase** result);
     70 
     71     /*!
     72         @method iconForURL:withSize:
     73         @discussion Calls iconForURL:withSize:cache: with YES for cache.
     74         @param URL
     75         @param size
     76         - (NSImage *)iconForURL:(NSString *)URL withSize:(NSSize)size;
     77     */
     78     /*!
     79         @method iconForURL:withSize:cache:
     80         @discussion Returns an icon for a web site URL from memory or disk. nil if none is found.
     81         Usually called by a UI element to determine if a site URL has an associated icon.
     82         Often called by the observer of WebIconChangedNotification after the notification is sent.
     83         @param URL
     84         @param size
     85         @param cache If yes, caches the returned image in memory if not already cached
     86         - (NSImage *)iconForURL:(NSString *)URL withSize:(NSSize)size cache:(BOOL)cache;
     87     */
     88     /*!
     89         @method iconURLForURL:withSize:cache:
     90         @discussion Returns an icon URL for a web site URL from memory or disk. nil if none is found.
     91         @param URL
     92         - (NSString *)iconURLForURL:(NSString *)URL;
     93     */
     94     HRESULT iconForURL([in] BSTR url, [in] LPSIZE size, [in] BOOL cache, [out, retval] OLE_HANDLE* hBitmap);
     95 
     96     /*!
     97         @method defaultIconWithSize:
     98         @param size
     99         - (NSImage *)defaultIconWithSize:(NSSize)size;
    100     */
    101     HRESULT defaultIconWithSize([in] LPSIZE size, [out, retval] OLE_HANDLE* hBitmap);
    102 
    103     /*!
    104         @method retainIconForURL:
    105         @abstract Increments the retain count of the icon.
    106         @param URL
    107         - (void)retainIconForURL:(NSString *)URL;
    108     */
    109     HRESULT retainIconForURL([in] BSTR url);
    110 
    111     /*!
    112         @method releaseIconForURL:
    113         @abstract Decrements the retain count of the icon.
    114         @param URL
    115         - (void)releaseIconForURL:(NSString *)URL;
    116     */
    117     HRESULT releaseIconForURL([in] BSTR url);
    118 
    119     /*!
    120         @method removeAllIcons:
    121         @abstract Emtpies the Icon Database
    122         - (void)removeAllIcons;
    123     */
    124     HRESULT removeAllIcons();
    125 
    126     /*!
    127         @method delayDatabaseCleanup:
    128         @discussion Only effective if called before the database begins removing icons.
    129         delayDatabaseCleanUp increments an internal counter that when 0 begins the database clean-up.
    130         The counter equals 0 at initialization.
    131         - (void)delayDatabaseCleanup;
    132     */
    133     HRESULT delayDatabaseCleanup();
    134 
    135     /*!
    136         @method allowDatabaseCleanup:
    137         @discussion Informs the database that it now can begin removing icons.
    138         allowDatabaseCleanup decrements an internal counter that when 0 begins the database clean-up.
    139         The counter equals 0 at initialization.
    140         - (void)allowDatabaseCleanup;
    141     */
    142     HRESULT allowDatabaseCleanup();
    143 
    144     /*!
    145         @method iconURLForURL:withSize:cache:
    146         @discussion Returns an icon URL for a web site URL from memory or disk. nil if none is found.
    147         @param URL
    148         - (NSString *)iconURLForURL:(NSString *)URL;
    149     */
    150     HRESULT iconURLForURL([in] BSTR url, [out, retval] BSTR* iconURL);
    151 
    152     /*!
    153         @method isEnabled
    154         @discussion Returns true if the icon database is currently enabled, or false if it
    155         is disabled.
    156         - (BOOL)isEnabled;
    157     */
    158     HRESULT isEnabled([out, retval] BOOL* result);
    159 
    160     /*!
    161         @method setEnabled:
    162         @discussion Enables or disables the icon database based on the flag passed in.
    163         @param flag Pass true to enable the icon database, or false to disable it.
    164         - (void)setEnabled:(BOOL)flag;
    165     */
    166     HRESULT setEnabled([in] BOOL flag);
    167 }
    168