?/TD>
Microsoft DirectX 9.0

IDirectInputDevice8::SendForceFeedbackCommand Method


Sends a command to the device's force-feedback system.

Syntax

HRESULT SendForceFeedbackCommand(      

    DWORD dwFlags );

Parameters

dwFlags
Single value indicating the desired change in state. The value can be one of the following.
DISFFC_CONTINUE
Paused playback of all active effects is to be continued. It is an error to send this command when the device is not in a paused state.
DISFFC_PAUSE
Playback of all active effects is to be paused. This command also stops the clock-on effects so that they continue playing to their full duration when restarted.

While the device is paused, new effects cannot be started, and existing ones cannot be modified. Doing so can cause the subsequent DISFFC_CONTINUE command to fail to perform properly.

To abandon a pause and stop all effects, use the DISFFC_STOPALL or DISFCC_RESET commands.

DISFFC_RESET
The device's force-feedback system is to be put in its startup state. All effects are removed from the device, are no longer valid, and must be re-created if they are to be used again. The device's actuators are disabled.
DISFFC_SETACTUATORSOFF
The device's force-feedback actuators are to be disabled. While the actuators are off, effects continue to play but are ignored by the device. Using the analogy of a sound playback device, they are muted, rather than paused.
DISFFC_SETACTUATORSON
The device's force-feedback actuators are to be enabled.
DISFFC_STOPALL
Playback of any active effects is to be stopped. All active effects are reset, but are still being maintained by the device and are still valid. If the device is in a paused state, that state is lost. This command is equivalent to calling the IDirectInputEffect::Stop method for each effect playing.

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.

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.