Palm OS Programmer's Companion Volume II/3-2

←　1 節に戻る　↑3 章トップへ　3 節に進む　→

3-2 PDI ライブラリについて

Palm OS PDI ライブラリは、以下のオブジェクトと関数を提供する共有ライブラリです。

• 入力データストリームから vCard オブジェクトの読み取り。PDI リーダの作成ではどのように PDI リーダを作成して使用するかを説明し、PDI リーダの利用例セクションでは入力ストリームから vCard データを読み取る例を提供します。
• 出力データストリームへ vCard オブジェクトの書き込み。PDI ライタの作成ではどのように PDI ライタを作成して使用するかを説明し、PDI ライタの利用例セクションでは出力ストリームへ vCard データを書き込む例を提供します。

訳注

リスト2番目の説明文が1番目と同じく PDI リーダに関するものだったので、適宜変更しました。

PDI ライブラリは、多くのフォーマット・多くのメディアからのオブジェクトの読み書きを扱います。メディアの指定について詳しくは「異なるメディアへの UDA の使用」を参照して下さい。

PDI プロパティとパラメータの形式

PDI ライブラリは、リーダまたはライタオブジェクトでプロパティ情報を指定するのに使用できる定数を提供します。これらは vObject標準で定義されている以下の形式の定数を含みます。

• プロパティ名定数は、PDI プロパティ名を表します。各プロパティ名定数は kPdiPRN_ プレフィックスで始まります。例えば、kPdiPRN_ADR 定数は ADR プロパティ名を表します。詳しくは、Palm OS Programmer's API Reference の第 88 章「Personal Data Interchange Library」?を参照して下さい。
• プロパティ値フィールド定数は、構造化されたフィールド値を持つプロパティの、プロパティ値フィールドの位置を表します。各プロパティ値フィールド定数は kPdiPVF_ プレフィックスで始まります。例えば、kPdiPVF_ADR_COUNTRY 定数は ADR プロパティ値の COUNTRY フィールドを表します。詳しくは、Palm OS Programmer's API Reference の第 88 章「Personal Data Interchange Library」?セクションを参照して下さい。
• パラメータ名定数は、vObject プロパティのパラメータ名を表します。各パラメータ名定数は kPdiPAN_ プレフィックスで始まります。例えば、kPdiPAN_Type 定数は TYPE パラメータを表し、kPdiPAN_Encoding 定数は ENCODING パラメータを表します。詳しくは、Palm OS Programmer's API Reference の第 88 章「Personal Data Interchange Library」?セクションを参照して下さい。
• パラメータ値定数は、パラメータの名前と値が結合したものを表します。各パラメータ値定数は kPdiPAV_ プレフィックスで始まります。例えば、kPdiPAV_ENCODING_BASE64 定数は {{span style='color:blue;font-family:monospace;',Base64} エンコーディングを表します。詳しくは、Palm OS Programmer's API Reference の第 88 章「Personal Data Interchange Library」?セクションを参照して下さい。

これら定数の完全な一覧は、PdiConst.h ファイルを参照して下さい。

PDI ライブラリプロパティ辞書

PDI ライブラリは「よく知られた（well-known）」とみなされるプロパティについての情報を保管する辞書をfeatureしています。よく知られたプロパティは、 vObject標準（vCard と vCal 標準を含む）仕様で定義されたものの一つです。これらの標準は、PDI developer's web page（http://www.imc.org/pdi/pdiproddev.html） にてオンラインで探すことができます。
PDI リーダとライタは、特定のプロパティに対してどのように読み書きを行なうかを決めるために、プロパティ辞書内の情報を使用します。もっと明確に言うなら、この辞書は各プロパティ値のフォーマットについての情報を保存しています。つまり、リーダはプロパティ値を正確に解釈するためにこの情報を使用し、ライタは書き込む値を正確にフォーマットするためにこの情報を使用します。プロパティ値は複数フィールドで構造化されていることがあるため、この情報は重要です。
例えば、標準的な住所（ADR）プロパティは 7 つのフィールドを持った構造化された値を持っており、フィールドはセミコロンで区切られています。辞書はこの情報を保管しており、PDI リーダは ADR プロパティを解釈する際に 7 つのセミコロンで区切られたフィールドを読み取ることを知っています。
デフォルトによって、入出力の解釈時に各 PDI リーダ及びライタは標準辞書を使用します。しかし、他の方法でプロパティの値を解釈もしくは生成するようにこの振舞いを上書きすることも可能です。詳しくは、「プロパティ値の読み取り」または「プロパティ値の書き込み」を参照して下さい。
あなたのアプリケーション向けにカスタマイズされた PDI プロパティの解釈あるいは生成を追加するために、辞書を改めたり置き換えたりすることもできます。詳しくは「カスタム拡張子の追加」を参照して下さい。

PDI リーダ

vObject 入力の読み取り及び解釈のために、PDIライブラリはPDI リーダオブジェクトを提供します。PDI リーダオブジェクトは、PDI 入力ストリーム解釈の現在の状態を保持する構造体です。
PDI リーダは入力ストリームを一つのプロパティに解釈します。Begin Object プロパティで始まり End Object プロパティで終わります。
PdiReaderType 構造体は、入力ストリームの解釈の現在状態について様々な情報を保持します。また、現在のプロパティについて以下の情報を含みます。

• エンコードとキャラクタセット
• 現在のプロパティ、パラメータ、プロパティ値、の形式
• 現在のプロパティとパラメータの名前
• 現在のプロパティの値文字列
• 現在のプロパティが遭遇した解釈イベントのマスク

解釈イベントについて

PDI リーダは、プロパティの処理中に遭遇した各解釈イベントを記録します。例えば、BEGIN:VCARD プロパティを解釈するとき、PDI リーダは kPdiBeginObjectEventMask を記録します。また、プロパティ名を解釈するとき、PDI リーダは kPdiPropertyNameEventMask を記録します。
各イベントは PdiReaderType 構造体の一つとして表現されます。
現在のプロパティを解釈している間に特定のイベントが発生したかどうかを、そのイベントの定数をリーダ構造体内の events フィールドに対してテストすることによって決定することができます。例えば、入力ストリームの最後に達したなら以下のステートメントは false を返します。

return((reader->events & kPdiEOFEventMask)==0);

PDI ライタ

vObject 出力の書き込みのために、PDI ライブラリは PDI ライタオブジェクトを提供します。PDI ライタオブジェクトは、PDI データについて状態の保持や生成の管理を行なう構造体です。
PDI ライタは、一つのプロパティにつき一回データを出力ストリームに送ります。Begin Object プロパティで始まり End Object プロパティで終わります。
PdiWriterType構造体は、出力ストリームへの書き込みの状態についての情報を保持します。以下のものが含まれます。

• 現在のプロパティのエンコードとキャラクタセット
• 現在のプロパティ、パラメータ、プロパティ値、の形式
• 現在のプロパティとパラメータの名前
• 現在のプロパティの値文字列
• 現在のプロパティが遭遇した解釈イベントのマスク
• 現在のプロパティのエンコーディングとキャラクタセット
• 現在のプロパティ値を書き込むのに使用するモード（プロパティ値がどのように構造化されているかを指定する）
• 現在のプロパティ値に要求されるフィールドの数

フォーマットの互換性

PDI ライブラリは以下のフォーマットでデータストリームを読み書きすることができます。

• vCard 3.0
• vCard 2.1
• vCal 1.0
• iCalendar
• Palm フォーマット

あるフォーマットを使用した入力データストリームを別フォーマットの出力データストリームへ変換するのに PDI ライブラリを使用することができます。詳しくは「PDI バージョンの指定」を参照してください。

Palm OS 旧バージョンとの互換性

PDI ライブラリは Palm OS の旧バージョンとの互換性を維持できるようにデザインされています。つまり、旧バージョンのデバイスから vObject を受信したり逆に vObject を送信したりするのに、ライブラリ関数を使用できるということです。
この互換性の利点を得るために、PDI ライブラリは異なるフォーマット（ ImcUtils 実装を含む旧バージョンの Palm OSでサポートされるフォーマット）のデータを送受信するように構築されています。
この互換性サポートを PDI リーダに含めるには、PdiReaderNew 関数のコール時にkPdiOpenParser 定数を指定します。
この互換性サポートを PDI ライタに含めるには、PdiWriterNew 関数のコール時に kPdiPalmCompatibility オプションを指定します。

国際性の考慮

PDI ライブラリはカタカナを含む様々なキャラクタセットを扱います。もし入力ストリームで CHARSET パラメータを指定するなら、PDI リーダはプロパティ値を性格に読み取るでしょう。
Palm OS^(R) 4.0 に含まれる PDI ライブラリは、以下のキャラクタセットを理解します。

• charEncodingAscii
• charEncodingISO8859_1
• charEncodingShiftJIS
• charEncodingISO2022Jp

もし未知のキャラクタセットを指定するなら、現在のキャラクタセットは charEncodingUnknown 定数で表される「未知」の状態になります。

未サポートのフィーチャー

Palm OS 4.0 に含まれる PDI ライブラリは以下のフィーチャーを扱えません。

• マルチパート MIME メッセージは扱えません。
• vObject の XML バージョンはサポートされません。
• アプリケーションはグルーピングを無視します。PDI リーダはグループ識別しを解釈しますが、それらを無視します。しかし、最近解釈したグループ名は PdiReaderType オブジェクトの groupName フィールドに保持されます。

←　1 節に戻る　↑3 章トップへ　3 節に進む　→