IDirectMusicPerformance::FreePMsg

This method frees a message.

HRESULT FreePMsg(
  DMUS_PMSG* pPMSG
);

Parameters

• pPMSG
  Address of a variable that contains a message to free. This message must have been allocated using the IDirectMusicPerformance::AllocPMsg method.

Return Values

If the method succeeds, the return value is S_OK.

If it fails, the method can return one of the following error values:

DMUS_E_CANNOT_FREE

E_POINTER

Remarks

Most messages are released automatically by the performance once they have been processed, and IDirectMusicPerformance::FreePMsg must not be called on a message that has been sent by using IDirectMusicPerformance::SendPMsg. However, IDirectMusicPerformance::FreePMsg can be used within IDirectMusicTool::ProcessPMsg or IDirectMusicTool::Flush to free a message that is no longer needed. It must also be used to free notification messages.

The method returns DMUS_E_CANNOT_FREE in the following cases:

• If pPMSG is not a message allocated by AllocPMsg.
• If it is currently in the performance queue because IDirectMusicPerformance::SendPMsg was called on it.
• If it has already been freed.

If there is a value in the pTool, pGraph, or punkUser members (see DMUS_PMSG), each referenced object is released.

Requirements

OS Versions: Windows CE .NET 4.0 and Windows CE .NET 4.1.
Header: Dmusici.h.
Link Library: Dmusic.lib.

See Also

DirectMusic Messages | IDirectMusicPerformance::AllocPMsg | IDirectMusicPerformance::SendPMsg | IDirectMusicTool::Flush | IDirectMusicTool::ProcessPMsg | DMUS_PMSG

 Last updated on Monday, April 12, 2004

© 1992-2002 Microsoft Corporation. All rights reserved.