Using the Places annotation service

by 3 contributors:

注釈サービスは Firefox 3 で Web ページに間する様々な情報を保存できるように設計されました。それは拡張機能のような信頼された Firefox のコードからは利用できますが、Web ページからは利用できません。インタフェースは toolkit/components/places/public/nsIAnnotationService.idl で定義され、実装は toolkit/components/places/src/nsAnnotationService.cpp にあります。

Places のデータベース設計の概要は Places の設計 を参照してください。

注釈サービスをつくる

注釈サービスのコンストラクタ ID は @mozilla.org/browser/annotation-service;1 です。

var annotationService = Components.classes["@mozilla.org/browser/annotation-service;1"]
                                  .getService(Components.interfaces.nsIAnnotationService);

注釈サービスはスレッドセーフでは ありません。あなたはメインスレッドからのみ使うべきです。

注釈の命名

あなたの注釈の名前には、<名前空間>/<名前> 形式を使うべきです。例えば "my_extension/page_state"。現在注釈サービスは注釈の名前形式を強制しませんが、将来これは変更されるかもしれません。また、私たちは与えられた名前空間に一致した「あなたの」注釈全てを取得する関数を追加するかもしれません。

あなたの注釈の名前には HTML パスとして不正な文字は一切使うべきではありません。これにはコロンや空白、ほとんどの句読点、アスキー以外の文字が含まれます。

あなたは注釈名を比較的少なくするよう試みるべきです。サービスは別々のテーブルにこれらの名前を格納します。名前が少なければ少ないほど名前を得るのはより効率的でしょう。あなたは何百もの固有な注釈名を必要とするサービスを設計するべきではありません。

注釈のサービス

注釈は様々に異なる種類のセッタを提供しています (実際の宣言は nsIAnnotationService.idl を参照)。

  • setPageAnnotationString
  • setPageAnnotationInt32
  • setPageAnnotationInt64
  • setPageAnnotationDouble
  • setPageAnnotationBinary: 注意、どんな Web ページでも注釈サービスから画像を読み込むことができます。 画像をほかの場所に送信することや中身を得ることはできませんが、注釈サービスに機密情報の画像を保存するべきではありません。

これらの注釈はどれも同じようなパラメタをとります:

  • URI: これは注釈をつけるページの URI
  • name: 注釈の名前。上の名前付けの章を参照
  • value
  • flags: 現在未定義、0 にすべきです。
  • expiration: 失効は現在未実装です (下の "Lifetime of annotations" を参照してください)。
var ioservice = Components.classes["@mozilla.org/network/io-service;1"]
                          .getService(Components.interfaces.nsIIOService);
var uri = ioservice.newURI("http://www.mozilla.org/", null, null);

annotationService.setAnnotationString(uri, "my_extension/some_annotation",
  "This is the annotation value", 0, 0);

注釈を得る

上のセッタに対応するゲッタがあります (厳密な宣言は nsIAnnotationService.idl を参照)

  • getPageAnnotationString
  • getPageAnnotationInt32
  • getPageAnnotationInt64
  • getPageAnnotationDouble
  • getPageAnnotationBinary

与えられた注釈に対して正しい型を要求するのは呼び出し関数の責任です。注釈サービスはそれらの型を sqlite を使っている Storage サービスに渡します。要求した型とデータベースの中の値が一致しない時 Sqlite は自動的に型を変換しようと試みます。時にはうまくいきます (Int32 から double)が、時にはうまくいきません (文字列から Int32)。それが動かない時は、リクエストした型のデフォルトの値を受け取るでしょう。型をわかり得ない方法 (type-agnostic way)で注釈を処理するより強固な方法の提供は バグ 331654 です。

これらの関数は要求された注釈が存在しないとき NS_ERROR_NOT_AVAILABLE を返すでしょう。要求した注釈をページが持っているか事前に確かめるために hasAnnotation を使うことができます。しかし、操作を try、例外を catch するのがもっとも効果的です。付加的なチェックは余計なデータベースのルックアップ (より高いオーバーヘッドを持っている) を必要とします。

ゲッタ関数は注釈の値しか返しません。注釈に関連付けられた他の値 (フラグ、有効期限、MIME タイプ、データ型) を得るには nsIAnnotationService.getAnnotationBinary を使ってください。データ型は mozIStorageValueArray.idl の VALUE_TYPE 定数の中の一つです。

バグ 377066 以降で VALUE_TYPE_* はこのように変更されました。this:

  • TYPE_INT32 = 1
  • TYPE_DOUBLE = 2
  • TYPE_STRING = 3
  • TYPE_BINARY = 4
  • TYPE_INT64 = 5
try {
  var value = annotationService.getAnnotationString(uri, "my_extension/some_annotation");
} catch(e) {
  // 注釈は存在しない
}

その他の関数

  • getPagesWithAnnotation: 与えられた注釈を付けられた全ページのリストを取得する。C++ 呼び出し関数はメモリ管理をはるかに簡単にしてリークする機会を減らす COM の配列を返すGetPagesWithAnnotationCOMArray を使いたくなるでしょう。
  • getPageAnnotationNames: 与えられた URI の全注釈のリストを取得する。C++ 呼び出し関数はメモリ管理をはるかに簡単にしてリークする機会を減らす COM の配列を返すGetPageAnnotationNamesTArray を使いたくなるでしょう。
  • pageHasAnnotation: ページが与えられた名前から始まる注釈を持っている場合は true を返します。
  • removePageAnnotation: ページから与えられた注釈を削除します。
  • removePageAnnotations: 与えられたページから全ての注釈を削除します。
  • copyPageAnnotations: あるページの注釈全てを他のページにコピーします。衝突した場合にコピー先の注釈を残すか置き換えるかを指定できます。

注釈のプロトコル

注釈サービスは "moz-anno:" プロトコルのプロトコルハンドラを提供します。これは注釈サービスに保存されたデータに直接リンクできます。nsIAnnotationService.getAnnotationURI を呼び出すことで与えられた URI/name の組み合わせの注釈 URI を得ることができます。

注釈プロトコルを動かすには、注釈は MIME タイプを宣言すべきです。MIME タイプのない注釈は動作しないでしょう。

また、注釈サービスの特別なケース取り扱いを提供します。 注釈名が "favicon" であるとき、注釈プロトコルハンドラは処理のために要求をファビコンサービスへ渡すでしょう。 与えられたファビコンの注釈 URI を得るにはnsIFaviconService.getFaviconLinkForIconを使用し、与えられたページから favicon 注釈 URI を得るには nsIFaviconService.getFaviconLinkForPage を使ってください。これらの機能を使用して、あなた自身の URI を作らないのは重要です。なぜならこれらの関数はファビコンが見付からなかった時にデフォルトのページファヴィコンを効果的に設定するからです。詳細は Places ファビコンサービス を参照してください。

注釈の一生

現在注釈の失効は実装されていないので、注釈は永遠に残りつづけます。方針はまだ決定していませんが、将来私たちは必ず注釈を失効させます。 この機能のバグは バグ 319455 です。


ドキュメントのタグと貢献者

Contributors to this page: Mgjbot, Potappo, Taken
最終更新者: Mgjbot,