Microsoft DirectX 8.0 (Visual Basic)

DirectSetup コールバック関数の作成

セットアップ プロセスをカスタマイズするには、まず次の宣言で示した 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 を返す。