toolkit/components/places/nsINavHistoryService.idlScriptable
Represents the global options for executing a query.
1.0
66
Introduced
Gecko 1.9
Inherits from: nsISupports Last changed in Gecko 13.0 (Firefox 13.0 / Thunderbird 13.0 / SeaMonkey 2.10)

Method overview

nsINavHistoryQueryOptions clone();

Attributes

Attribute Type Description
applyOptionsToContainers boolean If true, the query options are only applied to the containers.
asyncEnabled boolean

When true, the root container node generated by these options and all of its descendant containers are opened asynchronously if they support doing so. By default, this is false.

Note: Currently, only bookmark folder containers support being opened asynchronously.
excludeItemIfParentHasAnnotation Obsolete since Gecko 13.0 AUTF8String 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.
excludeItems boolean 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.
excludeQueries boolean 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.
excludeReadOnlyFolders boolean 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").
expandQueries boolean 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's getFolderURI method. These are always expanded and will appear as bookmark folders.
includeHidden boolean 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.
maxResults long 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.
queryType short 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. See Query type constants for possible values.
redirectsMode unsigned short

Specifies how to handle redirects; see Redirects mode constants for details. The default value is REDIRECTS_MODE_ALL.

Note: This option is only used on QUERY_TYPE_HISTORY.
resolveNullBookmarkTitles boolean If a bookmark title is NULL (note, not empty), attempt to use the history title. It is set to false by default.
resultType short Sets the result type. See Result type constants for possible values.
showSessions boolean Separate/group history items based on session information. Only matters when sorting by date.
sortingAnnotation AUTF8String The annotation to use in SORT_BY_ANNOTATION_* sorting modes.
sortingMode short The sorting annotation to use; see Sorting methods for possible values.

Constants

Sorting methods

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. Note: re-sorting is slower, as is sorting by title or when you have a host name.

Constant Value Description
SORT_BY_NONE 0 For bookmark items, this constant means sort by the natural bookmark order.
SORT_BY_TITLE_ASCENDING 1 Sort by the ascending title order.
SORT_BY_TITLE_DESCENDING 2 Sort by the descending title order.
SORT_BY_DATE_ASCENDING 3 Sort by the ascending date order.
SORT_BY_DATE_DESCENDING 4 Sort by the descending date order.
SORT_BY_URI_ASCENDING 5 Sort by the ascending URI order.
SORT_BY_URI_DESCENDING 6 Sort by the descending URI order.
SORT_BY_VISITCOUNT_ASCENDING 7 Sort by the ascending visit count order.
SORT_BY_VISITCOUNT_DESCENDING 8 Sort by the descending visit count order.
SORT_BY_KEYWORD_ASCENDING 9 Sort by the ascending keyword order.
SORT_BY_KEYWORD_DESCENDING 10 Sort by the descending keyword order.
SORT_BY_DATEADDED_ASCENDING 11 Sort by the ascending added date order.
SORT_BY_DATEADDED_DESCENDING 12 Sort by the descending added date order.
SORT_BY_LASTMODIFIED_ASCENDING 13 Sort by the ascending last modified order.
SORT_BY_LASTMODIFIED_DESCENDING 14 Sort by the descending last modified order.
SORT_BY_TAGS_ASCENDING 17 Sort by the ascending tags order.
SORT_BY_TAGS_DESCENDING 18 Sort by the descending tags order.
SORT_BY_ANNOTATION_ASCENDING 19 Sort by the ascending annotation order.
SORT_BY_ANNOTATION_DESCENDING 20 Sort by the descending annotation order.
SORT_BY_FRECENCY_ASCENDING 21 Sort by ascending frecency order.
SORT_BY_FRECENCY_DESCENDING 22 Sort by descending frecency order.

Result type constants

Constant Value Description
RESULTS_AS_URI 0 "URI" results, one for each URI visited in the range. Individual result nodes will be of type "URI".
RESULTS_AS_VISIT 1 "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".
RESULTS_AS_FULL_VISIT 2

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).

Note: Supported only for QUERY_TYPE_HISTORY.
RESULTS_AS_DATE_QUERY 3

Returns nsINavHistoryQueryResultNode nodes for each predefined date range where we had visits.

Note: Supported only for QUERY_TYPE_HISTORY.
RESULTS_AS_SITE_QUERY 4

Returns nsINavHistoryQueryResultNode nodes for each site where we have visits.

Note: Supported only for QUERY_TYPE_HISTORY.
RESULTS_AS_DATE_SITE_QUERY 5

Returns nsINavHistoryQueryResultNode nodes for each site where we have visits, grouped by date.

Note: Supported only for QUERY_TYPE_HISTORY.
RESULTS_AS_TAG_QUERY 6

Returns nsINavHistoryQueryResultNode nodes for each tag. Each tag node is a RESULTS_AS_TAG_CONTENTS container defined as place:querytype=1&resultType=7&folder=tag_folder_id.

Note: Using this result type forces the query type to be QUERY_TYPE_BOOKMARKS.
RESULTS_AS_TAG_CONTENTS 7

Returns nsINavHistoryResultNode nodes for each bookmark contained into the defined tag. To specify the tag you need to add a folder=tag_folder_id to the query, and only one folder is allowed.

Note: Using this result type forces the query type to be QUERY_TYPE_BOOKMARKS. At this time, sorting methods are not supported; results will always be returned in reverse order of insertion.

Query type constants

Constant Value Description
QUERY_TYPE_HISTORY 0 Query's type is history.
QUERY_TYPE_BOOKMARKS 1 Query's type is bookmarks.
QUERY_TYPE_UNIFIED 2 Query's type is unified.

Redirects mode constants

Constant Value Description
REDIRECTS_MODE_ALL 0 Include both redirected-from and redirected-to pages in the results.
REDIRECTS_MODE_SOURCE 1 Include redirected-from pages but not redirected-to pages in the results.
REDIRECTS_MODE_TARGET 2 Include redirected-to pages but not redirected-from pages in the results.

Methods

clone()

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

 nsINavHistoryQueryOptions clone();
Parameters

None.

Return value

Returns the newly created cloned options.

See also