Firefox의 히스토리와 북마크 데이터는 "플레이스" 질의 API를 이용하여 접근할 수 있습니다. 이 API는 히스토리, 북마크, 그리고 두 가지 모두에 대하여 복잡한 질의를 실행할 수 있는 기능을 제공합니다. 질의의 결과는 조건에 맞는 데이터의 단순 목록이나 트리 구조를 포함한 개체입니다. 질의 API와 결과 데이터의 구조에 대한 정의는 toolkit/components/places/public/nsINavHistoryService.idl에 있습니다. 이 페이지는 일반적인 작업에 대한 소개와 핵심 API 사용법에 대한 예제를 제공합니다.
플레이스 질의는 몇 가지 기본 요소을 가지고 있습니다.
nsINavHistoryQuerynsINavHistoryQueryOptionsnsINavHistoryService첫 번째 단계는 질의와 옵션을 생성하고 원하는 매개 변수를 채우는 것입니다. 빈 개체를 얻으려면 nsINavHistoryService.getNewQuery()와 nsINavHistoryService.getNewQueryOptions()를 사용합니다. 이 개체의 기본 값은 모든 브라우저 히스토리를 단순 목록으로 반환하는 질의를 낳습니다.
var historyService = Components.classes["@mozilla.org/browser/nav-history-service;1"]
.getService(Components.interfaces.nsINavHistoryService);
// no query parameters will get all history
// XXX default sorting is... ?
var options = historyService.getNewQueryOptions();
// no query parameters will return everything
var query = historyService.getNewQuery();
// execute the query
var result = historyService.executeQuery(query, options);
nsINavHistoryQueryOptions는 resultType 속성을 가지고 있는데 이는 결과로 반환되는 그룹화와 세부사항 수준의 구성을 가능하게 합니다. 이 속성의 여러 가지 값은 아래에 나와 있습니다. 이 값은 nsINavHistoryQueryOptions의 속성이기도 한데, Components.interfaces.nsINavHistoryQueryOptions.RESULTS_AS_VISIT와 같이 접근할 수 있습니다.
RESULT_TYPE_URI 형식의 하나의 결과 노드를 반환합니다.RESULT_TYPE_VISIT 형식이며 각 방문에 대한 세션 ID를 제공합니다. 이 세션 ID는 링크를 클릭해서 방문한 모든 페이지에 대해 동일합니다. 사용자가 새로운 URL을 입력하거나 북마크를 따라가면 새로운 세션이 시작합니다.RESULT_TYPE_VISIT의 확장된 버전입니다. 결과는 RESULT_TYPE_FULL_VISIT 형식으로서 방문에 대한 추가 정보와 이동 방식(입력, 리디렉트, 링크 등)에 대한 정보를 가지고 있습니다.const unsigned long TIME_RELATIVE_EPOCH = 0 const unsigned long TIME_RELATIVE_TODAY = 1 const unsigned long TIME_RELATIVE_NOW = 2 attribute PRTime beginTime attribute unsigned long beginTimeReference readonly attribute boolean hasBeginTime readonly attribute PRTime absoluteBeginTime attribute PRTime endTime attribute unsigned long endTimeReference readonly attribute boolean hasEndTime readonly attribute PRTime absoluteEndTime attribute AString searchTerms readonly attribute boolean hasSearchTerms attribute long minVisits attribute long maxVisits attribute boolean onlyBookmarked attribute boolean domainIsHost attribute AUTF8String domain readonly attribute boolean hasDomain attribute boolean uriIsPrefix attribute nsIURI uri readonly attribute boolean hasUri attribute boolean annotationIsNot attribute AUTF8String annotation readonly attribute boolean hasAnnotation readonly attribute unsigned long folderCount
const unsigned short GROUP_BY_DAY = 0 const unsigned short GROUP_BY_HOST = 1 const unsigned short GROUP_BY_DOMAIN = 2 const unsigned short GROUP_BY_FOLDER = 3 const unsigned short SORT_BY_NONE = 0 const unsigned short SORT_BY_TITLE_ASCENDING = 1 const unsigned short SORT_BY_TITLE_DESCENDING = 2 const unsigned short SORT_BY_DATE_ASCENDING = 3 const unsigned short SORT_BY_DATE_DESCENDING = 4 const unsigned short SORT_BY_URI_ASCENDING = 5 const unsigned short SORT_BY_URI_DESCENDING = 6 const unsigned short SORT_BY_VISITCOUNT_ASCENDING = 7 const unsigned short SORT_BY_VISITCOUNT_DESCENDING = 8 const unsigned short SORT_BY_KEYWORD_ASCENDING = 9 const unsigned short SORT_BY_KEYWORD_DESCENDING = 10 const unsigned short SORT_BY_DATEADDED_ASCENDING = 11 const unsigned short SORT_BY_DATEADDED_DESCENDING = 12 const unsigned short SORT_BY_LASTMODIFIED_ASCENDING = 13 const unsigned short SORT_BY_LASTMODIFIED_DESCENDING = 14 const unsigned short SORT_BY_ANNOTATION_ASCENDING = 15 const unsigned short SORT_BY_ANNOTATION_DESCENDING = 16 const unsigned short RESULTS_AS_URI = 0 const unsigned short RESULTS_AS_VISIT = 1 const unsigned short RESULTS_AS_FULL_VISIT = 2 attribute unsigned short sortingMode attribute AUTF8String sortingAnnotation attribute unsigned short resultType attribute boolean excludeItems attribute boolean excludeQueries attribute boolean excludeReadOnlyFolders attribute boolean expandQueries attribute boolean includeHidden attribute boolean showSessions attribute unsigned long maxResults const unsigned short QUERY_TYPE_HISTORY = 0 const unsigned short QUERY_TYPE_BOOKMARKS = 1 const unsigned short QUERY_TYPE_UNIFIED = 2 attribute unsigned short queryType
하나 이상의 nsINavHistoryQuery 개체를 executeQueries()로 전달할 수 있습니다. 하나의 질의 개체 안에서 모든 매개 변수는
AND
로 연결됩니다. 그리고 서로 다른 질의 개체의 조건들은
OR
로 연결됩니다. 이는 여전히 표현력이 있으면서도 중첩된 절을 가진 완전한 논리 연산보다 더 간단한 구현과 인터페이스를 가능하게 합니다.
다음은 방문한 모든 페이지 중 제목이나 URL에 "firefox"라는 단어를 포함한 페이지나 오늘 mozilla.org에서 방문한 페이지를 질의하는 예제입니다.
// first query object searches for "firefox" in title/URL var query1 = historyService.getNewQuery(); query1.searchTerms = "firefox"; // second query object searches for visited in past 24 hours AND from mozilla.org var query2 = historyService.getNewQuery(); query2.beginTimeReference = query2.TIME_RELATIVE_NOW; query2.beginTime = -24 * 60 * 60 * 1000000; // 24 hours ago in microseconds query2.endTimeReference = query2.TIME_RELATIVE_NOW; query2.endTime = 0; // now query2.domain = "mozilla.org"; var result = historyService.executeQueries([query1, query2], 2, options);
간단한 북마크 질의를 실행하기 위한 빠른 시작 설명이 Accessing Bookmarks에 있습니다.
북마크 폴더의 내용은 질의 개체에 "folders" 멤버를 설정하는 것으로 구할 수 있습니다. 이 항목은 북마크 서비스에서 온 폴더 ID의 배열입니다. 일반적으로 이 목록에는 해당 폴더의 내용을 알려줄 하나의 폴더 ID가 있습니다. 여러 개의 폴더를 지정할 수 있으며 결과는 모든 폴더의 교집합이 됩니다.
정렬에 대해서는 보통 (기본 값인) SORT_BY_NONE를 사용하는데 이는 사용자가 북마크 관리자에서 지정한 "자연스러운" 순서로 항목을 반환하기 때문입니다. 그러나 다른 정렬도 작동합니다.
북마크 질의에 대해서는 보통 요청한 폴더의 모든 항목을 구하기 위하여 질의 매개 변수가 없습니다. 정확하게 하나의 폴더 및 GROUP_BY_FOLDER를 지정하고 매개 변수가 없으면 이는 정확하게 하나의 폴더에 대응하므로 시스템은 훨씬 효율적인 질의를 수행하고 최신 결과를 유지하게 됩니다.
var bookmarkService = Components.classes["@mozilla.org/browser/nav-bookmarks-service;1"]
.getService(Components.interfaces.nsINavBookmarksService);
// |query| and |options| are objects created in the previous section
query.setFolders([bookmarkService.toolbarFolder], 1);
options.setGroupingMode([options.GROUP_BY_FOLDER], 1);
var result = historyService.executeQuery(query, options);
질의와 옵션 개체는 queriesToQueryString를 사용하여 "place:"로 시작하는 문자열로 직렬화할 수 있습니다. 결과 문자열은 저장하거나 북마크할 수 있습니다. "place:" URI를 북마크하면 사용자가 그것을 열 때 질의의 결과로 확장됩니다. 원본 개체는 queryStringToQueries를 사용하여 문자열로부터 직렬화를 해제할 수 있습니다.
주의할 점은 문자열이 비어 있으면 queryStringToQueries는 어떠한 질의 개체도 반환하지 않는다는 것입니다. 코드는 이를 처리해야 합니다. 반환되는 옵션 구조는 항상 있습니다. 옵션을 지정하지 않으면 기본 값을 갖게 됩니다. 질의 매개 변수가 없는데 입력 문자열이 빈 것이 아니면(옵션이 있었습니다) 기본 질의 값을 포함하는 하나의 질의 개체를 얻게 됩니다.
다음은 두 개의 질의와 하나의 옵션 개체를 직렬화하고 해제하는 예제입니다.
var queryString = historyService.queriesToQueryString([query1, query2], 2, options);
var queriesRef = { };
var queryCountRef = { };
var optionsRef = { };
historyService.queryStringToQueries(queryString, queriesRef, queryCountRef, optionsRef);
// now use queriesRef.value, optionsRef.value
"place:" URI에서 이용 가능한 용어에 대한 참조는 Places:PlaceURIs를 참고하십시오.
결과를 사용하는 가장 일반적인 방법은 뷰를 구현하는 것입니다. 결과를 트리 콘트롤에 넣는 내장 뷰가 있으며 여러분 자신의 뷰를 구현할 수도 있습니다. 자세한 사항은 Places:Views를 참고하시기 바랍니다. 이 섹션은 결과를 직접 접근하는 방법에 대해서 다룹니다. 예를 들어, 여러분 자신의 뷰를 생성하거나 결과를 표시하는 대신 처리하는 경우입니다.
참고: 노드를 접근할 대는 참조를 유지하지 않도록 주의하십시오. 정렬과 같은 프로그래머가 실행하는 명령어 뿐만 아니라 히스토리와 북마크 시스템에서 결과로 보내는 알림은 구조가 변경되거나 노드가 삽입, 삭제, 대체되도록 합니다.
executeQuery()/executeQueries()가 반환하는 nsINavHistoryResult 개체는 주어진 히스토리나 북마크 질의에 부합하는 목록을 포함합니다. 이 결과는 노드로 구성된 트리 구조에 포함됩니다. 노드 형식은 type 속성을 이용해서 구할 수 있습니다. 이 형식은 더 자세한 정보를 얻기 위해서 어떤 인테페이스를 QueryInterface 할 수 있는지 알려줍니다.
nsINavHistoryResultNode에서 파생되고, 세션 정보를 담고 있습니다.nsINavHistoryVisitResultNode에서 파생되고, 사용자가 이 페이지를 탐색한 방법에 대한 정보를 담고 있습니다.
참고: 현재 구현되지 않은 상태입니다. bug 320831를 참고하십시오.
nsINavHistoryResultNode에서 파생됩니다. 북마크 폴더는 이 형식입니다.다음은 노드의 형식을 구하는 예제입니다.
var Ci = Components.interfaces;
switch(node.type) {
case node.RESULT_TYPE_URI:
dump("URI result " + node.uri + "\n");
break;
case node.RESULT_TYPE_VISIT:
var visit = node.QueryInterface(Ci.nsINavHistoryVisitResultNode);
dump("Visit result " + node.uri + " session = " + visit.sessionId + "\n");
break;
case node.RESULT_TYPE_FULL_VISIT:
var fullVisit = node.QueryInterface(Ci.nsINavHistoryFullVisitResultNode);
dump("Full visit result " + node.uri + " session = " + fullVisit.sessionId + " transitionType = " +
fullVisit.transitionType + "\n");
break;
case node.RESULT_TYPE_HOST:
var container = node.QueryInterface(Ci.nsINavHistoryContainerResultNode);
dump("Host " + container.title + "\n");
break;
case node.RESULT_TYPE_REMOTE_CONTAINER:
var container = node.QueryInterface(Ci.nsINavHistoryContainerResultNode);
dump("Remote container " + container.title + " type = " + container.remoteContainerType + "\n");
break;
case node.RESULT_TYPE_QUERY:
var query = node.QueryInterface(Ci.nsINavHistoryQueryResultNode);
dump("Query, place URI = " + query.uri + "\n");
break;
case node.RESULT_TYPE_FOLDER:
// Note that folder nodes are of type nsINavHistoryContainerResultNode by default, but
// can be QI'd to nsINavHistoryQueryResultNode to access the query and options that
// created it.
dump("Folder " + node.title + " id = " + node.itemId + "\n");
break;
case node.RESULT_TYPE_SEPARATOR:
dump("-----------\n");
break;
}
콘테이너는 다른 콘테이너 목록과 결과 노드를 포함합니다. 각 결과는 질의의 루트를 나타내는 콘테이너를 가지고 있습니다. 이는 결과의 root 속성을 이용하여 구할 수 있습니다. 일반적인 질의에 대해서 이 루트 콘테이너는 원본 질의에서 여러분이 제공한 질의 매개 변수와 옵션을 포함한 nsINavHistoryQueryResultNode입니다. 하나의 북마크 폴더로 대응하는 질의에 대해서 이는 nsINavHistoryContainerResultNode이 됩니다.
콘테이너는 열리거나 닫힐 수 있습니다. 이는 트리 뷰의 열린 상태나 닫힌 상태에 해당하며 메뉴를 보이거나 감추는 것에 대응할 수 있습니다. 콘테이너의 내용을 얻으려면 먼저 콘테이너를 열어야 합니다. 대부분의 콘테이너 형식은 자신을 지연된 방식으로(lazily) 채우기 때문에 콘테이너를 여는 것은 실제 주어진 질의를 실행하는 것에 해당합니다. 콘테이너가 열린 동안에는 히스토리와 북마크 시스템의 알림을 듣고 내용을 수정하여 최신 상태로 유지합니다. 이러한 이유로 작업을 마치자 마자 콘테이너를 닫는 것이 최선인데, 이는 더 나은 성능을 제공하기 때문입니다. 콘테이너를 닫고 히스토리나 북마크 변경 알림이 도착하기 전에 다시 열면 보통 결과는 여전히 존재하고 작업은 빠르게 됩니다.
다음은 콘테이너를 탐색하는 예제입니다.
var cont = result.root;
cont.containerOpen = true;
for (var i = 0; i < cont.childCount; i ++) {
var node = cont.getChild(i);
dump(node.title + "\n");
}
cont.containerOpen = false;
결과를 UI에 대응하려면 nsINavHistoryResultViewer 인터페이스를 구현하고 그것을 nsINavHistoryResult.viewer 속성과 함께 결과에 붙입니다. 사용자 동작의 결과로서 또는 북마크와 히스토리 시스템의 알림의 결과로서 결과 트리가 바뀌면 이 뷰어가 호출됩니다. 그러면 여러분의 구현은 이러한 변경을 UI에 반영하게 됩니다.
nsITreeBoxObject에 대한 미리 준비된 뷰 인터페이스가 제공되는데 이는 트리의 복잡한 뷰 요구사항을 관리합니다. 이 개체의 인터페이스는 nsINavHistoryResultTreeViewer (nsINavHistoryResultViewer의 파생 인터페이스)입니다. 더 자세한 정보와 예제는 Places:Views를 참고하시기 바랍니다.