iTunes COM Interface: _IiTunesEvents Interface Reference

iTunes COM

previous page next page
Main Page | Namespace List | Class Hierarchy | Alphabetical List | Class List | File List | Namespace Members | Class Members | File Members | Related Pages

_IiTunesEvents Interface Reference

List of all members.

Detailed Description

Defines the outgoing event interface of the IiTunes interface.

Public Member Functions

HRESULT OnDatabaseChangedEvent ([in] VARIANT deletedObjectIDs,[in] VARIANT changedObjectIDs)
 The ITEventDatabaseChanged event is fired when the iTunes database is changed.
HRESULT OnPlayerPlayEvent ([in] VARIANT iTrack)
 The ITEventPlayerPlay event is fired when a track begins playing.
HRESULT OnPlayerStopEvent ([in] VARIANT iTrack)
 The ITEventPlayerStop event is fired when a track stops playing.
HRESULT OnPlayerPlayingTrackChangedEvent ([in] VARIANT iTrack)
 The ITEventPlayerPlayingTrackChanged event is fired when information about the currently playing track has changed.
HRESULT OnCOMCallsDisabledEvent ([in] ITCOMDisabledReason reason)
 The ITEventCOMCallsDisabled event is fired when calls to the iTunes COM interface will be deferred.
HRESULT OnCOMCallsEnabledEvent ()
 The ITEventCOMCallsEnabled event is fired when calls to the iTunes COM interface will no longer be deferred.
HRESULT OnQuittingEvent ()
 The ITEventQuitting event is fired when iTunes is about to quit.
HRESULT OnAboutToPromptUserToQuitEvent ()
 The ITEventAboutToPromptUserToQuit event is fired when iTunes is about prompt the user to quit.
HRESULT OnSoundVolumeChangedEvent ([in] long newVolume)
 The ITEventSoundVolumeChanged event is fired when the sound output volume has changed.

Member Function Documentation

HRESULT _IiTunesEvents::OnAboutToPromptUserToQuitEvent (   ) 
 

The ITEventAboutToPromptUserToQuit event is fired when iTunes is about prompt the user to quit.

This event gives clients the opportunity to prevent the warning dialog prompt from occurring.

If the user attempts to quit iTunes while a client still has outstanding iTunes COM objects instantiated, iTunes will display a warning dialog. This event is fired just before the warning dialog is shown. iTunes will then wait up to 5 seconds for clients to release any outstanding iTunes COM objects. If all objects are released during this time, the warning dialog will not be shown and iTunes will quit immediately.

Otherwise, the warning dialog will be shown. If the user chooses to quit iTunes anyway, the ITEventQuitting event is fired. See _IiTunesEvents::OnQuittingEvent() for more details.

Note:
This event is available in iTunes 4.7 and later (iTunes type library 1.2 and later).

HRESULT _IiTunesEvents::OnCOMCallsDisabledEvent (  [in] ITCOMDisabledReason  reason  ) 
 

The ITEventCOMCallsDisabled event is fired when calls to the iTunes COM interface will be deferred.

Typically, iTunes will defer COM calls when any modal dialog is being displayed. When the user dismisses the last modal dialog, COM calls will be enabled again, and any deferred COM calls will be executed. You can use this event to avoid making a COM call which will be deferred.

Note:
This event is available in iTunes 4.6 and later (iTunes type library 1.1 and later).
Parameters:
reason The reason the COM interface is being disabled. This is typically ITCOMDisabledReasonDialog.

HRESULT _IiTunesEvents::OnCOMCallsEnabledEvent (   ) 
 

The ITEventCOMCallsEnabled event is fired when calls to the iTunes COM interface will no longer be deferred.

Typically, iTunes will defer COM calls when any modal dialog is being displayed. When the user dismisses the last modal dialog, COM calls will be enabled again, and any deferred COM calls will be executed.

Note:
This event is available in iTunes 4.6 and later (iTunes type library 1.1 and later).

HRESULT _IiTunesEvents::OnDatabaseChangedEvent (  [in] VARIANT  deletedObjectIDs,
[in] VARIANT  changedObjectIDs
) 
 

The ITEventDatabaseChanged event is fired when the iTunes database is changed.

Each parameter is a two-dimensional SAFEARRAY of VARIANTs, where each VARIANT in the array is of type VT_I4. The first dimension is the number of objects. The second dimension is always 4 and specifies each of the 4 IITObject IDs, where index 0 is the source ID, index 1 is the playlist ID, index 2 is the track ID, and index 3 is the track database ID. For more information on object IDs, see IITObject.

Note that you can use IiTunes::GetITObjectByID() to retrieve changed IITObjects, but not for deleted objects (since they no longer exist).

Even a simple change to the database can result in multiple changed objects. For example, if you delete a user playlist containing a single track, deletedObjectIDs will contain both the playlist and its track, and changedObjectIDs will contain at a minimum the main library source, as well as any playlists that also refer the same track (along with the track in each playlist).

You should avoid doing long operations during processing of this event (e.g. enumerating the entire iTunes library), since the iTunes user interface thread will be blocked until this call returns.

Example JScript code: 

    var     iTunesApp = WScript.CreateObject("iTunes.Application");
    var     numDBChanges = 0;
    var     maxDBChanges = 3;

    function ITEventTest_OnDatabaseChangedEvent(deletedObjects, changedObjects)
    {
        var     numObjects;
        var     i;
        var     sourceID, playlistID, trackID, databaseID;
        
        numDBChanges++;
        WScript.Echo("Database change " + numDBChanges);
        
        if (deletedObjects != undefined)
        {
            // calculate the number of objects from the deletedObjects VBArray object
            numObjects = (deletedObjects.ubound() - deletedObjects.lbound() + 1);
            WScript.Echo(numObjects + " deleted objects");
            
            // enumerate the objects that were deleted
            for (i = deletedObjects.lbound(); i <= deletedObjects.ubound(); i++)
            {
                sourceID = deletedObjects.getItem(i, 0);
                playlistID = deletedObjects.getItem(i, 1);
                trackID = deletedObjects.getItem(i, 2);
                databaseID = deletedObjects.getItem(i, 3);
                
                // note - since the object has been deleted, we can't ask for it
                // using iTunesApp.GetITObjectByID()

                WScript.Echo("  sourceID " + sourceID +
                    " playlistID " + playlistID +
                    " trackID " + trackID +
                    " databaseID " + databaseID);
            }
        }

        if (changedObjects != undefined)
        {
            // calculate the number of objects from the changedObjects VBArray object
            numObjects = (changedObjects.ubound() - changedObjects.lbound() + 1);
            WScript.Echo(numObjects + " changed objects");

            // enumerate the objects that were added or changed
            for (i = changedObjects.lbound(); i <= changedObjects.ubound(); i++)
            {
                sourceID = changedObjects.getItem(i, 0);
                playlistID = changedObjects.getItem(i, 1);
                trackID = changedObjects.getItem(i, 2);
                databaseID = changedObjects.getItem(i, 3);
                
                var changedObject = iTunesApp.GetITObjectByID(sourceID, playlistID, trackID, databaseID);
                
                WScript.Echo("  (" + changedObject.Name + ") sourceID " + sourceID +
                    " playlistID " + playlistID +
                    " trackID " + trackID +
                    " databaseID " + databaseID);
            }
        }
    }

    // attach event sink
    WScript.ConnectObject(iTunesApp, "ITEventTest_");

    WScript.Echo("Waiting for database changes...");

    while (numDBChanges < maxDBChanges)
    {
        WScript.Sleep(1000);
    }

    // disconnect event sink
    WScript.DisconnectObject(iTunesApp);

    WScript.Echo("Database changed " + numDBChanges + " times, exiting.");

Parameters:
deletedObjectIDs A two-dimensional array specifying the objects that have been deleted.
changedObjectIDs A two-dimensional array specifying the objects that have been added or changed.

HRESULT _IiTunesEvents::OnPlayerPlayEvent (  [in] VARIANT  iTrack  ) 
 

The ITEventPlayerPlay event is fired when a track begins playing.

When iTunes switches to playing another track, you will received an ITEventPlayerStop event followed by an ITEventPlayerPlay event, unless it is playing joined CD tracks (see _IiTunesEvents::OnPlayerPlayingTrackChangedEvent).

Parameters:
iTrack An IITTrack object (a VARIANT of type VT_DISPATCH) corresponding to the track that has started playing.

HRESULT _IiTunesEvents::OnPlayerPlayingTrackChangedEvent (  [in] VARIANT  iTrack  ) 
 

The ITEventPlayerPlayingTrackChanged event is fired when information about the currently playing track has changed.

This event is fired when the user changes information about the currently playing track (e.g. the name of the track).

This event is also fired when iTunes plays the next joined CD track in a CD playlist, since joined CD tracks are treated as a single track.

Parameters:
iTrack An IITTrack object (a VARIANT of type VT_DISPATCH) corresponding to the track that is now playing.

HRESULT _IiTunesEvents::OnPlayerStopEvent (  [in] VARIANT  iTrack  ) 
 

The ITEventPlayerStop event is fired when a track stops playing.

When iTunes switches to playing another track, you will received an ITEventPlayerStop event followed by an ITEventPlayerPlay event, unless it is playing joined CD tracks (see _IiTunesEvents::OnPlayerPlayingTrackChangedEvent).

Parameters:
iTrack An IITTrack object (a VARIANT of type VT_DISPATCH) corresponding to the track that has stopped playing.

HRESULT _IiTunesEvents::OnQuittingEvent (   ) 
 

The ITEventQuitting event is fired when iTunes is about to quit.

If the user attempts to quit iTunes while a client still has outstanding iTunes COM objects instantiated, iTunes will display a warning dialog. The user can still choose to quit iTunes anyway, in which case this event will be fired. After this event is fired, any existing iTunes COM objects will no longer be valid.

This event is only used to notify clients that iTunes is quitting, clients cannot prevent this from happening.

Note:
This event is available in iTunes 4.6 and later (iTunes type library 1.1 and later).

HRESULT _IiTunesEvents::OnSoundVolumeChangedEvent (  [in] long  newVolume  ) 
 

The ITEventSoundVolumeChanged event is fired when the sound output volume has changed.

Note:
This event is available in iTunes 4.7 and later (iTunes type library 1.2 and later).
Parameters:
newVolume The new sound output volume (0 = minimum, 100 = maximum).

Generated on Fri Mar 13 12:50:54 2009 for iTunes 8.1.0.52
©2004-2007 Apple Computer, Inc.

previous page start next page