iTunes COM Interface: IITObject Interface Reference

iTunes COM

IITObject Interface Reference

Inheritance diagram for IITObject:

IITPlaylist IITSource IITTrack IITAudioCDPlaylist IITLibraryPlaylist IITUserPlaylist IITIPodSource IITFileOrCDTrack IITURLTrack List of all members.

Detailed Description

Defines a source, playlist or track.

An IITObject uniquely identifies a source, playlist, or track in iTunes using four separate IDs. These are runtime IDs, they are only valid while the current instance of iTunes is running.

As of iTunes 7.7, you can also identify an IITObject using a 64-bit persistent ID, which is valid across multiple invocations of iTunes.

The main use of the IITObject interface is to allow clients to track iTunes database changes using _IiTunesEvents::OnDatabaseChangedEvent().

You can retrieve an IITObject with a specified runtime ID using IiTunes::GetITObjectByID().

An IITObject will always have a valid, non-zero source ID.

An IITObject corresponding to a playlist or track will always have a valid playlist ID. The playlist ID will be zero for a source.

An IITObject corresponding to a track will always have a valid track and track database ID. These IDs will be zero for a source or playlist.

A track ID is unique within the track's playlist. A track database ID is unique across all playlists. For example, if the same music file is in two different playlists, each of the tracks could have different track IDs, but they will have the same track database ID.

An IITObject also has a 64-bit persistent ID which can be used to identify the IITObject across multiple invocations of iTunes. Note that persistent IDs are only really persistent for objects that iTunes stores in its database. For example, the persistent IDs for transient objects like radio streams and objects from audio CDs will differ across multiple invocations of iTunes.

The persistent ID was exposed in the COM interface starting with iTunes 7.7, so methods and properties to retrieve the persistent ID could not be added to the IITObject interface without breaking existing COM clients. You can find these routines in IiTunes instead:

You can retrieve a source, playlist, or track with a specified persistent ID using the ItemByPersistentID property of the appropriate collection interface:

Public Member Functions

Methods
HRESULT GetITObjectIDs ([out] long *sourceID,[out] long *playlistID,[out] long *trackID,[out] long *databaseID)
 Returns the four IDs that uniquely identify this object.
Properties
HRESULT Name ([out, retval] BSTR *name)
 Returns the name of the object.
HRESULT Name ([in] BSTR name)
 Set the name of the object.
HRESULT Index ([out, retval] long *index)
 Returns the index of the object in internal application order.
HRESULT SourceID ([out, retval] long *sourceID)
 Returns the ID that identifies the source.
HRESULT PlaylistID ([out, retval] long *playlistID)
 Returns the ID that identifies the playlist.
HRESULT TrackID ([out, retval] long *trackID)
 Returns the ID that identifies the track within the playlist.
HRESULT TrackDatabaseID ([out, retval] long *databaseID)
 Returns the ID that identifies the track, independent of its playlist.

Member Function Documentation

HRESULT IITObject::GetITObjectIDs [out] long *  sourceID,
[out] long *  playlistID,
[out] long *  trackID,
[out] long *  databaseID
 

Returns the four IDs that uniquely identify this object.

This method is not usable from scripting clients, since it returns multiple output parameters. Scripting clients must use the IITObject::SourceID(), IITObject::PlaylistID(), IITObject::TrackID(), and IITObject::TrackDatabaseID() properties instead.

These are runtime IDs, they are only valid while the current instance of iTunes is running.

Parameters:
sourceID Returns the ID that identifies the source. Valid for a source, playlist, or track.
playlistID Returns the ID that identifies the playlist. Valid for a playlist or track. Will be zero for a source.
trackID Returns the ID that identifies the track within the playlist. Valid for a track. Will be zero for a source or playlist.
databaseID Returns the ID that identifies the track, independent of its playlist. Valid for a track. Will be zero for a source or playlist.
Return values:
S_OK The operation was successful.
E_POINTER sourceID, playlistID, trackID, or databaseID is NULL.
ITUNES_E_OBJECTDELETED The source, playlist, or track corresponding to this object has been deleted.
E_FAIL An unexpected error occurred.

HRESULT IITObject::Index [out, retval] long *  index  ) 
 

Returns the index of the object in internal application order.

You can pass this index to IITSourceCollection::Item(), IITPlaylistCollection::Item(), or IITTrackCollection::Item() to retrieve this object.

For tracks, this index is independent of play order. The play order index of a track can be retrieved using IITTrack::PlayOrderIndex().

Parameters:
index Returns the index of the object in internal application order.
Return values:
S_OK The operation was successful.
E_POINTER index is NULL.
ITUNES_E_OBJECTDELETED The source, playlist, or track corresponding to this object has been deleted.
E_FAIL An unexpected error occurred.

HRESULT IITObject::Name [in] BSTR  name  ) 
 

Set the name of the object.

You can only change the name of a track or playlist. You cannot change the name of a source.

Object names are not unique in iTunes, e.g. multiple playlists may share the same name.

Parameters:
name The new name of the object.
Return values:
S_OK The operation was successful.
E_POINTER name is NULL or empty.
ITUNES_E_OBJECTLOCKED The source, playlist, or track cannot be renamed.
ITUNES_E_OBJECTDELETED The source, playlist, or track corresponding to this object has been deleted.
E_FAIL An unexpected error occurred.

HRESULT IITObject::Name [out, retval] BSTR *  name  ) 
 

Returns the name of the object.

For a source, this is the name of the source (as displayed in the Source list).

For a playlist, this is the name of the playlist.

For a track, this is the name of the track.

Object names are not unique in iTunes, e.g. multiple playlists may share the same name.

Parameters:
name Returns the name of the object.
Return values:
S_OK The operation was successful.
E_POINTER name is NULL.
ITUNES_E_OBJECTDELETED The source, playlist, or track corresponding to this object has been deleted.
E_FAIL An unexpected error occurred.

HRESULT IITObject::PlaylistID [out, retval] long *  playlistID  ) 
 

Returns the ID that identifies the playlist.

Valid for a playlist or track. Will be zero for a source.

This is a runtime ID, it is only valid while the current instance of iTunes is running.

Parameters:
playlistID Returns the ID that identifies the playlist.
Return values:
S_OK The operation was successful.
E_POINTER playlistID is NULL.
ITUNES_E_OBJECTDELETED The playlist or track corresponding to this object has been deleted.
E_FAIL An unexpected error occurred.

HRESULT IITObject::SourceID [out, retval] long *  sourceID  ) 
 

Returns the ID that identifies the source.

Valid for a source, playlist, or track.

This is a runtime ID, it is only valid while the current instance of iTunes is running.

Parameters:
sourceID Returns the ID that identifies the source.
Return values:
S_OK The operation was successful.
E_POINTER sourceID is NULL.
ITUNES_E_OBJECTDELETED The source, playlist, or track corresponding to this object has been deleted.
E_FAIL An unexpected error occurred.

HRESULT IITObject::TrackDatabaseID [out, retval] long *  databaseID  ) 
 

Returns the ID that identifies the track, independent of its playlist.

Valid for a track. Will be zero for a source or playlist. If the same music file is in two different playlists, each of the tracks will have the same track database ID.

This is a runtime ID, it is only valid while the current instance of iTunes is running.

Parameters:
databaseID Returns the ID that identifies the track, independent of its playlist.
Return values:
S_OK The operation was successful.
E_POINTER databaseID is NULL.
ITUNES_E_OBJECTDELETED The track corresponding to this object has been deleted.
E_FAIL An unexpected error occurred.

HRESULT IITObject::TrackID [out, retval] long *  trackID  ) 
 

Returns the ID that identifies the track within the playlist.

Valid for a track. Will be zero for a source or playlist.

This is a runtime ID, it is only valid while the current instance of iTunes is running.

Parameters:
trackID Returns the ID that identifies the track within the playlist.
Return values:
S_OK The operation was successful.
E_POINTER trackID is NULL.
ITUNES_E_OBJECTDELETED The track corresponding to this object has been deleted.
E_FAIL An unexpected error occurred.


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