1 /* 2 * Copyright (C) 2003, 2004 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 <Foundation/Foundation.h> 30 31 @class NSError; 32 33 @class WebHistoryItem; 34 @class WebHistoryPrivate; 35 36 /* 37 @discussion Notifications sent when history is modified. 38 @constant WebHistoryItemsAddedNotification Posted from addItems:. This 39 notification comes with a userInfo dictionary that contains the array of 40 items added. The key for the array is WebHistoryItemsKey. 41 @constant WebHistoryItemsRemovedNotification Posted from removeItems:. 42 This notification comes with a userInfo dictionary that contains the array of 43 items removed. The key for the array is WebHistoryItemsKey. 44 @constant WebHistoryAllItemsRemovedNotification Posted from removeAllItems 45 @constant WebHistoryLoadedNotification Posted from loadFromURL:error:. 46 */ 47 extern NSString *WebHistoryItemsAddedNotification; 48 extern NSString *WebHistoryItemsRemovedNotification; 49 extern NSString *WebHistoryAllItemsRemovedNotification; 50 extern NSString *WebHistoryLoadedNotification; 51 extern NSString *WebHistorySavedNotification; 52 53 extern NSString *WebHistoryItemsKey; 54 55 /*! 56 @class WebHistory 57 @discussion WebHistory is used to track pages that have been loaded 58 by WebKit. 59 */ 60 @interface WebHistory : NSObject { 61 @private 62 WebHistoryPrivate *_historyPrivate; 63 } 64 65 /*! 66 @method optionalSharedHistory 67 @abstract Returns a shared WebHistory instance initialized with the default history file. 68 @result A WebHistory object. 69 */ 70 + (WebHistory *)optionalSharedHistory; 71 72 /*! 73 @method setOptionalSharedHistory: 74 @param history The history to use for the global WebHistory. 75 */ 76 + (void)setOptionalSharedHistory:(WebHistory *)history; 77 78 /*! 79 @method loadFromURL:error: 80 @param URL The URL to use to initialize the WebHistory. 81 @param error Set to nil or an NSError instance if an error occurred. 82 @abstract The designated initializer for WebHistory. 83 @result Returns YES if successful, NO otherwise. 84 */ 85 - (BOOL)loadFromURL:(NSURL *)URL error:(NSError **)error; 86 87 /*! 88 @method saveToURL:error: 89 @discussion Save history to URL. It is the client's responsibility to call this at appropriate times. 90 @param URL The URL to use to save the WebHistory. 91 @param error Set to nil or an NSError instance if an error occurred. 92 @result Returns YES if successful, NO otherwise. 93 */ 94 - (BOOL)saveToURL:(NSURL *)URL error:(NSError **)error; 95 96 /*! 97 @method addItems: 98 @param newItems An array of WebHistoryItems to add to the WebHistory. 99 */ 100 - (void)addItems:(NSArray *)newItems; 101 102 /*! 103 @method removeItems: 104 @param items An array of WebHistoryItems to remove from the WebHistory. 105 */ 106 - (void)removeItems:(NSArray *)items; 107 108 /*! 109 @method removeAllItems 110 */ 111 - (void)removeAllItems; 112 113 /*! 114 @method orderedLastVisitedDays 115 @discussion Get an array of NSCalendarDates, each one representing a unique day that contains one 116 or more history items, ordered from most recent to oldest. 117 @result Returns an array of NSCalendarDates for which history items exist in the WebHistory. 118 */ 119 - (NSArray *)orderedLastVisitedDays; 120 121 /*! 122 @method orderedItemsLastVisitedOnDay: 123 @discussion Get an array of WebHistoryItem that were last visited on the day represented by the 124 specified NSCalendarDate, ordered from most recent to oldest. 125 @param calendarDate A date identifying the unique day of interest. 126 @result Returns an array of WebHistoryItems last visited on the indicated day. 127 */ 128 - (NSArray *)orderedItemsLastVisitedOnDay:(NSCalendarDate *)calendarDate; 129 130 /*! 131 @method itemForURL: 132 @abstract Get an item for a specific URL 133 @param URL The URL of the history item to search for 134 @result Returns an item matching the URL 135 */ 136 - (WebHistoryItem *)itemForURL:(NSURL *)URL; 137 138 /*! 139 @method setHistoryItemLimit: 140 @discussion Limits the number of items that will be stored by the WebHistory. 141 @param limit The maximum number of items that will be stored by the WebHistory. 142 */ 143 - (void)setHistoryItemLimit:(int)limit; 144 145 /*! 146 @method historyItemLimit 147 @result The maximum number of items that will be stored by the WebHistory. 148 */ 149 - (int)historyItemLimit; 150 151 /*! 152 @method setHistoryAgeInDaysLimit: 153 @discussion setHistoryAgeInDaysLimit: sets the maximum number of days to be read from 154 stored history. 155 @param limit The maximum number of days to be read from stored history. 156 */ 157 - (void)setHistoryAgeInDaysLimit:(int)limit; 158 159 /*! 160 @method historyAgeInDaysLimit 161 @return Returns the maximum number of days to be read from stored history. 162 */ 163 - (int)historyAgeInDaysLimit; 164 165 @end 166