?/TD>
Microsoft DirectX 9.0

IDirectInputDevice8::GetForceFeedbackState Method


Retrieves the state of the device's force-feedback system.

Syntax

HRESULT GetForceFeedbackState(      

    LPDWORD pdwOut );

Parameters

pdwOut
Location for flags that describe the current state of the device's force-feedback system.

The value is a combination of the following constants.

DIGFFS_ACTUATORSOFF
The device's force-feedback actuators are disabled. If the device cannot report the actuator state, neither DIGFFS_ACTUATORSON nor DIGFFS_ACTUATORSOFF is returned.
DIGFFS_ACTUATORSON
The device's force-feedback actuators are enabled. If the device cannot report the actuator state, neither DIGFFS_ACTUATORSON nor DIGFFS_ACTUATORSOFF is returned.
DIGFFS_DEVICELOST
The device suffered an unexpected failure and is in an indeterminate state. It must be reset either by unacquiring and reacquiring the device, or by sending a DISFFC_RESET command.
DIGFFS_EMPTY
The device has no downloaded effects.
DIGFFS_PAUSED
Playback of all active effects has been paused.
DIGFFS_POWEROFF
The force-feedback system is not currently available. If the device cannot report the power state, neither DIGFFS_POWERON nor DIGFFS_POWEROFF is returned.
DIGFFS_POWERON
Power to the force-feedback system is currently available. If the device cannot report the power state, neither DIGFFS_POWERON nor DIGFFS_POWEROFF is returned.
DIGFFS_SAFETYSWITCHOFF
The safety switch is currently off; that is, the device cannot operate. If the device cannot report the state of the safety switch, neither DIGFFS_SAFETYSWITCHON nor DIGFFS_SAFETYSWITCHOFF is returned.
DIGFFS_SAFETYSWITCHON
The safety switch is currently on; that is, the device can operate. If the device cannot report the state of the safety switch, neither DIGFFS_SAFETYSWITCHON nor DIGFFS_SAFETYSWITCHOFF is returned.
DIGFFS_STOPPED
No effects are playing, and the device is not paused.
DIGFFS_USERFFSWITCHOFF
The user force-feedback switch is currently off; that is, the device cannot operate. If the device cannot report the state of the user force-feedback switch, neither DIGFFS_USERFFSWITCHON nor DIGFFS_USERFFSWITCHOFF is returned.
DIGFFS_USERFFSWITCHON
The user force-feedback switch is currently on; that is, the device can operate. If the device cannot report the state of the user force-feedback switch, neither DIGFFS_USERFFSWITCHON nor DIGFFS_USERFFSWITCHOFF is returned.

Applications should ignore any flags that are not currently defined.

Return Value

If the method succeeds, the return value is DI_OK.

If the method fails, the return value can be one of the following error values.

DIERR_INPUTLOSTAccess to the input device has been lost. It must be reacquired.
DIERR_INVALIDPARAMAn 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_NOTEXCLUSIVEACQUIREDThe operation cannot be performed unless the device is acquired in DISCL_EXCLUSIVE mode.
DIERR_NOTINITIALIZEDThe object has not been initialized.
DIERR_UNSUPPORTEDThe function called is not supported at this time. This value is equal to the E_NOTIMPL standard COM return value.


Remarks

The device must be acquired at the exclusive cooperative level for this method to succeed.

The DIGFFS_PAUSED and DIGFFS_STOPPED flags may not always be reported correctly because there is no mechanism for the drivers to report that they support these flags.

Note  When calling IDirectInputDevice8::GetForceFeedbackState, it is possible for the state of the device returned not to match the expected state. This might happen if commands recently sent by IDirectInputDevice8::SendForceFeedbackCommand are still pending. Wait a short time and then check the device state again.


© 2002 Microsoft Corporation. All rights reserved.