Palm Programmer's Laboratory
C/C++ Sync Suite Companion601/2
この章は、C API-ベース コンジットを紹介します。あなたがコンジットを設計するとき、あなたがあなたの同期プロセスがどのように動作するのか、各同期アクションに応答する責任があるシステムはどの部分なのかを理解することが必要不可欠です。それゆえ、あなたが新たにコンジット開発を始める場合、先に進む前に Introduction to Conduit Development を読んでください。
この章には以下の節があります:
C/C++ Sync Suite はどのようにコンジットをサポートするか ^TOP^
この節は、C/C++ Sync Suite がどのように C API-ベース コンジットをサポートするのかについての概要を提供します:
コンジット アーキテクチャ ^TOP^
HotSync マネージャは、コンジットのいくつかの必須エントリ ポイントを呼び出すことによって、コンジットと通信します。コンジットは、同期マネージャ API を呼び出すことによって、ハンドヘルド上のデータベースにアクセスします。図 2.1 は、コンジット、HotSync マネージャ、同期マネージャ API、デスクトップ アプリケーション間の関係を示しています。
コンジット エントリ ポイント ^TOP^
HotSync マネージャは、コンジットにタスクを実行させる OpenConduit() 関数を含む、コンジットの中にあるいくつかのエントリ ポイントを呼び出します。コンジットはこれらのエントリ ポイントのいくつかを提供しなければならず、他のエントリ ポイントをオプションとして提供することができます。
新しいコンジットを作成する最も容易な方法は、Visual C++ で Conduit Development Utilities Guide の中の [[コンジット ウィザード|Conduit Development Utilities Guide601/2}} の中で説明されているコンジット ウィザードを使用することです（訳者: CDK 6.0.1 が提供する VC++ 2003 .NET 用のコンジット ウィザードを VC++ 2005 .NET で使用する方法をご存知の方は是非情報を提供してください。）コンジット ウィザードは Windows のための C/C++ Sync Suite と共にインストールされます。
ウィザードを使って機能的なコンジット シェルを作成したら、生成されたコンジットをカスタマイズする必要があります。エントリ ポイントを以下のように変更します:
- GetConduitInfo() をあなたのコンジットについての情報を返すように変更します。
- GetConduitVersion() をあなたのコンジットのバージョン番号を返すように変更します。
- OpenConduit() にあなたの実際の同期操作を実行するためのコードを追加します。
- CfgConduit(), ConfigureConduit() のどちらかまたは両方を、ユーザがあなたのコンジットがどのように動作するのかを変更することを許可するように変更します。これらの関数はコンジットの必須エントリ ポイントではありませんが、PalmSource 社はそれらを含めることを強く推奨していることに注意してください。
必須エントリ ポイント関数とオプションのエントリ ポイント関数についての更なる情報は、コンジット エントリ ポイントの実装 を参照してください。
同期マネージャ API ^TOP^
同期マネージャ API は、ハンドヘルドと通信するための low-level なプログラム的なインターフェイスです。コンジットは同期マネージャ関数を呼び出してハンドヘルドとデータの送受信を行います。あなたのコンジットが Generic Conduit Framework を使用する場合、直接に同期マネージャ API を使用する必要はないかもしれません。
同期マネージャ API についての更なる情報は、クラシック同期マネージャ API の使用 を参照してください。
Generic Conduit Framework ^TOP^
直接的に同期マネージャ API を頼りにせずに、C/C++ Sync Suite で提供される C++ Generic Conduit Framework を使ってコンジットを開発することができます。これらの C++ クラスは、より高いレベルでコンジットのタスクを管理し、いくつかのベースとなる関数を提供します; 特に、ハンドヘルドとデスクトップ コンピュータの両方で変更が行われた場合の調和をとる場合に。コンジット ウィザードはコンジット クラス オブジェクトを作成することができ、あなたはそれからある特定のメソッドをあなたのコンジットを実装するようにオーバライドします。
C API-ベース コンジットの HotSync マネージャへの登録 ^TOP^
Windows のためのコンジットのすべてのタイプでそうなのですが、あなたは C API-ベース コンジットを、HotSync マネージャがそれを実行する前に、登録しなけばなりません。このことは主に、Introduction to Conduit Development の中の コンジットと通知機能の HotSync マネージャへの登録 でカバーされています。
あなたは開発中、テスト中であってもコンジットを登録しなければならないため、あなたのコンジットを配置するためのインストーラを書く前に、あなたはすばやく容易にあなたのコンジットをあなたの開発システムに登録するための 2 つオプションを持っています:
- フォルダ-登録コンジットを実装します。登録は単純にあなたのコンジットを Conduits フォルダにコピーするだけです。この方法は HotSync マネージャ バージョン 6.0 以降でサポートされます。より詳細については、フォルダによるコンジットの登録 を参照してください。
- CDK の中で提供されるコンジット コンフィグレーション（CondCfg）ユーティリティを使って従来通りにあなたのコンジットを登録します。CondCfg は、あなたがあなたの開発マシン上でグラフィカル ユーザ インターフェイスを使ってあなたのコンジットを登録することを可能にする Windows アプリケーションです。CondCfg は <CDK>\Common\Bin ディレクトリの中にあります。更なる情報は、Conduit Development Utilities Guide の中の コンジット コンフィグレーション ユーティリティ? を参照してください。
重要: CondCfg は、コンジット マネージャを呼び出すコードを書くこと無しに、開発/テスト中にあなたがあなたのコンジットを従来通りに登録することを可能にします。しかしながら、CondCfg はエンド-ユーザのユーティリティではありません。そのため、PalmSource は CondCfg をあなたのコンジットと一緒に配布することを許可しません。
あなたのコンジットをエンド-ユーザのマシンに配置するためのインストーラを開発する準備が整ったときは、C API-ベース コンジットを登録するためのインストール時のコンジット マネージャ API 呼び出しについての詳細である インストーラの作成 を参照してください。
コンジット設計の決定 ^TOP^
この節は、あなたのコンジットの top-level 設計に関係する決定を行うために、あなたが使用できる情報を提供します。
重要: あなたの目的がハンドヘルドとデスクトップ間でデータ フォーマットの変換を行う必要があるだけである場合、HotSync マネージャ バージョン 6.0 以降の HotSync 交換機能を使用することができるかもしれません。使用する場合、コンジットを開発する必要はまったくありません。Introduction to Conduit Development の中の HotSync 交換の使用 を参照してください。
あなたのコンジットが単純なテキスト-ベースの同期以上のことを行う必要がある場合、あなたは Generic Conduit Framework の有利性をとることもできますし、走り書きからコンジットを書くこともできます。あなたが Generic Conduit Framework を使用することを望むかどうかを理解するために、まずいかの質問に答えてください:
- コンジットがハンドヘルド データとデスクトップ データの同期をとった結果として、ミラー-イメージ データとなりますか？
- 「はい」の場合、あなたは Generic Conduit Framework を使用することを望むかもしれません。なぜなら、それはハンドヘルドとデスクトップの両方で行われた変更を調和させるためのロジックを実装するからです。あなたはあなたのデスクトップ データ フォーマットを読み書きするためのメソッドを実装する必要があるだけです。
あなたがコンジットを設計するときに考慮するべき最も重要な点は:
- データは両方のプラットフォーム上でどのように保存されるのか
- 同期は一方通行、ミラー-イメージ、トランザクション-ベースのどれなのか
以下の質問へのあなたの回答が、あなたが実装する必要があるコンジットのタイプを決定するのを助けます。
- 存在するデスクトップ コンピュータ データベースはレコードの入出力を行うためのパブリックな API を提供しますか？提供する場合、その API はスタンド-アロン ライブラリとしてパッケージされたものですか？
- 各レコードは固有のレコード ID フィールドを持ちますか？持つ場合、コンジットはレコード ID をキーにしてレコードを参照することができますか？参照できる場合、コンジットはレコードのレコード ID を再代入することができますか？デスクトップ コンピュータ上のレコード ID のフォーマットは、ハンドヘルド上のレコード ID のフォーマットと互換性がありますか？PalmSource 社は、ハンドヘルド上のみにレコード ID を代入することを強く推奨します。
- 各レコードは状態フラグ フィールドを維持しますか？維持する場合、使用可能な状態値は追加、変更、削除ですか？同期操作の終了時点であなたはどのように状態フラグをクリアしますか？
- 変更されたレコードを検出するための簡単な方法はありますか？最終変更日付を示すタイム スタンプ（時分秒を持つ）をこの目的のために使用できます。あなたのコンジットは高速同期をサポートするためにこの機能をサポートする必要があります。
- 存在するデータベースの中でカテゴリというコンセプトはサポートされますか？サポートされる場合、使用可能なカテゴリ数の制限はどのようなものですか？カテゴリ情報を同期させますか？どのようにデスクトップ カテゴリをハンドヘルド上のカテゴリにマッピングしますか？
- フィールド データのサブセットだけをハンドヘルドにダウンロードする可能性を許容できますか？許容できる場合、同期プロセスの間、デスクトップ コンピュータ上のデータをどのように維持するか考慮してください。
- コンジットはハンドヘルド上の複数のデータベースとデスクトップ コンピュータ上の 1 つ以上のデータベースとを同期させる必要がありますか（マルチ-データベース同期）？
- データベースの一方通行のコピーを望みますか？
- コンジットの動作は高速同期と低速同期とでは異なりますか？
- 変更された各レコードは両方で更新されるようにレコード レベルでデータの同期を行いますか？
- レコード-レベルでの同期を望む場合、あなたは同期ロジックを Generic Conduit Framework で実装することを望みますか？
- コンジットはハンドヘルド上の 1 つのデータベースとデスクトップ コンピュータ上の 1 つのデータベースとを同期させますか（シングル データベース同期）？
- デスクトップ コンピュータのレコード フィールドとハンドヘルド レコードは互いにどれくらいマッピングしやすいですか？
- あなたのデスクトップ アプリケーションとハンドヘルド アプリケーションはマルチ データベースまたはマルチ ユーザのコンセプトをサポートしますか？
- アーカイブをサポートしますか？
- 同期にかかる時間を最小限に抑えてタイム-アウトを回避するのに効果のあるデータの前処理を実行することができますか？例えば、あなたのコンジットがインターネット上の情報にアクセスする場合、同期を開始する前にその情報にアクセスするのがベストな方法です。
コンジット開発のアウトライン ^TOP^
以下の 5 つのステップは、CDK でコンジットを作成するプロセスのアウトラインです。あなたのシステムをどのようにセット アップし開始するのかについてのより詳細な説明は、付録 A 「クイック スタート: Visual C++ .NET を使用してのコンジットのビルド」 を参照してください。
A. コンジット開発ツールをインストールする ^TOP^
あなたは以下のソフトウェアをあなたの Windows デスクトップ コンピュータにインストールする必要があります。
- CDK によってサポートされる開発環境をインストールします。サポートされる開発環境のリストは、第 1 章 「Palm OS CDK の新機能」 を参照してください。
- Windows のための CDK の一部である C/C++ Sync Suite をインストールします。
あなたがコンジットを作成、デバッグするのを助けてくれる使用可能なツールについての更なる情報は、Conduit Developmnet Utilities Guide? を参照してください。
B. シェルとして使用できるサンプル コンジットを生成する ^TOP^
（訳者注: ここで言うシェルとは、コンジットの骨格となるコードのことだと思われる。）
開始する最も容易な方法は、C/C++ Sync Suite に含まれるサンプル コードを生成することです。このコードはあなたがシェルとして使用できる機能と文法的な正確さが完璧なコンジットです。
Visual C++ .NET では:
- あなたが C/C++ Sync Suite をインストールするときに VC++ .NET にインストールされるコンジット ウィザードを実行します。（コンジット ウィザードは Visual C++ .NET でのみ使用可能です。）
- あなたがする必要がある最初の、最も基本的な選択は、ウィザードにコードを生成させるときにウィザードに以下のどれを使用させるかです:
- Generic Conduit Framework
- コンジット エントリ ポイントのみ（同期ロジック無し）
あなたが Generic Conduit Framework を選択する場合、付録 A 「クイック スタート: Visual C++ .NET を使用してのコンジットのビルド」 に従ってください。そうする代わりにあなた自身が同期ロジックを書き、lower-level 同期マネージャ API を使用することを選択する場合、エントリ ポイントのみ - 同期ロジックはまったく無い - を生成させるためにウィザードを使用します。
- あなたが指定したソリューション ファイルとコードを生成させるためにウィザードを使用します。
クイック-スタート ガイドは、CDK の中で提供されるメモ帳のデータ受け渡しアプリケーション（原文: Memo Port application。Port は「移植」を意味するのか、それとも「データの受け渡し」を意味するのか？）のためのコンジットを作成するプロセスをステップごとにガイドします。
コンジット ウィザードの使用についての更なる情報は、Conduit Development Utilities Guide の中の 第 2 章 「コンジット ウィザード」? を参照してください。
C. 試しに実行する ^TOP^
あなたのサンプル コンジットをビルドして登録できるか、そして HotSync マネーはそれを実行できるか検証するために、試しにあなたのサンプル コンジットを実行します:
- ウィザードによって生成されたコンジットを、ソース ファイルに何も変更を加えずにビルドします。
- あなたのコンジットを登録します。クイック-スタート ガイドで行われているようにフォルダ-ベース コンジットを実装している場合、あなたはあなたのコンジットを Conduits フォルダに置くだけです - コンジット ウィザードが自動的に行います。しかしながら、あなたがあなたのコンジットを通常通りの方法で登録する場合、あなたはコンジット コンフィグレーション（CondCfg.exe）ユーティリティを使用することができます。（このユーティリティはエンド ユーザがあなたのコンジットをインストールするのに使用することを意図したものではありません。あなたは依然として で説明されているインストーラを提供する必要があります。
- 標準の HotSync を実行することによってあなたのコンジットを実行します。あなたのコンジットの実行を検証するために HotSync ログを閲覧します。
ここで、クイック-スタート ガイドは終了です。これはあなたが、あなたのシステムが正しくセット アップされているか、あなたがサンプル コンジットをビルドしてじこうできるかを確認するのを助けます。
- 重要
- HotSync マネージャが、あなたがコンジット ウィザードを使って生成したコンジットを、あなたがコンジットのコードに何らかの変更を加える前に実行できるということを確認してください。実行できない場合、あなたがコンジットを適切にビルドし、登録したということを保証するために、クイック-スタート ガイドを見直してください。
D. コンジット エントリ ポイントの実装 ^TOP^
あなたがコンジット ウィザードで生成したサンプル コンジットは、GetConduitVersion()|C/C++ Sync Suite Reference/6, GetConduitName()|C/C++ Sync Suite Reference/6, GetConduitInfo()|C/C++ Sync Suite Reference/6 を完全に実装します。あなたがウィザードの中でコンジットに代入した名前を変更すると決めた場合にのみ、これらを変更します。
あなたは、あなたのコンジットの興味のある動作が実行される OpenConduit()|C/C++ Sync Suite Reference/6 エントリ ポイントをコードに追加する必要があります。HotSync マネージャ アプリケーションはこのエントリ ポイントを呼び出して、あなたのコンジットにデスクトップ コンピュータとハンドヘルド間のデータの交換を実行させます。たいていのコンジットは以下の基本的なステップを実行します:
- ハンドヘルド上のデータベースとデスクトップ コンピュータ上のデータ ソースをオープンします。
- 同期マネージャ API を使ってハンドヘルドからデータを読み込み、デスクトップ アプリケーションのネイティブ API を使ってデスクトップ コンピュータのデータ ソースからデータを読み込みます。同期マネージャは、あなたのコンジットがハンドヘルドと通信するためも lowest-level な手段です。あなたが Generic Conduit Framework を使用する場合、これらのクラスの中で指定されるメソッドがあなたのために適切な同期マネージャ呼び出しを行います。
- 必要なデータ交換または同期を行います。
- 結果のデータをハンドヘルド データベースとデスクトップ データ ソースに書き込みます。
- ハンドヘルドのレコード状態フラグをクリアします。
- ハンドヘルド データベースとデスクトップ データ ソースをクローズします。
デバッグとトラブルシューティングについては、第 7 章 「コンジットのデバッグ」 を参照してください。
コンジット ウィザードは、CfgConduit()|C/C++ Sync Suite Reference/6 と ConfigureConduit()|C/C++ Sync Suite Reference/6 のあるバージョンを生成します。これらはあなたのコンジットのためのデフォルトのコンフィグレーション 大ログ ボックスを表示します。デフォルトのダイアログ ボックスはユーザのための基本的なコンフィグレーション オプションを含みます: ファイルの同期を行う、デスクトップがハンドヘルドを上書きする、ハンドヘルドがデスクトップを上書きする、何もしない。あなたがあなたのコンジットのユーザのために異なるオプションを提供する必要がある場合、これらのエントリ ポイントを変更します。
これらのエントリ ポイントと他のエントリ ポイントについての更なる情報は、このドキュメントの中の 第 3 章 「コンジット エントリ ポイントの実装」 または C/C++ Sync Suite Reference の中の 第 6 章 「コンジット エントリ ポイント API」 を参照してください。
E. あなたのコンジットのためのインストール プログラムを作成する ^TOP^
あなたは、エンド ユーザのためにあなたのコンジットをコンピュータにインストールするための簡単な手段を提供する必要があります。コンジット コンフィグレーション開発者ユーティリティはユーザには適切ではありません。そのため、あなたはインストーラ プログラムを作成しなければなりません。
あなたは、あなたのコンジットをユーザのシステムにインストールする、アンインストールするの両方をテストする - ユーザがあなたのコンジットをインストールまたはアンインストールした後も HotSync マネージャが適切に実行され続けるということを検証することを含む - 必要があるということを覚えておかなければなりません。
あなたのインストーラは、あなたのコンジットを登録する、あなたのハンドヘルド アプリケーションをインストールする、デスクトップ ユーザ情報を変更するためにコンジット マネージャ、インストール援助機能を呼び出すことができます。これらの API についての更なる情報は、第 9 章 「インストーラの作成」 を参照してください。
