IDirectInputDevice8::SetActionMap Method

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_OK The operation completed successfully. This value is equal to the S_OK standard Component Object Model (COM) return value.
DI_SETTINGSNOTSAVED The action map was applied to the device, but the settings could not be saved.
DI_WRITEPROTECT A SUCCESS code indicating that settings cannot be modified.
DIERR_ACQUIRED The operation cannot be performed while the device is acquired.
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 COM return value.

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

DI_OK	The operation completed successfully. This value is equal to the S_OK standard Component Object Model (COM) return value.
DI_SETTINGSNOTSAVED	The action map was applied to the device, but the settings could not be saved.
DI_WRITEPROTECT	A SUCCESS code indicating that settings cannot be modified.
DIERR_ACQUIRED	The operation cannot be performed while the device is acquired.
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 COM return value.