WebHistory Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/WebKit.framework
Availability
Available in OS X v10.2 with Safari 1.0 and later.
Available in OS X v10.2.7 and later.
Companion guide
Declared in
WebHistory.h

Overview

WebHistory objects are used to maintain the pages visited by users. Visited pages are represented by WebHistoryItem objects. You add and remove history items using the addItems: and removeItems: methods. These methods post appropriate notifications when items are added or removed so you can update the display. WebHistory organizes the WebHistoryItem objects by the day they were visited, ordered from most recent to oldest. You can request all the days that contain history items using the orderedLastVisitedDays method or request the items visited on a particular day using the orderedItemsLastVisitedOnDay: method. WebHistory objects can be loaded and saved by specifying a file URL (see loadFromURL:error:).

Tasks

Accessing Shared History Objects

Adding and Removing History Items

Getting Web History Items

Loading and Saving History Information

Getting and Setting Attributes

Class Methods

optionalSharedHistory

Returns a shared web history object, if one exists.

+ (WebHistory *)optionalSharedHistory
Return Value

A shared web history object initialized with the default web history file, or nil if one was not previously specified using the setOptionalSharedHistory: method.

Availability
  • Available in OS X v10.2 with Safari 1.0 and later.
  • Available in OS X v10.2.7 and later.
Declared In
WebHistory.h

setOptionalSharedHistory:

Sets the web history object to share.

+ (void)setOptionalSharedHistory:(WebHistory *)history
Parameters
history

The web history object to share.

Availability
  • Available in OS X v10.2 with Safari 1.0 and later.
  • Available in OS X v10.2.7 and later.
Declared In
WebHistory.h

Instance Methods

addItems:

Inserts or updates the specified items in the web history.

- (void)addItems:(NSArray *)newItems
Parameters
newItems

An array of web history items to add. If an item in the array already exists in the web history this method replaces the existing item, so that the last-visited date for the item is updated.

Discussion

When successful, this method posts a notification (WebHistoryItemsAddedNotification).

Availability
  • Available in OS X v10.2 with Safari 1.0 and later.
  • Available in OS X v10.2.7 and later.
Declared In
WebHistory.h

historyAgeInDaysLimit

Returns the maximum age of web history items that can be retrieved.

- (int)historyAgeInDaysLimit
Return Value

The maximum age, in days, of web history items that can be retrieved.

Availability
  • Available in OS X v10.3.9 and later.
Declared In
WebHistory.h

historyItemLimit

Returns the maximum number of web history items that can be stored.

- (int)historyItemLimit
Return Value

The maximum number of web history items that can be stored.

Availability
  • Available in OS X v10.3.9 and later.
Declared In
WebHistory.h

itemForURL:

Returns the web history item that corresponds to the specified web location.

- (WebHistoryItem *)itemForURL:(NSURL *)URL
Parameters
URL

The location, as a URL, of the webpage that was visited.

Return Value

The web history item that represents visits to the specified URL, or nil if none was found.

Availability
  • Available in OS X v10.2 with Safari 1.0 and later.
  • Available in OS X v10.2.7 and later.
Declared In
WebHistory.h

loadFromURL:error:

Loads the contents of the specified web history file.

- (BOOL)loadFromURL:(NSURL *)URL error:(NSError **)error
Parameters
URL

The URL of the file to load. The file should have been created previously by a web history object. Note that the file’s format is private and should not be edited directly.

error

On output, nil if the load was successful; otherwise, error, contains details of the failure.

Return Value

YES if successful; otherwise, NO.

Discussion

When successful, this method posts a notification (WebHistoryLoadedNotification).

Availability
  • Available in OS X v10.2 with Safari 1.0 and later.
  • Available in OS X v10.2.7 and later.
Declared In
WebHistory.h

orderedItemsLastVisitedOnDay:

Returns web history items that were last visited on the specified date.

- (NSArray *)orderedItemsLastVisitedOnDay:(NSCalendarDate *)calendarDate
Parameters
calendarDate

The date on which the web history items were last visited.

Return Value

An array of web history items that were last visited on the specified date.

Availability
  • Available in OS X v10.2 with Safari 1.0 and later.
  • Available in OS X v10.2.7 and later.
Declared In
WebHistory.h

orderedLastVisitedDays

Returns all calendar days represented in the web history.

- (NSArray *)orderedLastVisitedDays
Return Value

An array of calendar days, in order from most recent to oldest. Each calendar day is associated with at least one web history item.

Availability
  • Available in OS X v10.2 with Safari 1.0 and later.
  • Available in OS X v10.2.7 and later.
Declared In
WebHistory.h

removeAllItems

Removes all items from the web history.

- (void)removeAllItems
Discussion

When successful, this method posts a notification (WebHistoryAllItemsRemovedNotification).

Availability
  • Available in OS X v10.2 with Safari 1.0 and later.
  • Available in OS X v10.2.7 and later.
Declared In
WebHistory.h

removeItems:

Removes the specified items from the web history.

- (void)removeItems:(NSArray *)items
Parameters
items

An array of web history items to remove.

Discussion

When successful, this method posts a notification (WebHistoryItemsRemovedNotification).

Availability
  • Available in OS X v10.2 with Safari 1.0 and later.
  • Available in OS X v10.2.7 and later.
Declared In
WebHistory.h

saveToURL:error:

Saves the web history to the specified file.

- (BOOL)saveToURL:(NSURL *)URL error:(NSError **)error
Parameters
URL

The URL of the file to contain the web history information. The file must be user-writable, but its format is private and should not be edited directly.

error

On output, nil if the load was successful; otherwise, error, which contains details of the failure.

Return Value

YES if successful; otherwise, NO

Discussion

When successful, this method posts a notification (WebHistorySavedNotification).

Availability
  • Available in OS X v10.2 with Safari 1.0 and later.
  • Available in OS X v10.2.7 and later.
Declared In
WebHistory.h

setHistoryAgeInDaysLimit:

Sets the maximum age of web history items that can be retrieved.

- (void)setHistoryAgeInDaysLimit:(int)limit
Parameters
limit

The maximum age, in days, of retrievable web history items.

Availability
  • Available in OS X v10.3.9 and later.
Declared In
WebHistory.h

setHistoryItemLimit:

Sets the maximum number of web history items to store.

- (void)setHistoryItemLimit:(int)limit
Parameters
limit

The maximum number of web history items to store.

Availability
  • Available in OS X v10.3.9 and later.
Declared In
WebHistory.h

Constants

Web History Dictionary Keys

The key for accessing the web history items stored in a notification’s user information dictionary.

extern NSString *WebHistoryItemsKey;
Constants
WebHistoryItemsKey

The key to access an array containing the added or removed web history items.

Available in OS X v10.2 and later.

Declared in WebHistory.h.

Discussion

This string is used as the key in the userInfo dictionary passed as the argument to the WebHistoryAllItemsRemovedNotification, WebHistoryItemsAddedNotification, and WebHistoryItemsRemovedNotification notifications.

Availability
  • Available in OS X v10.2 with Safari 1.0 and later.
  • Available in OS X v10.2.7 and later.
Declared In
WebHistory.h

Notifications

WebHistoryAllItemsRemovedNotification

Posted when all history items have been removed from the web history.

The notification object is the web history from which the history items were removed. The userInfo dictionary contains the following information:

Key

Value

@”WebHistoryItemsKey”

An NSArray object containing the removed items.

Availability
See Also
Declared In
WebHistory.h

WebHistoryItemsAddedNotification

Posted when history items have been added to a web history.

The notification object is the web history to which the items were added. The userInfo dictionary contains the following information:

Key

Value

@”WebHistoryItemsKey”

An NSArray object containing the added items.

Availability
See Also
Declared In
WebHistory.h

WebHistoryItemsRemovedNotification

Posted when items have been removed from the web history.

The notification object is the web history from which the history items were removed. The userInfo dictionary contains the following information:

Key

Value

@”WebHistoryItemsKey”

An NSArray object containing the removed items.

Availability
See Also
Declared In
WebHistory.h

WebHistoryLoadedNotification

Posted when web history items have been loaded from a URL.

The notification object is the web history that loaded the history items. This notification does not contain a userInfo dictionary.

Availability
See Also
Declared In
WebHistory.h

WebHistorySavedNotification

Posted when web history items have been saved to a URL.

The notification object is the web history that saved the history items. This notification does not contain a userInfo dictionary.

Availability
See Also
Declared In
WebHistory.h