IDirectInputDevice8::BuildActionMap メソッド
IDirectInputDevice8::BuildActionMap メソッド
デバイスのアクション マップを作成し、それに関する情報を取得する。
構文
HRESULT BuildActionMap(
LPDIACTIONFORMAT lpdiaf,
LPCTSTR lpszUserName,
DWORD dwFlags
);
パラメータ
- lpdiaf
アクション マップに関する情報を受け取る DIACTIONFORMAT 構造体のアドレス。 - lpszUserName
どのユーザーのマッピングを要求しているかを指定する文字列へのポインタ。NULL の場合は、現在のユーザーが想定される。 - dwFlags
マッピングを制御するフラグ。この値は、次のいずれかである。DIDBAM_DEFAULT
アプリケーション指定のマッピング (つまり DIACTION 構造体に DIA_APPMAPPED フラグを持つマッピング) を除くすべてのマッピングを上書きする。DIDBAM_HWDEFAULTS
アプリケーション指定のマッピングを含め、すべてのマッピングを上書きする。このフラグは DIDBAM_INITIALIZE に類似しているが、ユーザーがマップしたアクションは、デバイス ドライバまたは Microsoft® DirectInput® に指定されたデフォルト アクションで自動的に上書きされる。DIDBAM_INITIALIZE
アプリケーション指定のマッピングを含め、すべてのマッピングを上書きする。DIDBAM_PRESERVE
このデバイス、またはその他の構成済みデバイスに割り当てられた現在のマッピングを保存する。
戻り値
成功した場合は、DI_OK、DI_NOEFFECT、または DI_WRITEPROTECT を返す。「注意」を参照すること。
失敗した場合は、次のいずれかのエラー値を返す。
| DIERR_INVALIDPARAM | 無効なパラメータが、戻ってくる関数に渡されたか、オブジェクトがその関数を呼び出せる状態になかった。この値は、標準のコンポーネント オブジェクト モデル (COM) 戻り値である E_INVALIDARG に等しい。 |
| DIERR_MAPFILEFAIL | ベンダーが提供するデバイスのアクション マッピング ファイルの読み込み中か、またはデバイスのユーザー構成ファイルの読み込み中または書き込み中にエラーが発生した。 |
注意
デバイスにマッピングが作成されていない場合、このメソッドは DI_NOEFFECT を返す。たとえば、キーボードまたはマウスが、ジャンル固有アクションのマッピングを提供しない場合である。
DIERR_INVALIDPARAM が返される場合、マッピングの 1 つ以上が無効である。DIACTION 構造体の dwHow メンバには DIAH_ERROR が設定される。アプリケーションは、アクション マップの全体でエラーの検出と修正を補間できる。
DIEFF_MAPFILEFAIL が返された場合は、ベンダーが提供するデバイス ファイルの読み込み中か、またはデバイスのユーザー構成ファイルの読み込み中または書き込み中にエラーが発生したことを示す。
マッピングが構成可能でない場合は、DI_WRITEPROTECT が返される。たとえば、音声コントローラのボタンは再構成できない。これは、各ボタンによってハードウェア特有のアクションが発生するためである。DI_WRITEPROTECT は他の成功コードを上書きするので、アクションがマッピングされた場合は、戻りコードを調べてもわからない。
IDirectInputDevice8::BuildActionMap が成功しても、いずれのアクションもマッピングされない場合、その後 IDirectInputDevice8::SetActionMap を呼び出すと DI_OK が返されるが、IDirectInputDevice8::Acquire を呼び出すと失敗し、DIERR_INVALIDPARAM が返される。
参照
IDirectInputDevice8::SetActionMap、IDirectInputDevice8::SetDataFormat