iTunes COM Interface: _IiTunesEvents Interface Reference

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.

    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.");


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.

_IiTunesEvents Interface Reference

Detailed Description

Public Member Functions

Member Function Documentation