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*/
37cpp_quote("#define WebHistoryItemsAddedNotification TEXT(\"WebHistoryItemsAddedNotification\")")
38cpp_quote("#define WebHistoryItemsRemovedNotification TEXT(\"WebHistoryItemsRemovedNotification\")")
39cpp_quote("#define WebHistoryAllItemsRemovedNotification TEXT(\"WebHistoryAllItemsRemovedNotification\")")
40cpp_quote("#define WebHistoryLoadedNotification TEXT(\"WebHistoryLoadedNotification\")")
41cpp_quote("#define WebHistoryItemsDiscardedWhileLoadingNotification TEXT(\"WebHistoryItemsDiscardedWhileLoadingNotification\")")
42cpp_quote("#define WebHistorySavedNotification TEXT(\"WebHistorySavedNotification\")")
43
44#ifndef DO_NO_IMPORTS
45import "oaidl.idl";
46import "ocidl.idl";
47import "IWebError.idl";
48import "IWebHistoryItem.idl";
49#endif
50
51interface IWebError;
52interface 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]
66interface 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}