C/C++ Sync Suite Companion601/9-1

←　8 章に戻る　↑トップへ　付録 A に進む　→

9 インストーラの作成 （ページ 1）

• （ページ 1）
• インストーラのタスク
• HotSync マネージャのバイナリの検索
• インストールするファイル
• コンジット マネージャ API の使用
  • 通常通りの方法でのコンジットの登録
  • フォルダでのコンジットの登録
  • コンジットの登録解除
  • コンジット衝突の解決
  • 登録されたコンジット情報へのアクセス
  • 開発者-定義コンジット コンフィグレーション エントリへのアクセス
  • フォルダ-登録コンジット情報の取得
  • バックアップ コンジットの登録と登録解除
  • COM ポートのコンフィグレーション
  • コンジット マネージャのユーティリティ関数の使用
  • コンジット マネージャ関数の要約
• インストール援助機能 API の使用
  • インストール援助機能の機能
  • データベースを主記憶装置にインストールするためにキューに追加する
  • ファイルを HotSync 交換を経由して主記憶装置にインストールするためにキューに追加する
  • ファイルを拡張カードにインストールするためにキューに追加する
  • HotSync ユーザ情報の取得
  • 登録されたインストール コンジット情報へのアクセス
  • インストール援助機能のユーティリティ関数の使用
  • インストール援助機能関数の要約
• ユーザ データ API の使用
  • HotSync ユーザの追加と削除
  • HotSync ユーザのディレクトリの検索と設定
  • HotSync ユーザについての情報へのアクセス
  • HotSync ユーザの同期設定へのアクセス
  • HotSync ユーザの拡張スロット情報の取得
  • HotSync ユーザのインストール コンジット フラグの変更
  • ユーザ データ保存場所の中の開発者-定義エントリへのアクセス
  • ユーザ データ API ユーティリティ関数の使用
  • ユーザ データ API 関数の要約
• （ページ 2）
• HotSync マネージャ API の使用
  • HotSync マネージャ API 関数の要約
• 通知機能インストール マネージャ API の使用
  • 通知機能の登録と登録解除
  • 登録された通知機能情報へのアクセス
  • 通知機能インストール マネージャ関数の要約
• インストール コンジット マネージャ API の使用
  • インストール コンジットの登録
  • インストール コンジットの登録解除
  • 登録されているすべてのインストール コンジットについての情報へのアクセス
  • 開発者-定義インストール コンジット コンフィグレーション エントリへのアクセス
  • インストール コンジット マネージャ関数の要約
• コンジットのアンインストール
• インストーラのテスト
• インストール トラブルシューティング Tips
• サンプル インストーラ

↑　9 章のトップへ　9 章のページ 2 へ　→

インストーラのタスク ^TOP^

あなたのインストーラはコンジットとともにハンドヘルド アプリケーション、ハンドヘルド データベース、デスクトップ アプリケーションをインストールする必要があるかもしれません。したがって、ユーザにとって最良なのは一度にこれらをすべてインストールする単一のインストーラを作成することです。ハンドヘルド データベースのために、あなたのインストーラは、複数の HotSync ユーザがいる場合はユーザ リストを表示して、次の HotSync 実施でインストールするデータベースを準備すべきです。あなたのインストーラはあなたのコンジットを登録しなければなりません。さもないと HotSync マネージャはそれを実行することができません。最後にインストーラはユーザに HotSync を実行して実際にあなたのアプリケーションとデータベースをハンドヘルドにインストールすることを要求しなければありません。

要約すると、あなたのインストーラは少なくとも以下のタスクを実行して、あなたの製品をエンド ユーザのデスクトップ コンピュータとハンドヘルドに配置しなければなりません:

• あなたのインストール ファイルをすべてエンド ユーザのデスクトップ コンピュータにコピーします。
• あなたの製品がデスクトップ アプリケーションを含む場合、そのアプリケーションをインストールします。
• HotSync マネージャがインストールされているかチェックします。コンジット マネージャ API CondMgr.dll を使用します。いずれのインストーラでも必須です。
• あなたの製品があなたのコンジット ファイルと通知機能 DLL を提供する場合、それらを最終目的地であるディレクトリにコピーします。
• あなたのコンジットを HotSync マネージャに登録します。コンジット マネージャ API CondMgr.dll を使用して、通常通りの登録を行うか、フォルダで登録する場合は Conduits フォルダを検索します。登録はいずれのコンジットでも必須です。
• あなたの通知機能を HotSync マネージャに登録します。通知機能インストール マネージャ API CondMgr.dll を使用します。あなたが通知機能を提供する場合にのみ必須です。
• コンジットの登録後に HotSync マネージャを再起動します。HotSync マネージャ API HSAPI.dll を使用します。HotSync マネージャ バージョンが 6.0 よりも前のものにコンジットを登録する場合にのみ必須です。バージョン 6.0 以降では必要ありません。
• 次の HotSync 実施の間にハンドヘルドにインストールするデータベースまたはアプリケーション - または拡張カードにインストールするファイル - をキューに追加します。インストール援助機能 API InstAide.dll を使用します。ハンドヘルドにインストールするいずれのデータベースまたはファイルでも必須です。
• あなたがデスクトップ アプリケーション、コンジット、通知機能を提供する場合はそれらをアンインストールします - これはあなたのコンジットと通知機能の HotSync マネージャへの登録を解除することも含みます。

HotSync マネージャのバイナリの検索 ^TOP^

インストーラが実行しなければならない最初のタスクの 1 つは、HotSync マネージャの実行形式のファイルとそのサポート DLL がエンド ユーザのコンピュータにインストールされているかどうかを明らかにすることです。これを行うために、あなたのインストーラはコンジット マネージャを呼び出して HotSync マネージャの実行形式ファイルのパスを取得しなければなりません。しかし、あなたのインストーラが使用しなければならないコンジット マネージャ ライブラリ（CondMgr.dll）は HotSync マネージャと同じディレクトリにあります。

この循環的な依存を打破するために、PalmSource は、エンド ユーザのコンピュータにすでにインストールされている CondMgr.dll を検索するという単一の目的のために、あなたがあなたのインストーラの中で CondMgr.dll の一時コピーを再配布することを許可します。あなたがインストールされたコピーを見つけた後は、あなたはあなたの一時コピーをユーザのコンピュータから削除しなければなりません。

それ以外の目的では、PalmSource はCDK の他のバイナリ ファイルのいずれかを再配布することを許可しません。

---

WARNING! 常にユーザのコンピュータにすでにインストールされている CondMgr.dll とその他の HotSync マネージャ サポート DLL ファイルを使用してください。インストールされている DLL を他のコピーで置き換えてはいけません。これはインストールされた他のバイナリのバージョンとの非互換を引き起こすかもしれません。ユーザのコンピュータ上で異なる HotSync マネージャ バイナリのバージョンが混在することはデータの喪失を引き起こす可能性があります。

---

以下のステップは、HotSync マネージャがすでにユーザのコンピュータにインストールされているかどうかをどのように明らかにするのかのアウトラインです:

1. <CDK>\Common\Bin フォルダの中で提供されている CondMgr.dll ファイルのコピーをあなたのインストーラにインクルードします。
2. CondMgr.dll をエンド ユーザのコンピュータ上の一時フォルダにコピーします。
3. あなたの CondMgr.dll の一時コピーを使用して、あなたが コンジット マネージャ バージョン 3 以降を使用している場合は CmGetSystemHotSyncExecPath() を、あなたが コンジット マネージャ バージョン 2 以前を使用している場合は CmGetHotSyncExecPath() を呼び出します。
   これらの関数はどちらかが pPath パラメータ経由で空の文字列を返してくる場合、HotSync マネージャはインストールされていません。PalmSource は、あなたがユーザにハンドヘルドと共に提供される Palm OS Desktop ソフトウェアをインストールするよう促し、それから再度あなたの製品をインストールしようと試みることを推奨します。ステップ 6 に飛んでください。
   しかしながら、これらの関数のどちらかが pPath パラメータ経由で空ではない文字列を返してくる場合、HotSync マネージャはすでにインストールされています。このパラメータは HotSync マネージャの実行形式ファイルのフル パスとファイル名を指します。次のステップに進んでください。
4. CmGetSystemHotSyncExecPath() によって返されるパスから HotSync.exe ファイル名を取り去ります。これは、すでにユーザのコンピュータにインストールされている CondMgr.dll と他のサポート DLL ファイルのパスです。
5. ステップ 4 で返されたパスの中にあるインストールされた CondMgr.dll ファイルを使用して、コンジット マネージャ API のバージョンを取得するために CmGetLibVersion() を呼び出します。
   このステップは、あなたがインストール済みの CondMgr.dll ファイルを呼び出すことができ、その API のバージョン番号を取得できることを確認します。あなたのインストーラが後期のバージョンの中でのみ使用可能なコンジット マネージャ関数を必要とする場合、このバージョン番号を使って先に進むべきかどうか、どのように続行すべきかを明らかにします。C/C++ Sync Suite Reference の 「コンジット マネージャ関数」 の中で、各関数の説明がどのバージョンのコンジット マネージャがその関数を提供するのかを示しています。
6. あなたは、HotSync マネージャがすでにインストールされているかどうかにかかわらず、ユーザのコンピュータからあなたの CondMgr.dll の一時コピー（ステップ 2）を削除しなければなりません。PalmSource は、あなたがあなたの CondMgr.dll の一時コピーをユーザのコンピュータに残すことを許可しません。
7. 必要があれば、ステップ 4 で見つけたディレクトリの中にあるインストールされた他の HotSync マネージャ サポート DLL を呼び出します。

NOTE

HotSync マネージャ サポート DLL のパスを取得するために、CmGetCorePath() ではなく、CmGetSystemHotSyncExecPath() を使用するように注意してください。CmGetCorePath() は HotSync ユーザのフォルダのパスを取得します。このフォルダは、HotSync マネージャ バージョンが 6.0 よりも前であれば HotSync 実行形式ファイルのパスと同じです。しかしながら、6.0 以降では、それらのパスは異なります。

表 9.1 はこの節で説明されたコンジット マネージャ API 関数を要約しています。

表 9.1 HotSync マネージャとコンジット マネージャの検索

タスク	コンジット マネージャ API 関数
HotSync マネージャの実行形式ファイルのパスとファイル名を取得します。HotSync.exe ファイル名を取り去って、すべての HotSync マネージャのバイナリを保持しているフォルダのパスを取得します。	CmGetSystemHotSyncExecPath()
現在の Windows ユーザのための HotSync ユーザのディレクトリのパスを取得します。各 Windows ユーザは固有のパスを持たなくてはならないため、システム-レベル パスではありません。	CmGetCorePath()

インストールするファイル ^TOP^

インストールされた HotSync マネージャを見つけた後、あなたのインストーラは通常以下のファイルをユーザのコンピュータにインストールする必要があります:

• MyApp.prc。あなたのハンドヘルド アプリケーションとそれとは別にあるかもしれないデータベース。
• MyCondut.dll。あなたの C API-ベース コンジット。
• MyApp.exe とサポート ファイル。あなたのデスクトップ アプリケーション（あなたの製品がそれを含む場合は）。
• PalmSource のコンジット マネージャ ライブラリ CondMgr.dll。「HotSync マネージャ バイナリの検索」 で説明したように、あなたはこのHotSync マネージャ サポート DLL をユーザのコンピュータに一時的にコピーするかもしれません。

コンジット マネージャ API の使用 ^TOP^

この節では、インストーラがコンジット マネージャを使って実行する最も共通なタスクを説明します。

• 通常通りの方法でのコンジットの登録
• フォルダでのコンジットの登録
• コンジット登録の解除
• コンジット衝突の解決
• 登録されたコンジット情報へのアクセス
• 開発者-定義コンジット コンフィグレーション エントリへのアクセス
• フォルダ-登録コンジット情報の取得
• バックアップ コンジットの登録と登録解除
• COM ポートのコンフィグレーション
• コンジット マネージャのユーティリティ関数の使用
• コンジット マネージャ関数の要約

HotSync マネージャ バージョン 6.0 以降とコンジット マネージャ バージョン 3 以降は Windows のマルチ-ユーザ バージョンをサポートします。予備知識として、Introduction to Conduit Development の 「マルチ-ユーザのサポート」 を参照してください。以下の小節では、ユーザのためのコンジット登録とシステムのためのコンジット登録の違いについて説明します。

NOTE

コンジット マネージャ関数を呼び出してシステム-レベル設定を変更する前に、まず CmIsCurrentUserAdmin() を呼び出して現在の Windows ユーザが管理者権限を持っているかどうかを明らかにします。変更を行うシステム-レベル呼び出しは、ユーザが管理者権限を持っている場合にのみ成功します; さもないと、これらの呼び出しは ERR_INSUFFICIENT_PRIVILEGES を返して失敗します。情報を読み込むだけのシステム-レベル呼び出しは権利者権限を必要としません。

通常通りの方法でのコンジットの登録 ^TOP^

ここでは、通常通りに同期コンジットを登録するためにコンジット マネージャ API をどのように使用するのかについて説明します。予備知識とここで使用されるテクノロジの説明は、Introduction to Conduit Development の 第 6 章 「コンジットと通知機能の HotSync マネージャへの登録」 を参照してください。

コンジット マネージャ API は、コンジット登録情報の基本的な保存をコンジットの登録と登録解除のプロセスから切り離します。この抽象化は、あなたがどのようにコンジットを登録、登録解除するかに影響を与えることなしに基本的な保存の詳細を変更することを可能にします。

NOTE

コンジットを登録するために Windows のレジストリを直接操作してはいけません。あなたがコンジット マネージャを出し抜いてコンジットを登録する場合、あなたのインストーラは将来のバージョンの HotSync マネージャでは機能しないかもしれません。

コンジットマネージャは、コンジットのコンフィグレーション エントリの中の値を読み書きするために、登録される各コンジットに代入される固有の作成者 ID を使用します。HotSync マネージャが読み込むコンジット コンフィグレーション エントリの説明は、Introduction to Conduit Development の 付録 A 「コンフィグレーション エントリ」 を参照してください。

あなたは、以下の小節で説明されるように通常通りの方法でコンジットを登録するために、2 つの異なる方法でコンジット マネージャを使用することができます:

• 単一の構造体を作成する
• 別個のコンフィグレーション エントリを作成する

単一の構造体を作成する ^TOP^

単一の構造体から C API-ベース コンジットを登録するために、CmConduitType2 構造体を割り当て、構造体のフィールド値を適切にセットし、この構造体を CmInstallConduitByStruct() に渡します。この関数は、構造体の中であなたが指定した作成者 ID のために、あなたのコンジットのコンフィグレーション エントリを保存しようと試みます。他のコンジットがすでに同じ作成者 ID を使って登録されている場合、この関数は ERR_CREATORID_ALREADY_IN_USE エラーを返して、あなたのコンジットを登録しません。

C API-ベース コンジットを登録するためにあなたがセットしなければならない CmConduitType2 の中のフィールドは:

• dwCreatorID - コンジットの作成者 ID
• szConduitPath - コンジット DLL のパスとファイル名（またはファイル名のみ）

他のフィールドはオプションです。詳細は C/C++ Sync Suite Reference の CmConduitType2 を参照してください。

コード 9.1 は、現在の Windows ユーザのためにコンジットを登録するための CmInstallConduitByStruct() の使用例です。システムのためにコンジットを登録するには、単純にこの関数呼び出しを CmInstallSystemConduitByStruct() で置き換えるだけです。

コード 9.1 単一の構造体でコンジットを登録する例

int RegisterConduitByStruct () {
   CmConduitType2 pConduit;
   DWORD id;
   int retval = 0;

   memset(&pConduit, '\0', sizeof(pConduit));

   strcpy(pConduit.szConduitPath,"MyConduit.dll");
   strcpy(pConduit.szLocalDirectory, "MyConduitDir");
   strcpy(pConduit.szLocalFile,"MyDesktopFile.dat");
   strcpy(pConduit.szRemoteDB,"MyHandheldDatabase");
   strcpy(pConduit.szTitle,"My Conduit Display Name");

   CmConvertStringToCreatorID("MyID", &id);
   pConduit.dwCreatorID = id;
   pConduit.dwPriority = 2;

   retval = CmInstallConduitByStruct(pConduit);
// If retval is ERR_CREATORID_ALREADY_IN_USE, then another 
// conduit is already registered with this creator ID, so 
// this call fails.
   return retval;
}

互換性についての注意

CmConduitType2 構造体と CmInstallConduitByStruct() 関数は、コンジット マネージャ API バージョン 3 以降で使用可能です。この構造体は、すべてのバージョンの HotSync マネージャが使用するコンフィグレーション エントリだけを保持し、文字列を単純な文字配列として保存します。

すべてのバージョンのコンジット マネージャは、同じことをするために、CmConduitType 構造体と CmInstallConduit() 関数を提供します。CmConduitType 構造体は以下の 2 点が CmConduitType2 とは異なります:

• いくつかのフィールドはそれぞれ、構造体の開始点から null で終了する文字列の開始点までのオフセットを指定します。このテクニックは、文字列容量を浪費することなく、構造体を効率的にビルドすることを可能にします。しかしながら、あなたが CmConduitType 構造体を作成するとき、あなたは構造体自体とあなたが指定する文字列のために容量を割り当てる必要があります。あなたがこのメモリ管理作業を回避したいのなら、PalmSource は、あなたが代わりに CmConduitType2 構造体を使用して、それを CmInstallConduitByStruct() に渡すことを推奨します。
• いくつかのフィールドは、コンジット マネージャ バージョン 3 以降では推奨しない値を指定します。

表 9.2 は、構造体でコンジットを現在の Windows ユーザとシステムの両方のために登録するための関数を要約しています。

表 9.2 通常通りの方法でコンジットを登録するための単一の構造体の作成

タスク	コンジット マネージャ API 関数
通常通りの方法でコンジットを登録します。単一の CmConduitType2 構造体の中に渡します。コンジット マネージャ バージョン 3 以降で使用可能です。	ユーザ: CmInstallConduitByStruct() システム: CmInstallSystemConduitByStruct()
通常通りの方法でコンジットを登録します。単一の CmConduitType 構造体の中に渡します。すべてのバージョンのコンジット マネージャで使用可能です。この構造体を使用するシステム-レベル関数は無いということに注意してください。	ユーザ: CmInstallConduit() システム: N/A

別個のコンフィグレーション エントリを作成する ^TOP^

一連の関数呼び出しでいくつかのコンフィグレーション エントリを作成することによって C API-ベース 同期コンジットを登録するには、まずあなたのコンジットの作成者 ID で CmInstallCreator() を呼び出します。この関数が成功した場合、以下の一連の関数を呼び出して - 特定の順番はありません - 他のコンジット コンフィグレーション値をセットします:

• CmSetCreatorName() - CmInstallCreator() に加えて、これは、あなたがいずれのタイプのコンジットを登録する場合であってもセットしなければならない他の値をセットします。残りはオプションです。
• CmSetCreatorPriority()
• CmSetCreatorTitle()
• CmSetCreatorDirectory()
• CmSetCreatorFile()
• CmSetCreatorRemote()

開発者-定義コンジット コンフィグレーション エントリ で説明されているように、あなたはあなた自身のコンフィグレーション エントリを作成して、それらをインストール時にセットすることもできます。

コード 9.2 は CmInstallCreator() といくつかの CmInstallCreator...() 関数を呼び出す単純なコンジット登録を示しています。

コード 9.2 一連のコンジット マネージャ関数でのコンジットの登録

int RegisterConduitWithMultipleCalls () {
   err = CmInstallCreator("Xyzz", CONDUIT_APPLICATION);
   if (err == 0)
      err = CmSetCreatorName("Xyzz", 
         "C:\\MyCond\\Debug\\MyCond.DLL");
   if (err == 0)
      err = CmSetCreatorDirectory("Xyzz", "MyCond");
   if (err == 0)
      err = CmSetCreatorFile("Xyzz", "MyCond");
   if (err == 0)
      err = CmSetCreatorPriority("Xyzz", 2);
   if (err == 0)
      printf(" Registration succeeded\n");
   else
      printf(" Registration failed %d\n", err);
   return err;
}

表 9.3 は、別個にコンフィグレーション エントリを作成することによって現在の Windows ユーザとシステムの両方のためにコンジットを登録する関数を要約しています。

タスク	コンジット マネージャ API 関数
通常通りの方法でコンジットを登録します。まず、CmInstallCreator() または CmInstallSystemCreator() を呼び出します。それから残りを同じ作成者 ID で呼び出します。	ユーザ: CmInstallCreator() CmSetCreatorName() CmSetCreatorPriority() CmSetCreatorTitle() CmSetCreatorDirectory() CmSetCreatorFile() CmSetCreatorRemote() システム: CmInstallSystemCreator() CmSetSystemCreatorName() CmSetSystemCreatorPriority() CmSetSystemCreatorTitle() CmSetSystemCreatorDirectory() CmSetSystemCreatorFile() CmSetSystemCreatorRemote()

これらの関数についての更なる情報は、C/C++ Sync Suite Reference の 第 11 章 「コンジット マネージャ API」 を参照してください。

フォルダでのコンジットの登録 ^TOP^

ここでは、C API-ベース同期コンジットをシステムまたは現在の Windows ユーザの Conduits フォルダに置くことによって C API-ベース同期コンジットを登録するために、コンジット マネージャ API をどのように使用するのかについて説明します。予備知識とここで使用されるテクノロジの説明は、Introduction to Conduit Development の 第 6 章 「コンジットと通知機能のHotSync マネージャへの登録」 を参照してください。

NOTE

NTFS ファイル システムでは、コンジットを含むいずれかのファイルをシステム-レベルのエリアに移動させるには、ユーザは管理者権限を持っている必要があります。あなたはまず CmIsCurrentUserAdmin() を呼び出してユーザが必要のある権限を持っているかどうかを決定します。

フォルダ-登録コンジットは、値が eRegistrationInfo である入力 infoType パラメータに応答するために GetConduitInfo() エントリ ポイントの中のロジックを実装しなければなりません。このことについての更なる情報は、GetConduitInfo() を参照してください。

インストール時に現在の Windows ユーザの Conduits フォルダを見つけるために、FmGetCurrentUserConduitFolder()|C/C++ Sync Suite Companion601/11 を呼び出します; システムの Conduits フォルダを見つけるためには FmGetSystemConduitFolder()|C/C++ Sync Suite Companion601/11 を呼び出します。これらの関数は常にパスを返します。なぜなら、Conduits フォルダが存在しない場合、これらの関数はフォルダを作成するからです。

Conduits フォルダのパスを取得した後、あなたの同期コンジット DLL をそのフォルダにコピーします。コンジット マネージャは、次に HotSync マネージャがコンジットのリストについてコンジット マネージャに問い合わせをするときに、フォルダにあるあなたのコンジットを見つけます。

TIPS

たいていのインストーラはアンインストール中にファイルがもともとインストールされた場所からファイルを削除するように設計されます。それゆえ、少なくともあなたのインストーラに関する限りあなたのフォルダ-登録コンジットを同じ場所に置き続けるために、このテクニックをあなたのインストーラに実装してください。

1. あなたのコンジットを Disabled サブフォルダにインストールします。
2. それを Conduits フォルダに移動させるために FmEnableCurrentUserConduitByPath()|C/C++ Sync Suite Companion601/11 または FmEnableSystemConduitByPath()|C/C++ Sync Suite Companion601/11 を呼び出します。あなたのインストーラはあなたのコンジットはまだ Disabled サブフォルダにあると考えます。
3. アンインストール時に、まずあなたのコンジットを Disabled サブフォルダに戻すために FmDisableCurrentUserConduitByPath()|C/C++ Sync Suite Companion601/11 または FmDisableSystemConduitByPath()|C/C++ Sync Suite Companion601/11 を呼び出します。この時点で、あなたのインストーラはあなたのコンジットをそれがもともとインストールされた場所から削除することができます。

1. このテクニックは、パワー ユーザがインストール後にあなたのコンジットを Disabled サブフォルダに移動させるようなケースもカバーします。アンインストール時に、コンジットを使用不能にするための呼び出しは失敗しますが、コンジットはもともとインストールされた場所にあるのであなたのインストーラはそれでもコンジットを削除することができます。

---

互換性についての注意

フォルダ-ベース コンジットの登録はコンジット マネージャのバージョン 3 以降（HotSync マネージャのバージョン 6.0 以降）でサポートされます。あなたがそれより前のバージョンを持つシステムにコンジットをインストールするつもりがある場合、あなたは 通常通りの方法でのコンジットの登録 で説明されているようにコンジットを登録しなくてはなりません。

表 9.4 は、現在の Windows ユーザとシステムの両方のためにフォルダでコンジットを登録するための関数を要約しています。

表 9.4 フォルダでのコンジットの登録と登録解除

タスク	コンジット マネージャ API 関数
Conduits フォルダと Disalbed サブフォルダを見つけます。	ユーザ: FmGetCurrentUserConduitFolder()|C/C++ Sync Suite Companion601/11 FmGetCurrentUserDisabledConduitFolder()|C/C++ Sync Suite Companion601/11 システム: FmGetSystemConduitFolder()|C/C++ Sync Suite Companion601/11 FmGetSystemDisabledConduitFolder()|C/C++ Sync Suite Companion601/11
使用不能/使用可能にされているコンジットを使用可能/使用不能にします。コンジットのパスとファイル名（またはファイル名のみ）を渡します。"	ユーザ: FmEnableCurrentUserConduitByPath()|C/C++ Sync Suite Companion601/11 FmDisableCurrentUserConduitByPath()|C/C++ Sync Suite Companion601/11 システム: FmEnableSystemConduitByPath()|C/C++ Sync Suite Companion601/11 FmDisableSystemConduitByPath()|C/C++ Sync Suite Companion601/11
使用可能にされているコンジットを使用不能にします。フォルダ-登録コンジットのインデックスを渡します。	ユーザ: FmDisableCurrentUserConduitByIndex()|C/C++ Sync Suite Companion601/11 システム: FmDisableSystemConduitByIndex()|C/C++ Sync Suite Companion601/11

コンジットの登録解除 ^TOP^

あなたがあなたのコンジットをアンインストールするとき、あなたはコンジットの登録を解除して HotSync マネージャがもう存在していないあなたのコンジット DLL を呼び出そうとしないようにしなければなりません。以下の小節では、通常通りの方法で登録されたコンジットとフォルダ-登録コンジットをどのように登録解除するのかについて説明します。

通常通りの方法で登録されたコンジット

現在の Windows ユーザのために通常通りの方法で登録された同期コンジットの登録を解除するには、CmRemoveConduitByCreatorID()|C/C++ Sync Suite Companion601/11 を呼び出して登録を解除するコンジットの作成者 ID を渡します。システムのために同様に登録された同期コンジットの登録を解除するには、CmRemoveSystemConduitByCreatorID()|C/C++ Sync Suite Companion601/11 を呼び出します。これらの関数はコンジットのコンフィグレーション エントリをすべて削除しますが、コンジット DLL を削除することはしません。

表 9.5 は、現在の Windows ユーザとシステムの両方のために通常通りの方法で登録されたコンジットを登録解除するための関数を要約しています。

表 9.5 通常通りの方法で登録されたコンジットの登録解除

タスク	コンジット マネージャ API
作成者 ID でコンジットを登録解除します。	ユーザ: CmRemoveConduitByCreatorID() システム: CmRemoveSystemConduitByCreatorID()
インデックスでコンジットを登録解除します。インデックスの上限を取得するには CmGetConduitCount() または CmGetSystemConduitCount() を呼び出します。	ユーザ: CmRemoveConduitByIndex() システム: CmRemoveSystemConduitByIndex()

フォルダ-登録コンジット

あなたはフォルダ-登録コンジットを以下の 3 つの方法で登録解除することができます:

• あなたのコンジット DLL を Conduits フォルダから削除します。Conduits フォルダを見つけるには、FmGetCurrentUserConduitFolder() または FmGetSystemConduitFolder() を呼び出します。
• CmRemoveConduitByCreatorID() または CmRemoveSystemConduitByCreatorID() を呼び出して、削除するコンジットの作成者 ID を渡します。コンジット マネージャはコンジットを Conduits フォルダから Disabled サブフォルダに移動させます。
• CmRemoveConduitByIndex() または CmRemoveSystemConduitByIndex() を呼び出して、削除するコンジットのインデックスを渡します。コンジット マネージャはコンジットを Conduits フォルダから Disabled サブフォルダに移動させます。
• FmDisableCurrentUserConduitByPath() または FmDisableSystemConduitByPath() を呼び出して削除するコンジットのパスまたはファイル名を渡します。または FmDisableCurrentUserConduitByIndex() または FmDisableSystemConduitByIndex() を呼び出して削除するコンジットのインデックスを渡します。コンジット マネージャはコンジットを Conduits フォルダから Disabled サブフォルダに移動させます。

コンジットを Conduits フォルダから Disabled サブフォルダに移動させることは効率的にコンジットを登録解除し、それにより HotSync マネージャはそのコンジットを呼び出そうとしなくなります。再び Disabled サブフォルダにあるコンジットを登録または使用可能にするには、FmEnableCurrentUserConduitByPath() またはFmEnableSystemConduitByPath() を呼び出すか他の何らかの手段でそのコンジットを Conduits フォルダに戻します。

NOTE

NTFS ファイル システムでは、コンジットを含むいずれかのファイルをシステム-レベルのエリアに移動させるには、ユーザは管理者権限を持っている必要があります。あなたはまず CmIsCurrentUserAdmin() を呼び出してユーザが必要のある権限を持っているかどうかを決定することができます。

ファイルをそのファイルがインストールされたフォルダからアンインストールしなければならないインストーラをどのように作成するかについての Tips は、「フォルダでのコンジットの登録」 を参照してください。

表 9.4 は、現在の Windows ユーザとシステムの両方のためにフォルダでコンジットを登録するための関数を要約しています。

コンジット衝突の解決 ^TOP^

Introduction to Conduit Development の コンジット衝突の解決 で説明されているように、2 つ以上のフォルダ-登録コンジットが同じ作成者 ID を持つ可能性があり、1 つ以上のフォルダ-登録コンジットが通常通りの方法で登録されたコンジットと同じ作成者 ID を持つ可能性があります。あなたはあなたのコンジットを登録する前に、同じ作成者 ID を持つコンジットがすでに登録されていないか確認して潜在的な衝突を避けるようにすべきです。

あなたが現在の Windows ユーザのためだけにあなたのコンジットを登録しようとしている場合、CmGetCreatorIDList() を呼び出してユーザのために登録されたコンジットのすべての作成者 ID のリストを取得します; そうでない場合は、CmGetSystemCreatorIDList() を呼び出します。あなたの作成者 ID がすでにリストにある場合、ユーザにあなたのコンジットを登録するかそれともすでにインストールされているコンジットを残すか選択するように促します。ユーザがあなたのコンジットをインストールすることを選択した場合、あなたはあなたのコンジットを登録する前にすでにあるコンジットを登録解除しなければなりません。

あなたがあなたのコンジットを通常通りの方法で登録する場合、同じ作成者 ID を持つ他のコンジットがすでい登録されていると登録を行うコンジット マネージャ呼び出しは ERR_CREATORID_ALREADY_IN_USE エラーを返し、失敗します。これにより、コンジット マネージャは通常通りに登録されるコンジットが衝突するのを防ぎます。しかしながら、あなたがあなたのコンジットを Conduits フォルダにコピーすることによって登録しようとする場合、衝突を防ぐためにあなたがとれる方法はただ 1 つ、すで説明したようにあなたの作成者 ID が登録されたコンジットのリストにあるかどうかをチェックすることです。

コンジット マネージャはもう 1 つの方法で衝突があるということをあなたに警告することができます。あなたがすでに他のコンジットと衝突している登録されたコンジットのためのコンフィグレーション エントリを取得またはセットしようとする関数を呼び出すときはいつでも、ERR_AMBIGUOUS_CREATORID エラーを返して失敗します。このエラーを返す可能性がある関数は 表 9.18 でリストされています。

登録されたコンジット情報へのアクセス ^TOP^

コンジット マネージャは、すべての登録された同期コンジット - 通常通りの方法で登録されたかフォルダ-登録かに関係なく - についての情報を取得するための関数を提供します。これらの API は、インストール コンジットとバックアップ コンジットにはアクセスしません。表 9.6 は、あなたがコンジット マネージャ API で取得またはセットすることができる情報の種類 - ユーザのために登録されたコンジットとシステムのために登録されたコンジットの両方に対して - について説明しています。

いくつかの API は、「別個のコンフィグレーション エントリを作成する」 で説明した通常通りの方法でコンジットを登録する場合にあなたがコンジットのコンフィグレーション エントリの値をセットするのと同様の方法で、あなたがセットすることを可能にします。

NOTE

あなたは通常通りの方法で登録されたコンジットに対してのみコンジット コンフィグレーション エントリをセットすることができます。あなたがフォルダ-登録コンジットのためにエントリを作成またはセットする関数を呼び出した場合、その関数は ERR_CONDUIT_READ_ONLY エラーを返して失敗します。

表 9.6 登録されたコンジットの情報へのアクセス

タスク	コンジット マネージャ API 関数
すべてのコンジットの数を取得します。インデックスの上限として他のインデックスでの呼び出しで使用します。	ユーザ: CmGetConduitCount() システム: CmGetSystemConduitCount()
すべてのコンジットの作成者 ID のリストを取得します。	ユーザ: CmGetCreatorIDList() システム: CmGetSystemCreatorIDList()
インデックスでコンジットの作成者 ID を取得します。	ユーザ: CmGetConduitCreatorID() システム: CmGetSystemConduitCreatorID()
インデックスで登録情報を取得します。CmConduitType2 構造体を戻してきます。	ユーザ: CmGetConduitByIndex() システム: CmGetSystemConduitByIndex()
インデックスでコンジットが通常通りに登録されたのかそれともフォルダ-ベースで登録されたのか、HotSync マネージャはそれを読み込めるかどうかを決定します。CmDiscoveryInfoType 構造体を戻してきます。	ユーザ: CmGetDiscoveryInfoByIndex() システム: CmGetSystemDiscoveryInfoByIndex()
作成者 ID でコンジットの登録情報を取得します。CmConduitType 構造体を返してきます。	ユーザ: CmGetConduitByCreator() システム: CmGetSystemConduitByCreator()
作成者 ID で標準のコンジット コンフィグレーション エントリを取得します。CmConduitType2 構造体で定義されているのと同じエントリがあります。	ユーザ: CmGetCreatorName() CmGetCreatorPriority() CmGetCreatorTitle() CmGetCreatorDirectory() CmGetCreatorFile() CmGetCreatorRemote() システム: CmGetSystemCreatorName() CmGetSystemCreatorPriority() CmGetSystemCreatorTitle() CmGetSystemCreatorDirectory() CmGetSystemCreatorFile() CmGetSystemCreatorRemote()
作成者 ID で標準のコンジット コンフィグレーション エントリをセットします。CmConduitType2 構造体で定義されているのと同じエントリがあります。	ユーザ: CmSetCreatorName() CmSetCreatorPriority() CmSetCreatorTitle() CmSetCreatorDirectory() CmSetCreatorFile() CmSetCreatorRemote() システム: CmSetSystemCreatorName() CmSetSystemCreatorPriority() CmSetSystemCreatorTitle() CmSetSystemCreatorDirectory() CmSetSystemCreatorFile() CmSetSystemCreatorRemote()

開発者-定義コンジット コンフィグレーション エントリへのアクセス ^TOP^

コンジット コンフィグレーション エントリ は拡張可能です。あなたは、ユーザのために登録されるコンジットごととシステムのために登録されるコンジットごとに情報を保存するためにあなた自身のエントリを定義することができます。表 9.7 は、あなたがコンジット マネージャ API で取得、セットすることができる情報の種類について説明しています。あなたのインストーラ、コンジット、デスクトップ アプリケーションはあなたのコンジット特有のコンジット コンフィグレーション エントリの中に情報を保存することができます。

あなたがコンジットを登録解除するとき、コンジット マネージャは、あなたが定義したものを含むすべてのコンジットのコンフィグレーション エントリを削除します。コンジット マネージャは他のいかなる状況でもあなたのエントリにアクセスすることはありません。

NOTE

あなたは通常通りの方法で登録されるコンジットでのみあなた自身のコンジット コンフィグレーション エントリを定義することができます。あなたがフォルダ-登録コンジットのためのエントリを作成、セットする関数を呼び出す場合、その関数は ERR_CONDUIT_READ_ONLY エラーを返し失敗します。

表 9.7 開発者-定義コンジット コンフィグレーション エントリへのアクセス

タスク	コンジット マネージャ API 関数
作成者 ID でコンジットためのエントリの DWORD 値を取得またはセットします。セットする関数は、エントリがまだ存在していない場合、エントリを作成します。	ユーザ: CmGetCreatorValueDword() CmSetCreatorValueDword() システム: CmGetSystemCreatorValueDword() CmSetSystemCreatorValueDword()
作成者 ID でコンジットのためのエントリの文字列値を取得またはセットします。セットする関数は、エントリがまだ存在していない場合、エントリを作成します。	ユーザ: CmGetCreatorValueString() CmSetCreatorValueString() システム: CmGetSystemCreatorValueString() CmSetSystemCreatorValueString()

フォルダ-登録コンジット情報の取得 ^TOP^

ここでは、フォルダ-登録コンジットのみについての情報を取得するためにコンジット マネージャ API が提供する関数について説明します。フォルダ-登録コンジットと通常通りの方法で登録されたコンジットの両方についての情報にアクセスする関数については、「登録されたコンジット情報へのアクセス」 を参照してください。

表 9.8 は、フォルダで登録されたユーザのためのコンジットとシステムのためのコンジットの両方のために、あなたがコンジット マネージャ API で取得することができる情報の種類について説明しています。

NOTE

これらの関数は情報を取得するだけです。あなたはコンジット マネージャ API を使ってフォルダ-登録コンジットの登録情報をセットすることはできません。

表 9.8 フォルダ-登録コンジット情報の取得

タスク	コンジット マネージャ API 関数
すべてのフォルダ-登録コンジットの数を取得します。インデックスの上限として他のインデックスで呼び出される関数呼び出しの中で使用します。	ユーザ: FmGetCurrentUserConduitCount() システム: FmGetSystemConduitCount()
インデックスで登録情報を取得します。CmConduitType2 構造体を戻してきます。	ユーザ: FmGetCurrentUserConduitByIndex() システム: FmGetSystemConduitByIndex()

バックアップ コンジットの登録と登録解除 ^TOP^

HotSync マネージャは、1 度の HotSync 実施の間に 1 つだけバックアップ コンジットを実行します。（あなたがユーザのために 1 つ、システムのために 1 つ登録することができますが、HotSync マネージャはユーザのために 1 つ登録されている場合はそれだけを呼び出します; さもなければシステムのために登録されているバックアップ コンジットを呼び出します。Introduction to Conduit Development の 「ユーザのために登録されるコンジットと通知機能、システムのために登録されるコンジットと通知機能」 を参照してください。）それゆえ、表 9.9 が示すように、コンジット マネージャは、ユーザとシステムのためのバックアップ コンジットを登録/登録解除するためと、それらのファイル名を取得するための関数のみを提供します。

---

WARNING! あなたがバックアップ コンジットを登録解除する場合、それを置き換えるために他のバックアップ コンジットを登録してください; さもないとユーザのデータのいくつかは次の HotSync 実施の間にバックアップされません。

---

表 9.9 バックアップ コンジットの登録と登録解除

タスク	コンジット マネージャ API 関数
ファイル名でバックアップ コンジットを登録します。登録解除するには、異なるバックアップ コンジットのファイル名を渡します。"	ユーザ: CmSetBackupConduit() システム: CmSetSystemBackupConduit()
登録されたバックアップ コンジットのファイル名を取得します。	ユーザ: CmGetBackupConduit() システム: CmGetSystemBackupConduit()

COM ポートのコンフィグレーション ^TOP^

コンジット マネージャは、表 9.10 が示す、HotSync マネージャが直接（ローカル）接続とモデム接続のために使用する COM ポートをコンフィグレーションするための関数を提供します。システム-レベル COM ポート設定は無いことに注意してください; COM ポート設定は現在の Windows ユーザのためだけです。各 Window ユーザが最初に HotSync を実行するとき、コンジット マネージャは各ユーザのためにデフォルトの COM ポート値をセットします。あなたは、望むならば、これらの関数を使ってこれらのデフォルト値を読み込む、変更することができます。

表 9.10 COM ポートのコンフィグレーション

タスク	コンジット マネージャ API 関数
指定されたタイプの接続のために HotSync マネージャが使用する COM ポートの名前を取得します。	ユーザ: CmGetComPort() システム: N/A
指定されたタイプの接続のために HotSync マネージャが使用する COM ポートの名前をセットします。	ユーザ: CmSetComPort() システム: N/A

コンジット マネージャのユーティリティ関数の使用 ^TOP^

コンジット マネージャ API は、表 9.11 で要約されているいくつかのユーティリティ関数を含みます。

表 9.11 ユーティリティ関数の使用

タスク	コンジット マネージャ API 関数
作成者 ID を文字列/ DWORD から DWORD /文字列へ変換します。多くのコンジット マネージャ関数は文字列としてではなく DWORD として作成者 ID をとります。	ユーザ: CmConvertCreatorIDToString() CmConvertStringToCreatorID() システム: N/A
コンジット マネージャ API のバージョン番号を取得します。どのコンジット マネージャのバージョンで関数が使用可能なのか知るには各関数の「互換性」部分を参照してください。"	ユーザ: CmGetLibVersion() システム: N/A
現在の Windows ユーザが管理者権限を持っているかどうかを決定します。この関数を呼び出してシステム-レベル コンジット マネージャ呼び出しが成功するかどうかを決定します。"	ユーザ: CmIsCurrentUserAdmin() システム: N/A

コンジット マネージャ関数の要約 ^TOP^

• コンジット マネージャ関数
  • HotSync マネージャの検索とコンフィグレーション
    • CmGetCorePath()
    • CmGetComPort()
    • CmSetComPort()
    • CmGetPCIdentifier()
    • CmGetSystemHotSyncExecPath()
  • 通常通りの方法での同期コンジットの登録/登録解除
    • CmInstallCreator()
    • CmInstallConduitByStruct()
      
    • CmRemoveConduitByIndex()
    • CmRemoveConduitByCreatorID()
      
    • CmInstallConduit()
    • CmInstallSystemCreator()
    • CmInstallSystemConduitByStruct()
      
    • CmRemoveSystemConduitByIndex()
    • CmRemoveSystemConduitByCreatorID()
  • フォルダ-登録コンジットの登録/登録解除
  • 登録されたコンジット情報の読み込み
    • CmGetConduitCount()
    • CmGetCreatorIDList()
    • CmGetConduitCreatorID()
    • CmGetConduitByCreator()
    • CmGetConduitByIndex()
    • CmGetDiscoveryInfoByIndex()
    • CmGetSystemConduitCount()
    • CmGetSystemCreatorIDList()
    • CmGetSystemConduitCreatorID()
    • CmGetSystemConduitByCreator()
    • CmGetSystemConduitByIndex()
    • CmGetSystemDiscoveryInfoByIndex()
  • 標準コンジット コンフィグレーション情報へのアクセス
    • CmGetCreatorName()
    • CmSetCreatorName()
    • CmGetCreatorPriority()
    • CmSetCreatorPriority()
    • CmGetCreatorTitle()
    • CmSetCreatorTitle()
    • CmGetCreatorDirectory()
    • CmSetCreatorDirectory()
    • CmGetCreatorFile()
    • CmSetCreatorFile()
    • CmGetCreatorRemote()
    • CmSetCreatorRemote()
    • CmGetSystemCreatorName()
    • CmSetSystemCreatorName()
    • CmGetSystemCreatorPriority()
    • CmSetSystemCreatorPriority()
    • CmGetSystemCreatorTitle()
    • CmSetSystemCreatorTitle()
    • CmGetSystemCreatorDirectory()
    • CmSetSystemCreatorDirectory()
    • CmGetSystemCreatorFile()
    • CmSetSystemCreatorFile()
    • CmGetSystemCreatorRemote()
    • CmSetSystemCreatorRemote()
  • 開発者-定義コンジット コンフィグレーション エントリへのアクセス
    • CmGetCreatorValueDword()
    • CmSetCreatorValueDword()
    • CmGetCreatorValueString()
    • CmSetCreatorValueString()
    • CmGetSystemCreatorValueDword()
    • CmSetSystemCreatorValueDword()
    • CmGetSystemCreatorValueString()
    • CmSetSystemCreatorValueString()
  • フォルダ-登録コンジット情報の取得
    • FmGetCurrentUserConduitCount()
    • FmGetCurrentUserConduitByIndex()
    • FmGetSystemConduitCount()
    • FmGetSystemConduitByIndex()
  • バックアップ コンジットの登録と登録解除
    • CmGetBackupConduit()
    • CmSetBackupConduit()
    • CmGetSystemBackupConduit()
    • CmSetSystemBackupConduit()
  • COM ポートのコンフィグレーション
    • CmGetComPort()
    • CmSetComPort()
  • ユーティリティ関数
    • CmConvertCreatorIDToString()
    • CmConvertStringToCreatorID()
    • CmGetLibVersion()
    • CmIsCurrentUserAdmin()

インストール援助機能 API の使用 ^TOP^

インストール援助機能は、あなたのデスクトップ アプリケーションやインストーラが HotSync 実施中にハンドヘルドにインストールするファイルをキューに追加することを可能にします。この節では、インストール援助機能がどのように機能するのか、インストール援助機能を使ってインストーラが実行する最も一般的なタスクについて説明します:

• インストール援助機能の機能
• データベースを主記憶装置にインストールするためにキューに追加する
• ファイルを HotSync 交換を経由して主記憶装置にインストールするためにキューに追加する
• ファイルを拡張カードにインストールするためにキューに追加する
• HotSync ユーザ情報の取得
• 登録されたインストール コンジット情報へのアクセス
• インストール援助機能のユーティリティ関数の使用
• インストール援助機能関数の要約

インストール援助機能関数についての詳細は、C/C++ Sync Suite Reference の 第 15 章 「インストール援助機能 API」 を参照してください。

インストール援助機能の機能 ^TOP^

インストール援助機能は実際にはデスクトップとハンドヘルド間でデータを移動さません; 単純にデスクトップ上にあるキュー ディレクトリに移動させて、HotSync マネージャにインストールするものがあることを知らせます。HotSync 実施中に HotSync マネージャによって呼び出される登録された インストール コンジット が実際にキューにあるファイルをハンドヘルドの主記憶装置または拡張カードに転送します。HotSync マネージャはいくつかのインストール コンジットと共に出荷されるため、あなたはあなた自身のインストール コンジットを実装する必要はないかもしれません。Introduction to Conduit Development の インストール コンジットの実行 では、それらのインストール コンジットとそれらがインストールできるファイルのタイプをリストにしています。

インストール援助機能 API は、あなたのインストーラ、デスクトップ アプリケーション、コンジットがファイルをインストール キューに追加するために呼び出すことができる 2 つの関数を提供します: 主記憶装置にファイルをインストールするための PltInstallFile() と拡張カードにファイルをインストールするための PlmSlotInstallFile() です。あなたがこれらの関数の 1 つを呼び出すとき、あなたは HotSync ユーザとあなたがインストールしたいファイルのパスを指定します。あなたがこれらの関数の 1 つを呼び出した時点で、インストール援助機能は以下のタスクを実行します:

1. インストール援助機能は、表 9.12 が示すように、あなたが指定するファイルの拡張子とあなたが呼び出すインストール関数に基づいて実行するデフォルトのインストール コンジットを選択します。各インストール コンジットは、ある特定のファイル拡張子を扱うように登録されます。

表 9.12 ファイル拡張子に基づくインストール援助機能のインストールコンジットとインストール先の選択

ファイル拡張子	呼び出された関数	インストール援助機能によって使用されるインストール コンジット	ハンドヘルド上のインストール先
RPC, PDB, SDB, SSD, PQA	PltInstallFile()	インストール	主記憶装置
PNC, SCP	PltInstallFile()	インストール サービス テンプレート [1]	主記憶装置
*.*	PltInstallFile()	HotSync 交換	主記憶装置
*.*	PlmSlotInstallFile()	カードへのインストール	指定された拡張スロットのカード

• [1]Palm OS Cobalt より前の Palm OS のバージョンを実行しているハンドヘルドに対してのみ機能します。

インストール援助機能は、ファイル拡張子が前述の Palm OS ファイル拡張子には一致しないがハンドヘルド アプリケーションがハンドヘルド上の交換マネージャに登録した拡張子に一致する場合、HotSync 交換コンジットを選択します。Introduction to Conduit Development の 第 3 章 「HotSync 交換の使用」 を参照してください。

NOTE

あなたが PltInstallFile() でインストールするファイルはファイル拡張子を持たなくてはなりません。さもないと、インストール関数は失敗し、ERR_IA_INVALID_FILE_TYPE を返します。なぜなら、インストール援助機能はどのインストール コンジットを使用するか決定できないからです。

2. インストール援助機能はファイルを、ステップ 1 で選択されたインストール コンジットに関連付けられているインストール ディレクトリにコピーします。

3. インストール援助機能はコンフィグレーション エントリの中で指定された HotSync ユーザのためにインストール フラグを作成します。

4. インストール援助機能はインストール フラグの値を、指定されたタイプのハンドヘルド ファイルに対して登録されているインストール コンジットに関連付けられているビット マスクの値にセットします。HotSync マネージャはこのインストール フラグを、次に指定されたユーザのためにインストール コンジットを実行するときに、読み込みます。このフラグは HotSync マネージャに一致するマスク値を持つインストール コンジットを実行しなければならないということを知らせます。

あなたが、HotSync マネージャが再びインストール コンジットを実行する前に、再びインストール関数の 1 つを呼び出す場合、これらのステップが繰り返されます - インストール援助機能がその後に続く各呼び出しで存在しているインストール フラグ値の論理輪をとる以外は。例えば、最初の呼び出しがビット マスク値 1 のインストール コンジットを選択し、2 番目の呼び出しはビット マスク値 4 のインストール コンジットを選択する場合、次にインストール コンジットが実行されるときにこのインストール フラグの値は 5 になります。それゆえ、HotSync マネージャは 2 つのインストール コンジットを実行します - 1 つは 1 のビット マスクで登録されたもので、もう 1 つは 4 のビット マスクで登録されたものです。

各インストール コンジットは、インストールが成功または不成功のときに、そのマスク値を HotSync ユーザのインストール フラグから削除するかどうかを決定します。不成功の場合、インストール コンジットはマスク値をそのままにしておきます; 成功の場合、削除します。HotSync 交換インストール コンジットはマスクに依存せずに実行されます。なぜなら、ハンドヘルドからデスクトップに転送される必要のあるファイルがあるかもしれないからです。

HotSync マネージャは 2 度インストール コンジットを呼び出します: すべての同期コンジットを実行する前と後です。インストール関数の 1 つが HotSync の外側で呼び出される場合、インストール コンジットはキューに追加されているファイルを次の HotSync 実施時にインストールします。HotSync の最中にコンジットがインストール関数の 1 つを呼び出す場合、インストール コンジットはキューに追加されているファイルを現在の HotSync 実施の最後にインストールします。

インストール援助機能は、インスールするためのキューに追加されるファイルの管理を助けるためと拡張スロットの情報を取得するためのその他の関数を提供します。これらの関数はこの節の残りで説明され、詳細は C/C++ Sync Suite Reference の 第 15 章 「インストール援助機能 API」 を参照してください。

インストール ディレクトリ用語

表 9.13 は、次の HotSync の最中にデフォルトのインストール コンジットによってインストールされるためにキューに追加されるファイルをインストール援助機能がどのデスクトップ ディレクトにコピーするかを定義しています。図 9.1 は現在の Windows ユーザのためのこれらのディレクトリの相対的な位置関係を示しています。

表 9.13 インストール援助機能に関連付けられているデスクトップ ディレクトリ

ディレクトリ名	説明
Windows ユーザのディレクトリ	現在の Windows ユーザのために、このディレクトリはすべての HotSync マネージャ ファイルとすべての HotSync ユーザのためのユーザ ディレクトリを（デフォルトで）保持します。このパスを取得するには、CmGetCorePath() を呼び出します。
HotSync ユーザのディレクトリ	各 HotSync ユーザのために、このディレクトリはハンドヘルドとスロットにインストールするためのディレクトリを保持します。同様に、各 デフォルトのコンジットのためのデータ ディレクトリを保持します。
ハンドヘルド-インストール ディレクトリ	各 HotSync のために、このディレクトリは次のインストール コンジット実行時に関連付けされたインストール コンジットによってハンドヘルドのメイン メモリにインストールされるようにキューに追加される Palm OS アプリケーションとデータベースを保持します。このディレクトリは、複数のインストール コンジットそれぞれのためのディレクトリである可能性があります。
スロット ディレクトリ	各 HotSync ユーザのために、このディレクトリはユーザのハンドヘルドの各スロットのためのサブディレクトリ（スロット-インストール ディレクトリ）を保持します。このディレクトリとそのサブディレクトリはファイルを拡張カードにインストールするインストール コンジットに関連付けされます。
スロット-インストール ディレクトリ	HotSync ユーザの各ハンドヘルドの各スロットのために、このディレクトリは次のインストール コンジット実行時に関連付けされたスロットのカードにインストールされるようにキューに追加されるファイルを保持します。
HotSync 交換ディレクトリ	各 HotSync ユーザのために、Exchange ディレクトリは To と From サブディレクトリを保持します。To ディレクトリは HotSync 交換経由でハンドヘルドのメイン メモリにインストールされるファイルを保持します。From ディレクトリはハンドヘルドからデスクトップに送られたファイルを保持します。

図 9.1 デフォルトのインストール コンジットがファイルをキューに追加するためのディレクトリ

ファイル タイプの指定

PltGetFileConduit(), PltGetFileInfo(), PltGetFileName() 関数は呼び出し元が pExtension パラメータにファイル名を渡すことを要求します。このパラメータはフォーマット "*.extension" の文字列を要求します - 例えば、以下の拡張子は標準 Palm OS データベース イメージ ファイルの拡張子です:

• "*.prc" - アプリケーション
• "*.pdb" - クラシック データベースまたは拡張データベース
• "*.sdb" - スキーマ データベース
• "*.ssd" - セキュリティ スキーマ データベース
• "*.pqa" - クエリ アプリケーション
• "*.pnc" - ネットワーク コンフィグレーション ファイル
• "*.scp" - ネットワーク スクリプト ファイル

あなたがあるインストール コンジットを完成させた場合、あなたがあなたのインストール コンジットを登録するときあなた自身のファイル拡張子登録することができます。「インストール コンジット マネージャ API の使用」 を参照してください。

ファイル拡張子を戻してくるそれらの関数 - 例えば、PltGetFileTypeExtension() - は、拡張子を同じフォーマットで戻してきます。

ファイル フィルタを戻してくる関数 - PltGetInstallFileFilter(), PltGetInstallFileFilterForUser() - は、Windows 標準フォーマットで連結されたファイル フィルタ タイプを指定する文字列を保持するバッファでファイル フィルタを戻してきます - 例えば:

　　　"type1 (*.ext1)|*.ext1|type2 (*.ext2)|*.ext2||"

データベースを主記憶装置にインストールするためにキューに追加する ^TOP^

インストール援助機能は、あなたが Palm OS データベース イメージ ファイルを、次に HotSync マネージャがインストール コンジットを実行するときにハンドヘルドの主記憶メモリにインストールするために、キューに追加することを可能にします。この操作を実行するために、HotSync ユーザの名前とファイルのパスを PltInstallFile() 関数に渡します。インストール援助機能は、インストール援助機能の機能 で説明されている通りに残りの作業を実行します。

「Install」という名前のデフォルトのインストール コンジットは、Palm OS データベース イメージ ファイルの拡張子を持つファイルだけを扱います。他のタイプのファイルを主記憶装置にインストールするためのキューに追加するためにはどのようにインストール援助機能を使用するかのかについては、ファイルを HotSync 交換を経由して主記憶装置にインストールするためにキューに追加する を参照してください。

コード 9.3 は、アプリケーション（MyApp.prc）をハンドヘルドの主記憶装置にインストールするためのキューに追加する PltInstallFile() の使用例です。

コード 9.3 主記憶装置にインストールするためにファイルをキューに追加する例

int QueueFileToInstallInPrimary () {

int iRetval = 0;
TCHAR pUser[45];
short psUserBufSize = sizeof (pUser);
unsigned int iIndex = 0;

   // Get the HotSync user's name. This example just gets the 
   // first user in the user data store. 
   psUserBufSize = sizeof (pUser);
   memset (pUser, 0, psUserBufSize);
   iRetval = PltGetUser (iIndex, pUser, &psUserBufSize);

   if (iRetval > 0)
   {
      // Queue file for installation for the first user.
      iRetval = PltInstallFile (pUser, "C:\MyApp.prc");
   }
   return iRetVal;
}

表 9.14 は主記憶装置にインストールするためにファイルをキューに追加する関数を要約しています。

表 9.14 主記憶装置にインストールするためにデータベースをキューに追加する

タスク	インストール援助機能 API 関数
name で指定された HotSync ユーザのために、主記憶装置にインストールするファイルをキューに追加します。ファイルは登録されたインストール コンジットによってサポートされるタイプでなければなりません。	PltInstallFile()
name で指定された HotSync ユーザのために、キューに追加されたファイルをキュー フォルダから削除します。	PltRemoveInstallFile()
拡張カードにインストールするためのキューに追加されたファイルを主記憶装置にインストールするためのキューに移動させます。user ID で HotSync ユーザを指定します。	PlmMoveInstallFileToHandheld()
主記憶装置にインストールするためのキューに追加されているファイルの数、名前、サイズを取得します。name で HotSync ユーザを指定します。	PltGetFileCount() PltGetFileInfo() PltGetFileName()
ファイルをハンドヘルドの主記憶装置にインストールするための登録されたインストール コンジットによってサポートされるすべてのファイル タイプの数と拡張子を取得します。	PltGetFileTypeExtension() PltGetFileTypesCount()

ファイルを HotSync 交換を経由して主記憶装置にインストールするためにキューに追加する ^TOP^

主記憶装置にインストールするファイルをキューに追加することは、Palm OS データベースのイメージ ファイルをキューに追加するのと似ています。どのように主記憶装置にインストールする Palm OS データベースをキューに追加するかは、「データベースを主記憶装置にインストールするためにキューに追加する」 を参照してください。あなたが Palm OS データベース イメージ ファイルではないファイルを主記憶装置にインストールするためにキューに追加するとき、インストール援助機能は HotSync 交換 インストール コンジットを使用します。この機能の主な違いは以下の通りです:

• HotSync マネージャのバージョン 6.0 以降だけが HotSync 交換インストール コンジットを含みます。Palm OS Cobalt だけが、ハンドヘルド上の交換マネージャによって使用される必須の HotSync 交換マネージャ ライブラリを持ちます。
• インストール援助機能が使用するデフォルトのインストール コンジットは「HotSync 交換」と呼ばれます。これは、ハンドヘルド アプリケーションが交換マネージャに登録したファイル タイプだけを扱うために登録されています。
• HotSync マネージャは、各 HotSync 実行の開始時に HotSync 交換マネージャ ライブラリ（またはその中の必要なもの）から情報を取得して、それを対応するユーザのためにデスクトップ上のユーザ データ保存場所に保存します。しかしながら、ある HotSync 実行からある HotSync 実行の間にユーザはハンドヘルドを変更または更新する可能性があります - 例えば、ユーザはある特定のファイル拡張子のために交換マネージャに登録するアプリケーションを追加または削除する可能性があります。次の HotSync 実行時には、すでに削除されてしまったアプリケーションに対応付けされた拡張子を持つファイルがキューに追加されていても、HotSync 交換インストール コンジットはそれらを扱うことはできません。そのため、それらはインストールされません。

HotSync 交換についての予備知識は、Introduction to Conduit Development の 第 3 章 「HotSync 交換の使用」 を参照してください。

ファイルを拡張カードにインストールするためにキューに追加する ^TOP^

ファイルを拡張カードにインストールするためにキューに追加することは、ファイルを主記憶装置にインストールするためにキューに追加することに似ています。ですから、「データベースを主記憶装置にインストールするためにキューに追加する」 を参照してください。主な違いは:

• インストール援助機能 API のバージョン 4.0 以降だけが拡張カードをサポートします。
• ファイルをカードにインストールするには PlmSlotInstallFile() を呼び出します。
• 拡張カードのためのデフォルトのインストール コンジットは「カードへのインストール」と呼ばれ、すべてのファイル拡張子を扱うために登録されます。
• HotSync マネージャは、各 HotSync 実施の開始時にハンドヘルドの拡張スロット（またはそれらに必要なもの）についての情報を取得して、それをデスクトップ上のユーザ情報保存場所の中の対応するユーザのために保存します。しかしながら、HotSync 実施と次の HotSync 実施の間に、ユーザはハンドヘルドを変更または更新する可能性があります - 例えば、ユーザはハンドヘルドをより多くのスロットを持つようにアップグレードする、または、まったくスロットを持たないように切り替えることができます。次の HotSync 実施時に、HotSync マネージャはユーザに新しい HotSync ユーザ名を作成するか、現在の Windows ユーザとして以前に HotSync を実行した HotSync ユーザのリストから 1 つ選択するように頼みます。ユーザがリストから HotSync ユーザ名を選択した場合、そのユーザのために最後の HotSync 実施の開始時に保存されたスロット情報は不正確なものとなります。
• あなたのアプリケーションまたはインストーラが HotSync 実施の以外の場所からインストール援助機能を呼び出した場合、次回の HotSync 実施時にスロットまたはカードが存在しなければあなたのファイルはインストールされないかもしれないということに注意してください。
• ユーザ データ API を呼び出してユーザのハンドヘルドの拡張スロットとカードについての情報を取得します。あなたはユーザ ID と拡張スロット ID を拡張-関連インストール援助機能 API に渡さなければなりません。「ユーザ データ API の使用」 を参照してください。

Listing 9.4 はファイル（MyPhoto.jpg）を、拡張カードにインストールするために、キューに追加する PlmSlotInstallFile() の使用例です。

コード 9.4 拡張カードにインストールするためにファイルをキューに追加する例

long QueueFileToInstallOnCard () {

long kSuccess = 0;
short sIndex = 0;                // Index of the first HotSync user.
long retval = 0;
DWORD dwUserID = 0;
WORD numSlots = 0;
DWORD *pdwSlotIdList;
char szFile[] = "\\MyPhoto.jpg"; // Name of file to queue for installation.

   // Get the HotSync user's name. This example just gets the first user 
   // in the user data store.
   retval = UmGetUserID (sIndex, &dwUserID);
   if (retval == kSuccess)
   {
      // Get the number of expansion slots.
      retval = UmSlotGetSlotCount (dwUserID, &numSlots);
      if (retval == kSuccess)
      {
         if(numSlots > 0 )
         {
            // Get the slot IDs.
            pdwSlotIdList = new DWORD[numSlots];
            retval = UmSlotGetInfo (dwUserID, pdwSlotIdList, &numSlots);
            if (retval == kSuccess)
            {
               // Queue file to install on card in the first expansion slot.
               retval = PlmSlotInstallFile (dwUserID, *pdwSlotIdList, szFile);
               if (retval == kSuccess)
               {
                  delete[] pdwSlotIdList;
                  return retval;
               }
            }
         }
         else 
         {
            return retval; // User's handheld has no slots.
         }
      }
   } 
}

表 9.15 は、ファイルを拡張カードにインストールするためにキューに追加するインストール援助機能 API 関数を要約しています。

表 9.15 ファイルを拡張カードにインストールするためにキューに追加する

タスク	インストール援助機能 API
ファイルを拡張カードにインストールするためにキューに追加します。ユーザ ID で HotSync ユーザを、スロット ID で拡張スロットを指定します。	PlmSlotInstallFile()
スロットにインストールするためのファイルからキューに追加されたファイルを削除します。ユーザ ID で HotSync ユーザを、スロット ID で拡張スロットを指定します。	PlmSlotRemoveInstallFile()
主記憶装置にインストールするためにキューに追加されたファイルを拡張カードにインストールされるように移動します。ユーザ ID で HotSync ユーザを、スロット ID で拡張スロットを指定します。	PlmMoveInstallFileToSlot()
ある拡張カードにインストールするためにキューに追加されたファイルを他の拡張カードにインストールされるように移動します。ユーザ ID で HotSync ユーザを、スロット ID で拡張スロットを指定します。	PlmSlotMoveInstallFile()
拡張カードにインストールするためにキューに追加されたファイルの数、名前、サイズを取得します。ユーザ ID で HotSync ユーザを、スロット ID で拡張スロットを指定します。	PlmSlotGetFileCount() PlmSlotGetFileInfo()

HotSync ユーザ情報の取得 ^TOP^

インストール援助機能 API は、デスクトップ上のユーザ データ保存場所から HotSync ユーザの情報を取得するための 表 9.16 でリストアップされている関数を提供します。しかしながら、PalmSource 社は変わりにユーザ データ API を使用することを推奨します。詳細は、「ユーザ データ API の使用」 を参照してください。

表 9.16 HotSync ユーザ情報の取得

タスク	インストール援助機能 API 関数
インデックスで HotSync ユーザ名を取得します。PltGetUserCount() を呼び出してインデックスの上限を取得します。	PltGetUser() PltGetUserCount()
HotSync ユーザのフォルダ名を取得します。user name を指定します。	PltGetUserDirectory()
user ID/name を指定することで HotSync ユーザの名前/ ID を取得します。	PlmGetUserIDFromName() PlmGetUserNameFromID()
HotSync ユーザが実際に ユーザ プロファイル であるかどうかを決定します。	PltIsUserProfile()

登録されたインストール コンジット情報へのアクセス ^TOP^

インストール援助機能 API は、HotSync マネージャが現在の Windows ユーザのために実行することができるインストール コンジットについての情報を取得するための関数を提供します。（インストール援助機能 API は、コンジット マネージャの調和させられたインストール コンジットのリストにあるインストール コンジットだけにアクセスします。更なる情報は、Introduction to Conduit Development の 「ユーザのために登録されるコンジットと通知機能と、システムのために登録されるコンジットと通知機能」 を参照してください。登録されたすべてのインストール コンジットについての情報を取得するには、「インストール コンジット マネージャ API の使用」 で説明されているインストール コンジット マネージャを使用します。）これらの API は同期コンジットやバックアップ コンジットにはアクセスしません。表 9.17 は、あなたがインストール援助機能 API で取得またはセットすることができるインストール 根治tt情報の種類について説明しています。

表 9.17 登録されたインストール コンジットの情報へのアクセス

タスク	インストール援助機能 API
登録されたすべてのインストール コンジットの数を取得します。他のインデックスによる呼び出しでインデックスの上限として使用します。	PltGetInstallConduitCount()
index でインストール コンジットの登録情報を取得します。FileInstallType 構造体を返してきます。	PltGetInstallConduitInfo()
unique ID でインストール コンジットの登録情報を取得します。FileInstallType 構造体を返してきます。	PltGetInstallCreatorInfo()
すべての HotSync ユーザまはた指定された HotSync ユーザのためのすべてのインストール コンジットによって登録されたすべてのファイル拡張子からなるファイル フィルタを取得します。あなたが HotSync ユーザを指定した場合、インストール援助機能は指定されたユーザのハンドヘルドの拡張カードは同期したことがあるかどうかを考慮します; カードが以前から存在していた場合にのみ、関連するファイルのフィルタが含まれます。	PltGetInstallFileFilter() PltGetInstallFileFilterForUser()
index でコンジットが通常通りの方法で登録されているのか、それともフォルダ-ベースで登録されているのかと、HotSync マネージャはそれをロードすることができるかどうかを決定します。CmDiscoveryInfoType 構造体を返してきます。	ユーザ: CmGetDiscoveryInfoByIndex() システム: CmGetSystemDiscoveryInfoByIndex()
インストール コンジットは実行されるようにセットされているか、それとも、それのインストール フラグがクリアされているので実行されないのかを決定します。	PltIsInstallMaskSet() PltResetInstallMask()

インストール援助機能のユーティリティ関数の使用 ^TOP^

インストール援助機能 API は 表 9.18 で要約されているいくつかのユーティリティ関数を含みます。

表 9.18 インストール援助機能のユーティリティ関数の使用

タスク	インストール援助機能 API 関数
インストール援助機能 API のバージョン番号を取得します。インストール援助機能 API のどのバージョンでこの関数が使用可能かを調べるには各関数の「互換性」部分を参照してください。	PlmGetLibVersion()
現在の Windows ユーザのための HotSync ユーザのフォルダのパスの 1 つを取得します。各 Windows ユーザは固有のパスを持たなくてはならないので、システム-レベルの値はありません。	PltGetPath()

インストール援助機能関数の要約 ^TOP^

• インストール援助機能関数
  • 主記憶装置にインストールするためにデータベースまたはファイルをキューに追加する
    • PltInstallFile()
    • PltRemoveInstallFile()
    • PlmMoveInstallFileToHandheld()
    • PltGetFileCount()
    • PltGetFileInfo()
    • PltGetFileName()
    • PltGetFileTypeExtension()
    • PltGetFileTypesCount()
  • 拡張カードにインストールするためにファイルをキューに追加する
    • PlmSlotInstallFile()
    • PlmSlotRemoveInstallFile()
    • PlmMoveInstallFileToSlot()
    • PlmSlotMoveInstallFile()
    • PlmSlotGetFileCount()
    • PlmSlotGetFileInfo()
  • HotSync ユーザ情報を取得する
    • PltGetUser()
    • PltGetUserCount()
    • PltGetUserDirectory()
    • PltIsUserProfile()
    • PlmGetUserIDFromName()
    • PlmGetUserNameFromID()
  • 登録されたインストール コンジット情報にアクセスする
    • PltGetInstallConduitCount()
    • PltGetInstallConduitInfo()
    • PltGetInstallCreatorInfo()
    • PltGetInstallFileFilter()
    • PltGetInstallFileFilterForUser()
    • PltIsInstallMaskSet()
    • PltResetInstallMask()
  • ユーティリティ関数
    • PlmGetLibVersion()
    • PltGetPath()

ユーザ データ API の使用 ^TOP^

ユーザ データ API は、デスクトップ上のHotSync ユーザ データ保存場所 の中の情報にアクセスするためのものです。（他の API もいくつか似たような機能を提供しますが、PalmSource はそれらの代わりにユーザ データ API を使用することを推奨します。）ユーザ データ保存場所は現在の Windows ユーザによって作成された各 HotSync ユーザのための名前、ID、同期設定、デスクトップ ディレクトリ、パスワードを保持します。

この節では、インストーラまたはデスクトップ アプリケーションがユーザ データ API を使って実行する最も一般的なタスクについて説明します。

• HotSync ユーザの追加と削除
• HotSync ユーザのディレクトリの検索と設定
• HotSync ユーザについての情報へのアクセス
• HotSync ユーザの同期設定へのアクセス
• HotSync ユーザの拡張スロット情報の取得
• HotSync ユーザのインストール コンジット フラグの変更
• ユーザ データ保存場所の中の開発者-定義エントリへのアクセス
• ユーザ データ API ユーティリティ関数の使用
• ユーザ データ API 関数の要約

ユーザ データ API 関数についての詳細は、C/C++ Sync Suite Reference の 第 16 章 「ユーザ データ API」 を参照してください。

HotSync ユーザの追加と削除 ^TOP^

あなたのデスクトップ アプリケーションまたはインストーラがデスクトップ上の HotSync ユーザを管理する必要がある場合、ユーザ データ API が 表 9.19 で説明されている関数を提供します。

表 9.19 HotSync ユーザの追加と削除

タスク	ユーザ データ API 関数
新しい HotSync ユーザまたは ユーザ プロファイル をユーザ データ保存場所に追加します。user name を指定します。ユーザ データ保存場所が存在しない場合、この関数はそれを作成します。	UmAddUser()
HotSync ユーザを削除します。user IDを指定します。	UmDeleteUser()

HotSync ユーザのディレクトリの検索と設定 ^TOP^

HotSync マネージャがインストールされるとき、デフォルト コンジット は自身のデスクトップ データを 図 9.1 で示されているように各 HotSync ユーザのディレクトリのサブディレクトリに保存します。あなたが同様のことをしたい場合、表 9.20 で説明されているユーザ データ API 関数を使うことで現在の Windows ユーザの HotSync ユーザ ディレクトリを検索またはセットすることができます。

表 9.20 HotSync ユーザのディレクトリの検索とセット

タスク	ユーザ データ API 関数
現在の Windows ユーザのための HotSync ユーザのディレクトリのパスを取得します。これは Core\Path|Introduction to Conduit Development/A コンフィグレーション エントリの中に保存されている値です。	UmGetRootDirectory()
HotSync ユーザのディレクトリ名を取得またはセットします。HotSync user ID を指定します。	UmGetUserDirectory() UmSetUserDirectory()

HotSync ユーザについての情報へのアクセス ^TOP^

ユーザ データ API は現在の Windows ユーザによって作成された各 HotSync ユーザについての情報にアクセスするための関数を提供します。表 9.21 はどのようにこの情報にアクセスするかについて説明しています。

表 9.21 HotSync ユーザについての情報へのアクセス

タスク	ユーザ データ API 関数
index で HotSync ユーザ ID を取得します。UmGetUserCount() を呼び出してインデックスの上限を取得します。	UmGetUserID() {{UmGetUserCount,UmGetUserCount()|C/C++ Sync Suite Reference601/16}}
user ID で HotSync ユーザの名前を取得またはセットします。	UmGetUserName() UmSetUserName()
user ID で HotSync ユーザの暗号化されたパスワードを取得します。PwdVerify() を呼び出してユーザの入力と一致するか検証します。	UmGetUserPassword()
HotSync ユーザが現在の Windows ユーザとして少なくとも 1 回 HotSync を実行したかどうか（「インストール済み (installed)」フラグがセットされているか）を決定します。user ID で HotSync ユーザ名を指定します。	UmIsUserInstalled() UmSetUserInstall()
ある HotSync ユーザが実際のところ ユーザ プロファイル であるかどうかを決定します。user ID で HotSync ユーザ名を指定します。	UmIsUserProfile()

HotSync ユーザの同期設定へのアクセス ^TOP^

ユーザ データ API は HotSync ユーザの永久的、一時的な同期設定にアクセスするための関数を提供します。HotSync マネージャとあなたのコンジット間でそのコンジットの CfgConduit() エントリ ポイント経由で渡される設定があるため、あなたのコンジットはそれらの設定をユーザに変更させることができます。同期設定の予備知識は、Introduction to Conduit Development の 「ユーザのコンジット同期設定」 を参照してください。

表 9.22 は、ユーザ データ API でこの情報にどのようにアクセスするのかについて説明しています。

表 9.22 HotSync ユーザの同期設定へのアクセス

タスク	ユーザ データ API
user ID で指定された HotSync ユーザのコンジットの永久的または一時的な設定を取得またはセットします。	UmGetUserPermSyncPreferences() UmSetUserPermSyncPreferences() UmGetUserTempSyncPreferences() UmSetUserTempSyncPreferences()
user ID で指定された HotSync ユーザのすべてのコンジットの永久的または一時的な同期設定を削除します。	UmDeleteUserPermSyncPreferences() UmDeleteUserTempSyncPreferences()
user ID で指定された HotSync ユーザのコンジットの一時的な同期設定を削除します。	UmRemoveUserTempSyncPreferences()

HotSync ユーザの拡張スロット情報の取得 ^TOP^

HotSync 実施の開始時に、HotSync マネージャはハンドヘルドからハンドヘルドが拡張カードを持つかどうかを取得し、持つ場合はそれらのスロットの中のカードについての情報を取得します。HotSync マネージャはその情報をユーザ データ保存場所に保存して、HotSync 実施中にその情報にアクセスできるようにします - 例えば、インストール ツールはその情報を使って HotSync ユーザが次回の HotSync 実施時にインストールするためにファイルをキューに追加できるかどうかを決定します。ユーザ データ API はハンドヘルドから直接スロット情報を取得せずに最後の HotSync 実施時にユーザ データ保存場所に保存された情報を取得するだけなので、この情報は次回の HotSync 実施時には正確なものではなくなっているかもしれません; ユーザはその間にハンドヘルドを変更または更新するかもしれません。

表 9.23 は、ユーザ データ API でこの拡張スロット情報にどのようにアクセスするのかについて説明しています。

表 9.23 HotSync ユーザの拡張スロット情報の取得

タスク	ユーザ データ API
user ID で指定された HotSync ユーザのハンドヘルド上の拡張マネージャ ライブラリのバージョンを取得します。	UmSlotGetExpMgrVersion()
user ID で指定された HotSync ユーザのハンドヘルド上の拡張スロットの数を取得します。	UmSlotGetSlotCount()
user ID で指定された HotSync ユーザのハンドヘルド上のすべての拡張スロットのスロット ID を取得します。	UmSlotGetInfo()
user ID で指定された HotSync ユーザのための slot ID で指定された拡張スロットの表示名を取得します。	UmSlotGetDisplayName()
user ID で指定された HotSync ユーザのための slot ID で指定されたスロットの中にあるメディアのタイプを取得します。	UmSlotGetMediaType()
user ID で指定された HotSync ユーザのための slot ID で指定されたスロットのためのデスクトップ上のスロット-インストール ディレクトリの名前を取得します。	UmSlotGetInstallDirectory()

HotSync ユーザのインストール コンジット フラグの変更 ^TOP^

ユーザのインストール コンジット フラグにアクセスするためのユーザ データ API 関数のいくつかはインストール援助機能 API と同じ動作をします。しかしながら、ユーザ データ API はさらに UmSetInstallMask() を持ちます。更なる情報は、「インストール援助機能の機能」 と 「登録されたコンジット情報へのアクセス」 を参照してください。

表 9.24 はユーザのインストール コンジット フラグの状態をどのように変更、取得するのかについて説明しています。

表 9.24 HotSync ユーザのインストール コンジット フラグの変更

タスク	ユーザ データ API 関数
mask 値で指定されたインストール コンジットは、user ID で指定された HotSync ユーザの次回の HotSync 実施時に実行されるようにセットされているかどうかを決定します。	UmIsInstallMaskSet()
mask 値で指定されたインストール コンジットを選択または選択解除して、user ID で指定された HotSync ユーザの次回の HotSync 実施時に実行するまたは実行しないようにセットします。	UmSetInstallMask() UmClearInstallMask()

ユーザ データ保存場所の中の開発者-定義エントリへのアクセス ^TOP^

コンジット マネージャ API があなたがあなた自身のコンジット コンフィグレーション エントリを定義することを可能にするのと同じ手法で、ユーザ データ API はユーザ データ保存場所のために同じことをします。しかし、コンジット コンフィグレーション エントリは現在の Windows ユーザのコンジットごとに保存されるのに対して、ユーザ データ保存場所の中の情報は HotSync ユーザごとに保存されます。

ユーザ データ保存場所は、名前を付けられたセクションに分割されています。名前を付けられたセクションは、誰の値をセットできるのかを示す名前付きのキーを保持します。あなたはセクション、キーの作成、キーの値のセットと取得を行うことができます。

表 9.25 は、あなたがユーザ データ保存場所の中の整数と文字列値を取得、セットするために呼び出すことができる関数について説明しています。

表 9.25 ユーザ データ保存場所の中の開発者-定義エントリへのアクセス

タスク	ユーザ データ API 関数
user ID で指定された HotSync ユーザのためのエントリの整数または文字列値を取得またはセットします。セットする関数は、セクションとキーがまだ存在しない場合、それらを作成します。	UmGetInteger() UmSetInteger() UmGetString() UmSetString()
user ID で指定された HotSync ユーザのためのキーまたはエントリ セクションを削除します。	UmDeleteKey()

ユーザ データ API ユーティリティ関数の使用 ^TOP^

ユーザ データ API は、表 9.26 で要約されているいくつかのユーティリティ関数を含みます。

表 9.26 ユーザ データ API ユーティリティ関数の使用

タスク	ユーザ データ API 関数
ユーザ データ API のバージョン番号を取得します。この関数がユーザ データ API のどのバージョンで使用可能なのかを調べるには、関数の「互換性」部分を参照してください。	UmGetLibVersion()
HotSync ユーザの name または directory で HotSync ユーザ ID を取得します。	UmGetIDFromName() UmGetIDFromPath()

ユーザ データ API 関数の要約 ^TOP^

• ユーザ データ API 関数
  • HotSync ユーザの追加と削除
    • UmAddUser()
    • UmDeleteUser()
  • HotSync ユーザのディレクトリの検索と設定
    • UmGetUserDirectory()
    • UmSetUserDirectory()
    • UmGetRootDirectory()
  • HotSync ユーザ情報へのアクセス
    • UmGetUserCount()
    • UmGetUserID()
    • UmGetUserName()
    • UmSetUserName()
    • UmGetUserPassword()
    • UmIsUserInstalled()
    • UmSetUserInstall()
    • UmIsUserProfile()
  • HotSync ユーザの同期設定へのアクセス
    • UmGetUserPermSyncPreferences()
    • UmSetUserPermSyncPreferences()
    • UmGetUserTempSyncPreferences()
    • UmSetUserTempSyncPreferences()
    • UmDeleteUserPermSyncPreferences()
    • UmDeleteUserTempSyncPreferences()
    • UmRemoveUserTempSyncPreferences()
  • HotSync ユーザの拡張スロット情報の取得
    • UmSlotGetDisplayName()
    • UmSlotGetExpMgrVersion()
    • UmSlotGetInfo()
    • UmSlotGetInstallDirectory()
    • UmSlotGetMediaType()
    • UmSlotGetSlotCount()
  • インストール コンジット フラグの変更
    • UmClearInstallMask()
    • UmSetInstallMask()
    • UmIsInstallMaskSet()
  • ユーザ データ保存場所の中の開発者-定義エントリへのアクセス
    • UmGetInteger()
    • UmSetInteger()
    • UmGetString()
    • UmSetString()
    • UmDeleteKey()
  • ユーティリティ関数
    • UmGetIDFromName()
    • UmGetIDFromPath()
    • UmGetLibVersion()

↑　9 章のトップへ　9 章のページ 2 へ　→

←　8 章に戻る　↑トップへ　付録 A に進む　→