Skip to main content

Visit Mozilla.org

nsINavHistoryQueryOptions

From MDC

This article covers features introduced in Firefox 3


The nsINavHistoryQueryOptions interface represents the global options for executing a query.

Contents

nsINavHistoryService is defined in toolkit/components/places/public/nsINavHistoryService.idl. It is scriptable and unfrozen (hasn't changed since Mozilla 1.9).

Inherits from: nsISupports

[edit] Method overview

nsINavHistoryQueryOptions clone();

[edit] Attributes

Attribute Type Description
sortingMode short The sorting mode to be used for this query. Mode is one of SORT_BY_*
sortingAnnotation AUTF8String The annotation to use in SORT_BY_ANNOTATION_* sorting modes.
resultType short Sets the result type. One of RESULTS_AS_* which includes how URIs are represented.
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").
excludeItemIfParentHasAnnotation 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.
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.
showSessions boolean Separate/group history items based on session information. Only matters when sorting by date.
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.

resolveNullBookmarkTitles boolean If a bookmark title is NULL (note, not empty), attempt to use the history title. It is set to false by default.
applyOptionsToContainers boolean Only apply our query options to the containers.
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.

[edit] Constants

Constant Value Description
SORT_BY_NONE 0 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. For bookmark items, this constant means sort by the natural bookmark order.
SORT_BY_TITLE_ASCENDING 1 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. Sort by the ascending title order.
SORT_BY_TITLE_DESCENDING 2 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. Sort by the descending title order.
SORT_BY_DATE_ASCENDING 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. Note: re-sorting is slower, as is sorting by title or when you have a host name. Sort by the ascending date order.
SORT_BY_DATE_DESCENDING 4 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. Sort by the descending date order.
SORT_BY_URI_ASCENDING 5 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. Sort by the ascending URI order.
SORT_BY_URI_DESCENDING 6 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. Sort by the descending URI order.
SORT_BY_VISITCOUNT_ASCENDING 7 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. Sort by the ascending visit count order.
SORT_BY_VISITCOUNT_DESCENDING 8 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. Sort by the descending visit count order.
SORT_BY_KEYWORD_ASCENDING 9 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. Sort by the ascending keyword order.
SORT_BY_KEYWORD_DESCENDING 10 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. Sort by the descending keyword order.
SORT_BY_DATEADDED_ASCENDING 11 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. Sort by the ascending added date order.
SORT_BY_DATEADDED_DESCENDING 12 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. Sort by the descending added date order.
SORT_BY_LASTMODIFIED_ASCENDING 13 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. Sort by the ascending last modified order.
SORT_BY_LASTMODIFIED_DESCENDING 14 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. Sort by the descending last modified.
SORT_BY_COUNT_ASCENDING 15 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. Sort by the ascending count order.
SORT_BY_COUNT_DESCENDING 16 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. Sort by the descending count order.
SORT_BY_ANNOTATION_ASCENDING 17 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. Sort by the ascending annotation order.
SORT_BY_ANNOTATION_DESCENDING 18 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. Sort by the descending annotation order.
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). Not yet implemented -- see bug 320831.
RESULTS_AS_DATE_QUERY 3 Returns nsINavHistoryQueryResultNode nodes for each predefined date range where we had visits. The node contains information how to load its content: 
  * visits for the given date range will be loaded.
RESULTS_AS_SITE_QUERY 4 Returns nsINavHistoryQueryResultNode nodes for each site where we have visits. The node contains information how to load its content: 
  * last visit for each url in the given host will be loaded.
RESULTS_AS_DATE_SITE_QUERY 5 Returns nsINavHistoryQueryResultNode nodes for each site where we have visits, grouped by date. The node contains information how to load its content: 
  * list of hosts visited in the given period will be loaded.
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. The node contains information how to load its content: 
  * list of bookmarks with the given tag will be loaded.
RESULTS_AS_TAG_CONTENTS 7 Returns nsINavHistoryResultNode nodes for each bookmark contained into the defined tag. This kind or resultType can be applied only if queryType == QUERY_TYPE_BOOKMARKS. To specify the tag you need to add a folder=tag_folder_id to the query, only one folder is allowed. Notice that sorting methods are not yet supported by this resultType, instead results will be returned in inverse order of insertion.
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.

[edit] Methods

[edit] clone()

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

 nsINavHistoryQueryOptions clone();
[edit] Parameters

None.

[edit] Return value

Returns the newly created cloned options.

[edit] See also

Retrieved from "http://developer.mozilla.org/en/docs/nsINavHistoryQueryOptions"