76c30374fdbf47a4aec281f5d6dd61c8600256b5
[WebKit-https.git] / WebKit / Misc / WebIconDatabase.h
1 /*
2  * Copyright (C) 2005 Apple Computer, 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  *
8  * 1.  Redistributions of source code must retain the above copyright
9  *     notice, this list of conditions and the following disclaimer. 
10  * 2.  Redistributions in binary form must reproduce the above copyright
11  *     notice, this list of conditions and the following disclaimer in the
12  *     documentation and/or other materials provided with the distribution. 
13  * 3.  Neither the name of Apple Computer, Inc. ("Apple") nor the names of
14  *     its contributors may be used to endorse or promote products derived
15  *     from this software without specific prior written permission. 
16  *
17  * THIS SOFTWARE IS PROVIDED BY APPLE AND ITS CONTRIBUTORS "AS IS" AND ANY
18  * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
19  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
20  * DISCLAIMED. IN NO EVENT SHALL APPLE OR ITS CONTRIBUTORS BE LIABLE FOR ANY
21  * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
22  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
23  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
24  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
25  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
26  * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
27  */
28
29 #import <Cocoa/Cocoa.h>
30
31 // Sent whenever a site icon has changed. The object of the notification is the icon database.
32 // The userInfo contains the site URL whose icon has changed.
33 // It can be accessed with the key WebIconNotificationUserInfoURLKey.
34 extern NSString *WebIconDatabaseDidAddIconNotification;
35
36 extern NSString *WebIconNotificationUserInfoURLKey;
37
38 extern NSString *WebIconDatabaseDirectoryDefaultsKey;
39 extern NSString *WebIconDatabaseEnabledDefaultsKey;
40
41 extern NSSize WebIconSmallSize;  // 16 x 16
42 extern NSSize WebIconMediumSize; // 32 x 32
43 extern NSSize WebIconLargeSize;  // 128 x 128
44
45 @class WebIconDatabasePrivate;
46
47 /*!
48     @class WebIconDatabase
49     @discussion Features:
50         - memory cache icons at different sizes
51         - disk storage
52         - icon update notification
53         
54         Uses:
55         - WebIconLoader to cache icon images
56         - UI elements to retrieve icons that represent site URLs.
57         - Save icons to disk for later use.
58  
59     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.
60     
61     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.
62     
63     Retention methods can be called for icons that are not yet in the database.
64 */
65 @interface WebIconDatabase : NSObject {
66
67 @private
68     WebIconDatabasePrivate *_private;
69     BOOL _isClosing;
70 }
71
72
73 /*!
74     @method sharedIconDatabase
75     @abstract Returns a shared instance of the icon database
76 */
77 + (WebIconDatabase *)sharedIconDatabase;
78
79 /*!
80     @method iconForURL:withSize:
81     @discussion Calls iconForURL:withSize:cache: with YES for cache.
82     @param URL
83     @param size
84 */
85 - (NSImage *)iconForURL:(NSString *)URL withSize:(NSSize)size;
86
87 /*!
88     @method iconForURL:withSize:cache:
89     @discussion Returns an icon for a web site URL from memory or disk. nil if none is found.
90     Usually called by a UI element to determine if a site URL has an associated icon.
91     Often called by the observer of WebIconChangedNotification after the notification is sent.
92     @param URL
93     @param size
94     @param cache If yes, caches the returned image in memory if not already cached
95 */
96 - (NSImage *)iconForURL:(NSString *)URL withSize:(NSSize)size cache:(BOOL)cache;
97
98 /*!
99     @method iconURLForURL:withSize:cache:
100     @discussion Returns an icon URL for a web site URL from memory or disk. nil if none is found.
101     @param URL
102 */
103 - (NSString *)iconURLForURL:(NSString *)URL;
104
105 /*!
106     @method defaultIconWithSize:
107     @param size
108 */
109 - (NSImage *)defaultIconWithSize:(NSSize)size;
110
111 /*!
112     @method retainIconForURL:
113     @abstract Increments the retain count of the icon.
114     @param URL
115 */
116 - (void)retainIconForURL:(NSString *)URL;
117
118 /*!
119     @method releaseIconForURL:
120     @abstract Decrements the retain count of the icon.
121     @param URL
122 */
123 - (void)releaseIconForURL:(NSString *)URL;
124
125 /*!
126     @method delayDatabaseCleanup:
127     @discussion Only effective if called before the database begins removing icons.
128     delayDatabaseCleanUp increments an internal counter that when 0 begins the database clean-up.
129     The counter equals 0 at initialization.
130 */
131 - (void)delayDatabaseCleanup;
132
133 /*!
134     @method allowDatabaseCleanup:
135     @discussion Informs the database that it now can begin removing icons.
136     allowDatabaseCleanup decrements an internal counter that when 0 begins the database clean-up.
137     The counter equals 0 at initialization.
138 */
139 - (void)allowDatabaseCleanup;
140
141 @end
142
143