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

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

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

• （ページ 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 章のページ 1 へ　↑　9 章のトップへ

HotSync マネージャ API の使用 ^TOP^

HotSync マネージャ API は、あなたのデスクトップ アプリケーションまたはインストーラが 表 9.27 で要約されているように HotSync マネージャ アプリケーションを制御することを可能にします。

HotSync マネージャ API 関数のいずれかを呼び出す前に、HsCheckApiStatus() 関数を呼び出して、あなたが HotSync マネージャと通信できるかどうかを決定します。

表 9.27 HotSync マネージャ API の使用

[1] バージョン 6.0 よりも前の HotSync マネージャはコンジットの登録後にリフレッシュまたは再開しなければなりません。バージョン 6.0 以降の HotSync マネージャは、自動的にコンジットのリストをリフレッシュするため、この呼び出しは必要ありません。

HotSync マネージャ API 関数の詳細は、C/C++ Sync Suite Reference の 第 14 章 「HotSync マネージャ API」? を参照してください。

HotSync マネージャ API 関数の要約 ^TOP^

• HotSync マネージャ API 関数
  • HotSync マネージャのチェック、開始、停止、リフレッシュ
    • HsSetAppStatus()
    • HsGetSyncStatus()
    • HsCheckApiStatus()
    • HsRefreshConduitInfo()
  • HotSync マネージャ ダイアログ ボックスの表示
    • HsDisplayCustomDlg()
    • HsDisplayLog()
    • HsDisplaySetupDlg()
  • 通信状態の取得と設定
    • HsGetCommStatus()
    • HsResetComm()
    • HsSetCommStatus()
  • ユーティリティ関数
    • HsGetApiVersion()

通知機能インストール マネージャ API の使用 ^TOP^

通知機能インストール マネージャは 通知機能 を HotSync マネージャに登録または登録解除します。その API は、通知機能の登録と登録解除から通知機能の登録情報の基本的な保存を分離します。この抽象化は、あなたがどのようにあなたの通知機能をインストールまたはアンインストールするかに影響を与えることなく基本的な保存の詳細を変更することを可能にします。

通知機能インストール マネージャは HotSync マネージャに登録する通知機能のファイル名のみを使用します。他にも、あなたはフル パスを指定することができますが、これらの関数は、あなたが通知機能を登録するときに正確な文字列を提供することによってのみ、通知機能にアクセスするということに注意してください。それゆえ、あなたが通知機能を登録するときにフル パスを指定した場合、あなたはそれを登録解除するときも同じフル パスを指定しなくてはなりません。

この節では、インストーラが通知機能インストール マネージャを使って実行する最も一般的なタスクについて説明します。

• 通知機能の登録と登録解除
• 登録された通知機能情報へのアクセス
• 通知機能インストール マネージャ関数の要約

これらの関数の詳細は、C/C++ Sync Suite Reference の 第 13 章 「通知機能インストール マネージャ API」 を参照してください。

通知機能の登録と登録解除 ^TOP^

HotSync マネージャは、HotSync プロセスの開始時と終了時にのみ、固有のパスとファイル名を持つすべての登録された通知機能を実行します。表 9.28 は、現在の Windows ユーザのためとシステムのための通知機能を登録、登録解除するための関数を要約しています。

表 9.28 通知機能の登録と登録解除

登録された通知機能情報へのアクセス ^TOP^

通知機能インストール マネージャ API は、現在の Windows ユーザのためとシステムのために登録されている通知既往についての情報を取得するための別個の関数を提供します。表 9.29 はこれらの関数を要約しています。

表 9.29 登録された通知機能の情報へのアクセス

通知機能インストール マネージャ関数の要約 ^TOP^

• 通知機能インストール マネージャ関数
  • 通知機能の登録/登録解除
    • NmRegister()
    • NmUnregister()
    • NmRegisterSystem()
    • NmUnregisterSystem()
  • 登録された通知機能の情報へのアクセス
    • NmFind()
    • NmGetCount()
    • NmGetByIndex()
    • NmRenameByIndex()
    • NmFindSystem()
    • NmGetSystemCount()
    • NmGetSystemByIndex()
    • NmRenameSystemByIndex()

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

インストール コンジット マネージャは、標準同期コンジットを登録するためのコンジット マネージャが提供するコンジットの登録、登録解除とほとんど同じ機能を提供します。インストール コンジット は、ハンドヘルドに Palm OS データベースとアプリケーションをインストールする（またはデスクトップからハンドヘルドの拡張カードにファイルをコピーする）C API-ベース コンジットの特別なタイプです。インストール援助機能がどのようにインストール コンジットを使用するかについての更なる情報は、「インストール援助機能の機能」 を参照してください。

NOTE

たいていのコンジットは、インストールコンジットではなく同期コンジットであり、コンジット マネージャに登録されなくてはなりません（「コンジット マネージャ API の使用」 を参照してください）。

この節では、インストーラがインストール コンジット マネージャを使って実行する最も一般的なタスクについて説明します:

• インストール コンジットの登録
• インストール コンジットの登録解除
• 登録されているすべてのインストール コンジットについての情報へのアクセス
• 開発者-定義インストール コンジット コンフィグレーション エントリへのアクセス
• インストール コンジット マネージャ関数の要約

インストール コンジットの登録 ^TOP^

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

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

NOTE

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

あなたがインストール コンジットを HotSync マネージャに登録するとき、あなたはあなたのインストール コンジットに関連付けされる固有のビット マスク（Mask）、固有の ID（CreatorID）、1 つ以上のファイル拡張子（Extensions）を指定しなければなりません。HotSync マネージャはマスク値だけを使ってあなたのインストール コンジットを認識しますが、インストール コンジット マネージャはインストール コンジットのコンフィグレーション エントリへのアクセス、保存のために固有の ID を要求します。この ID はあなたが PalmSource 社に登録する作成者 ID と関連する必要はありません。しかしながら、あなたが指定する値が固有であることを保証する 1 つの方法は、あなたが PalmSource 者に登録する作成者 ID を使用することです。あなたはインストール コンジット マネージャ API を使ってあなたのインストール コンジットに関連付けされるこれらの値とその他の値をインストール コンジット コンフィグレーション エントリに追加します。

NOTE

インストール コンジット マネージャは、あなたのインストール コンジットの 作成者 ID をすでに登録されているインストール コンジットの作成者 ID に対してチェックするだけです。あなたの Mask 値は固有でなければならないため、あなたはまずあなたのインストール コンジットの Mask がすでに登録されているインストール コンジットの Mask に対してチェックしなければなりません。インストール コンジット マネージャは、あなたの CreatorID 値が同じであるとき、エラーを返します。しかし、あなたの Mask 値が同じであるときエラーを返しません。それゆえ、あなたのインストーラは Mask 値が固有であることを保証しなければなりません。

あらかじめ宣言されているインストール コンジット エントリについての説明は、C/C++ Sync Suite Reference の 「インストール コンジット コンフィグレーション エントリ」 を参照してください。

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

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

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

単一の構造体からインストール コンジットを登録するには、FileInstallType 構造体とこの構造体に関連付けされた文字列を割り当て、構造体のフィールド値を適切にセットし、この構造体を ImRegister() 似渡します。この関数は、あなたが構造体の中で指定した固有の ID のために、あなたのインストール コンジットのコンフィグレーション エントリを保存しようと試みます。他のインストール コンジットが同じ固有 ID またはファイル拡張子で登録されている場合、この関数はエラーを返し、あなたのインストール コンジットを登録しません。

インスール コンジットを登録するためにあなたがセットしなければならない FileInstallType のフィールドは以下のものだけです:

• dwCreatorID - インストール コンジットの固有 ID。
• szExt - インストール コンジットがインストールすることができるファイルの拡張子。
• szModule - インストール コンジット DLL のパスとファイル名（またはファイル名のみ）。
• dwMask - インストール コンジットの固有のビット マスク。

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

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

コード 9.5 単一の構造体でのインストール コンジットの登録例

void RegisterInstallConduitByStruct () {
   FileInstallType pInstConduit;
   DWORD id;
   int retval = 0;

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

   strcpy(pInstConduit.szModule,"MyInstConduit.dll");
   strcpy(pInstConduit.szDir, "MyInstallDir");
   strcpy(pInstConduit.szName,"My Install Conduit Display 
      Name");
   strcpy(pInstConduit.szExt,"*.ext");

   CmConvertStringToCreatorID("MyID", &id);
   pInstConduit.dwCreatorID = id;
// Check the mask value of all registered install conduits 
// and use a value that is not already in use.
   pInstConduit.dwMask = 0x00000001;

   retval = ImRegister(pInstConduit);
// If retval is not 0, then registration fails. Check for 
// negative error codes.
}

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

表 9.30 インストール コンジットを登録するための単一の構造体の作成

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

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

• ImSetExtension() - 必須
• ImSetModule() - 必須
• ImSetMask() - 必須
• ImSetDirectory() - オプション
• ImSetName() - オプション

{{{goto Accessing Developer-defined Install Conduit Configuration Entries,「開発者-定義インストール コンジット コンフィグレーション エントリへのアクセス」|C/C++ Sync Suite Companion601/9-1}} で説明されているように、あなたはあなた自身のコンフィグレーション エントリを作成して、インスール時に上記の関数でそれらをセットすることもできます。

コード 9.6 は、ImRegisterID() といくつかの ImSet...() 関数を呼び出す単純なインストール コンジット登録を示しています。

コード 9.6 一連のインストール コンジット マネージャ関数でインストール コンジットを登録する

int RegisterInstallConduitWithMultipleCalls () {
   DWORD id;
   CmConvertStringToCreatorID("MyID", &id);

   err = ImRegisterID(id);
   if (err == 0)
      err = ImSetExtension()(id, "*.ext");
   if (err == 0)
      err = ImSetModule()(id, 
         "C:\\MyCond\\Debug\\MyInstCond.DLL");
   if (err == 0)
      // Check the mask value of all registered install 
      // conduits and use a value that is not already in use.
      err = ImSetMask()(id, 0x00000001);
   if (err == 0)
      err = ImSetDirectory()(id, "MyInstallDir");
   if (err == 0)
      err = ImSetName()(id, "My Install Conduit Display 
         Name");
   if (err == 0)
      printf(" Registration succeeded\n");
   else
      printf(" Registration failed %d\n", err);
   return err;
}

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

表 9.31 インストール コンジットを登録するためのいくつかのコンフィグレーション エントリの作成

これらの関数の詳細は、C/C++ Sync Suite Reference の 第 12 章 「インストール コンジット マネージャ API」 を参照してください。

インストール コンジットの登録解除 ^TOP^

あたながあなたのインストール コンジットをアンインストールするとき、あなたはそれを登録解除して HotSync マネージャがもはや存在していないあなたのインストール コンジット DLL を呼び出さないようにしなくてはなりません。インストール コンジットを登録解除するには、ImUnregisterID() を呼び出し、登録解除するインストール コンジットの固有 ID を渡します。システムのために登録されているコンジットに対しても同様に ImUnregisterSystemID() を呼び出します。これらの関数はインストール コンジットのすべてのコンフィグレーション エントリを削除します。しかし、インストール コンジット DLL を削除しません。

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

表 9.32 登録されているインストール コンジットの登録解除

これらの関数の詳細は、C/C++ Sync Suite Reference の 第 12 章 「インストール コンジット マネージャ API」 を参照してください。

登録されているすべてのインストール コンジットについての情報へのアクセス ^TOP^

インストール コンジット マネージャ API は、登録されているすべてのインストール コンジットについての情報を取得するための関数を提供します。これらの API は同期コンジットやバックアップ コンジットにはアクセスしません。表 9.33 は、インストール コンジット マネージャ API であなたが取得またはセットすることができる現在の Windows ユーザのためとシステムのためのコンジットの両方の情報の種類を説明しています。

いくつかの API は、「別個のコンフィグレーション エントリを作成する」 で説明されているのと同様の方法で、あなたが単一のインストール コンジット コンフィグレーション エントリの値をセットすることを可能にします。

HotSync マネージャが現在の Windows ユーザのために実行することができるインストール コンジットだけのリストの始めから終わりまでを繰り返し処理するには、「登録されているインストール コンジット情報へのアクセス」 で説明されているインストール援助機能関数を使用します。

表 9.33 登録されているインストール コンジット情報へのアクセス

これらの関数についての詳細は、C/C++ Sync Suite Reference の 「インストール コンジット マネージャ 関数」 を参照してください。

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

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

あなたがインストール コンジットを登録解除するとき、インストール コンジット マネージャはインストール コンジットのすべてのエントリ - あなたが定義したものを含む - を削除します。一方、インストール コンジット マネージャはあなたのエントリには一切アクセスしません。このため、あなたはいつでも HotSync マネージャをリフレッシュまたは再開する必要なしにこれらの関数を呼び出すことができます。

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

これらの関数の詳細は、C/C++ Sync Suite Reference の 「インストール コンジット マネージャ 関数」 を参照してください。

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

• インストール コンジット マネージャ 関数
  • インストール コンジットの登録/登録解除
    • ImRegister()
    • ImUnregisterID()
    • ImRegisterSystem()
    • ImUnregisterSystemID()
  • 標準インストール コンジット コンフィグレーション情報へのアクセス
    • ImGetExtension()
    • ImSetExtension()
    • ImGetModule()
    • ImSetModule()
    • ImGetMask()
    • ImSetMask()
    • ImGetDirectory()
    • ImSetDirectory()
    • ImGetName()
    • ImSetName()
    • ImGetSystemExtension()
    • ImSetSystemExtension()
    • ImGetSystemModule()
    • ImSetSystemModule()
    • ImGetSystemMask()
    • ImSetSystemMask()
    • ImGetSystemDirectory()
    • ImSetSystemDirectory()
    • ImGetSystemName()
    • ImSetSystemName()
  • 開発者-定義インストール コンジット コンフィグレーション エントリへのアクセス
    • ImGetDWord()
    • ImSetDWord()
    • ImGetString()
    • ImSetString()
    • ImGetSystemDWord()
    • ImSetSystemDWord()
    • ImGetSystemString()
    • ImSetSystemString()

コンジットのアンインストール ^TOP^

ユーザは、インストール時にコンピュータにインストールされたアプリケーションに関連するすべてのファイルとその他の情報を間単に削除する機能をアプリケーションが提供すると予測します。あなたのアンインストール アプリケーションは以下のことをしなければなりません:

• あなたのコンジットの登録解除。「コンジットの登録解除」 を参照してください。
• 通知 DLL をインストールした場合は、その DLL の登録解除。「通知機能の登録と登録解除」 を参照してください。
  • ユーザ データ保存場所の中にエントリを作成した場合、そのエントリの削除。「ユーザ データ保存場所の中の開発者-定義エントリへのアクセス」 を参照してください。
• インストールされたすべてのファイルの削除。
• その他のクリーンアップの実行。

あなたのコンジットがすでにユーザのマシンにインストールされていたコンジット（デフォルトのコンジットのようなもの）を置き換えていた場合、あなたはユーザに置き換えられたコンジットを HotSync マネージャに登録するためのオプションを提供して、ユーザのマシンをインストールする前の状態に戻すべきです。

インストーラのテスト ^TOP^

HotSync プロセスの最も重要な目標の 1 つはユーザにとって簡単に使用できることなので、あなたのコンジットのインストールとアンインストールは正確で容易であることを保証する必要があります。PalmSource 社は、あなたが最低でも以下のコンジット インストールと削除条件をテストすることを強く推奨します:

• ユーザのデスクトップ コンピュータ上に HotSync が存在するかチェックする。「HotSync マネージャのバイナリの検索」 を参照してください。
• あなたのコンジットをインストールした後、ユーザは HotSync ボタンを押すことができる、同期を正しく行うことができる、同期の間にユーザは何か入力することを求められない。
• あなたのコンジットを削除（アンインストール）した後、ユーザは HotSync ボタンを押すことができる、同期を正しく行うことができる、同期の間にユーザは何か入力することを求められない。
• あなたのコンジットの削除後、コンジット コンフィグレーション エントリはコンジットのインストール前の状態に戻される。

NOTE

HotSync マネージャ バージョン 6.0 より前のものは、あなたがコンフィグレーション エントリのどれかを変更したときはいつでも、あなたが HsSetAppStatus() を呼び出して HotSync マネージャを再開してほとんどのコンジット コンフィグレーションの変更を認識させるか、HsRefreshConduitInfo() を呼び出してコンジット コンフィグレーションの変更を認識させることを要求します。しかしながら、HotSync マネージャ バージョン 6.0 以降のものは、これらの関数を呼び出すことなしに自動的にコンジット コンフィグレーション情報への変更を発見します。他の変更（HotSync マネージャ通信設定、バックアップ コンジットなど）を認識させるためには、あなたは依然として HsSetAppStatus() を呼び出して HotSync マネージャを再開させなければなりません。

さらに、あなたのコンジットのインストールとアンインストール実施がユーザのデスクトップ コンピュータを完全に操作可能な状態のままにしておくことを検証ために、あなたはあなたのコンジットがユーザにとって不快な副作用を引き起こす可能性があるハンドヘルド上の以下の状況を意識している必要があります。

• あなたのコンジットが状態情報をハンドヘルドに保存する場合、あなたはあなたのコンジットの削除時にその状態情報を忘れずにクリーン アップしなければなりません。
• あなたがあなたのものではない作成者 ID を持つデータを作成した場合、あなたのコンジットはとても不快な結果を引き起こす可能性があります。あなたのものではない作成者 ID を使用しないでください。

インストール トラブルシューティング Tips ^TOP^

この節では、インストーラの問題に遭遇したときにチェックすべきことを 2, 3 提案します。

• コンジットの実行後に HotSync ログをチェックします。ログは、問題解決の決め手となるかもしれないエラー メッセージを保持します。適切なユーザのログ エントリをチェックするように気をつけてください。
• 追加の（冗長な）ログ情報は、HotSync マネージャを終了し、Windows のコマンド プロンプトから c:\<HotSync Manager dir>\hotsync.exe -v と入力して HotSync マネージャを起動します。
• コンジットは、あなたのコンジットが HotSync マネージャにそれをとにかく実行するように命令しない限り、ハンドヘルド上に作成者 ID が一致するアプリケーションがある場合ののみ HotSync マネージャによって実行されます。GetConduitInfo()|C/C++ Sync Suite Reference601/3 を参照してください。
• コンジット コンフィグレーション設定を閲覧するには CondCfg.exe を使用します。設定をダブル チェックし、あなたのコンジット DLL があなたが示した場所に実際にあるかどうかといったことを調べます。
• コンジットで指定された作成者 ID （CondCfg.exe を使用して、エントリを閲覧します）がハンドヘルド上のアプリケーションの作成者 ID と一致していることを確認します。
• 冗長なログを使ってハンドヘルド上の作成者 ID のリストを取得します。

コンジット コンフィグレーション ユーティリティ（CondCfg.exe）とその他の助けになるツールの使用方法の詳細は、Conduit Development Utilities Guide? を参照してください。

サンプル インストーラ ^TOP^

サンプルのコンジット インストーラは、Palm OS Knowledge Base の中の記事 "Sample Code for a Conduit Installer in C++" を参照してください。この記事はコンジット インストーラを生成する Microsoft Visual C++ 6.0 プロジェクトを提供しています。

←　9 章のページ 1 へ　↑　9 章のトップへ

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