![]() |
![]() |
![]() |
Builds an action map for the device and retrieves information about it.
Syntax
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 Microsoft 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 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.
Remarks
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.
See Also
IDirectInputDevice8::SetActionMap, IDirectInputDevice8::SetDataFormat