Palm Programmer's Laboratory
C/C++ Sync Suite Companion601/5
拡張同期マネージャ API は、拡張データベース に対する HotSync 実施への low-level プログラミング インターフェイスです。この章はこの API と 第 4 章 「クラシック同期マネージャ API の使用」 の中で説明されたクラシック データベースのための API を比較します。
同期マネージャ API ライブラリは、C/C++ Sync Suite の <CDK>\C++\WIN\lib ディレクトリの中にあります。
拡張同期マネージャ API とクラシック同期マネージャ API の比較 ^TOP^
Palm OS Cobalt のデータ マネージャは拡張レコード データベースと拡張リソース データベースをサポートします。拡張データベースはいくつかの点でクラシック データベースと異なります。2 つの重要な違いは:
- クラシック データベース レコード、リソース、その他のデータは 64 KB までに制限されます。拡張データベース データはより大きくなることが可能で、レコードサイズはほぼ 64 MB までになります。
- クラシック データベース、拡張データベース、スキーマ データベースはつながりのない名前空間に存在します。
- クラシック データベース名前空間内では、データベース名は固有でなければなりません。
- 拡張データベースとスキーマ データベース名前空間内では、データベース名はあたえられた作成者 ID に対してのみ固有でなければなりません。
名前空間はつながりがないため、同じ名前と作成者 ID を持つデータベースは 3 つまで存在する可能性があります - 名前空間ごとに 1 つのデータベースです。
すべてのデータベース タイプの比較は、Introduction to Conduit Development の中の を参照してください。
同期マネージャ バージョン 2.4 （HotSync マネージャ 6.0 で初めて出荷されました）は拡張データベースにアクセスするための API を提供します。拡張同期マネージャ API は以下の点でクラシック同期マネージャ API とは異なります:
- 拡張データベース API の名前は "Sync" の代わりに "SyncDm" で始まります。
- 拡張データベース API は メモリ カード 番号をパラメータとしてとりません。Palm OS Cobalt はメモリ カードをサポートしません。
- 拡張データベース サイズとオフセット パラメータは、32 ビットです。16 ビットではありません。
- 一意にデータベースを同定する必要がある拡張データベース API は、作成者 ID と データベース名 の両方をとります。
- 複数の拡張（またはスキーマ）データベースが同時にオープンされるかもしれません; 同時に複数の拡張（またはスキーマ）データベースの始めから終わりまでを繰り開始処理していくことが可能です。
- 拡張データベースの始めから終わりまでを繰り開始処理している間のレコードの変更、削除、作成がサポートされます。
- 使用方法を単純にするため、拡張データベース API は CRawRecordInfo のような構造体をパラメータにするのではなく、別々に分かれたパラメータを好みます。これは文体上の違いであり、機能的には少しの違いもありません。
- より大きなデータ サイズのためにフレキシビリティを提供するため、拡張データベース API は、追加のオフセット パラメータを使用して部分的な読み込み、書き込みをサポートします; これは、スキーマ データベースの単一列の読み込み、書き込み API と矛盾しません。
- ハンドヘルドへの参照を最小限に抑えるため、拡張データベース読み込み API はハンドヘルド データをデスクトップ上にキャッシュします。これはサイズが不明である大きなサイズの可能性があるデータを読み込むときに特に有用です。なぜなら、そのようなデータの読み込みは通常、動的なバッファ割り当てを要求するからです。動的な割り当ては 2 つの呼び出しをようきゅうします: 1 つはデータ サイズを取得するためのもので、もう 1 つは実際のデータを取得するためのものです。最初の呼び出しのときにデータをキャッシュすることによって、2 度目のハンドヘルドへの参照のオーバヘッドは回避されます。
クラシック同期マネージャ API と拡張同期マネージャ API の違いの例として、クラシック SyncWriteRec() API について考えます:
class CRawRecordInfo{
public:
HSByte m_FileHandle;
UInt32 m_RecId;
UInt16 m_RecIndex;
HSByte m_Attribs;
SInt16 m_CatId;
SInt32 m_ConduitId;
UInt32 m_RecSize;
UInt16 m_TotalBytes;
HSByte *m_pBytes;
UInt32 m_dwReserved;
}
SInt32 SyncWriteRec (CRawRecordInfo &rInfo);
これに対応する拡張データベースのレコード書き込み API は SyncDmWriteRecord()|C/C++ Sync Suite Reference601/3 です。
HSError SyncDmWriteRecord ( HSByte handle, UInt32 *pRecordID, UInt16 categoryIndex, HSByte attributes, UInt32 dataOffset, UInt32 dataSize, HSBytePtr pRecordData);
クラシック API でサポートされている CRawReocrdInfo のメンバが拡張 API のパラメータになっていることに注意してください。
クラシック SyncReadRecordById() も同様に:
SInt32 SyncReadRecordById (CRawRecordInfo &rInfo);
が拡張 SyncDmReadRecordByID()|C/C++ Sync Suite Reference601/3 になります:
HSError SyncDmReadRecordByID( HSByte handle, UInt16 *pRecordIndex, UInt32 recordID, UInt16 *pCategoryIndex, HSByte *pAttributes, UInt32 dataOffset, UInt32 *pDataSize, HSBytePtr pRecordData, UInt32 *pDataRemaining);
各読み込み、書き込み関数に対して同様の変換が行われて拡張同期マネージャ API に置き換えられます。
拡張同期マネージャの書込み操作後の最終的なデータ サイズ - レコード サイズ、リソース サイズ、など - は dataOffset + dataSize と等しくなります。これは、指定されたオフセットの後に存在するすべてのデータは失われることを意味します。読み込み後のトータルのデータ サイズは dataOffset + *pDataSize + *pDataRemaining です。データを読み込むことなしにデータ サイズを知るために、呼び出し元は 0 オフセットと pDataRemaining を除くすべての出力フィールドに NULL を渡すことができます。すでに注意書きしたように、これは実際のデータの取得し、それをデスクトップ上にキャッシュします。
