WARNING: Most of this content (with the exception of the Mozilla 1.9 XPCOM reference) is very old, and can be expected to be out of date and possibly obsolete. For better XUL documentation, please visit the XUL hub at the Mozilla Developer Center.

nsINavHistoryQueryOptions

IID:ff73bf85-2755-4c1a-a48d-8c91ccca770e
Inherits From:nsISupports

Constants

Grouping by day. The results will be an array of nsINavHistoryResults with type = RESULT_TYPE_DAY, one for each day where there are results. These will have children of corresponding to the search results of that day.
PRUint16 GROUP_BY_DAY = 0
Grouping by exact host. The results will be an array of nsINavHistoryResults with type = RESULT_TYPE_HOST, one for each unique host (for example, "bugzilla.mozilla.org" and "www.mozilla.org" will be separate). The children of these will correspond to the results for each host.
PRUint16 GROUP_BY_HOST = 1
Grouping by toplevel domain. Similar to GROUP_BY_HOST, but there will be one result for each toplevel domain (mozilla.org will be one entry, and will contain results including, for example, "bugzilla.mozilla.org" and "www.mozilla.org").
PRUint16 GROUP_BY_DOMAIN = 2
Group by bookmark folders. Results from the query are grouped in folders containers. This option requires there to be at least one parent folder specified via nsINavHistoryQuery::setFolders. Note, since the folder containers are built from the items that match the results that we are grouping, you will not get any folders (when grouping by folder) with zero items.
PRUint16 GROUP_BY_FOLDER = 3
You can ask for the results to be pre-sorted. Since the DB has indices of many items, it can produce sorted results almost for free. These should be self-explanatory.

Note: re-sorting is slower, as is sorting by title or when you have a host name.

For bookmark items, SORT_BY_NONE means sort by the natural bookmark order.

PRUint16 SORT_BY_NONE = 0
PRUint16 SORT_BY_TITLE_ASCENDING = 1
PRUint16 SORT_BY_TITLE_DESCENDING = 2
PRUint16 SORT_BY_DATE_ASCENDING = 3
PRUint16 SORT_BY_DATE_DESCENDING = 4
PRUint16 SORT_BY_URI_ASCENDING = 5
PRUint16 SORT_BY_URI_DESCENDING = 6
PRUint16 SORT_BY_VISITCOUNT_ASCENDING = 7
PRUint16 SORT_BY_VISITCOUNT_DESCENDING = 8
PRUint16 SORT_BY_KEYWORD_ASCENDING = 9
PRUint16 SORT_BY_KEYWORD_DESCENDING = 10
PRUint16 SORT_BY_DATEADDED_ASCENDING = 11
PRUint16 SORT_BY_DATEADDED_DESCENDING = 12
PRUint16 SORT_BY_LASTMODIFIED_ASCENDING = 13
PRUint16 SORT_BY_LASTMODIFIED_DESCENDING = 14
PRUint16 SORT_BY_COUNT_ASCENDING = 15
PRUint16 SORT_BY_COUNT_DESCENDING = 16
PRUint16 SORT_BY_TAGS_ASCENDING = 17
PRUint16 SORT_BY_TAGS_DESCENDING = 18
PRUint16 SORT_BY_ANNOTATION_ASCENDING = 19
PRUint16 SORT_BY_ANNOTATION_DESCENDING = 20
"URI" results, one for each URI visited in the range. Individual result nodes will be of type "URI".
PRUint16 RESULTS_AS_URI = 0
"Visit" results, with one for each time a page was visited (this will often give you multiple results for one URI). Individual result nodes will have type "Visit"
PRUint16 RESULTS_AS_VISIT = 1
This is identical to RESULT_TYPE_VISIT except that individual result nodes will have type "FullVisit". This is used for the attributes that are not commonly accessed to save space in the common case (the lists can be very long).
PRUint16 RESULTS_AS_FULL_VISIT = 2
PRUint16 QUERY_TYPE_HISTORY = 0
PRUint16 QUERY_TYPE_BOOKMARKS = 1
PRUint16 QUERY_TYPE_UNIFIED = 2

Properties

PRBool applyOptionsToContainers

Only apply our query options to the containers

AUTF8String excludeItemIfParentHasAnnotation

This option excludes items from a bookmarks query if the parent of the item has this annotation. An example is to exclude livemark items (parent folders have the "livemark/feedURI" annotation) Ignored for queries over history.

PRBool excludeItems

This option excludes all URIs and separators from a bookmarks query. This would be used if you just wanted a list of bookmark folders and queries (such as the left pane of the places page). Ignored for queries over history. Defaults to false.

PRBool excludeQueries

Set to true to exclude queries ("place:" URIs) from the query results. Simple folder queries (bookmark folder symlinks) will still be included. Defaults to false.

PRBool excludeReadOnlyFolders

Set to true to exclude read-only folders from the query results. This is designed for cases where you want to give the user the option of filing something into a list of folders. It only affects cases where the actual folder result node would appear in its parent folder and filters it out. It doesn't affect the query at all, and doesn't affect more complex queries (such as "folders with annotation X").

PRBool expandQueries

When set, allows items with "place:" URIs to appear as containers, with the container's contents filled in from the stored query. If not set, these will appear as normal items. Doesn't do anything if excludeQueries is set. Defaults to false.

Note that this has no effect on folder links, which are place: URIs returned by nsINavBookmarkService.GetFolderURI. These are always expanded and will appear as bookmark folders.

PRBool includeHidden

Most items in history are marked "hidden." Only toplevel pages that the user sees in the URL bar are not hidden. Hidden things include the content of iframes and all images on web pages. Normally, you don't want these things. If you do, set this flag and you'll get all items, even hidden ones. Does nothing for bookmark queries. Defaults to false.

PRUint32 maxResults

This is the maximum number of results that you want. The query is exeucted, the results are sorted, and then the top 'maxResults' results are taken and returned. Set to 0 (the default) to get all results.

THIS DOES NOT WORK IN CONJUNCTION WITH SORTING BY TITLE. This is because sorting by title requires us to sort after using locale-sensetive sorting (as opposed to letting the database do it for us).

Instead, we get the result ordered by date, pick the maxResult most recent ones, and THEN sort by title.

PRUint16 queryType

The type of search to use when querying the DB; This attribute is only honored by query nodes. It is silently ignored for simple folder queries.

PRUint16 resultType

Sets the result type. One of RESULT_TYPE_* which includes how URIs are represented.

PRBool showSessions

Separate/group history items based on session information. Only matters when sorting by date.

AUTF8String sortingAnnotation

The annotation to use in SORT_BY_ANNOTATION_* sorting modes.

PRUint16 sortingMode

The sorting mode to be used for this query. mode is one of SORT_BY_*

Methods

nsINavHistoryQueryOptions clone ( ) void getGroupingMode ( out PRUint32 groupCount , out arrayof PRUint16 groupingMode ) void setGroupingMode ( arrayof PRUint16 groupingMode , PRUint32 groupCount )

nsINavHistoryQueryOptions clone ( )

Creates a new options item with the same parameters of this one.

void getGroupingMode ( out PRUint32 groupCount , out arrayof PRUint16 groupingMode )

The grouping mode to be used for this query. Grouping mode is an array of GROUP_BY_* values that specifies the structure of the tree you want. For example, an array consisting of [GROUP_BY_DAY, GROUP_BY_DOMAIN] will give you a tree whose first level is a list of days, and whose second level is a list of domains, and whose third level is a list of pages in those domains. If you don't want grouping, you can specify an empty array.

Arguments:
groupCount
groupingMode

void setGroupingMode ( arrayof PRUint16 groupingMode , PRUint32 groupCount )

Arguments:
groupingMode
groupCount

References

This interface is the type of the following properties:

nsINavHistoryQueryResultNode.queryOptions

This interface is passed as an argument to the following methods:

nsIDynamicContainer.onContainerNodeOpening, nsINavHistoryService.executeQueries, nsINavHistoryService.executeQuery, nsINavHistoryService.queriesToQueryString, nsINavHistoryService.queryStringToQueries

This interface is returned from the following methods:

nsINavHistoryQueryOptions.clone, nsINavHistoryService.getNewQueryOptions

Reference documentation is generated from Mozilla's source.