IDirectInputDevice8::BuildActionMap Method
HRESULT BuildActionMap(
LPDIACTIONFORMAT lpdiaf,
LPCTSTR lpszUserName,
DWORD dwFlags
)
Parameters
- lpdiaf
- Address of a DIACTIONFORMAT structure that receives information about the action map.
- lpszUserName
- Pointer to a string that specifies the name of the user for whom mapping is requested. When using ANSI compiler settings, pass NULL and DirectInput will assume the current user name. When using Unicode compiler settings, do not pass NULL because the mappings will not be saved.
- dwFlags
-
Flags to control the mapping. This can be one of the following values.
- DIDBAM_DEFAULT
- Overwrite all mappings except application-specified mappings; that is, mappings that have the DIA_APPMAPPED flag in the DIACTION structure.
- DIDBAM_HWDEFAULTS
- 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 DirectInput.
- DIDBAM_INITIALIZE
- Overwrite all mappings, including application-specified mappings.
- DIDBAM_PRESERVE
- Preserve current mappings assigned for this device or any other configured device.
Return Value
If the method succeeds, the return value is DI_OK, DI_NOEFFECT, or DI_WRITEPROTECT>. See Remarks. If the method fails, the return value can be one of the following error values: DIERR_INVALIDPARAM, DIERR_MAPFILEFAIL.
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 Interface will fail with DIERR_INVALIDPARAM.