IDirectInputDevice8::BuildActionMap Method

Article
09/10/2011

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 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.

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 Interface will fail with DIERR_INVALIDPARAM.

Requirements

Header: Declared in dinput.h.