1 /* 2 * Copyright (C) 2006, 2007, 2008 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 /* 27 @discussion Notifications sent when history is modified. 28 @constant WebHistoryItemsAddedNotification Posted from addItems:. This 29 notification comes with a userInfo dictionary that contains the array of 30 items added. The key for the array is WebHistoryItemsKey. 31 @constant WebHistoryItemsRemovedNotification Posted from removeItems:. 32 This notification comes with a userInfo dictionary that contains the array of 33 items removed. The key for the array is WebHistoryItemsKey. 34 @constant WebHistoryAllItemsRemovedNotification Posted from removeAllItems 35 @constant WebHistoryLoadedNotification Posted from loadFromURL:error:. 36 */ 37 cpp_quote("#define WebHistoryItemsAddedNotification TEXT(\"WebHistoryItemsAddedNotification\")") 38 cpp_quote("#define WebHistoryItemsRemovedNotification TEXT(\"WebHistoryItemsRemovedNotification\")") 39 cpp_quote("#define WebHistoryAllItemsRemovedNotification TEXT(\"WebHistoryAllItemsRemovedNotification\")") 40 cpp_quote("#define WebHistoryLoadedNotification TEXT(\"WebHistoryLoadedNotification\")") 41 cpp_quote("#define WebHistoryItemsDiscardedWhileLoadingNotification TEXT(\"WebHistoryItemsDiscardedWhileLoadingNotification\")") 42 cpp_quote("#define WebHistorySavedNotification TEXT(\"WebHistorySavedNotification\")") 43 44 #ifndef DO_NO_IMPORTS 45 import "oaidl.idl"; 46 import "ocidl.idl"; 47 import "IWebError.idl"; 48 import "IWebHistoryItem.idl"; 49 #endif 50 51 interface IWebError; 52 interface IWebHistoryItem; 53 54 /*! 55 @class WebHistory 56 @discussion WebHistory is used to track pages that have been loaded 57 by WebKit. 58 */ 59 [ 60 object, 61 oleautomation, 62 hidden, 63 uuid(F34E4B1A-361D-4b9f-9A3F-D869DCD97F9A), 64 pointer_default(unique) 65 ] 66 interface IWebHistory : IUnknown 67 { 68 /*! 69 @method optionalSharedHistory 70 @abstract Returns a shared WebHistory instance initialized with the default history file. 71 @result A WebHistory object. 72 + (WebHistory *)optionalSharedHistory; 73 */ 74 HRESULT optionalSharedHistory([out, retval] IWebHistory** history); 75 76 /*! 77 @method setOptionalSharedHistory: 78 @param history The history to use for the global WebHistory. 79 + (void)setOptionalSharedHistory:(WebHistory *)history; 80 */ 81 HRESULT setOptionalSharedHistory([in] IWebHistory* history); 82 83 /*! 84 @method loadFromURL:error: 85 @param URL The URL to use to initialize the WebHistory. 86 @param error Set to nil or an NSError instance if an error occurred. 87 @abstract The designated initializer for WebHistory. 88 @result Returns YES if successful, NO otherwise. 89 - (BOOL)loadFromURL:(NSURL *)URL error:(NSError **)error; 90 */ 91 HRESULT loadFromURL([in] BSTR url, [out] IWebError** error, [out, retval] BOOL* succeeded); 92 93 /*! 94 @method saveToURL:error: 95 @discussion Save history to URL. It is the client's responsibility to call this at appropriate times. 96 @param URL The URL to use to save the WebHistory. 97 @param error Set to nil or an NSError instance if an error occurred. 98 @result Returns YES if successful, NO otherwise. 99 - (BOOL)saveToURL:(NSURL *)URL error:(NSError **)error; 100 */ 101 HRESULT saveToURL([in] BSTR url, [out] IWebError** error, [out, retval] BOOL* succeeded); 102 103 /*! 104 @method addItems: 105 @param newItems An array of WebHistoryItems to add to the WebHistory. 106 - (void)addItems:(NSArray *)newItems; 107 */ 108 HRESULT addItems([in] int itemCount, [in] IWebHistoryItem** items); 109 110 /*! 111 @method removeItems: 112 @param items An array of WebHistoryItems to remove from the WebHistory. 113 - (void)removeItems:(NSArray *)items; 114 */ 115 HRESULT removeItems([in] int itemCount, [in] IWebHistoryItem** items); 116 117 /*! 118 @method removeAllItems 119 - (void)removeAllItems; 120 */ 121 HRESULT removeAllItems(); 122 123 /*! 124 @method orderedLastVisitedDays 125 @discussion Get an array of NSCalendarDates, each one representing a unique day that contains one 126 or more history items, ordered from most recent to oldest. 127 @result Returns an array of NSCalendarDates for which history items exist in the WebHistory. 128 129 ADVISORY NOTE: This method may change for the 1.0 SDK. 130 - (NSArray *)orderedLastVisitedDays; 131 */ 132 HRESULT orderedLastVisitedDays([in, out] int* count, [in] DATE* calendarDates); 133 134 /*! 135 @method orderedItemsLastVisitedOnDay: 136 @discussion Get an array of WebHistoryItem that were last visited on the day represented by the 137 specified NSCalendarDate, ordered from most recent to oldest. 138 @param calendarDate A date identifying the unique day of interest. 139 @result Returns an array of WebHistoryItems last visited on the indicated day. 140 141 ADVISORY NOTE: This method may change for the 1.0 SDK. 142 - (NSArray *)orderedItemsLastVisitedOnDay:(NSCalendarDate *)calendarDate; 143 */ 144 HRESULT orderedItemsLastVisitedOnDay([in, out] int* count, [in] IWebHistoryItem** items, [in] DATE calendarDate); 145 146 /*! 147 @method itemForURL: 148 @abstract Get an item for a specific URL 149 @param URL The URL of the history item to search for 150 @result Returns an item matching the URL 151 - (WebHistoryItem *)itemForURL:(NSURL *)URL; 152 */ 153 HRESULT itemForURL([in] BSTR url, [out, retval] IWebHistoryItem** item); 154 155 /*! 156 @method setHistoryItemLimit: 157 @discussion Limits the number of items that will be stored by the WebHistory. 158 @param limit The maximum number of items that will be stored by the WebHistory. 159 - (void)setHistoryItemLimit:(int)limit; 160 */ 161 HRESULT setHistoryItemLimit([in] int limit); 162 163 /*! 164 @method historyItemLimit 165 @result The maximum number of items that will be stored by the WebHistory. 166 - (int)historyItemLimit; 167 */ 168 HRESULT historyItemLimit([out, retval] int* limit); 169 170 /*! 171 @method setHistoryAgeInDaysLimit: 172 @discussion setHistoryAgeInDaysLimit: sets the maximum number of days to be read from 173 stored history. 174 @param limit The maximum number of days to be read from stored history. 175 - (void)setHistoryAgeInDaysLimit:(int)limit; 176 */ 177 HRESULT setHistoryAgeInDaysLimit([in] int limit); 178 179 /*! 180 @method historyAgeInDaysLimit 181 @return Returns the maximum number of days to be read from stored history. 182 - (int)historyAgeInDaysLimit; 183 */ 184 HRESULT historyAgeInDaysLimit([out, retval] int* limit); 185 }
