Opera File Formats(私家訳)

この文書はOperaのファイル形式に関する文書 Opera File Foramtsを t.ashula<office@ashula.info> が独自に翻訳したものです.この文書の公式なものはURI http://www.opera.com/docs/fileformats/ にあるもので,その著作権は Opera Software ASA が保持しています.また,Operaのファイル形式として公式に日本語で公開されても居ます.

翻訳すると同時に文書の構成を明瞭にするためと,XHTMLとしてvalidになるように一部markupを変更しています.

翻訳に誤りが存在している可能性に留意してください.本文書の誤訳&誤植などにお気づきの方は,t.ashula<officedashula.info&gt までお知らせ願います.

はじめに

この文書は,Opera5 でキャッシュやクッキーの管理に使われている新しいバイナリ形式のファイルフォーマットについて記述する.

新しいファイルフォーマットは,連続するタグ付きのレコードで構成される.それぞれのレコードは数値や文字列や任意のバイナリデータといったいくつかの種類のデータを保持する.

このファイルフォーマットは Opera3.x 以前のものと互換性がないが,Opera4以降のものとは適度な互換性を持つことを目的として作られている.つまり,将来のバージョンで何か新しい項目がファイルフォーマットに追加された場合においても,古いバージョンのOperaは理解できるところだけを理解しながら,将来のバージョンのファイルを読めるということである.

主にレコードの長さを表す整数値の上位ビットに関して,いくつか制限がある.現在,このフォーマットは,ディスクキャッシュのインデックスファイル ( dcache4.url ),訪問済みリンクのファイル( vlink4.dat ),ダウンロードレスキューファイル ( download.dat )および,クッキー管理ファイル ( cookies4.dat) に用いられている.このファイルフォーマットについて次のように説明していく.

  • 新しいフォーマットでの共通バイナリフォーマットについて
  • キャッシュ,訪問済みリンク,ダウンロードレスキューファイルで用いられる値やデータ構造について
  • クッキーの管理ファイルで用いられる値や構造について

ウィンドウの履歴,ニュースの購読ファイル,履歴管理ファイルは Opera3 での形式と同じなのでこの文書の範囲外である.

共通データフォーマット

データタイプ

このフォーマットで使われる整数値は符号無しで,MSBが先に来るビッグエンディアンで格納される.レコード中の整数値もビッグエンディアンで格納されるが,符号がなかったり,短かったりすることもある.

The following datatypes are used in this document:

この文書で使用されるデータタイプは下記のとおり

int*符号つきの * ビット整数値
uint*符号なしの * ビット整数値
byte8 ビットの符号なしの値
string文字の並び.Null終端ではない.
time_tuint32 で表される 00:00 Jan 1, 1970 GMT からの経過時間(秒). 将来,32bitでは足りなくなるだろう.(訳注:2038年1月を過ぎると32bitに収まらない値になる)
tag_id_typeヘッダの idtag_length フィールドによってサイズが指定された 符号なし整数値.Operaのこのバイナリのファイルを扱おうとするソフトウェアは,この値を符号なし整数値として扱う必要があり,そのサイズは32bitが望ましい.詳細はファイルのフォーマットを参照のこと.
payload_length_typeヘッダの length_length フィールドによってサイズの指定された符号なし整数値. Operaのこのバイナリのファイルを扱おうとするソフトウェアは,この値を符号なし整数値として扱う必要があり,そのサイズは32bitが望ましい.詳細はファイルのフォーマットを参照のこと.
recordいろいろと定義されたフィールドの並び.

データレコード

一般的なレコードのフォーマットは次のとおり

struct record
{
// アプリケーション毎に異なる,レコードの中身を表すタグ
tag_id_type tag_id;
// ペイロードの長さ
payload_length_type length;
// レコードの本体
bytepayload[length];
};

NOTE: tag と length のバイト長は可変,詳しくは後述.

レコードのそれぞれのフィールドの意味は以下のとおり

tag_id

レコードの識別子.クッキーやキャッシュなどのファイルごとに決められた値.ペイロードの内容が何かを表す.

実際のコンテンツの中身については,実際のファイルや super-record に使用される定義による.

最上位bit(MSB) が 1 のtag_id 値は 長さのないレコードを表すものとする.そのときは length も payload も持たない.これらのレコードは Boolean フラグとして用いられ,レコードが存在する場合は “tag_idの表すもの” = trueであり,存在しない場合は “tag_idの表すもの” = false となる.

このことは,ファイルをバイナリで保持するとき,tag_id のMSB が 内部表現の整数値においてもMSBとして格納されなければならないということを意味する.また,与えられた長さの tag_id において使用可能なタグの数にも上限が設定される.When a file is read into a program, the program must take care to move the MSB of the binary stored tag to a common (internal) bit position, such as the MSB of the program’s own unsigned integers.

bytes tag として使える最大数
10x7f
20x7fff
30x7fffff
40x7fffffff

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

たとえば,通常のレコードのタグに 0x0001 をつけて,フラグのレコードのタグに 0x8001 をつけるということも技術的には可能だが,お勧めしない.

length
payload のバイト長を表す.0 もありうる.
payload

ペイロードは 長さ length のバイトの並び.

内容の意味はより上位の構造での定義によって決まる.たとえば,レコードの配列であったり,符号なし整数値だったり,文字の並びだったりする.

とくに後方互換性を維持しようとすると,可変の (タグのない) タイプ の形式は,柔軟性がなくバージョンをまたいで維持することが困難な傾向があるので,データのタイプが変化するときには,ここで記述されたタイプのレコードのみを用いることが 推奨される.(It is recommended that only records of the types described here are used if the type of the data varies, as variable (un-tagged) type formats tend to be inflexible and difficult to maintain across versions, especially when compatibility with older versions is desired.)

単一の整数値の場合,符号にかかわりなく,0のバイトを削除した短縮形になることがある.一方,配列の場合の整数値は,常に固定長で表されるので,配列の大きさをペイロードの大きさから求めることができる.将来,整数値のバイト長が変わるときは tag も新しくなる.

ファイルのフォーマット

レコードの形を取らずに直接格納されるものもある

uint32 file_version_number;
uint32 app_version_number;
// id tag のバイト長, 現在は 1
uint16 idtag_length;
// レコードの lenght のバイト長, 現在は 2
uint16 length_length;
// record の配列, 配列の大きさはファイル長から計算される.
struct record items[]; 

現在のファイルフォーマットのバージョン(file_version_number)は 0x00001000である.このうち下位12ビット (0x00000fff) はマイナーバージョンを表し,残りのビットがメジャーバージョンを表す.古いバージョンのソフトで正常に読み込めなくなるほどのフォーマットの変更をしたときにはマイナーバージョンの変更をしてはいけない.また,ソフトウェアは対応できないメジャーバージョンのファイルを読んではいけない

ファイルフォーマットのすべてののバージョンにおいて,整数値のサイズはメジャーバージョンに対して固定である.

app_version_number はファイルバージョンとは独立に,アプリケーションごとに決められた値である.個々のアプリケーションにおいて互換性を維持するために使われるかもしれないが,この文書の範囲外である.アプリケーションバージョンの値の解釈はそれぞれのアプリに依存する.

“idtag_length” は レコードのタグを表す tag_id が何バイトの値かを規定する. “length_length” は レコードのペイロードの長さを表す payload_length_type が何バイトの値かを規定する.

tag_id_type と payload_length_type の値と それぞれの規定する型は以下のとおりである.

Valuetag_id_typepayload_length_type
inidtag_lengthlength_length
1uint8uint8
2uint16uint16
3uint24uint24
4uint32uint32

バイナリのファイルを処理するソフトウェアでの内部表現の型を定義しないが uint32 を用いることをお勧めする.idtag_length や length_length が 4 以上のときや,その処理系で扱えるサイズ以上のとき,どう扱うべきかは定義しない.しかし,上位互換性のためのルールに則って実装すべきである.

Opera 4.x では idtag_length=1 (tag_id_type = uint8) and length_length=2 (payload_length_type=uint16)としている.

ヘッダのあとには レコード だけが続く.レコードの構成や値の意味づけはそれぞれのファイルによる.

上位互換性

long int を扱えないような古いタイプのソフトウェアでは,タグの値がオーバーフローを起こすようなときには回避しつつファイルの処理を試みるべきである.しかしながら, レコードの長さが扱える長さを超えているのならば,処理を続けてはならない

すべてのソフトウェアは,理解できない tag の値を無視するべきである.

キャッシュファイルなどのフォーマット

本節では 訪問済みリンクのファイル( vlink4.dat ),キャッシュのインデックスファイル( dcache4.dat ),およびダウンロードレスキューファイル( download.dat )における レコードの tag や 形式について詳述する.これらのファイルに対する app_version_number は 0x0002 0000である.メジャーが 2,マイナーが 0ということである.

これらのファイルは,同一のタグ集合のタグのついたレコードのシーケンスを含むレコードを使う.それぞれのファイルがファイルごとに使うタグの値は以下の表のとおり. ( These files use records (of different tag values) which contain a sequence of records with tags from the same set of tag ids. The different files use these tags for their records:

FileTag idVersion number
キャッシュのインデックス0x010x00020000
訪問済みリンク0x020x00020000
ダウンロードレスキュー0x410x00020000

それぞれのファイルはここに定義したタグのみを使うが,キャッシュのインデックスのファイルは例外で 0x40という値のタグも使う.そのタグのついたレコードには 次に使えるキャッシュファイルの5文字( oprXXXXX の XXXXX 部分 )が入っている.

(Each record is again a sequence of records with the same binary representation format as the records in the file.)

共通要素

これらの要素は すべてのキャッシュ関連のファイルで使われる.訪問済みリンクのファイルは,この共通要素しか現在のところ使っていない.

NOTE: “(0x0001 | MSB_VALUE)” というのはその値の型でのMSBがたっているということをあらわす.たとえば,32bitの型の値でこう書かれていたらそのタグの値は 0x8000 0001.

タグの値内容の型説明
0x0003string完全なURLの名前(The name of the URL, fully qualified)
0x0004time_t最終訪問日時
(0x000b | MSB_VALUE)flagそのURLがフォームの問い合わせ結果であるときにのみ存在
0x0022recordその文書に存在する 相対リンクの URL と 最終訪問日時のレコード.繰り返されることもある.

相対リンクのタグ(0x0022)のついたレコードの 中身のタグについて

タグの値内容の型説明
0x0023string相対リンクのURL
0x0024time_t最終訪問日時

ディスクキャッシュのファイルとダウンロードレスキューファイルで使われるフィールド

タグの値内容の型説明
0x0005time_tローカルの時間帯における,ファイルの最終取得日時.
0x0007uint8

ファイル取得の状態をあらわす.

2
取得済み
4
取得中断
5
取得失敗
0x0008uint32取得ファイルのサイズ
0x0009string取得ファイルの MIME type
0x000astring取得ファイルの文字集合 (Character set of content)
(0x000c | MSB_VALUE)flagキャッシュフォルダ以外の場所にダウンロードされたかどうか
0x000dstringファイル名 (cache files: キャッシュディレクトリに相対)
(0x000f | MSB_VALUE)flagファイルが更新されたかどうか.更新されてたら存在.
0x0010recordHTTP での通信に関する情報のレコード

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

タグの値内容の型説明
0x0028time_tダウンロードファイルの前回の取得開始時刻.
0x0029time_tダウンロードファイルの前回の取得中止時刻.
0x002Auint32ファイルの前回のダウンロードで取得したバイト数.ファイルの取得終了時刻が不明のとき,この値は 0 とみなされ,ダウンロード速度も0(不明値)にセットされる.

HTTP での通信に関する情報のレコードで使われるフィールド

POST での通信をキャッシュしていないので メソッドは GET が使われたものとしています.

(訳注) この表は特に翻訳しないが Hypertext Transfer Protocol – HTTP/1.1も参照のこと

タグの値内容の型説明
0x0015stringHTTP date header
0x0016time_tExpiry date
0x0017stringLast modified date
0x0018stringMIME type of document
0x0019stringEntity tag
0x001AstringMoved to URL (Location header)
0x001BstringResponse line text
0x001Cuint32Response code
0x001DstringRefresh URL
0x001Euint32Refresh delta time
0x001FstringSuggested file name
0x0020stringContent Encodings
0x0021stringContent Location
0x0025 uint32

タグ 0x0026と一緒に使い,最後にリソースを取得したときに使った User Agent の文字列をあらわす.

この値は内部でのみ使われ,変更すべきではない.

0x0026 uint32

タグ 0x0025と一緒に使い,最後にリソースを取得したときに使った User Agent の文字列をあらわす.こちらの値は User Agent の sub version をあらわす.

この値は内部でのみ使われ,変更すべきではない.

(0x0030 | MSB_VALUE)flag(予約領域)
(0x0031 | MSB_VALUE)flag(予約領域)

クッキー管理ファイルのフォーマット

本節ではクッキー管理ファイル (cookies4.dat)ににおける レコードの tag や 形式について詳述する.このファイルに対する app_version_number は 0x0002 0000である.メジャーが 2,マイナーが 0ということである.

クッキー管理ファイルはドメイン名によるノードの木構造から成る.それぞれのドメイン名のノードは,path のノードの木構造を持つ.そして,それぞれの pathのノードはクッキーをいくつか持つ.

NOTE: ノードは連続するレコードの形で表される.終端にはflag レコードがある.ひとつのレコードにすべてがぶら下がっているわけではない.

構造

ドメイン名のノード

ドメイン名のノードはそれぞれのサーバやドメインに対するクッキーやクッキーの処理方法の情報をまとめている.

ひとつのノードは domain record によって始まる.domain record は ドメイン名とそのドメインに関するいくつかのフラグを保持している.その後,クッキーと下位ディレクトリの path ノードを持った path ノードが続く.pathノードが pathノード の終端レコードで終わった後,ドメインノードの終端レコードが来るまで,サブドメインのノードが続く.

例 : www.opera.com に対する クッキーの格納方法.

[“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アドレスの場合を除いて”.” ドットがついていない.IPアドレスの場合は,たとえば “10.11.12.13”というように ドットの付いた文字列でしか処理できないからである.また,IPアドレスの場合,トップレベルに保存されサブドメインを含むことができない.

domain record は タグ 0x01を用いる.以下に使われるフィールドの値を示す.

タグの値内容の型説明
0x001Estringドメインの部分の名前
0x001F int8

このドメインに対するクッキーをどうフィルタリングするかをあらわす.このレコードがない場合,上位ドメインの設定が使われる.

  1. このドメインからの全クッキーを受け入れる.
  2. このドメインからの全クッキーを拒否する.
  3. このサーバからの全クッキーを受け入れる.上位ドメインでの設定より優先される.
  4. このサーバからの全クッキーを拒否する.上位ドメインでの設定より優先される.

ドメインに対する設定は,サブドメインに対する設定で上書きしない限り全サブドメインに対して適用される.


0x0021 int8 URLとは一致しないpath情報を含んだクッキーの取り扱う方法を定める.プライバシーの設定で受け入れる設定にしているとユーザに警告するようになるが,「警告する」が有効になっているときドメインによってフィルタリングされる.拒否するときは 1, 受け入れるときは 2. (Handling of cookies that have explicit paths which do not match the URL setting the cookies. If enabled in the privacy preferences the default is to warn the user, but when warning is enabled such cookies can be filtered by their domains: Value 1 indicates reject, and 2 is accept automatically.)
0x0025 int8

“Warn about third party cookies” モードになっているとき,このフィールドはその種のクッキーのフィルタリングに使われる.

  1. すべてのサードパーティーのクッキーを受け入れる.
  2. すべてのサードパーティーのクッキーを拒否する.
  3. このサーバからのすべてのサードパーティーのクッキーを受け入れる.上位ドメインでの設定より優先される.
  4. このサーバからのすべてのサードパーティーのクッキーを拒否する.上位ドメインでの設定より優先される.

ドメインに対する設定は,サブドメインに対する設定で上書きしない限り全サブドメインに対して適用される.

このレコードの後に 常に パスノード終端レコードで終わる 0 個以上の path のノードが続く.その後,0 個以上のドメインのノードが続く.

ドメインのノードは (0x0004 | MSB_VALUE) のフラグレコードで終わる.

pathのノード

pathのノードは ドメインの特定のディレクトリに対する サブディレクトリのクッキーを含む クッキーをまとめている.

ドメインのノードの直後のノードを除いて,pathのノードはpath record から始まり,たいていの場合いくつかのクッキーのレコードとサブディレクトリーのノードが続いている.

pathのレコードは 0x0002 のid を持つ.

タグの値内容の型説明
0x001Dstringpathパートの名前

pathのノードの終端レコードの tag は (0x0005 | MSB_VALUE)

クッキーのレコード

クッキーのエントリーは0x0003のタグを持つレコードに格納される.使用される値は次のとおりである.

タグの値内容の型説明
0x0010stringクッキーの名前
0x0011stringクッキーの値
0x0012time_t有効期限 (Expiry date)
0x0013time_t最後に使われた日時 (Last used)
0x0014stringRFC 2965 で使われる Comment/Description
0x0015stringRFC 2965 における Comment/Description に対する URL
0x0016stringversion=1 のクッキー(cf. RFC 2965)を受け取ったドメイン.
0x0017stringversion=1 のクッキー(cf. RFC 2965)を受け取ったpath.
0x0018stringversion=1 のクッキー(cf. RFC 2965)を受け取った port limitations
(0x0019 | MSB_VALUE)flagHTTPSのサーバにのみ送信する.
0x001Aint8+クッキーのバージョン(RFC 2965)
(0x001B | MSB_VALUE)flag送信元のサーバにのみクッキーを送信する.
(0x001C | MSB_VALUE)flag予約(削除保護の機能に)
(0x0020 | MSB_VALUE)flagpath が URL のprefix だったとき送信しない.たとえば path が /foo のとき /foo/bには送信しますが /foobar には送信しない.
(0x0022 | MSB_VALUE)flagパスワードのログインフォームの結果のクッキー.もしくはそのクッキーにさかのぼれるURLからのクッキー.
(0x0023 | MSB_VALUE)flagHTTP 認証による結果のクッキー.もしくはそのクッキーにさかのぼれるURLからのクッキー.
(0x0024 | MSB_VALUE) flag

“Display Third party cookies” モードのとき,サードパーティーのサーバからのクッキーに対してこのフラグがセットされる.また,このフラグの付いたクッキーは取得するURLがそのサードパーティーのものだった場合にのみ,送信される.サーバからあるリソースの読み込み中に受け取った cookie はサードパーティーのURLには送信されない.The reverse is NOT true.

NOTE: サードパーティーのサーバからもともとのサーバにリダイレクトするとき,リダイレクト先のURLはサードパーティサーバとみなされる.