IDirectMusicPerformance8::FreePMsg

Microsoft DirectX 8.1 (C++)

IDirectMusicPerformance8::FreePMsg

The FreePMsg method frees a message.

Syntax

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 IDirectMusicPerformance8::AllocPMsg method.

Return Values

If the method succeeds, the return value is S_OK.

If it fails, the method can return one of the error values shown in the following table.

Return code

DMUS_E_CANNOT_FREE

E_POINTER

Remarks

Most messages are released automatically by the performance after they have been processed, and IDirectMusicPerformance8::FreePMsg must not be called on a message that has been sent by using IDirectMusicPerformance8::SendPMsg. However, IDirectMusicPerformance8::FreePMsg can be used within IDirectMusicTool8::ProcessPMsg or IDirectMusicTool8::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 in the performance queue because IDirectMusicPerformance8::SendPMsg was called on it. However, applications cannot assume that FreePMsg will return DMUS_E_CANNOT_FREE for all sent messages, because SendPMsg is not synchronous.
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

Header: Declared in dmusici.h.

See Also