{{div_begin}}
[[←　4 章に戻る|C/C++ Sync Suite Companion601/4]]　[[↑トップへ|C/C++ Sync Suite Companion601]]　[[6 章に進む　→|C/C++ Sync Suite Companion601/6]]
{{div_end}}

{{div_begin style="margin-bottom:-10px"}}
!!!5 拡張同期マネージャ API の使用
{{div_end}}

{{div_begin "style='position:absolute;right:0px;font-size:70%;margin-right:15px;margin-top:15px;width:250px;'"}}
*{{goto Comparing Extended and Classic Sync Manager APIs,拡張同期マネージャ API とクラシック同期マネージャ API の比較}}
{{div_end}}

{{div_begin "style='position:relative;padding:0px;padding-right:5px;padding-left:10px;margin-right:250px;margin-top:20px;width:auto;border-right-style:dotted;border-right-width:2px;border-right-color:silver;'"}}
拡張同期マネージャ API は、{{goto extended database,拡張データベース|Introduction to Conduit Development601/Glossary}} に対する HotSync 実施への low-level プログラミング インターフェイスです。この章はこの API と [[第 4 章 「クラシック同期マネージャ API の使用」|C/C++ Sync Suite Companion601/4]] の中で説明されたクラシック データベースのための API を比較します。

*{{goto Comparing Extended and Classic Sync Manager APIs,拡張同期マネージャ API とクラシック同期マネージャ API の比較}}

同期マネージャ API ライブラリは、C/C++ Sync Suite の {{span style='color:blue;font-family:monospace;',<CDK>\C++\WIN\lib}} ディレクトリの中にあります。


!!{{anchor Comparing Extended and Classic Sync Manager APIs}}拡張同期マネージャ API とクラシック同期マネージャ API の比較 {{goto top,^TOP^}}

Palm OS Cobalt のデータ マネージャは拡張レコード データベースと拡張リソース データベースをサポートします。拡張データベースはいくつかの点でクラシック データベースと異なります。2 つの重要な違いは:

*クラシック データベース レコード、リソース、その他のデータは 64 KB までに制限されます。拡張データベース データはより大きくなることが可能で、レコードサイズはほぼ 64 MB までになります。
*クラシック データベース、拡張データベース、スキーマ データベースはつながりのない名前空間に存在します。
**クラシック データベース名前空間内では、データベース名は固有でなければなりません。
**拡張データベースとスキーマ データベース名前空間内では、データベース名はあたえられた作成者 ID に対してのみ固有でなければなりません。{{br}}{{br}}名前空間はつながりがないため、同じ名前と作成者 ID を持つデータベースは 3 つまで存在する可能性があります - 名前空間ごとに 1 つのデータベースです。

すべてのデータベース タイプの比較は、''Introduction to Conduit Development'' の中の {{goto Schema vs. Non-schema Databases|「スキーマデータベース 対 非スキーマ データベース|Introduction to Conduit Development601/8}} を参照してください。

同期マネージャ バージョン 2.4 （HotSync マネージャ 6.0 で初めて出荷されました）は拡張データベースにアクセスするための API を提供します。拡張同期マネージャ API は以下の点でクラシック同期マネージャ API とは異なります:

*拡張データベース API の名前は "Sync" の代わりに "SyncDm" で始まります。
*拡張データベース API は {{goto memory card,メモリ カード|Introduction to Conduit Development601/Glossary}} 番号をパラメータとしてとりません。Palm OS Cobalt はメモリ カードをサポートしません。
*拡張データベース サイズとオフセット パラメータは、32 ビットです。16 ビットではありません。
*一意にデータベースを同定する必要がある拡張データベース API は、{{goto creator ID,作成者 ID|Introduction to Conduit Development601/Glossary}} と {{goto database name,データベース名|Introduction to Conduit Development601/Glossary}} の両方をとります。
*複数の拡張（またはスキーマ）データベースが同時にオープンされるかもしれません; 同時に複数の拡張（またはスキーマ）データベースの始めから終わりまでを繰り開始処理していくことが可能です。
*拡張データベースの始めから終わりまでを繰り開始処理している間のレコードの変更、削除、作成がサポートされます。
*使用方法を単純にするため、拡張データベース API は {{goto CRawRecordInfo,CRawRecordInfo|C/C++ Sync Suite Reference601/4-1}} のような構造体をパラメータにするのではなく、別々に分かれたパラメータを好みます。これは文体上の違いであり、機能的には少しの違いもありません。
*より大きなデータ サイズのためにフレキシビリティを提供するため、拡張データベース API は、追加のオフセット パラメータを使用して部分的な読み込み、書き込みをサポートします; これは、スキーマ データベースの単一列の読み込み、書き込み API と矛盾しません。
*ハンドヘルドへの参照を最小限に抑えるため、拡張データベース読み込み API はハンドヘルド データをデスクトップ上にキャッシュします。これはサイズが不明である大きなサイズの可能性があるデータを読み込むときに特に有用です。なぜなら、そのようなデータの読み込みは通常、動的なバッファ割り当てを要求するからです。動的な割り当ては 2 つの呼び出しをようきゅうします: 1 つはデータ サイズを取得するためのもので、もう 1 つは実際のデータを取得するためのものです。最初の呼び出しのときにデータをキャッシュすることによって、2 度目のハンドヘルドへの参照のオーバヘッドは回避されます。

クラシック同期マネージャ API と拡張同期マネージャ API の違いの例として、クラシック {{goto SyncWriteRec,SyncWriteRec()|C/C++ Sync Suite Reference601/4-2}} 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 は {{goto SyncDmWriteRecord,SyncDmWriteRecord()|C/C++ Sync Suite Reference601/3}} です。

 HSError SyncDmWriteRecord (
    HSByte handle,
    UInt32 *pRecordID,
    UInt16 categoryIndex,
    HSByte attributes,
    UInt32 dataOffset,
    UInt32 dataSize,
    HSBytePtr pRecordData);

クラシック API でサポートされている {{span style='color:blue;font-family:monospace;',CRawReocrdInfo}} のメンバが拡張 API のパラメータになっていることに注意してください。

クラシック {{goto SyncReadRecordByID,SyncReadRecordById()|C/C++ Sync Suite Reference601/4-2}} も同様に:

 SInt32 SyncReadRecordById (CRawRecordInfo &rInfo);

が拡張 {{goto SyncDmReadRecordByID,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 に置き換えられます。


{{anchor Data Size}}
'''データ サイズ'''

拡張同期マネージャの書込み操作後の最終的なデータ サイズ - レコード サイズ、リソース サイズ、など - は {{span style='color:blue;font-family:monospace;',dataOffset}} + {{span style='color:blue;font-family:monospace;',dataSize}} と等しくなります。これは、指定されたオフセットの後に存在するすべてのデータは失われることを意味します。読み込み後のトータルのデータ サイズは {{span style='color:blue;font-family:monospace;',dataOffset}} + *{{span style='color:blue;font-family:monospace;',pDataSize}} + *{{span style='color:blue;font-family:monospace;',pDataRemaining}} です。データを読み込むことなしにデータ サイズを知るために、呼び出し元は 0 オフセットと {{span style='color:blue;font-family:monospace;',pDataRemaining}} を除くすべての出力フィールドに {{span style='color:blue;font-family:monospace;',NULL}} を渡すことができます。すでに注意書きしたように、これは実際のデータの取得し、それをデスクトップ上にキャッシュします。
{{div_end}}

{{div_begin "style='border-top-style:solid;border-top-width:1px;border-top-color:silver;'"}}
[[←　4 章に戻る|C/C++ Sync Suite Companion601/4]]　[[↑トップへ|C/C++ Sync Suite Companion601]]　[[6 章に進む　→|C/C++ Sync Suite Companion601/6]]
{{div_end}}