IDirectInputDevice8::SetActionMap Method

Article
09/10/2011

Sets the data format for a device and maps application-defined actions to device objects. It also sets the buffer size for buffered data.

Syntax

HRESULT SetActionMap(
         LPCDIACTIONFORMAT lpdiActionFormat,
         LPCTSTR lptszUserName,
         DWORD dwFlags
)

Parameters

lpdiActionFormat
Address of a DIACTIONFORMAT structure containing information about the action map to be applied.
lptszUserName
Unicode string that specifies the name of the user for which the action map is being set. A value of NULL specifies the user currently logged into the system.
dwFlags
DWORD value that specifies how the action map is applied. This can be one of the following values.
- DIDSAM_DEFAULT
  Set the action map for this user. If the map differs from the current map, the new settings are saved to disk.
- DIDSAM_FORCESAVE
  Always save the configuration to disk.
- DIDSAM_NOUSER
  Reset user ownership for this device in the default configuration property sheet. Resetting user ownership does not remove the current action map.

Return Value

If the method succeeds, the return value can be one of the following error values: DI_OK, DI_SETTINGSNOTSAVED, or DI_WRITEPROTECT. If the method fails, the return value can be one of the following error values: DIERR_ACQUIRED or DIERR_INVALIDPARAM, DI_SETTINGSNOTSAVED, DI_WRITEPROTECT, DIERR_ACQUIRED, DIERR_INVALIDPARAM.

Remarks

This method provides the mechanism to change action-to-control mapping from the device defaults. An application must use this method to map its in-game actions to virtual controls.

The user name passed to this method binds a set of action mappings for a device to a specific user. Settings are automatically saved to disk when they differ from the currently applied map. Applications that accept input from multiple users should be very careful when applying action maps to the system mouse or keyboard, as the action maps for each user may conflict.

The method can be called only when the device is not acquired.

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.