IDirectMusicTool8::Flush

DirectMusic

Microsoft DirectX 9.0 SDK Update (Summer 2004)

IDirectMusicTool8::Flush

The Flush method flushes messages from the queue when the performance stops. The tool can use the method to do whatever is necessary to flush the message. For instance, the output tool uses this method to ensure that any pending note-off messages are processed immediately.

Syntax

HRESULT Flush(
  IDirectMusicPerformance* pPerf, 
  DMUS_PMSG* pPMSG,
  REFERENCE_TIME rtTime
);

Parameters

pPerf

Address of the IDirectMusicPerformance8 interface.

pPMSG

Message to flush.

rtTime

Time at which to flush.

Return Values

Return values are determined by the implementation. If the method succeeds, the return value can be one of the following:

Return code
DMUS_S_REQUEUE
DMUS_S_FREE
S_OK

If it fails, the method can return E_POINTER.

Remarks

The message will have DMUS_PMSGF_TOOL_FLUSH set in its dwFlags member. See DMUS_PMSG.

If the method returns DMUS_S_REQUEUE, the message is placed back in the queue. The tool can put a new time stamp and parameters on the message, or change the delivery type.

If the return value is DMUS_S_FREE, the message is freed by the performance.

If the return value is S_OK, the message is not freed by the performance. The tool might be holding onto the message for some reason, or the tool might already have freed the message.

Be sure not to create a circular reference to the performance represented by pPerf. For more information, see DirectMusic Tools.

Requirements

  Header: Declared in dmplugin.h.

See Also


© 2004 Microsoft Corporation. All rights reserved.