Microsoft DirectX 8.0 (C++) |
セットアップ プロセスをカスタマイズするには、まず次の宣言で示した DirectXSetupCallbackFunction プロトタイプに適合するコールバック関数を作成する。
DWORD WINAPI DirectXSetupCallbackFunction( DWORD dwReason, DWORD dwMsgType, LPSTR szMessage, LPSTR szName, void *pInfo);
この例 (Dinstall を修正したもの) では、関数名がプロトタイプと同じになっているが、これは変更可能である。パラメータ名は、dsetup.h ヘッダー ファイルで宣言されているプロトタイプと若干異なるが、以下の説明ではこれらの名前を使用する。
dwReason は、コールバック関数が呼び出された理由を示すパラメータである。有効値の一覧および各有効値の説明については、DirectXSetupCallbackFunction のリファレンスを参照すること。
dwMsgType パラメータは、Microsoft® DirectSetup® がデフォルトで MessageBox に渡すフラグ (表示するボタンやアイコンを制御するフラグなど) と同等のフラグを受け取る。中でも、ボタン フラグは、必要な戻り値の指定に使用できる。この値が 0 の場合、イベントはユーザー入力を要求しないため、DirectSetup は通常ステータス メッセージを表示する。
szMessage パラメータは、コールバック関数を使用しない場合に DirectSetup がステータス ダイアログ ボックスまたは MessageBox に渡すものと同じテキストを受け取る。
ドライバがアップグレード対象の場合、szName パラメータにドライバ名が渡され、pInfo はアップグレードの処理方法 (既存のドライバの使用を推奨する、アップグレードを推奨するなど) に関する情報を示す。詳細については、「コールバック関数でのアップグレード フラグの使い方」を参照すること。
コールバック関数が各パラメータをどのように解釈するかについては、開発者の裁量で決定する。通常は、表示するメッセージ (dwReason に基づく) とユーザーに選択肢を提示するタイミングを選択し、それに応じてインターフェイスを変更する。
コールバック関数からの戻り値は、次の規則に従う必要がある。
dwMsgType が 0 以外の場合の適切な戻り値を確認するには、通常ならどのようなボタンがメッセージ ボックスに表示されるか実際にテストしてみる。次の例 (Dinstall の GetReply 関数より) は、このテスト方法を示したものである。
/* グローバル g_wReply は、ユーザーが選択したカスタム ダイアログ ボタンを示す。 */ switch (dwMsgType & 0x0000000F) { / * 通常、[OK] ボタンと [キャンセル] ボタンが配置される。 IDBUT1 は [OK] ボタンに対応する。ユーザーが [OK] ボタンをクリックしなかった場合は、 [キャンセル] ボタンがクリックされたと判定される。*/ case MB_OKCANCEL: wDefaultButton = (g_wReply == IDBUT1) ? IDOK : IDCANCEL; break; / * 上記以外のボタンの組み合わせの場合は、以下のようになる。*/ case MB_OK: wDefaultButton = IDOK; break; case MB_RETRYCANCEL: wDefaultButton = (g_wReply == IDBUT1) ? IDRETRY : IDCANCEL; break; case MB_ABORTRETRYIGNORE: if (g_wReply == IDBUT1) wDefaultButton = IDABORT; else if (g_wReply == IDBUT2) wDefaultButton = IDRETRY; else wDefaultButton = IDIGNORE; break; case MB_YESNOCANCEL: if (g_wReply == IDBUT1) wDefaultButton = IDYES; else if (g_wReply == IDBUT2) wDefaultButton = IDNO; else wDefaultButton = IDCANCEL; break; case MB_YESNO: wDefaultButton = (g_wReply == IDBUT1) ? IDYES : IDNO; break; default: wDefaultButton = IDOK; }
このルーチンは、カスタム インターフェイスからのボタン クリックを、コールバック関数なしの場合に DirectSetup が作成する標準ダイアログ ボックス内の対応するボックス識別子に平行移動する。wDefaultButton 変数は、対応する標準ダイアログ ボックス ボタンの識別子に設定される。コールバック関数から返されるのは、この値である。
dwMsgType が 0 以外の値の場合でも、必ずしもユーザーに選択肢を与える必要はない。たとえば、DirectSetup が通常ユーザーに確認を求めるような場合でも、自動的にドライバをアップグレードすることも可能である。サンプルの Dinstall は、問題のある場合のみメッセージを表示するようユーザーが選択している場合で、しかもドライバをアップグレードしても安全であると考えられるときに、次のように自動アップグレードを行うようになっている。
case DSETUP_CB_UPGRADE_SAFE: switch (dwMsgType & 0x0000000F) { case MB_YESNO: case MB_YESNOCANCEL: return IDYES; case MB_OKCANCEL: case MB_OK: default: return IDOK; } break;
コールバック関数は、ユーザーにアップグレードを続行するかどうか確認するダイアログ ボックスで肯定を表すボタンに応じて、IDYES または IDOK を返す。