nsINavHistoryQuery

toolkit/components/places/public/nsINavHistoryService.idlScriptable

Encapsulates all the query parameters you're likely to need when building up history UI. All parameters are ANDed together.

1.0

Introduced

Gecko 1.9

Inherits from: nsISupports Last changed in Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1)

The nsINavHistoryQuery is not intended to be a super-general query mechanism. This was designed so that most queries can be done in only one SQL query. This is important because, if the user has their profile on a networked drive, query latency can be non-negligible

Method overview

nsINavHistoryQuery clone();

void getFolders([optional

]out unsigned long count, [retval,array,size_is(count)] out long long folders);

void getTransitions([optional] out unsigned long count, [retval,array,size_is(count)] out unsigned long transitions);

void setFolders([const,array, size_is(folderCount)] in long long folders, in unsigned long folderCount);

void setTransitions([const,array, size_is(count)] in unsigned long transitions, in unsigned long count);

Attributes

Attribute	Type	Description
`absoluteBeginTime`	`PRTime`	Read only: Retrieves the begin time value that the currently loaded reference points + offset resolve to.
`absoluteEndTime`	`PRTime`	Read only: Retrieves the end time value that the currently loaded reference points + offset resolve to.
`annotation`	`AUTF8String`	The annotation name.
`annotationIsNot`	`boolean`	Test for existance or non-existance of a given annotation. We don't currently support >1 annotation name per query. If `annotationIsNot` is `true`, we test for the non-existance of the specified annotation. Testing for not annotation will do the same thing as a normal query and remove everything that doesn't have that annotation. Asking for things that DO have a given annotation is a little different. It also includes things that have never been visited. This allows place queries to be returned (which might include bookmark folders -- use the bookmark service's `GetFolderURI`) as well as anything else that may have been tagged with an annotation. This will only work for `RESULTS_AS_URI` since there will be no visits for these items.
`beginTime`	`PRTime`	Begin time range for results (INCLUSIVE).
`beginTimeReference`	`long`	One of the constants `TIME_RELATIVE_*` which indicates how to interpret the corresponding begin time value.
`domain`	`AUTF8String`	This is the host or domain name (controlled by `domainIsHost`). When `domainIsHost`, domain only does exact matching on host names. Otherwise, it will return anything whose host name ends in `domain`. This one is a little different than most. Setting it to an empty string is a real query and will match any URI that has no host name (local files and such). Set this to `NULL` (in C++ use `SetIsVoid`) if you don't want domain matching.
`domainIsHost`	`boolean`	This controls the meaning of `domain`, and whether it is an exact match `domainIsHost` = `true`, or hierarchical (`= false`).
`endTime`	`PRTime`	End time range for results (INCLUSIVE).
`endTimeReference`	`long`	One of the constants `TIME_RELATIVE_*` which indicates how to interpret the corresponding end time value.
`folderCount`	`long`	Read only: Count of folders.
`hasAnnotation`	`boolean`	Read only: Whether or not, `annotation` exists.
`hasBeginTime`	`boolean`	Read only: Whether or not, the corresponding begin time is considered.
`hasDomain`	`boolean`	Read only: Whether or not, `domain` exists.
`hasEndTime`	`boolean`	Read only: Whether or not, the corresponding end time is considered.
`hasSearchTerms`	`boolean`	Read only: Whether or not, text search terms exists.
`hasUri`	`boolean`	Read only: Whether or not, `uri` exists.
`maxVisits`	`long`	Set upper limits for how many times an item has been visited. The default value is `"-1"`, and in that case all items are matched regardless of their visit count.
`minVisits`	`long`	Set lower limits for how many times an item has been visited. The default value is `"-1"`, and in that case all items are matched regardless of their visit count.
`onlyBookmarked`	`boolean`	When set, returns only bookmarked items, when unset, returns anything. Setting this is equivalent to listing all bookmark folders in the `folders` parameter.
`searchTerms`	`AString`	Text search terms.
`tags`	`nsIVariant`	A list of tags to use for filtering query results. This attribute must be an array of strings. Duplicate tags may be specified, but when reading the list, only unique tags are returned. When called as a getter, this returns an array of strings sorted in ascending lexicographical (alphabetical) order. This array may be empty, in which case no filtering by tags is performed. To search for items that are tagged with any given tags instead of all, multiple queries may be passed to the `nsINavHistoryService` method `nsINavHistoryService.executeQueries()`.
`tagsAreNot`	`boolean`	If `true`, the results include only items that are not tagged with the specified `tags`. If `false`, only tags in the `tags` list are included in the results.
`uri`	`nsIURI`	This is a URI to match, to, for example, find out every time you visited a given URI. Use `uriIsPrefix` to control whether this is an exact match.
`uriIsPrefix`	`boolean`	Controls the interpretation of `uri`. When unset (default), the URI will request an exact match of the specified URI. When set, any history entry beginning in `uri` will match. For example `http://bar.com/foo` will match `http://bar.com/foo` as well as `http://bar.com/foo/baz.gif`.

Constants

Constant	Value	Description
`TIME_RELATIVE_EPOCH`	0	Default value. The time is relative to Jan 1 1970 GMT, (this is a normal PRTime). As a special case, a 0 time relative to `TIME_RELATIVE_EPOCH` indicates that the time is not part of the query. This is the default, so an empty query will match any time.
`TIME_RELATIVE_TODAY`	1	The time is relative to this morning at midnight. Normally used for queries relative to today. For example, a "past week" query would be (today-6 days -> today+1 day).
`TIME_RELATIVE_NOW`	2	The time is relative to right now.

Note: PRTime is in MICROseconds since 1 Jan 1970. JavaScript date objects are expressed in MILLIseconds since 1 Jan 1970.

Methods

getFolders()

This method retrieves all the folders with the folder count.

 void getFolders(
   [optional] out unsigned long count,
   [retval,array,size_is(count)] out long long folders
 );

Parameters

count Optional: The count of the folders. This optional parameter was required prior to Gecko 2.0.
folders: The retrieved folders.

setFolders()

This method sets the folders with the given folder count.

 void setFolders(
   [const,array, size_is(folderCount)] in long long folders,
   in unsigned long folderCount
 );

Parameters

count: The count of the folders.
folders: The folders to be set.

clone()

This method creates a new query item with the same parameters of this one.

 nsINavHistoryQuery clone();

Parameters

None.

Return value

Returns the newly created cloned query.

getTransitions()

Get the transitions set for this query.

void getTransitions(
  out unsigned long count, Optional
  [retval,array,size_is(count)] out unsigned long transitions
);

Parameters

count Optional: The number of transitions
transitions: Missing Description

setTransitions()

When the set of transitions is nonempty, results are limited to pages which have at least one visit for each of the transition types.

Limit results to the specified list of transition types.

void setTransitions(
  [const,array, size_is(count)] in unsigned long transitions,
  in unsigned long count
);

Parameters

transitions: Missing Description.
count: The number of transitions.

Method overview

Attributes

Constants

Methods

getFolders()

Parameters

setFolders()

Parameters

clone()

Parameters

Return value

getTransitions()

Parameters

setTransitions()

Parameters

See also