IDirectInputDevice8::BuildActionMap

Builds an action map for the device and retrieves information about it.

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. If NULL, the current user is assumed.

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 Microsoft® 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 Values

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.

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.

Requirements

  Windows NT/2000/XP: Requires Windows® 2000.
  Windows 98/Me: Requires Windows 98 or later. Available as a redistributable for Windows 98.
  Header: Declared in Dinput.h.

See Also

IDirectInputDevice8::SetActionMap, IDirectInputDevice8::SetDataFormat