Home | History | Annotate | Download | only in History 
      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