Mac Developer Library

Developer

ITLibrary Class Reference

Options
Deployment Target:

On This Page

ITLibrary

The ITLibrary class serves as the entry point to the iTunesLibrary framework. The properties and methods of ITLibrary may be used to retrieve media items (tracks) and playlists from the user's iTunes library. ITLibrary also provides methods for extracting artwork from a media file that may or may not be in the iTunes library. This functionality is provided to sandboxed and non-sandboxed applications wanting to re-use iTunes' ability to extract artwork.

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Not Applicable Not Applicable
  • Retrieves the artwork from a media file that may or may not be in the iTunes library.

    Declaration

    Objective-C

    - (ITLibArtwork*) artworkForMediaFile:(NSURL*)mediaFileURL;

    Parameters

    mediaFileURL

    The URL of the media file whose artwork is to be retrieved. The media file may or may not be in the iTunes library.

    Return Value

    An ITLibArtwork instance representing the media file artwork, or nil if the media file does not contain any artwork or the artwork cannot be extracted.

    Import Statement

  • Initializes an instance of ITLibrary.

    Declaration

    Objective-C

    - (id) initWithAPIVersion:(NSString*)requestedAPIVersion error:(NSError **)error;

    Parameters

    requestedAPIVersion

    The version of the iTunesLibrary framework API that the application is requesting. Set this parameter to "1.0" if unknown. The only supported version at the moment is "1.0".

    error

    A pointer to a variable that will receive an NSError if this method fails. Set this parameter to nil if the caller does not care about the error.

    Return Value

    An ITLibrary instance that can be used to retrieve media entities, or nil if this method fails.

    Discussion

    Upon initialization of the ITLibrary class, the default iTunes database for the current user is read and parsed. At this point all media entities (tracks) and playlists are cached in memory until the object is deallocated.

    Listing 1Initializing an ITLibrary
    • #import <iTunesLibrary/ITLibrary.h>
    • NSError * error = nil;
    • ITLibrary* library = [[ITLibrary alloc] initWithAPIVersion:@"1.0" error:&error];
    • if (library)
    • {
    • NSArray playlists = library.allPlaylists; // <- NSArray of ITLibPlaylist
    • NSArray mediaItems = library.allMediaItems; // <- NSArray of ITLibMediaItem
    • }

    See also libraryWithAPIVersion:error:.

    Import Statement

  • Creates and initializes an instance of ITLibrary.

    Declaration

    Objective-C

    + (id) libraryWithAPIVersion:(NSString*)requestedAPIVersion error:(NSError **)error;

    Parameters

    requestedAPIVersion

    The version of the iTunesLibrary framework API that the application is requesting. Set this parameter to "1.0" if unknown. The only supported version at the moment is "1.0".

    error

    A pointer to a variable that will receive an NSError if this method fails. Set this parameter to nil if the caller does not care about the error.

    Return Value

    An ITLibrary instance or nil if this method fails.

    Discussion

    Upon initialization of the ITLibrary class, the default iTunes database for the current user is read and parsed. At that point, all media entities (tracks) and playlists are cached in memory until the object is deallocated.

    Listing 2Creating and initializing an ITLibrary
    • #import <iTunesLibrary/ITLibrary.h>
    • NSError * error = nil;
    • ITLibrary* library = [libraryWithAPIVersion:@"1.0" error:&error];
    • if (library)
    • {
    • NSArray playlists = library.allPlaylists; // <- NSArray of ITLibPlaylist
    • NSArray mediaItems = library.allMediaItems; // <- NSArray of ITLibMediaItem
    • }

    See also initWithAPIVersion:error:.

    Import Statement

  • Whether to show content rating labels. (read-only)

    Declaration

    Objective-C

    @property (nonatomic, readonly, assign, getter = shouldShowContentRating) BOOL showContentRating;

    Import Statement

  • The location of the iTunes music folder. (read-only)

    Declaration

    Objective-C

    @property (nonatomic, readonly, copy) NSURL * musicFolderLocation;

    Import Statement

  • features features Property

    Deprecated. (read-only)

    Declaration

    Objective-C

    @property (nonatomic, readonly, assign) ITLibExportFeature features;

    Discussion

    This property has been deprecated and will be removed in future versions of the framework.

    Import Statement

  • The version of iTunes that created or modified the iTunes library being accessed. (read-only)

    Declaration

    Objective-C

    @property (nonatomic, readonly, copy) NSString * applicationVersion;

    Import Statement

  • The minor version number of the API exposed by the iTunesLibrary framework. (read-only)

    Declaration

    Objective-C

    @property (nonatomic, readonly, assign) NSUInteger apiMinorVersion;

    Import Statement

  • The major version number of the API exposed by the iTunesLibrary framework. (read-only)

    Declaration

    Objective-C

    @property (nonatomic, readonly, assign) NSUInteger apiMajorVersion;

    Import Statement

  • All the playlists in the iTunes library. (read-only)

    Declaration

    Objective-C

    @property (nonatomic, readonly, retain) NSArray * allPlaylists;

    Discussion

    Returns an array of ITLibPlaylists. See ITLibPlaylist Class Reference.

    Import Statement

  • All media items (tracks) in the iTunes library.

    Declaration

    Objective-C

    @property (nonatomic, readonly, retain) NSArray * allMediaItems;

    Discussion

    Returns an array of ITLibMediaItems. See ITLibMediaItem Class Reference.

    Import Statement