MusicEventIterator Reference

Framework
AudioToolbox/MusicPlayer.h
Declared in
MusicPlayer.h

Overview

Along with related opaque types, your application can use a music event iterator to play MIDI music tracks and audio unit parameter automation tracks. A music event iterator is an opaque MusicEventIterator data type.

The opaque types used with a music event iterator are described in the following documents:

Result codes for this opaque type are described in MusicPlayer Reference.

Functions by Task

Creating and Disposing of Music Event Iterators

Navigating Among Music Events

Managing Music Event Information

Functions

DisposeMusicEventIterator

Disposes of a music event iterator.

OSStatus DisposeMusicEventIterator (
   MusicEventIterator  inIterator
);
Parameters
inIterator

The music event iterator to dispose of.

Return Value

A result code.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
MusicPlayer.h

MusicEventIteratorDeleteEvent

Deletes the event at a music event iterator’s current position.

OSStatus MusicEventIteratorDeleteEvent (
   MusicEventIterator  inIterator
);
Parameters
inIterator

The music event iterator whose current event you want to delete.

Return Value

A result code.

Discussion

After calling this function, the music event iterator points to the event that follows the deleted event—if there is such an event. If the event you deleted was the final event, the iterator is then positioned immediately beyond the final event of the music track.

Availability
  • Available in OS X v10.0 and later.
Declared In
MusicPlayer.h

MusicEventIteratorGetEventInfo

Gets information about the event at a music event iterator’s current position.

OSStatus MusicEventIteratorGetEventInfo (
   MusicEventIterator  inIterator,
   MusicTimeStamp      *outTimeStamp,
   MusicEventType      *outEventType,
   const void          **outEventData,
   UInt32              *outEventDataSize
);
Parameters
inIterator

The music event iterator whose current event you want information about.

outTimeStamp

On output, the timestamp of the music event, in beats.

outEventType

On output, the type of music event. For possible event types, see “Music Event Types.”

outEventData

On output, a reference to the music event data. The type of data is specified by the outEventType parameter. Do not modify the referenced data directly; to change an event, use the MusicEventIteratorSetEventInfo function.

outEventDataSize

On output, the size, in bytes, of the music event data in the outEventData parameter.

Return Value

A result code.

Discussion

Pass NULL for any output parameter whose information you do not need.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
MusicPlayer.h

MusicEventIteratorHasCurrentEvent

Indicates whether or not a music track contains an event at the music event iterator’s current position.

OSStatus MusicEventIteratorHasCurrentEvent (
   MusicEventIterator  inIterator,
   Boolean             *outHasCurEvent
);
Parameters
inIterator

The music event iterator whose state you want to know about.

outHasCurEvent

On output, true (nonzero) if there is an event at the music event iterator’s current position; false (zero) otherwise.

Return Value

A result code.

Availability
  • Available in OS X v10.2 and later.
See Also
Declared In
MusicPlayer.h

MusicEventIteratorHasNextEvent

Indicates whether or not a music track contains an event beyond the music event iterator’s current position.

OSStatus MusicEventIteratorHasNextEvent (
   MusicEventIterator  inIterator,
   Boolean             *outHasNextEvent
);
Parameters
inIterator

The music event iterator whose state you want to know about.

outHasNextEvent

On output, true (nonzero) if there is an event closer to the end of the music track than the music event iterator’s current position; false (zero) otherwise.

Return Value

A result code.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
MusicPlayer.h

MusicEventIteratorHasPreviousEvent

Indicates whether or not a music track contains an event before the music event iterator’s current position.

OSStatus MusicEventIteratorHasPreviousEvent (
   MusicEventIterator  inIterator,
   Boolean             *outHasPrevEvent
);
Parameters
inIterator

The music event iterator whose state you want to know about.

outHasPrevEvent

On output, true (nonzero) if there is an event closer to the start of the music track than the music event iterator’s current position; false (zero) otherwise.

Return Value

A result code.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
MusicPlayer.h

MusicEventIteratorNextEvent

Positions a music event iterator at the next event on a music track.

OSStatus MusicEventIteratorNextEvent (
   MusicEventIterator  inIterator
);
Parameters
inIterator

The music event iterator to reposition.

Return Value

A result code.

Discussion

Use this function to increment the position of a music event iterator forward through a music track’s events.

If an iterator is at the final event of a track when you call this function, the iterator then moves beyond the final event. You can detect if the iterator is beyond the final event by calling the MusicEventIteratorHasCurrentEvent function.

The following code snippet illustrates how to use a music event iterator to proceed forward along a music track, from the start:

// Create a new iterator, which automatically points at the first event
// on the iterator's music track.
 
bool hasCurrentEvent;
MusicEventIteratorHasCurrentEvent (myIterator, &hasCurrentEvent);
while (hasCurrentEvent) {
        // do work here
    MusicEventIteratorNextEvent (myIterator);
    MusicEventIteratorHasCurrentEvent (myIterator, &hasCurrentEvent);
}
Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
MusicPlayer.h

MusicEventIteratorPreviousEvent

Positions a music event iterator at the previous event on a music track.

OSStatus MusicEventIteratorPreviousEvent (
   MusicEventIterator  inIterator
);
Parameters
inIterator

The music event iterator to reposition.

Return Value

A result code.

Discussion

Use this function to decrement a music event iterator, moving it backward through a music track’s events.

If an iterator is at the first event of a track when you call this function, the iterator position remains unchanged and this function returns an error.

The following code snippet illustrates how to use a music event iterator to proceed backward along a music track, from the end:

// Points iterator just beyond the final event on its music track
MusicEventIteratorSeek (myIterator, kMusicTimeStamp_EndOfTrack);
 
bool hasPreviousEvent;
MusicEventIteratorHasPreviousEvent (myIterator, &hasPreviousEvent);
while (hasPreviousEvent) {
    MusicEventIteratorPreviousEvent (myIterator);
        // do work here
    MusicEventIteratorHasPreviousEvent (myIterator, &hasPreviousEvent);
}
Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
MusicPlayer.h

MusicEventIteratorSeek

Positions a music event iterator at a specified timestamp, in beats.

OSStatus MusicEventIteratorSeek (
   MusicEventIterator  inIterator,
   MusicTimeStamp      inTimeStamp
);
Parameters
inIterator

The music event iterator that you want to position along a music track.

inTimeStamp

The new position for the music event iterator, in beats.

If there is no music event at the specified time, on output the iterator points to the first event after that time.

To position the iterator immediately beyond the final event of a music track, specify kMusicTimeStamp_EndOfTrack for this parameter. You can then call the MusicEventIteratorPreviousEvent to backtrack to the final event of the music track.

To position the iterator at the first event of a music track, specify a value of 0 for this parameter.

Return Value

A result code.

Availability
  • Available in OS X v10.0 and later.
Declared In
MusicPlayer.h

MusicEventIteratorSetEventInfo

Sets information for the event at a music event iterator’s current position.

OSStatus MusicEventIteratorSetEventInfo (
   MusicEventIterator  inIterator,
   MusicEventType      inEventType,
   const void          *inEventData
);
Parameters
inIterator

The music event iterator whose current event you want to set.

inEventType

The type of music event that you are specifying. For possible event types, see “Music Event Types.”

inEventData

The event data that you are specifying. The size and type of the data must be appropriate for the music event type you specify in the inEventType parameter.

Return Value

A result code.

Discussion

Use this function to set the music event type and event data for the event that a music event iterator is positioned at. This function doesn’t allow you to change an event’s timestamp; to do that, call the MusicEventIteratorSetEventTime function.

Availability
  • Available in OS X v10.2 and later.
See Also
Declared In
MusicPlayer.h

MusicEventIteratorSetEventTime

Sets the timestamp for the event at a music event iterator’s current position.

OSStatus MusicEventIteratorSetEventTime (
   MusicEventIterator  inIterator,
   MusicTimeStamp      inTimeStamp
);
Parameters
inIterator

The music event iterator whose current event you want to change the timestamp of.

inTimeStamp

The new timestamp for the event, in beats.

Return Value

A result code.

Discussion

After calling this function, the music event iterator remains positioned at the same event. However, because the event has been moved to a new location on the iterator’s music track, the iterator may no longer have a next or previous event. You can test this by calling MusicEventIteratorHasPreviousEvent and MusicEventIteratorHasNextEvent.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
MusicPlayer.h

NewMusicEventIterator

Creates a new music event iterator.

OSStatus NewMusicEventIterator (
   MusicTrack          inTrack,
   MusicEventIterator  *outIterator
);
Parameters
inTrack

The music track to iterate over.

outIterator

On output, the newly created music event iterator.

Return Value

A result code.

Discussion

A newly-created music event iterator points at the first event on the music track specified in the inTrack parameter.

If you edit a music track after associating it with a music event iterator, you must discard iterator and create a new one. Perform the following steps after editing the track:

  1. Obtain the current position using the MusicEventIteratorGetEventInfo function, and save the position.

  2. Dispose of the music event iterator.

  3. Create a new iterator.

  4. Seek to the desired position using the MusicEventIteratorSeek function.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
MusicPlayer.h

Data Types

MusicEventIterator

A music event iterator sequentially handles events on a music track.

typedef struct OpaqueMusicEventIterator *MusicEventIterator;
Availability
  • Available in OS X v10.0 and later.
Declared In
MusicPlayer.h

Constants

End of Track

The time, in beats, immediately beyond the end of a music track.

#define kMusicTimeStamp_EndOfTrack DBL_MAX
Constants
kMusicTimeStamp_EndOfTrack

Indicates a time immediately beyond the last music event in a music track. Use this value when selecting all music events starting at a designated time and extending to, and including, the last event in a track. Also use this value to position an iterator for moving backward through a track, from the end to the start. See also “Editing Music Tracks” and MusicEventIteratorSeek.

Available in OS X v10.0 and later.

Declared in MusicPlayer.h.

Music Event Types

MIDI and other music event types, used by music event iterator functions.

enum {
   kMusicEventType_NULL = 0,
   kMusicEventType_ExtendedNote,
   kMusicEventType_ExtendedControl,
   kMusicEventType_ExtendedTempo,
   kMusicEventType_User,
   kMusicEventType_Meta,
   kMusicEventType_MIDINoteMessage,
   kMusicEventType_MIDIChannelMessage,
   kMusicEventType_MIDIRawData,
   kMusicEventType_Parameter,
   kMusicEventType_AUPreset,
   kMusicEventType_Last
};
typedef UInt32 MusicEventType;
Constants
kMusicEventType_NULL

A null music event.

Available in OS X v10.0 and later.

Declared in MusicPlayer.h.

kMusicEventType_ExtendedNote

A non-MIDI music event with variable number of parameters.

Available in OS X v10.0 and later.

Declared in MusicPlayer.h.

kMusicEventType_ExtendedControl

A non-MIDI control event.

Available in OS X v10.0 and later.

Declared in MusicPlayer.h.

kMusicEventType_ExtendedTempo

An event that signals a change in tempo, in beats-per-minute.

Available in OS X v10.0 and later.

Declared in MusicPlayer.h.

kMusicEventType_User

User-defined data.

Available in OS X v10.0 and later.

Declared in MusicPlayer.h.

kMusicEventType_Meta

A standard MIDI file metaevent.

Available in OS X v10.0 and later.

Declared in MusicPlayer.h.

kMusicEventType_MIDINoteMessage

A MIDI note-on message, including duration.

Available in OS X v10.0 and later.

Declared in MusicPlayer.h.

kMusicEventType_MIDIChannelMessage

A MIDI channel message, other than note control.

Available in OS X v10.0 and later.

Declared in MusicPlayer.h.

kMusicEventType_MIDIRawData

MIDI system-exclusive data.

Available in OS X v10.0 and later.

Declared in MusicPlayer.h.

kMusicEventType_Parameter

An audio unit parameter event.

Available in OS X v10.2 and later.

Declared in MusicPlayer.h.

kMusicEventType_AUPreset

An event containing an audio unit user preset dictionary.

Available in OS X v10.3 and later.

Declared in MusicPlayer.h.

kMusicEventType_Last

A marker that indicates the final enumerator in the enumeration.

Available in OS X v10.0 through OS X v10.6.

Declared in MusicPlayer.h.



© 2009 Apple Inc. All Rights Reserved. (Last updated: 2009-11-24)

Did this document help you? Yes It's good, but... Not helpful...