IDirectMusicPerformance8::FreePMsg
The FreePMsg method frees memory allocated for a performance message.
Syntax
HRESULT FreePMsg(
DMUS_PMSG* pPMSG
);
Parameters
pPMSG
Pointer to the 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:** Dmusici.h
Library: Dmime.dll, Dmimed.dll
See Also