IDirectInputEffect::Start Method

Begins playing an effect. If the effect is already playing, it is restarted from the beginning. If the effect has not been downloaded or has been modified since its last download, it is downloaded before being started. This default behavior can be suppressed by passing the DIES_NODOWNLOAD flag.

Syntax

HRESULT Start(      

    DWORD dwIterations,
    DWORD dwFlags
);

Parameters

dwIterations
Number of times to play the effect in sequence. The envelope is re-articulated with each iteration.
To play the effect exactly once, pass 1. To play the effect repeatedly until explicitly stopped, pass INFINITE. To play the effect until explicitly stopped without re-articulating the envelope, modify the effect parameters with the IDirectInputEffect::SetParameters method, and change the dwDuration member to INFINITE.
dwFlags
Flags that describe how the effect should be played by the device. The value can be 0 or one or more of the following values:
DIES_SOLO
All other effects on the device should be stopped before the specified effect is played. If this flag is omitted, the effect is mixed with existing effects already started on the device.
DIES_NODOWNLOAD
Do not automatically download the effect.

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_INCOMPLETEEFFECT The effect could not be downloaded because essential information is missing. For example, no axes have been associated with the effect, or no type-specific information has been supplied.
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 Component Object Model (COM) return value.
DIERR_NOTEXCLUSIVEACQUIRED The operation cannot be performed unless the device is acquired in DISCL_EXCLUSIVE mode.
DIERR_NOTINITIALIZED The object has not been initialized.
DIERR_UNSUPPORTED The 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.
Not all devices support multiple iterations.

DIERR_INCOMPLETEEFFECT	The effect could not be downloaded because essential information is missing. For example, no axes have been associated with the effect, or no type-specific information has been supplied.
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 Component Object Model (COM) return value.
DIERR_NOTEXCLUSIVEACQUIRED	The operation cannot be performed unless the device is acquired in DISCL_EXCLUSIVE mode.
DIERR_NOTINITIALIZED	The object has not been initialized.
DIERR_UNSUPPORTED	The function called is not supported at this time. This value is equal to the E_NOTIMPL standard COM return value.