Opera のファイル形式

はじめに

このドキュメントでは、Opera 5 でキャッシュや cookie を管理するのに用いられるファイル用の新しいバイナリファイルについてご説明します。

以下のファイルがベースとする新しい一般的な形式は、長さが規制されたタグつきレコードのシークエンスとして構成されています。それぞれのレコードには、この形式内の新しいレコードなどの任意のバイナリデータ、文字列や整数値のように数多くの異なるデータタイプが含まれることがあります。

一般的な形式は Opera 3.x およびそれ以前のバージョンとは互換性がありませんが、Opera 4.0 およびそれ以降のバージョンとは、かなりの程度の互換性があります。すなわち、今後のバージョンで新しいフィールドが追加された場合、古いバージョンで、理解できないフィールドは無視する一方で、理解した情報を読むことができるということです。

幾つかの制限がありますが、これらの制限は主に、レコード長を指定するのに利用される整数における上位ビットの多くに関わるものです。同形式は現在ディスクキャッシュのインデックスファイル（dcache4.url）や訪問済みのリンクファイル（vlink4.dat）、ダウンロードレスキューファイル（download.dat）、cookie ファイル（cookies4.dat）などを保管するのに使われています。また、同形式は以下の連続によって記述されています:

• ニュース形式で用いられる一般的なバイナリ形式
• キャッシュ、訪問済みリンク、ダウンロードのファイル形式で用いられる特殊な定数およびデータ編成
• cookie 形式で用いられる特殊な定数およびデータ編成

ウィンドウの履歴やニュースファイル、全体履歴ファイルの形式は、Opera v3.x で用いられているのと同形式で、このドキュメントでは対象外となります。

一般的なバイナリ形式

データタイプ

同形式で用いられ、符号なしで、ビッグエンディアン/ネットワークのスタイル （最上位バイトが先に来る）に保管されている整数値。レコード内に保管されている整数値は、ビッグエンディアン形式にも保管されますが、符号が付されたり、切り捨てられたりすることがあります。

このドキュメントでは以下のデータタイプが使われています:

データレコード

通常のレコード形式のフォームは以下の通りです:

struct record
{
// application specific tag to identify content type
tag_id_type tag_id;
// length of payload
payload_length_type length;
// Payload/content of the record
bytepayload[length];
};

ご注意: タグと長さのバイト数は変更することもあります。下記をご覧ください。

それぞれのレコードのフィールドには以下の意味があります:

tag_id

レコードの識別子。この値はアプリケーション限定で、ペイロードコンテンツの意味を示すのに用いられます。

レコードの実コンテンツタイプは、実ファイルまたは super-record で用いられる定義によります。

MSB（最上位ビット）の値が 1 に設定されている tag_id は、no length のレコード用に保存しておかれます。length フィールドやペイロードバッファは tag_id フィールドに従いません。これらのレコードは Boolean フラグとして用いられます: 存在する場合は true、しない場合は false となります。

ファイルのバイナリ保管において、これは内部保管の整数値の MSB（最上位バイト）は、タグフィールドにおける最初のバイトの MSB として保管される必要があるということを意味します。これにより、所与の tag_id の length 整数値に用いることのできるタグ数の制限が設けられます。ファイルがプログラムの中に読まれると、プログラムはタグを保管した MSB を、プログラムそれ自体の符号なしの MSB のように、共通（内部）のビットポジションへ移動するよう処理する必要があります。

bytes	Max id available (excluding MSB)
1	0x7f
2	0x7fff
3	0x7fffff
4	0x7fffffff

通常のレコードやフラグレコード（ペイロードレコード用の 0x0001 [16 ビットタグ] やフラグレコード用の 0x8001 など）用に、同じ tag id（MSB なし） が技術的に利用可能な場合には、これは推奨されません。

length

このフィールドは、フィールドの直後に続くペイロードにおけるバイト数になります。ゼロのこともあります。

payload

ペイロードは、length フィールドで指定される length のバイトのシークエンスになります。

同コンテンツの意味は、所与のレコードもしくはファイル構成の定義で示されます。編成例は、レコードや符号なしの整数値、符号つきの整数値、または文字列などの配列であることもあります。

特に旧バージョンとの互換性が必要とされる際に、可変（タグなし）のタイプの形式が柔軟性に乏しくバージョンごとの相違に対応しにくい傾向があるものの、データのタイプが変化する場合は、ここで記載されているタイプのデータのみをご使用になるよう推奨します。

単一のアイテムの整数値（符号つきもしくは符号なし）は切り捨てられることもあります（ゼロバイトを削除）が、整数値の配列は常に固定のバイト数を用いて値を示し、ペイロードの length からアイテム数を導き出す必要があります。バイト数が将来のバージョンにおける値の変更を表示する必要があった場合は、新しいタグが用いられます。

ファイル形式

以下の要素はレコードとして保管されませんが直接バイナリに保管されます:

uint32 file_version_number;
uint32 app_version_number;
// number of bytes in the id tag, presently 1
uint16 idtag_length;   
// number of bytes in the length part of a record, presently 2
uint16 length_length;  
// array of records, number determined by length of file
struct record items[]; 

ファイル形式の現行バージョンのナンバー（file_version_number）は 0x00001000 となり、下位の 12 ビット（bitmask 0x00000fff）がマイナーバージョンのナンバーを示し、残りがメジャーバージョンのナンバーとなります。ソフトウェアの旧バージョンがファイルをうまく読むことができないような方法でファイル形式が変更された場合は、マイナーバージョンにおける変更は 使用してはなりません。マイナーバージョンのナンバーが、アプリケーションが読むことができるよりも新しい（古い）場合、ファイルを読んではなりません。

整数値のサイズは所与のメジャーバージョンに対し絶対で、ファイルのバージョンナンバーの整数値サイズはどのバージョンにおいても固定されています。

"app_version_number" とは、アプリケーションのバージョンナンバーで、file_version_number とは無関係です。これはファイル形式の対象外となる下位/上位互換を備えるのに必要なアクションを決定するアプリケーションに使用されます。アプリケーションのバージョンナンバーの解釈はアプリケーションに依存します。

"idtag_length" と "length_length" のフィールドは、tag_id_type や payload length のフィールドで定義されるように、また、payload_length_type で個々に定義されるように、IDタグのレコードで用いられるバイト数を与えます。

特に、これらのフィールドの値は tag_id_type と payload_length_type を以下の整数値タイプとして定義します:

これらのタイプのアプリケーションの内部 表現は定義されていませんが、uint32 が推奨されます。アプリケーションが "idtag_length" や "length_length" の値で 4 よりも大きな値や、内部の符号なし整数値のサイズよりも大きな値をいかに処理するかは定義されていませんが、アプリケーションは そのような状況に備えて、下位互換のガイドの中で特定のルールを用意すべきです。

Opera 4.x の現行バージョンでは、idtag_length=1 （uint8）ならびに length_length=2 （uint16）を用いています。

ヘッダーの後にはレコードだけが続きます。レコード編成ならびにそれらの解釈はアプリケーション限定となります。

下位互換

長い整数値を用いることができないファイル形式を使用するアプリケーションの旧バージョンは、これにかかわらず、ファイル処理を試みるべきですが、レコードの数値のタグがバージョンそれ自体の整数値幅を超える場合（例: 整数値のオーバーフロー）には、レコードを回避すべきです。ただし、レコードの length が整数値やバッファ許容量の制限を超える場合は、ファイルの処理を続行してはなりません。

全てのアプリケーションは理解できないタグ値を無視しなくてはなりません。

キャッシュファイル形式

このセクションには、訪問済みリンクファイル （vlink4.dat）やディスクキャッシュインデックスファイル（dcache4.url）、ダウンロードレスキューファイル（download.dat）で利用されるレコードタグおよび形式について詳述します。これらのファイルの現在の app_version_number は 0x00020000 （メジャーバージョン 2、マイナーバージョン 0）になります。

これらのファイルでは（異なるタグ値の）レコードを用いており、そのレコードには、同一のタグIDセットからのタグつきレコードのシークエンスが含まれます。異なるファイルでは以下のレコードにこれらのタグを用います:

それぞれのファイルはこのタイプのみのレコードから構成されていますが、ディスクキャッシュインデックスファイルは除きます。ディスクキャッシュインデックスファイルには id 0x40 のシングルレコードも含まれており、これには次のフリーキャッシュファイルナンバー（oprXXXXX）を探すのに用いられる 5 字の文字列が含まれています。

それぞれのレコードは再び、ファイル内のレコードと同様、同じバイナリ表現形式をもつレコードのシークエンスになります。

全てのファイルに共通の要素

これらの要素はキャッシュ関係の全ファイルで利用されます。訪問済みリンクの場合、これらは現在使われているフィールドのみになります。

ご注意: "(0x0001 | MSB_VALUE)" とは、ローカルの符号なし整数値の最上位ビットが設定されなければならないという事です。 32 ビット値が用いられる場合、これはタグの値が 0x80000001 であるという事になります。

関連リンク（tag 0x0022）レコードのコンテンツタグ

ディスクキャッシュならびにダウンロードレスキューファイルで用いられるフィールド

ダウンロードレスキューファイルのみで利用されるフィールド

HTTP プロトコル固有レコードで利用されるフィールド

全てのメソッドは標準で GET となり、現在は POST リクエストをキャッシュすることはできません。

Cookie ファイル形式

このセクションでは、cookies（cookies4.dat）の保管に用いられるレコードタグならびに形式について記述します。現在のこのファイルタイプの app_version_number は 0x00002000 （メジャーバージョン 2、マイナーバージョン 0）になります。

cookie ファイルはドメイン名コンポーネントのツリーとして編成されており、その時それぞれのコンポーネントはパスコンポーネントを保持し、それぞれのパスコンポーネントには cookies 数が含まれることもあります。

ご注意: コンポーネントはレコードのシークエンスで、単一のレコードではなく、flag レコードとともに終了されます。

Structure

ドメインコンポーネント

ドメインコンポーネントはそれぞれのサーバおよびドメイン向けに cookies を編成するのに利用されます。これらのサーバやドメイン用にcookies や cookie フィルタリング機能が定義されます。

ドメインコンポーネントはドメインレコードとともに開始され、これには特定のドメイン用にドメイン名や flag の幾つかが保持されています。domain-end flag レコードによって終了される前に、パスコンポーネントターミネータとサブドメイン数で続けられると、cookies を保持するパスコンポーネントやサブディレクトリのパスコンポーネント（および cookies）がその後に続きます。

例: ドメイン www.opera.com の cookies は以下のように保存されます:

["com" record]
  ["opera" record]
["www" record
  [cookies]
  [Path components]
  [Path component terminator]
  [other domains]
[end of domain flag ("www")]
  [end of domain flag ("opera")]
[end of domain flag ("com")]

ドメインコンポーネント名は全てドットなしになります。ただし、IP アドレスは除きますが、これは、Quad のドットつきストリング（例: "10.11.12.13"）として完全な IP アドレスとともにのみ保存されます。さらに、ドメインコンポーネント名は全て最上位に保存され、どのようなサブドメインも含むことができません。

ドメインレコードではタグ "0x01" が使用され、以下のフィールドのシークエンスが含まれます:

このレコードは 、ゼロもしくは、ドメインでサーバ上の最上位パスを定義するより多くのパスコンポーネントで続けることが可能です。また、パスコンポーネントターミネータが 常に 終了することも可能です。その時、ゼロもしくはより多くのドメインコンポーネントが続くことがあります。

ドメインコンポーネントは (0x0004 | MSB_VALUE) flag record によって終了されます。

パスコンポーネント

パスコンポーネントは、定義された cookie をもつこのディレクトリのサブディレクトリと同様に、所与のドメイン内の所与のディレクトリ用に定義された cookie を編成します。

ドメインコンポーネントレコードの直後に開始するパスコンポーネントを除き、それぞれのパスコンポーネントは常にパスレコードとともに開始します。さらに、その後に cookie レコードの任意の数とサブディレクトリのパスコンポーネントが続きます。

パスレコードはレコード ID "0x0002" を使用し、レコードには次のフィールドレコードがあります:

パスコンポーネントターミネータは (0x0005 | MSB_VALUE) flag レコードになります。

cookie レコード

cookie のエントリはタイプ "0x0003" のレコード内に保存され、以下のフィールドレコードを含みます::