|Microsoft DirectX 9.0|
Builds an action map for the device and retrieves information about it.
LPDIACTIONFORMAT lpdiaf, LPCTSTR lpszUserName, DWORD dwFlags );
- Address of a DIACTIONFORMAT structure that receives information about the action map.
- Pointer to a string that specifies the name of the user for whom mapping is requested. If NULL, the current user is assumed.
- Flags to control the mapping. This can be one of the following values.
- Overwrite all mappings except application-specified mappings; that is, mappings that have the DIA_APPMAPPED flag in the DIACTION structure.
- Overwrite all mappings, including application-specified mappings. This flag is similar to DIDBAM_INITIALIZE, but automatically overrides user-mapped actions with the defaults specified by the device driver or Microsoft?DirectInput?
- Overwrite all mappings, including application-specified mappings.
- Preserve current mappings assigned for this device or any other configured device.
If the method fails, the return value can be one of the following error values.
DIERR_INVALIDPARAM An invalid parameter was passed to the returning function, or the object was not in a state that permitted the function to be called. This value is equal to the E_INVALIDARG standard Component Object Model (COM) return value. DIERR_MAPFILEFAIL An error has occurred reading either the vendor-supplied action-mapping file for the device or reading or writing the user configuration file for the device.
The method returns DI_NOEFFECT if no mappings were created for the device. For example, a keyboard or mouse will not provide mappings for genre-specific actions.
If DIERR_INVALIDPARAM is returned, one or more of the mappings was not valid. The dwHow member of the DIACTION structure is set to DIAH_ERROR. The application can iterate through the action map to find and correct errors.
If DIEFF_MAPFILEFAIL is returned, an error has occurred either reading the vendor supplied file for the device or reading or writing the user configuration file for the device.
DI_WRITEPROTECT is returned if the mappings were not configurable. For example, the buttons on a voice controller cannot be reconfigured because each button causes a specific hardware action to occur. DI_WRITEPROTECT overrides other success codes, so a check of the return codes will not reveal if any actions have been mapped.
If IDirectInputDevice8::BuildActionMap succeeds but no actions have been mapped, a subsequent call to IDirectInputDevice8::SetActionMap will return DI_OK but a call to IDirectInputDevice8::Acquire will fail with DIERR_INVALIDPARAM.