iTunes COM Interface: IITUserPlaylist 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

IITUserPlaylist Interface Reference

Inheritance diagram for IITUserPlaylist:

IITPlaylist IITObject List of all members.

Detailed Description

Represents a user-defined playlist.

A user playlist includes both smart and manual user-defined playlists.

Public Member Functions

Methods
HRESULT AddFile ([in] BSTR filePath,[out, retval] IITOperationStatus **iStatus)
 Add a file or files inside a folder to the playlist.
HRESULT AddFiles ([in] VARIANT *filePaths,[out, retval] IITOperationStatus **iStatus)
 Add an array of files and/or folders to the playlist.
HRESULT AddURL ([in] BSTR url,[out, retval] IITURLTrack **iURLTrack)
 Add a streaming audio URL to the playlist.
HRESULT AddTrack ([in] VARIANT *iTrackToAdd,[out, retval] IITTrack **iAddedTrack)
 Add an existing track to the playlist.
HRESULT CreatePlaylist ([in] BSTR playlistName,[out, retval] IITPlaylist **iPlaylist)
 Creates a new playlist in a folder playlist.
HRESULT CreateFolder ([in] BSTR folderName,[out, retval] IITPlaylist **iFolder)
 Creates a new folder in a folder playlist.
HRESULT Reveal ()
 Reveals the user playlist in the main browser window.
Properties
HRESULT Shared ([out, retval] VARIANT_BOOL *isShared)
 Returns true if this playlist is being shared.
HRESULT Shared ([in] VARIANT_BOOL shouldBeShared)
 Control whether this playlist should be shared.
HRESULT Smart ([out, retval] VARIANT_BOOL *isSmart)
 Returns true if this playlist is a smart playlist.
HRESULT SpecialKind ([out, retval] ITUserPlaylistSpecialKind *specialKind)
 Returns the special kind of the playlist.
HRESULT Parent ([out, retval] IITUserPlaylist **iParentPlayList)
 Returns the parent folder of the playlist. If the playlist is not inside a folder, it has no parent.
HRESULT Parent ([in] VARIANT *iParent)
 Sets the parent folder of the playlist.

Member Function Documentation

HRESULT IITUserPlaylist::AddFile (  [in] BSTR  filePath,
[out, retval] IITOperationStatus **  iStatus
) 
 

Add a file or files inside a folder to the playlist.

You cannot use this method to add a file that requires conversion to be added (e.g. a CD track), use IiTunes::ConvertFile() or IiTunes::ConvertFile2() instead. If you add a folder that contains files that require conversion, they will be skipped.

Parameters:
filePath The full path to the file or folder to add.
iStatus Returns an IITOperationStatus object corresponding to the asynchronous operation. If an error occurs, or no files were added, this will be set to NULL.
Return values:
S_OK The operation was successful.
E_POINTER filePath or iStatus is NULL.
E_INVALIDARG filePath is empty or too long, or refers to a file that would require conversion.
ITUNES_E_OBJECTLOCKED This playlist is read-only.
ITUNES_E_OBJECTDELETED This playlist has been deleted.
E_FAIL An unexpected error occurred.

HRESULT IITUserPlaylist::AddFiles (  [in] VARIANT *  filePaths,
[out, retval] IITOperationStatus **  iStatus
) 
 

Add an array of files and/or folders to the playlist.

You cannot use this method to add a file that requires conversion to be added (e.g. a CD track), use IiTunes::ConvertFile() or IiTunes::ConvertFile2() instead. If you add a folder that contains files that require conversion, they will be skipped.

Parameters:
filePaths The single-dimensioned array of full paths to each file or folder. filePaths can be of type VT_ARRAY|VT_VARIANT, where each entry is a VT_BSTR, or VT_ARRAY|VT_BSTR. You can also pass a JScript Array object.
iStatus Returns an IITOperationStatus object corresponding to the asynchronous operation. If an error occurs, or no files were added, this will be set to NULL.
Return values:
S_OK The operation was successful.
E_POINTER filePaths or iStatus is NULL.
E_INVALIDARG filePaths is the wrong VARIANT type, or includes a file that would require conversion.
ITUNES_E_OBJECTLOCKED This playlist is read-only.
ITUNES_E_OBJECTDELETED This playlist has been deleted.
E_FAIL An unexpected error occurred.

HRESULT IITUserPlaylist::AddTrack (  [in] VARIANT *  iTrackToAdd,
[out, retval] IITTrack **  iAddedTrack
) 
 

Add an existing track to the playlist.

You cannot use this method to add a CD track (ITTrackKindCD) to another playlist, use IiTunes::ConvertTrack() or IiTunes::ConvertTrack2() instead.

You cannot add a shared library track (ITTrackKindSharedLibrary) to another playlist.

Parameters:
iTrackToAdd The track to add. This is a VARIANT of type VT_DISPATCH that points to an IITTrack.
iAddedTrack Returns an IITTrack object corresponding to the new track.
Return values:
S_OK The operation was successful.
E_POINTER iTrackToAdd or iAddedTrack is NULL.
E_INVALIDARG iTrackToAdd is the wrong VARIANT type, or is a CD or shared track.
ITUNES_E_OBJECTLOCKED This playlist is read-only.
ITUNES_E_OBJECTDELETED This playlist has been deleted.
E_FAIL An unexpected error occurred.

HRESULT IITUserPlaylist::AddURL (  [in] BSTR  url,
[out, retval] IITURLTrack **  iURLTrack
) 
 

Add a streaming audio URL to the playlist.

Parameters:
url The URL to add. The length of the URL can be 255 characters or less.
iURLTrack Returns an IITURLTrack object corresponding to the new track.
Return values:
S_OK The operation was successful.
E_POINTER url or iURLTrack is NULL.
E_INVALIDARG url is empty or too long.
ITUNES_E_OBJECTLOCKED This playlist is read-only.
ITUNES_E_OBJECTDELETED This playlist has been deleted.
E_FAIL An unexpected error occurred.

HRESULT IITUserPlaylist::CreateFolder (  [in] BSTR  folderName,
[out, retval] IITPlaylist **  iFolder
) 
 

Creates a new folder in a folder playlist.

This playlist must be a folder playlist. If folderName is NULL or empty, the folder will be created with a default name.

Note:
This method is available in iTunes 6.0.2 and later (iTunes type library 1.7 and later).
Parameters:
folderName The name of the new folder (may be NULL or empty).
iFolder Returns an IITPlaylist object corresponding to the new folder.
Return values:
S_OK The operation was successful.
E_POINTER iFolder is NULL.
E_INVALIDARG This playlist is not a folder playlist.
ITUNES_E_OBJECTDELETED This playlist has been deleted.
E_FAIL An unexpected error occurred.

HRESULT IITUserPlaylist::CreatePlaylist (  [in] BSTR  playlistName,
[out, retval] IITPlaylist **  iPlaylist
) 
 

Creates a new playlist in a folder playlist.

This playlist must be a folder playlist. If playlistName is NULL or empty, the playlist will be created with a default name.

Note:
This method is available in iTunes 6.0.2 and later (iTunes type library 1.7 and later).
Parameters:
playlistName The name of the new playlist (may be NULL or empty).
iPlaylist Returns an IITPlaylist object corresponding to the new playlist.
Return values:
S_OK The operation was successful.
E_POINTER iPlaylist is NULL.
E_INVALIDARG This playlist is not a folder playlist.
ITUNES_E_OBJECTDELETED This playlist has been deleted.
E_FAIL An unexpected error occurred.

HRESULT IITUserPlaylist::Parent (  [in] VARIANT *  iParent  ) 
 

Sets the parent folder of the playlist.

iParent is a VARIANT of type VT_DISPATCH that points to a folder IITUserPlaylist.

Specifying an empty or NULL iParent will move the playlist outside of all folders.

Note:
This method is available in iTunes 6.0.2 and later (iTunes type library 1.7 and later).
Parameters:
iParent The new parent folder. This is a VARIANT of type VT_DISPATCH that points to a folder IITUserPlaylist.
Return values:
S_OK The operation was successful.
E_INVALIDARG iParent is the wrong VARIANT type, or is not a folder playlist.
ITUNES_E_OBJECTDELETED This playlist has been deleted.
E_FAIL An unexpected error occurred.

HRESULT IITUserPlaylist::Parent (  [out, retval] IITUserPlaylist **  iParentPlayList  ) 
 

Returns the parent folder of the playlist. If the playlist is not inside a folder, it has no parent.

Note:
This property is available in iTunes 5.0 and later (iTunes type library 1.5 and later).
Parameters:
iParentPlayList Returns an IITUserPlaylist object corresponding to the parent folder. Will be set to NULL if this playlist is not inside a folder.
Return values:
S_OK The operation was successful.
S_FALSE This playlist is not inside a folder.
E_POINTER iParentPlayList is NULL.
ITUNES_E_OBJECTDELETED This playlist has been deleted.
E_FAIL An unexpected error occurred.

HRESULT IITUserPlaylist::Reveal (   ) 
 

Reveals the user playlist in the main browser window.

Note:
This method is available in iTunes 7.4 and later (iTunes type library 1.10 and later).
Return values:
S_OK The operation was successful.
ITUNES_E_OBJECTDELETED This playlist has been deleted.
E_FAIL An unexpected error occurred.

HRESULT IITUserPlaylist::Shared (  [in] VARIANT_BOOL  shouldBeShared  ) 
 

Control whether this playlist should be shared.

Parameters:
shouldBeShared True if this playlist should be shared.
Return values:
S_OK The operation was successful.
E_POINTER shouldBeShared is NULL.
ITUNES_E_OBJECTLOCKED Sharing is disabled, or is enabled for all playlists (not selected playlists), or playlist can't be shared.
ITUNES_E_OBJECTDELETED This playlist has been deleted.
E_FAIL An unexpected error occurred.

HRESULT IITUserPlaylist::Shared (  [out, retval] VARIANT_BOOL *  isShared  ) 
 

Returns true if this playlist is being shared.

Parameters:
isShared Returns true if this playlist is being shared.
Return values:
S_OK The operation was successful.
E_POINTER isShared is NULL.
ITUNES_E_OBJECTDELETED This playlist has been deleted.
E_FAIL An unexpected error occurred.

HRESULT IITUserPlaylist::Smart (  [out, retval] VARIANT_BOOL *  isSmart  ) 
 

Returns true if this playlist is a smart playlist.

Note that smart playlists cannot be modified.

Parameters:
isSmart Returns true if this playlist is a smart playlist.
Return values:
S_OK The operation was successful.
E_POINTER isSmart is NULL.
ITUNES_E_OBJECTDELETED This playlist has been deleted.
E_FAIL An unexpected error occurred.

HRESULT IITUserPlaylist::SpecialKind (  [out, retval] ITUserPlaylistSpecialKind *  specialKind  ) 
 

Returns the special kind of the playlist.

Note:
This property is available in iTunes 4.9 and later (iTunes type library 1.4 and later).
Parameters:
specialKind Returns the special kind of the playlist.
Return values:
S_OK The operation was successful.
E_POINTER specialKind is NULL.
ITUNES_E_OBJECTDELETED This playlist 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.

previous page start next page