From time to time your application may need to respond to a music event; for example, you might need to know when the end of a segment has been reached. You get this information by asking DirectMusic to notify you when a certain type of event has taken place.
You specify what types of music events you want to be notified of by calling the IDirectMusicPerformance::AddNotificationType method once for each desired type of event. The following example tells DirectMusic to set segment-related events. The actual type of event (such as segment start or segment end) will be derived later from the notification message.
/* It is assumed that pPerformance is a valid
IDirectMusicPerformance pointer. */
GUID guid = GUID_NOTIFICATION_SEGMENT;
// C syntax:
pPerformance->AddNotificationType(&guid);
// C++ syntax:
pPerformance->AddNotificationType(guid);
Notifications are sent in the form of a DMUS_NOTIFICATION_PMSG message structures. You can poll for any pending notification messages within the Windows message loop by calling the IDirectMusicPerformance::GetNotificationPMsg method, or else you can have DirectMusic signal an event object in a separate thread when a message is pending. (See Using Notification Events.)
More than one message may be waiting when an event is signaled, or when you call GetNotificationPMsg in the message loop. To be sure of catching all notifications, you must call GetNotificationPMsg repeatedly until it returns S_FALSE. Multiple messages with the same time stamp are not queued in any particular order.
It is your responsibility to free any message you retrieve, by calling the IDirectMusicPerformance::FreePMsg method.