You are on page 1of 61

Assets Library Framework Reference

Contents

Introduction 4 Classes 5 ALAsset Class Reference 6


Overview 6 Tasks 6 Properties 7 Instance Methods 8 Constants 14

ALAssetRepresentation Class Reference 17


Overview 17 Tasks 17 Instance Methods 19

ALAssetsFilter Class Reference 25


Overview 25 Tasks 25 Class Methods 26

ALAssetsGroup Class Reference 28


Overview 28 Tasks 28 Properties 29 Instance Methods 30 Constants 34

ALAssetsLibrary Class Reference 37


Overview 37 Tasks 38 Class Methods 39 Instance Methods 40 Constants 47

2010-04-19 | Copyright 2010 Apple Inc. All Rights Reserved.

Contents

Notifications 59

Document Revision History 60

2010-04-19 | Copyright 2010 Apple Inc. All Rights Reserved.

Introduction

Framework Header file directories Declared in

/System/Library/Frameworks/AssetsLibrary.framework /System/Library/Frameworks/AssetsLibrary.framework/Headers ALAsset.h ALAssetRepresentation.h ALAssetsFilter.h ALAssetsGroup.h ALAssetsLibrary.h

You use the Assets Library framework to access the pictures and videos managed by the Photos application.

2010-04-19 | Copyright 2010 Apple Inc. All Rights Reserved.

Classes

2010-04-19 | Copyright 2010 Apple Inc. All Rights Reserved.

ALAsset Class Reference

Inherits from Conforms to Framework Availability Declared in Related sample code

NSObject NSObject (NSObject) /System/Library/Frameworks/AssetsLibrary.framework Available in iOS 4.0 and later. ALAsset.h

MyImagePicker PhotosByLocation PrintPhoto

Overview
An ALAsset object represents a photo or a video managed by the Photo application. Assets can have multiple representations, for example a photo which was captured in RAW and JPG. Different representations of the same asset may have different dimensions.

Tasks
Asset Properties
valueForProperty:

(page 12) Returns the value for a given property. (page 7) property Indicates whether the asset is editable. (read-only) (page 8) property The original version of the asset. (read-only)

editable

originalAsset

2010-04-19 | Copyright 2010 Apple Inc. All Rights Reserved.

ALAsset Class Reference Properties

Accessing Representations
defaultRepresentation

(page 9) Returns an asset representation object for the default representation. (page 9) Returns an an asset representation object for a given representation UTI. (page 11) Returns a thumbnail representation of the asset. (page 8) Returns an aspect ratio thumbnail of the asset.

representationForUTI:

thumbnail

aspectRatioThumbnail

Setting New Image and Video Data


setImageData:metadata:completionBlock:

(page 10) Replaces the image data in the receiver with given image data (page 11) Replaces the video data in receiver with the video at a given URL.

setVideoAtPath:completionBlock:

Saving to the Saved Photos Album


writeModifiedImageDataToSavedPhotosAlbum:metadata:completionBlock:

(page 12)

Saves image data to the Saved Photos album.


writeModifiedVideoAtPathToSavedPhotosAlbum:completionBlock:

(page 13)

Saves the video at a specified path to the Saved Photos album.

Properties
editable
Indicates whether the asset is editable. (read-only)
@property(nonatomic, readonly, getter=isEditable) BOOL editable

Discussion The property value is YES if the application is able to edit the asset, and NO if the application is not able to edit the asset. Applications are only allowed to edit assets that they originally wrote.

2010-04-19 | Copyright 2010 Apple Inc. All Rights Reserved.

ALAsset Class Reference Instance Methods

Availability Available in iOS 5.0 and later. Declared in


ALAsset.h

originalAsset
The original version of the asset. (read-only)
@property(nonatomic, readonly) ALAsset *originalAsset

Discussion The property value is the original asset if the receiver was saved as a modified version of an asset. The property value is nil if the asset was not saved as a modified version of another asset. Availability Available in iOS 5.0 and later. Declared in
ALAsset.h

Instance Methods
aspectRatioThumbnail
Returns an aspect ratio thumbnail of the asset.
- (CGImageRef)aspectRatioThumbnail

Return Value An aspect ratio thumbnail of the asset. Discussion Returns a CGImage with an aspect ratio thumbnail of the asset. The size of the thumbnail is the appropriate size for the platform, and in the correct orientation. This method returns NULL for assets from a shared photo stream that are not yet available locally. If the asset becomes available in the future, an ALAssetsLibraryChangedNotification (page 59) notification is posted.

2010-04-19 | Copyright 2010 Apple Inc. All Rights Reserved.

ALAsset Class Reference Instance Methods

Availability Available in iOS 5.0 and later. Declared in


ALAsset.h

defaultRepresentation
Returns an asset representation object for the default representation.
- (ALAssetRepresentation *)defaultRepresentation

Return Value An asset representation object for the default representation. Discussion This method returns nil for assets from a shared photo stream that are not yet available locally. If the asset becomes available in the future, an ALAssetsLibraryChangedNotification (page 59) notification is posted. Availability Available in iOS 4.0 and later.
Related Sample Code

PhotosByLocation Declared in
ALAsset.h

representationForUTI:
Returns an an asset representation object for a given representation UTI.
- (ALAssetRepresentation *)representationForUTI:(NSString *)representationUTI

Parameters
representationUTI

A UTI describing a representation for the asset. Return Value An an asset representation object for the representation specified by representationUTI, or nil if the asset does not support the representation.

2010-04-19 | Copyright 2010 Apple Inc. All Rights Reserved.

ALAsset Class Reference Instance Methods

Discussion This method returns nil for assets from a shared photo stream that are not yet available locally. If the asset becomes available in the future, an ALAssetsLibraryChangedNotification (page 59) notification is posted. Availability Available in iOS 4.0 and later. Declared in
ALAsset.h

setImageData:metadata:completionBlock:
Replaces the image data in the receiver with given image data
- (void)setImageData:(NSData *)imageData metadata:(NSDictionary *)metadata

completionBlock:(ALAssetsLibraryWriteImageCompletionBlock)completionBlock

Parameters
imageData

Image data for the asset.


metadata

Metadata for the image.


completionBlock

The block invoked after the save operation completes. If the application is able to edit the asset, the completion block returns the same asset URL as the receiver, because a new asset is not created. If the application is not able to edit the asset, the completion blocks return a nil asset URL and an ALAssetsLibraryWriteFailedError. Discussion Before invoking this method, you should check the editable (page 7) property of the asset to determine whether it is possible to replace the image data. Availability Available in iOS 5.0 and later. Declared in
ALAsset.h

2010-04-19 | Copyright 2010 Apple Inc. All Rights Reserved.

10

ALAsset Class Reference Instance Methods

setVideoAtPath:completionBlock:
Replaces the video data in receiver with the video at a given URL.
- (void)setVideoAtPath:(NSURL *)videoPathURL

completionBlock:(ALAssetsLibraryWriteVideoCompletionBlock)completionBlock

Parameters
videoPathURL

An URL that specifies the location of video data.


completionBlock

The block invoked after the save operation completes. If the application is able to edit the asset, the completion block returns the same asset URL as the receiver, because a new asset is not created. If the application is not able to edit the asset, the completion blocks return a nil asset URL and an ALAssetsLibraryWriteFailedError. Discussion Before invoking this method, you should check the editable (page 7) property of the asset to determine whether it is possible to replace the video data. Availability Available in iOS 5.0 and later. Declared in
ALAsset.h

thumbnail
Returns a thumbnail representation of the asset.
- (CGImageRef)thumbnail

Return Value A thumbnail representation of the asset. Discussion The size of the thumbnail is the appropriate for the platform. The image is returned in the correct orientation (that is, pointing upyou shouldnt have to rotate the image). This method returns NULL for assets from a shared photo stream that are not yet available locally. If the asset becomes available in the future, an ALAssetsLibraryChangedNotification (page 59) notification is posted.

2010-04-19 | Copyright 2010 Apple Inc. All Rights Reserved.

11

ALAsset Class Reference Instance Methods

Availability Available in iOS 4.0 and later.


Related Sample Code

MyImagePicker Declared in
ALAsset.h

valueForProperty:
Returns the value for a given property.
- (id)valueForProperty:(NSString *)property

Parameters
property

The property for which you want the value. For valid keys, see Property Keys (page 14). Return Value The value for property. If property is not a valid key, returns ALErrorInvalidProperty (page 15). Availability Available in iOS 4.0 and later.
Related Sample Code

PhotosByLocation Declared in
ALAsset.h

writeModifiedImageDataToSavedPhotosAlbum:metadata:completionBlock:
Saves image data to the Saved Photos album.
- (void)writeModifiedImageDataToSavedPhotosAlbum:(NSData *)imageData

metadata:(NSDictionary *)metadata completionBlock:(ALAssetsLibraryWriteImageCompletionBlock)completionBlock

Parameters
imageData

Image data for the asset.

2010-04-19 | Copyright 2010 Apple Inc. All Rights Reserved.

12

ALAsset Class Reference Instance Methods

metadata

Metadata for the image.


completionBlock

The block invoked after the save operation completes. Discussion This method saves imageData to the saved photos album as a new asset that is considered a modified version of the receiver. Availability Available in iOS 5.0 and later. Declared in
ALAsset.h

writeModifiedVideoAtPathToSavedPhotosAlbum:completionBlock:
Saves the video at a specified path to the Saved Photos album.
- (void)writeModifiedVideoAtPathToSavedPhotosAlbum:(NSURL *)videoPathURL

completionBlock:(ALAssetsLibraryWriteVideoCompletionBlock)completionBlock

Parameters
videoPathURL

An URL that specifies the location of video data.


completionBlock

The block invoked after the save operation completes. Discussion This method saves the video at videoPathURL to the Saved Photos album as a new asset that is considered a modified version of the receiver. Availability Available in iOS 5.0 and later. Declared in
ALAsset.h

2010-04-19 | Copyright 2010 Apple Inc. All Rights Reserved.

13

ALAsset Class Reference Constants

Constants
Property Keys
Constants for the keys for the properties you can get from an asset.

NSString NSString NSString NSString NSString NSString NSString NSString

*const *const *const *const *const *const *const *const

ALAssetPropertyType; ALAssetPropertyLocation; ALAssetPropertyDuration; ALAssetPropertyOrientation; ALAssetPropertyDate; ALAssetPropertyRepresentations; ALAssetPropertyURLs; ALAssetPropertyAssetURL;

Constants
ALAssetPropertyType

A key to retrieve the type of the asset. Possible values are given in Asset Types (page 16). Available in iOS 4.0 and later. Declared in ALAsset.h.
ALAssetPropertyLocation

The key to retrieve the location information of the asset. The corresponding value is a CLLocation object. This is only available if location services are enabled for the caller. Available in iOS 4.0 and later. Declared in ALAsset.h.
ALAssetPropertyDuration

The key to retrieve the play time duration of a video asset. The corresponding value is a double wrapped in an NSNumber object. For photos, ALErrorInvalidProperty (page 15) is returned. Available in iOS 4.0 and later. Declared in ALAsset.h.
ALAssetPropertyOrientation

The key to retrieve the orientation of the asset. The corresponding value is an NSNumber object containing an asset's orientation as described by the TIFF format. Available in iOS 4.0 and later. Declared in ALAsset.h.

2010-04-19 | Copyright 2010 Apple Inc. All Rights Reserved.

14

ALAsset Class Reference Constants

ALAssetPropertyDate

The key to retrieve the creation date of the asset. The corresponding value is an NSDate object. Available in iOS 4.0 and later. Declared in ALAsset.h.
ALAssetPropertyRepresentations

The key to retrieve the representations available for a given asset (for example RAW, JPEG). The corresponding value is an NSArray object containing UTIs expressed as strings. Available in iOS 4.0 and later. Declared in ALAsset.h.
ALAssetPropertyURLs

The key to retrieve a dictionary that maps asset representations UTIs to URLs that uniquely identify the asset. The corresponding value is an NSDictionary object. Available in iOS 4.0 and later. Declared in ALAsset.h.
ALAssetPropertyAssetURL

The key to retrieve a URL identifier for the asset. The corresponding value is an NSURL object. This URL is used by the library-change notifications to identify assets and asset groups. Only the ALAssetRepresentation and ALAssetsGroup classes support this property. Available in iOS 6.0 and later. Declared in ALAsset.h.

Invalid Property Value


A constant to indicate that a property accessed by valueForProperty: (page 12) is invalid.

NSString *const ALErrorInvalidProperty;

Constants
ALErrorInvalidProperty

Value returned by valueForProperty: (page 12) if the property you tried to access is invalid. Available in iOS 4.0 and later. Declared in ALAsset.h.

2010-04-19 | Copyright 2010 Apple Inc. All Rights Reserved.

15

ALAsset Class Reference Constants

Asset Types
Constants that specify the type of an asset.

NSString *const ALAssetTypePhoto; NSString *const ALAssetTypeVideo; NSString *const ALAssetTypeUnknown;

Constants
ALAssetTypePhoto

Specifies that the asset is a photo. Available in iOS 4.0 and later. Declared in ALAsset.h.
ALAssetTypeVideo

Specifies that the asset is a video. Available in iOS 4.0 and later. Declared in ALAsset.h.
ALAssetTypeUnknown

Specifies that the asset's type cannot be determined. The asset could be a sound file, a video or photo file that the system doesnt know about or something else. This is possible only for assets imported from a camera onto the device. Available in iOS 4.0 and later. Declared in ALAsset.h. Discussion These constants represent the values you may get back for the ALAssetPropertyType (page 14) property.

2010-04-19 | Copyright 2010 Apple Inc. All Rights Reserved.

16

ALAssetRepresentation Class Reference

Inherits from Conforms to Framework Availability Declared in Related sample code

NSObject NSObject (NSObject) /System/Library/Frameworks/AssetsLibrary.framework Available in iOS 4.0 and later. ALAssetRepresentation.h

MyImagePicker PhotosByLocation PrintPhoto

Overview
An ALAssetRepresentation object encapsulates one of the representations of a given ALAsset object. A given asset in the library may have more than one representation. For example, if a camera provides RAW and JPEG versions of an image, the resulting asset will have two representationsone for the RAW file and one for the JPEG file.

Tasks
Getting Image Representations
CGImageWithOptions:

(page 19) Returns a full resolution CGImage of the representation. (page 20) Returns a CGImage representation of the asset. (page 20) Returns a CGImage of the representation that is appropriate for displaying full screen.

fullResolutionImage

fullScreenImage

2010-04-19 | Copyright 2010 Apple Inc. All Rights Reserved.

17

ALAssetRepresentation Class Reference Tasks

Getting Image Attributes


orientation

(page 22) Returns the representations orientation. (page 23) Returns the representations scale. (page 19) Returns the representations dimensions. (page 20) Returns a string representing the filename of the representation on disk.

scale

dimensions

filename

Getting Raw Data


size

(page 23) Returns the size in bytes of the file for the representation. (page 21) Copies a specified range of bytes into a given buffer.

getBytes:fromOffset:length:error:

Getting Metadata
UTI

(page 24) Returns the representation's UTI. (page 22) Returns a dictionary of dictionaries of metadata for the representation.

metadata

Getting an URL
url

(page 24) Returns a persistent URL uniquely identifying the representation.

2010-04-19 | Copyright 2010 Apple Inc. All Rights Reserved.

18

ALAssetRepresentation Class Reference Instance Methods

Instance Methods
CGImageWithOptions:
Returns a full resolution CGImage of the representation.
- (CGImageRef)CGImageWithOptions:(NSDictionary *)options

Parameters
options

A dictionary of options as described for CGImageSourceCreateWithData or CGImageSourceCreateWithURL. Return Value A full resolution CGImage of the representation. Discussion This method provides a convenient way to obtain a CGImage representation of an asset. This method returns the biggest, best representation available, unadjusted in any way. Availability Available in iOS 4.0 and later. Declared in
ALAssetRepresentation.h

dimensions
Returns the representations dimensions.
- (CGSize)dimensions

Return Value The representations dimensions. Discussion If the representation doesnt have valid dimensions, this method will return CGSizeZero. Availability Available in iOS 5.1 and later. Declared in
ALAssetRepresentation.h

2010-04-19 | Copyright 2010 Apple Inc. All Rights Reserved.

19

ALAssetRepresentation Class Reference Instance Methods

filename
Returns a string representing the filename of the representation on disk.
- (NSString *)filename

Return Value A string representing the filename of the representation on disk. Discussion For representations synced from iTunes, this will be the filename of the represenation on the host. Availability Available in iOS 5.0 and later. Declared in
ALAssetRepresentation.h

fullResolutionImage
Returns a CGImage representation of the asset.
- (CGImageRef)fullResolutionImage

Return Value A CGImage representation of the asset, or NULL if a CGImage representation could not be generated. Discussion This method returns the biggest, best representation available, unadjusted in any way. To create a correctly-rotated UIImage object from the CGImage, you use imageWithCGImage:scale:orientation: or initWithCGImage:scale:orientation:, passing the values of orientation (page 22) and scale (page 23). Availability Available in iOS 4.0 and later. Declared in
ALAssetRepresentation.h

fullScreenImage
Returns a CGImage of the representation that is appropriate for displaying full screen.

2010-04-19 | Copyright 2010 Apple Inc. All Rights Reserved.

20

ALAssetRepresentation Class Reference Instance Methods

- (CGImageRef)fullScreenImage

Return Value A CGImage of the representation that is appropriate for displaying full screen, or NULL if a CGImage representation could not be generated. Discussion The dimensions of the image are dependent on the device your application is running on; the dimensions may not, however, exactly match the dimensions of the screen. In iOS 5 and later, this method returns a fully cropped, rotated, and adjusted imageexactly as a user would see in Photos or in the image picker. Availability Available in iOS 4.0 and later.
Related Sample Code

MyImagePicker PrintPhoto Declared in

ALAssetRepresentation.h

getBytes:fromOffset:length:error:
Copies a specified range of bytes into a given buffer.
- (NSUInteger)getBytes:(uint8_t *)buffer fromOffset:(long long)offset

length:(NSUInteger)length error:(NSError **)error

Parameters
buffer

A buffer into which to copy the data. You typically use size (page 23) to allocate a buffer of the right size.
offset

The number of bytes from the beginning of the file to start copying.
length

The number of bytes to copy.


error

If an error occurs, upon return contains an NSError object that describes the problem. Pass NULL if you do not want error information.

2010-04-19 | Copyright 2010 Apple Inc. All Rights Reserved.

21

ALAssetRepresentation Class Reference Instance Methods

Return Value The number of bytes actually written to buffer. The number of bytes read will be less than the requested range if the range exceeds the file's size. If an error occurs, returns 0. Discussion This method returns the biggest, best representation available, unadjusted in any way. Availability Available in iOS 4.0 and later. See Also size (page 23)
Related Sample Code

PhotosByLocation Declared in

ALAssetRepresentation.h

metadata
Returns a dictionary of dictionaries of metadata for the representation.
- (NSDictionary *)metadata

Return Value A dictionary of dictionaries of metadata for the representation. Returns nil if the representation is one that the system cannot interpret. Availability Available in iOS 4.0 and later. Declared in
ALAssetRepresentation.h

orientation
Returns the representations orientation.
- (ALAssetOrientation)orientation

Return Value The representations orientation. For a list of possible values, see ALAssetOrientation (page 49).

2010-04-19 | Copyright 2010 Apple Inc. All Rights Reserved.

22

ALAssetRepresentation Class Reference Instance Methods

Availability Available in iOS 4.0 and later.


Related Sample Code

MyImagePicker PhotosByLocation PrintPhoto Declared in

ALAssetRepresentation.h

scale
Returns the representations scale.
- (float)scale

Return Value The representations scale. Availability Available in iOS 4.0 and later.
Related Sample Code

MyImagePicker PhotosByLocation Declared in

ALAssetRepresentation.h

size
Returns the size in bytes of the file for the representation.
- (long long)size

Return Value The size in bytes of the file for the representation. Discussion You typically use this method to allocate a buffer of the right size for getBytes:fromOffset:length:error: (page 21).

2010-04-19 | Copyright 2010 Apple Inc. All Rights Reserved.

23

ALAssetRepresentation Class Reference Instance Methods

Availability Available in iOS 4.0 and later.


Related Sample Code

PhotosByLocation Declared in

ALAssetRepresentation.h

url
Returns a persistent URL uniquely identifying the representation.
- (NSURL *)url

Return Value A persistent URL uniquely identifying the representation. Availability Available in iOS 4.0 and later.
Related Sample Code

PhotosByLocation Declared in

ALAssetRepresentation.h

UTI
Returns the representation's UTI.
- (NSString *)UTI

Return Value The representation's UTI Availability Available in iOS 4.0 and later. Declared in
ALAssetRepresentation.h

2010-04-19 | Copyright 2010 Apple Inc. All Rights Reserved.

24

ALAssetsFilter Class Reference

Inherits from Conforms to Framework Availability Declared in Related sample code

NSObject NSObject (NSObject) /System/Library/Frameworks/AssetsLibrary.framework Available in iOS 4.0 and later. ALAssetsFilter.h

AVMovieExporter AVPlayerDemo MyImagePicker

Overview
ALAssetsFilter encapsulates filtering criteria to be used when retrieving assets from a group.

You use filters with the setAssetsFilter: (page 33) method in ALAssetsGroup.

Tasks
Creating Filters
+ allAssets

(page 26) Returns a filter that gets all assets in the assets group. (page 26) Returns a filter that gets all photos in the assets group. (page 26) Returns a filter that gets all videos in the assets group.

+ allPhotos

+ allVideos

2010-04-19 | Copyright 2010 Apple Inc. All Rights Reserved.

25

ALAssetsFilter Class Reference Class Methods

Class Methods
allAssets
Returns a filter that gets all assets in the assets group.
+ (ALAssetsFilter *)allAssets

Return Value A filter that gets all assets in the assets group. Availability Available in iOS 4.0 and later. Declared in
ALAssetsFilter.h

allPhotos
Returns a filter that gets all photos in the assets group.
+ (ALAssetsFilter *)allPhotos

Return Value A filter that gets all photos in the assets group. Availability Available in iOS 4.0 and later.
Related Sample Code

MyImagePicker Declared in

ALAssetsFilter.h

allVideos
Returns a filter that gets all videos in the assets group.
+ (ALAssetsFilter *)allVideos

Return Value A filter that gets all videos in the assets group.

2010-04-19 | Copyright 2010 Apple Inc. All Rights Reserved.

26

ALAssetsFilter Class Reference Class Methods

Availability Available in iOS 4.0 and later.


Related Sample Code

AVMovieExporter AVPlayerDemo Declared in

ALAssetsFilter.h

2010-04-19 | Copyright 2010 Apple Inc. All Rights Reserved.

27

ALAssetsGroup Class Reference

Inherits from Conforms to Framework Availability Declared in Related sample code

NSObject NSObject (NSObject) /System/Library/Frameworks/AssetsLibrary.framework Available in iOS 4.0 and later. ALAssetsGroup.h

MyImagePicker PhotosByLocation

Overview
An ALAssetsGroup object represents an ordered set of the assets managed by the Photos application. The order of the elements is the same as the user sees in the Photos application. An asset can belong to multiple assets groups. Assets groups themselves are synced via iTunes, created to hold the users saved photos or created during camera import. You can indirectly modify the Saved Photos group by saving images or videos into it using the ALAssetsLibrary class.

Tasks
Enumerating Assets
enumerateAssetsUsingBlock:

(page 31) Invokes a given block using each of the assets in the group. (page 31) Invokes a given block using each of the assets in the group.

enumerateAssetsWithOptions:usingBlock:

2010-04-19 | Copyright 2010 Apple Inc. All Rights Reserved.

28

ALAssetsGroup Class Reference Properties

enumerateAssetsAtIndexes:options:usingBlock:

(page 30) Invokes a given block using each of the assets in the group at specified indexes.

Adding Assets
addAsset:

(page 30) Adds an existing asset to the receiver. (page 29) property Indicates whether the application can edit the group. (read-only)

editable

Filtering
numberOfAssets

(page 32) Returns the number of assets in the group that match the current filter. (page 33) Sets the filter for the group.

setAssetsFilter:

Accessing Properties
valueForProperty:

(page 34) Returns the groups value for a given property. (page 32) Returns the groups poster image

posterImage

Properties
editable
Indicates whether the application can edit the group. (read-only)
@property(nonatomic, readonly, getter=isEditable) BOOL editable

Discussion The value of the property is YES if the application is able to edit the group, otherwise it is NO.

2010-04-19 | Copyright 2010 Apple Inc. All Rights Reserved.

29

ALAssetsGroup Class Reference Instance Methods

Availability Available in iOS 5.0 and later. Declared in


ALAssetsGroup.h

Instance Methods
addAsset:
Adds an existing asset to the receiver.
- (BOOL)addAsset:(ALAsset *)asset

Parameters
asset

The asset to add to the receiver. Return Value YES if asset was added successfully, otherwise NO. Discussion The method may fail (return NO) if the group is not editable, or if the asset could not be added to the group. You should check the editable (page 29) property of the group to see if it is possible to add an asset to the group. Availability Available in iOS 5.0 and later. Declared in
ALAssetsGroup.h

enumerateAssetsAtIndexes:options:usingBlock:
Invokes a given block using each of the assets in the group at specified indexes.
- (void)enumerateAssetsAtIndexes:(NSIndexSet *)indexSet

options:(NSEnumerationOptions)options usingBlock:(ALAssetsGroupEnumerationResultsBlock)enumerationBlock

2010-04-19 | Copyright 2010 Apple Inc. All Rights Reserved.

30

ALAssetsGroup Class Reference Instance Methods

Parameters
indexSet

The indexes of the assets to enumerate. The index set must not specify any indexes exceeding numberOfAssets (page 32).
options

Options for the enumeration.


enumerationBlock

The block to invoke using each of the assets in the group at the indexes in indexSet. Discussion Availability Available in iOS 4.0 and later. Declared in
ALAssetsGroup.h

enumerateAssetsUsingBlock:
Invokes a given block using each of the assets in the group.
(void)enumerateAssetsUsingBlock:(ALAssetsGroupEnumerationResultsBlock)enumerationBlock

Parameters
enumerationBlock

The block to invoke using each of the assets in the group. Discussion Availability Available in iOS 4.0 and later.
Related Sample Code

PhotosByLocation Declared in

ALAssetsGroup.h

enumerateAssetsWithOptions:usingBlock:
Invokes a given block using each of the assets in the group.

2010-04-19 | Copyright 2010 Apple Inc. All Rights Reserved.

31

ALAssetsGroup Class Reference Instance Methods

- (void)enumerateAssetsWithOptions:(NSEnumerationOptions)options

usingBlock:(ALAssetsGroupEnumerationResultsBlock)enumerationBlock

Parameters
options

Options for the enumeration.


enumerationBlock

The block to invoke using each of the assets in the group. Discussion Availability Available in iOS 4.0 and later. Declared in
ALAssetsGroup.h

numberOfAssets
Returns the number of assets in the group that match the current filter.
- (NSInteger)numberOfAssets

Return Value The number of assets in the group that match the current filter. If no filter is set, returns the count of all assets in the group. Discussion Availability Available in iOS 4.0 and later. See Also
setAssetsFilter:

(page 33)

Declared in
ALAssetsGroup.h

posterImage
Returns the groups poster image

2010-04-19 | Copyright 2010 Apple Inc. All Rights Reserved.

32

ALAssetsGroup Class Reference Instance Methods

- (CGImageRef)posterImage

Return Value The groups poster image. Discussion The image is returned in the correct orientation (that is, pointing upyou shouldnt have to rotate the image). Availability Available in iOS 4.0 and later.
Related Sample Code

MyImagePicker PhotosByLocation Declared in

ALAssetsGroup.h

setAssetsFilter:
Sets the filter for the group.
- (void)setAssetsFilter:(ALAssetsFilter *)filter

Parameters
filter

The filter for the group. Discussion This method sets the filter the group; it does not execute the filter. The filter is applied when you invoke numberOfAssets (page 32) or enumerate the contents. If you dont set the filter, or set it to nil, the enumeration returns all the assets in the group. Special Considerations Only one filter is active at a time. Any enumeration currently in flight continues to completion using the previous filter. Availability Available in iOS 4.0 and later. Declared in
ALAssetsGroup.h

2010-04-19 | Copyright 2010 Apple Inc. All Rights Reserved.

33

ALAssetsGroup Class Reference Constants

valueForProperty:
Returns the groups value for a given property.
- (id)valueForProperty:(NSString *)property

Parameters
property

The name of a group property. For valid values, see Group Property Names (page 35). Return Value The groups value for property. Discussion Availability Available in iOS 4.0 and later.
Related Sample Code

MyImagePicker PhotosByLocation Declared in

ALAssetsGroup.h

Constants
ALAssetsGroupEnumerationResultsBlock
Signature for the block executed during enumeration of assets.

typedef void (^ALAssetsGroupEnumerationResultsBlock)(ALAsset *result, NSUInteger index, BOOL *stop);

Discussion The block takes the following arguments: result An asset that matches the filter set by the caller.

2010-04-19 | Copyright 2010 Apple Inc. All Rights Reserved.

34

ALAssetsGroup Class Reference Constants

index The index of the asset in the range being returned. If no asset is found, index is set to NSNotFound. stop A pointer to a Boolean value that indicates whether the enumeration should stop. Set the referenced value to YES to stop the enumeration. The value is set to YES if no asset is found. If the application is not given access to the data, result is nil, index is NSNotFound, and stop points to YES. Availability Available in iOS 4.0 and later. Declared in
ALAssetsGroup.h

Group Property Names


Constants for the names of group properties, used by valueForProperty: (page 34).

NSString NSString NSString NSString

*const *const *const *const

ALAssetsGroupPropertyName; ALAssetsGroupPropertyType; ALAssetsGroupPropertyPersistentID; ALAssetsGroupPropertyURL;

Constants
ALAssetsGroupPropertyName

Key to retrieve the name of the group. The corresponding value is an NSString object. Available in iOS 4.0 and later. Declared in ALAssetsGroup.h.
ALAssetsGroupPropertyType

Key to retrieve the group type. The corresponding value is an ALAssetsGroupType constant wrapped in an NSNumber object. Available in iOS 4.0 and later. Declared in ALAssetsGroup.h.

2010-04-19 | Copyright 2010 Apple Inc. All Rights Reserved.

35

ALAssetsGroup Class Reference Constants

ALAssetsGroupPropertyPersistentID

Key to retrieve the groups persistent ID. The corresponding value is an NSString object. Available in iOS 4.0 and later. Declared in ALAssetsGroup.h.
ALAssetsGroupPropertyURL

Key to retrieve a URL that uniquely identifies the group. The corresponding value is an NSURL object. Available in iOS 5.0 and later. Declared in ALAssetsGroup.h.

2010-04-19 | Copyright 2010 Apple Inc. All Rights Reserved.

36

ALAssetsLibrary Class Reference

Inherits from Conforms to Framework Availability Declared in Related sample code

NSObject NSObject (NSObject) /System/Library/Frameworks/AssetsLibrary.framework Available in iOS 4.0 and later. ALAssetsLibrary.h

AVCam AVMovieExporter AVPlayerDemo MyImagePicker PhotosByLocation

Overview
An instance of ALAssetsLibrary provides access to the videos and photos that are under the control of the Photos application. The library includes those that are in the Saved Photos album, those coming from iTunes, and those that were directly imported into the device. You use it to retrieve the list of all asset groups and to save images and videos into the Saved Photos album. You create an instance of ALAssetsLibrary using alloc and init:
ALAssetsLibrary* library = [[ALAssetsLibrary alloc] init];

The lifetimes of objects you get back from a library instance are tied to the lifetime of the library instance. Many of the methods declared by ALAssetsLibrary take blocks for failure and success as arguments. These methods are all asynchronous because the user may need to be asked to grant access to the data.

2010-04-19 | Copyright 2010 Apple Inc. All Rights Reserved.

37

ALAssetsLibrary Class Reference Tasks

Tasks
Accessing Assets
+ authorizationStatus

(page 39) Returns photo data authorization status for this application.

Managing Notifications
+ disableSharedPhotoStreamsSupport

(page 39) Disables shared photo streams notifications and asset retrieval.

Finding Assets
assetForURL:resultBlock:failureBlock:

(page 41) Invokes a given block passing as a parameter an asset identified by a specified file URL.

Enumerating Assets
enumerateGroupsWithTypes:usingBlock:failureBlock:

(page 42) Invokes a given block passing as a parameter each of the asset groups that match the given asset group type.

Saving Assets
writeVideoAtPathToSavedPhotosAlbum:completionBlock:

(page 46) Saves a video identified by a given URL to the Saved Photos album. (page 44) Returns a Boolean value that indicates whether a video identified by a given URL is compatible with the Saved Photos album. (page 46) (page 44) Saves a given image to the Saved Photos album.

videoAtPathIsCompatibleWithSavedPhotosAlbum:

writeImageToSavedPhotosAlbum:orientation:completionBlock:

writeImageDataToSavedPhotosAlbum:metadata:completionBlock:

Writes given image data and metadata to the Photos Album.

2010-04-19 | Copyright 2010 Apple Inc. All Rights Reserved.

38

ALAssetsLibrary Class Reference Class Methods

writeImageToSavedPhotosAlbum:metadata:completionBlock:

(page 45)

Writes a given image and metadata to the Photos Album.

Managing Asset Groups


addAssetsGroupAlbumWithName:resultBlock:failureBlock:

(page 40)

Adds a new assets group to the library.


groupForURL:resultBlock:failureBlock:

(page 43) Returns an assets group in the result block for a URL previously retrieved from an ALAssetsGroup object.

Class Methods
authorizationStatus
Returns photo data authorization status for this application.
+ (ALAuthorizationStatus)authorizationStatus

Return Value Photo data authorization status for this application. For the constants returned, see ALAuthorizationStatus (page 54). Discussion This method does not prompt the user for access. You can use it to detect restricted access and simply hide UI instead of prompting for access. Availability Available in iOS 6.0 and later. Declared in
ALAssetsLibrary.h

disableSharedPhotoStreamsSupport
Disables shared photo streams notifications and asset retrieval.
+ (void)disableSharedPhotoStreamsSupport

2010-04-19 | Copyright 2010 Apple Inc. All Rights Reserved.

39

ALAssetsLibrary Class Reference Instance Methods

Discussion Shared photo streams can generate frequent notifications. Use this method to disable support if appropriate for your app. Apps compiled against versions of iOS prior to iOS 6.0 do not have support for shared photo streams. Availability Available in iOS 6.0 and later. Declared in
ALAssetsLibrary.h

Instance Methods
addAssetsGroupAlbumWithName:resultBlock:failureBlock:
Adds a new assets group to the library.
- (void)addAssetsGroupAlbumWithName:(NSString *)name

resultBlock:(ALAssetsLibraryGroupResultBlock)resultBlock failureBlock:(ALAssetsLibraryAccessFailureBlock)failureBlock

Parameters
name

The name for the new group. If name conflicts with another assets group with the same name, then the group is not created and resultBlock returns a nil group.
resultBlock

The block invoked after the add operation completes. For a description of the block, see ALAssetsLibraryAccessFailureBlock (page 53).
failureBlock

The block to invoke if the add operation failsfor example, if the user denies access to the application. For a description of the block, see ALAssetsGroupFaces (page 48). Discussion The name of the new asset group is name, its type is ALAssetsGroupAlbum (page 48), and the editable (page 29) property is YES.

2010-04-19 | Copyright 2010 Apple Inc. All Rights Reserved.

40

ALAssetsLibrary Class Reference Instance Methods

This method is asynchronous. When the assets group is added, the user may be asked to confirm the applications access to the data; the method, though, returns immediately. You should perform whatever work you want with the group in resultBlock. If the user denies access to the application, or if no application is allowed to access the data, or if the data is currently unavailable, the failure block is called. Availability Available in iOS 5.0 and later. Declared in
ALAssetsLibrary.h

assetForURL:resultBlock:failureBlock:
Invokes a given block passing as a parameter an asset identified by a specified file URL.
- (void)assetForURL:(NSURL *)assetURL

resultBlock:(ALAssetsLibraryAssetForURLResultBlock)resultBlock failureBlock:(ALAssetsLibraryAccessFailureBlock)failureBlock

Parameters
assetURL

An asset URL previously retrieved from an ALAsset object.


resultBlock

The block to invoke using the asset identified by assetURL. For a description of the block, see ALAssetsLibraryAssetForURLResultBlock (page 51).
failureBlock

The block to invoke if the user denies access to the assets library. For a description of the block, see ALAssetsLibraryAccessFailureBlock (page 53). Discussion This method is asynchronous. When the asset is requested, the user may be asked to confirm the application's access to the library; the method, though, returns immediately. You should perform whatever work you want with the asset in resultBlock. If the user denies access to the application, or if no application is allowed to access the data, the failure block is called. Availability Available in iOS 4.0 and later.

2010-04-19 | Copyright 2010 Apple Inc. All Rights Reserved.

41

ALAssetsLibrary Class Reference Instance Methods

Related Sample Code

PrintPhoto

Declared in
ALAssetsLibrary.h

enumerateGroupsWithTypes:usingBlock:failureBlock:
Invokes a given block passing as a parameter each of the asset groups that match the given asset group type.
- (void)enumerateGroupsWithTypes:(ALAssetsGroupType)types

usingBlock:(ALAssetsLibraryGroupsEnumerationResultsBlock)enumerationBlock failureBlock:(ALAssetsLibraryAccessFailureBlock)failureBlock

Parameters
types

The types of asset group over which to enumerate. The value is a bitfield; you can OR together values from writeImageDataToSavedPhotosAlbum:metadata:completionBlock: (page 44).
enumerationBlock

The block to invoke using each asset group in turn. When the enumeration is done, enumerationBlock is invoked with group set to nil. For a description of the block, see ALAssetsLibraryGroupsEnumerationResultsBlock (page 50).
failureBlock

The block to invoke if the user denies access to the assets library. For a description of the block, see ALAssetsLibraryAccessFailureBlock (page 53). Discussion The results are passed one by one to the caller by executing the enumeration block. This method is asynchronous. When groups are enumerated, the user may be asked to confirm the application's access to the data; the method, though, returns immediately. You should perform whatever work you want with the assets in enumerationBlock. If the user denies access to the application, or if no application is allowed to access the data, the failureBlock is called. Special Considerations This method will fail with error ALAssetsLibraryAccessGloballyDeniedError (page 59) if the user has not enabled Location Services (in Settings > General).

2010-04-19 | Copyright 2010 Apple Inc. All Rights Reserved.

42

ALAssetsLibrary Class Reference Instance Methods

Availability Available in iOS 4.0 and later.


Related Sample Code

AVMovieExporter AVPlayerDemo MTAudioProcessingTap Audio Processor Declared in


ALAssetsLibrary.h

groupForURL:resultBlock:failureBlock:
Returns an assets group in the result block for a URL previously retrieved from an ALAssetsGroup object.
- (void)groupForURL:(NSURL *)groupURL

resultBlock:(ALAssetsLibraryGroupResultBlock)resultBlock failureBlock:(ALAssetsLibraryAccessFailureBlock)failureBlock

Parameters
groupURL

The URL for an ALAssetsGroup object.


resultBlock

The block invoked after the access operation completes. For a description of the block, see ALAssetsLibraryAccessFailureBlock (page 53).
failureBlock

The block to invoke if the access operation failsfor example, if the user denies access to the application. For a description of the block, see ALAssetsGroupFaces (page 48). Discussion This method is asynchronous: it returns immediately. You should perform whatever work you want with the assets group in resultBlock. This method is asynchronous. When the assets group is requested, the user may be asked to confirm the applications access to the data; the method, though, returns immediately. You should perform whatever work you want with the asset group in resultBlock. If the user denies access to the application, or if no application is allowed to access the data, or if the data is currently unavailable, the failure block is called. Availability Available in iOS 5.0 and later.

2010-04-19 | Copyright 2010 Apple Inc. All Rights Reserved.

43

ALAssetsLibrary Class Reference Instance Methods

Declared in
ALAssetsLibrary.h

videoAtPathIsCompatibleWithSavedPhotosAlbum:
Returns a Boolean value that indicates whether a video identified by a given URL is compatible with the Saved Photos album.
- (BOOL)videoAtPathIsCompatibleWithSavedPhotosAlbum:(NSURL *)videoPathURL

Parameters
videoPathURL

An URL that points to a video file. Return Value YES if the video identified by videoPathURL is compatible with the Saved Photos album, otherwise NO. Discussion This method returns the same value as UIVideoAtPathIsCompatibleWithSavedPhotosAlbum would for the same URL. Availability Available in iOS 4.0 and later. See Also
writeVideoAtPathToSavedPhotosAlbum:completionBlock:

(page 46)

Declared in
ALAssetsLibrary.h

writeImageDataToSavedPhotosAlbum:metadata:completionBlock:
Writes given image data and metadata to the Photos Album.
- (void)writeImageDataToSavedPhotosAlbum:(NSData *)imageData metadata:(NSDictionary

*)metadata completionBlock:(ALAssetsLibraryWriteImageCompletionBlock)completionBlock

Parameters
imageData

Data for the image to add to the album.


metadata

The metadata to associate with the image.

2010-04-19 | Copyright 2010 Apple Inc. All Rights Reserved.

44

ALAssetsLibrary Class Reference Instance Methods

completionBlock

The block invoked after the save operation completes. For a description of the block, see ALAssetsLibraryWriteImageCompletionBlock (page 52). Discussion If there is a conflict between the metadata in the image data and the metadata dictionary, the image data metadata values will be overwritten. Availability Available in iOS 4.1 and later.
Related Sample Code

SquareCam

Declared in
ALAssetsLibrary.h

writeImageToSavedPhotosAlbum:metadata:completionBlock:
Writes a given image and metadata to the Photos Album.
- (void)writeImageToSavedPhotosAlbum:(CGImageRef)imageRef metadata:(NSDictionary

*)metadata completionBlock:(ALAssetsLibraryWriteImageCompletionBlock)completionBlock

Parameters
imageRef

The image to add to the album.


metadata

The metadata to associate with the image.


completionBlock

The block invoked after the save operation completes. For a description of the block, see ALAssetsLibraryWriteImageCompletionBlock (page 52). Discussion You must specify the orientation key in the metadata dictionary to preserve the orientation of the image. Availability Available in iOS 4.1 and later. Declared in
ALAssetsLibrary.h

2010-04-19 | Copyright 2010 Apple Inc. All Rights Reserved.

45

ALAssetsLibrary Class Reference Instance Methods

writeImageToSavedPhotosAlbum:orientation:completionBlock:
Saves a given image to the Saved Photos album.
- (void)writeImageToSavedPhotosAlbum:(CGImageRef)imageRef

orientation:(ALAssetOrientation)orientation completionBlock:(ALAssetsLibraryWriteImageCompletionBlock)completionBlock

Parameters
imageRef

The image to save to the Saved Photos album.


orientation

The orientation at which to save the image.


completionBlock

The block invoked after the save operation completes. For a description of the block, see ALAssetsLibraryWriteImageCompletionBlock (page 52). Discussion If you want to save a UIImage object, you can use the UIImage method CGImage to get a CGImageRef, and cast the images imageOrientation to ALAssetOrientation. Availability Available in iOS 4.0 and later. See Also
writeVideoAtPathToSavedPhotosAlbum:completionBlock:

(page 46)

Declared in
ALAssetsLibrary.h

writeVideoAtPathToSavedPhotosAlbum:completionBlock:
Saves a video identified by a given URL to the Saved Photos album.
- (void)writeVideoAtPathToSavedPhotosAlbum:(NSURL *)videoPathURL

completionBlock:(ALAssetsLibraryWriteVideoCompletionBlock)completionBlock

Parameters
videoPathURL

An URL that points to a video file.

2010-04-19 | Copyright 2010 Apple Inc. All Rights Reserved.

46

ALAssetsLibrary Class Reference Constants

completionBlock

The block invoked after the save operation completes. For a description of the block, see ALAssetsLibraryWriteVideoCompletionBlock (page 52). Discussion Availability Available in iOS 4.0 and later. See Also
videoAtPathIsCompatibleWithSavedPhotosAlbum:

(page 44) (page 46)

writeImageToSavedPhotosAlbum:orientation:completionBlock:

Related Sample Code

AVCam AVMovieExporter AVSimpleEditoriOS RosyWriter StopNGo for iOS Declared in

ALAssetsLibrary.h

Constants
ALAssetsGroupType
A bitfield to identify types of asset.

typedef NSUInteger ALAssetsGroupType;

Discussion For possible values, see Types of Asset (page 48). Availability Available in iOS 4.0 and later. Declared in
ALAssetsLibrary.h

2010-04-19 | Copyright 2010 Apple Inc. All Rights Reserved.

47

ALAssetsLibrary Class Reference Constants

Types of Asset
Constants to identify types of asset.

enum { ALAssetsGroupLibrary ALAssetsGroupAlbum ALAssetsGroupEvent ALAssetsGroupFaces ALAssetsGroupSavedPhotos ALAssetsGroupPhotoStream ALAssetsGroupAll };

= = = = = = =

(1 << 0), (1 << 1), (1 << 2), (1 << 3), (1 << 4), (1 << 5), 0xFFFFFFFF,

Constants
ALAssetsGroupLibrary

The Library group that includes all assets that are synced from iTunes. Available in iOS 4.0 and later. Declared in ALAssetsLibrary.h.
ALAssetsGroupAlbum

All the albums created on the device or synced from iTunes, not including Photo Stream or Shared Streams Available in iOS 4.0 and later. Declared in ALAssetsLibrary.h.
ALAssetsGroupEvent

All events, including those created during Camera Connection Kit import. Available in iOS 4.0 and later. Declared in ALAssetsLibrary.h.
ALAssetsGroupFaces

All the faces albums synced from iTunes. Available in iOS 4.0 and later. Declared in ALAssetsLibrary.h.
ALAssetsGroupSavedPhotos

All the photos in the Camera Roll. Available in iOS 4.0 and later. Declared in ALAssetsLibrary.h.

2010-04-19 | Copyright 2010 Apple Inc. All Rights Reserved.

48

ALAssetsLibrary Class Reference Constants

ALAssetsGroupPhotoStream

The PhotoStream album. In iOS 6.0 and later, this also includes Shared Streams. Available in iOS 5.0 and later. Declared in ALAssetsLibrary.h.
ALAssetsGroupAll

The same as ORing together all the group types except for ALAssetsGroupLibrary. Available in iOS 4.0 and later. Declared in ALAssetsLibrary.h.

ALAssetOrientation
Constants to indicate the orientation of an asset.

typedef enum { ALAssetOrientationUp, ALAssetOrientationDown, ALAssetOrientationLeft, ALAssetOrientationRight, ALAssetOrientationUpMirrored, ALAssetOrientationDownMirrored, ALAssetOrientationLeftMirrored, ALAssetOrientationRightMirrored, } ALAssetOrientation;

Constants
ALAssetOrientationUp

Indicates that the picture is in its default orientation, as shown here. Available in iOS 4.0 and later. Declared in ALAssetsLibrary.h.
ALAssetOrientationDown

Indicates that the picture has been rotated through 180 degrees with respect to
ALAssetOrientationUp

(page 49), as shown here.

Available in iOS 4.0 and later. Declared in ALAssetsLibrary.h.

2010-04-19 | Copyright 2010 Apple Inc. All Rights Reserved.

49

ALAssetsLibrary Class Reference Constants

ALAssetOrientationLeft

Indicates that the picture has been rotated through 90 degrees counter-clockwise with respect to
ALAssetOrientationUp

(page 49), as shown here.

Available in iOS 4.0 and later. Declared in ALAssetsLibrary.h.


ALAssetOrientationRight

Indicates that the picture has been rotated through 90 degrees clockwise with respect to
ALAssetOrientationUp

(page 49), as shown here.

Available in iOS 4.0 and later. Declared in ALAssetsLibrary.h.


ALAssetOrientationUpMirrored

Indicates that the picture has been flipped horizontally with respect to ALAssetOrientationUp (page 49), as shown here. Available in iOS 4.0 and later. Declared in ALAssetsLibrary.h.
ALAssetOrientationDownMirrored

Indicates that the picture has been rotated through 180 degrees with respect to
ALAssetOrientationUp

(page 49) and then flipped horizontally, as shown here.

Available in iOS 4.0 and later. Declared in ALAssetsLibrary.h.


ALAssetOrientationLeftMirrored

Indicates that the picture has been rotated through 90 degrees counter-clockwise with respect to
ALAssetOrientationUp

(page 49) and then flipped vertically, as shown here.

Available in iOS 4.0 and later. Declared in ALAssetsLibrary.h.


ALAssetOrientationRightMirrored

Indicates that the picture has been rotated through 90 degrees clockwise with respect to
ALAssetOrientationUp

(page 49) and then flipped vertically, as shown here.

Available in iOS 4.0 and later. Declared in ALAssetsLibrary.h.

ALAssetsLibraryGroupsEnumerationResultsBlock
Signature for the block executed when a match is found during enumeration using enumerateGroupsWithTypes:usingBlock:failureBlock: (page 42).

2010-04-19 | Copyright 2010 Apple Inc. All Rights Reserved.

50

ALAssetsLibrary Class Reference Constants

typedef void (^ALAssetsLibraryGroupsEnumerationResultsBlock)(ALAssetsGroup *group, BOOL *stop);

Discussion The block parameters are defined as follows: group The current asset group in the enumeration. stop A pointer to a boolean value; set the value to YES to stop enumeration. Availability Available in iOS 4.0 and later. Declared in
ALAssetsLibrary.h

ALAssetsLibraryAssetForURLResultBlock
Signature for the block executed if the user has granted access to the caller to access the data managed by the framework in assetForURL:resultBlock:failureBlock: (page 41).

typedef void (^ALAssetsLibraryAssetForURLResultBlock)(ALAsset *asset);

Discussion The block parameter is defined as follows: asset The asset identified by the URL parameter in assetForURL:resultBlock:failureBlock: (page 41). If the asset is not found, asset is nil. Availability Available in iOS 4.0 and later. Declared in
ALAssetsLibrary.h

2010-04-19 | Copyright 2010 Apple Inc. All Rights Reserved.

51

ALAssetsLibrary Class Reference Constants

ALAssetsLibraryWriteImageCompletionBlock
SignaturefortheblockexecutedwhenwriteImageToSavedPhotosAlbum:orientation:completionBlock:(page 46) completes.

typedef void (^ALAssetsLibraryWriteImageCompletionBlock)(NSURL *assetURL, NSError *error);

Discussion The block parameters are defined as follows: assetURL An URL that identifies the saved image file. If the image is not saved, assetURL is nil. error If the image is not saved, an error object that describes the reason for failure, otherwise nil. Availability Available in iOS 4.0 and later. Declared in
ALAssetsLibrary.h

ALAssetsLibraryWriteVideoCompletionBlock
Signature for the block executed when writeVideoAtPathToSavedPhotosAlbum:completionBlock: (page 46) completes.

typedef void (^ALAssetsLibraryWriteVideoCompletionBlock)(NSURL *assetURL, NSError *error);

Discussion The block parameters are defined as follows: assetURL An URL that identifies the saved video file. If the video is not saved, assetURL is nil. error If the video is not saved, an error object that describes the reason for failure, otherwise nil.

2010-04-19 | Copyright 2010 Apple Inc. All Rights Reserved.

52

ALAssetsLibrary Class Reference Constants

Availability Available in iOS 4.0 and later. Declared in


ALAssetsLibrary.h

ALAssetsLibraryAccessFailureBlock
Signature for the block executed if the user does not grant access to the caller to access the data managed by the framework.

typedef void (^ALAssetsLibraryAccessFailureBlock)(NSError *error);

Discussion The block parameter is defined as follows: error An error object that describes why access to the library failed. This block type is used by assetForURL:resultBlock:failureBlock: (page 41) and enumerateGroupsWithTypes:usingBlock:failureBlock: (page 42). Availability Available in iOS 4.0 and later. Declared in
ALAssetsLibrary.h

ALAssetsLibraryGroupResultBlock
Signature for the block executed if the user grants access to the caller to access the data managed by the framework..

typedef void (^ALAssetsLibraryGroupResultBlock)(ALAssetsGroup *group));

Discussion The block parameter is defined as follows:

2010-04-19 | Copyright 2010 Apple Inc. All Rights Reserved.

53

ALAssetsLibrary Class Reference Constants

group The group that was added to the assets library. If the group is not found or not created (for example, because of a name collision), group is nil. This block type is used by addAssetsGroupAlbumWithName:resultBlock:failureBlock: (page 40) and groupForURL:resultBlock:failureBlock: (page 43). Availability Available in iOS 5.0 and later. Declared in
ALAssetsLibrary.h

ALAuthorizationStatus
Constants to indicate authorization status.

typedef NS_ENUM(NSInteger, ALAuthorizationStatus) { ALAuthorizationStatusNotDetermined = 0, ALAuthorizationStatusRestricted, ALAuthorizationStatusDenied, ALAuthorizationStatusAuthorized };

Constants
ALAuthorizationStatusNotDetermined

User has not yet made a choice with regards to this application. Available in iOS 6.0 and later. Declared in ALAssetsLibrary.h.
ALAuthorizationStatusRestricted

This application is not authorized to access photo data. The user cannot change this applications status, possibly due to active restrictions such as parental controls being in place. Available in iOS 6.0 and later. Declared in ALAssetsLibrary.h.
ALAuthorizationStatusDenied

User has explicitly denied this application access to photos data. Available in iOS 6.0 and later. Declared in ALAssetsLibrary.h.

2010-04-19 | Copyright 2010 Apple Inc. All Rights Reserved.

54

ALAssetsLibrary Class Reference Constants

ALAuthorizationStatusAuthorized

User has authorized this application to access photos data. Available in iOS 6.0 and later. Declared in ALAssetsLibrary.h.

Notification Keys
Keysusedtogetvaluesfromtheuserinformationdictionaryofthe ALAssetsLibraryChangedNotification (page 59) notification.

NSString NSString NSString NSString

* * * *

const const const const

ALAssetLibraryUpdatedAssetsKey; ALAssetLibraryInsertedAssetGroupsKey; ALAssetLibraryUpdatedAssetGroupsKey; ALAssetLibraryDeletedAssetGroupsKey;

Constants
ALAssetLibraryUpdatedAssetsKey

Value is a set of NSURL objects identifying the assets that were updated. Available in iOS 6.0 and later. Declared in ALAssetsLibrary.h.
ALAssetLibraryInsertedAssetGroupsKey

Value is a set of NSURL objects identifying the assets that were inserted. Available in iOS 6.0 and later. Declared in ALAssetsLibrary.h.
ALAssetLibraryUpdatedAssetGroupsKey

Value is a set of NSURL objects identifying the asset groups that were updated. Available in iOS 6.0 and later. Declared in ALAssetsLibrary.h.
ALAssetLibraryDeletedAssetGroupsKey

Value is a set of NSURL objects identifying the asset groups that were deleted. Available in iOS 6.0 and later. Declared in ALAssetsLibrary.h. Discussion Assets that are modified use the ALAssetLibraryUpdatedAssetsKey key. Assets that are inserted or deleted use the ALAssetLibraryUpdatedAssetGroupsKey key for the asset group that contains the asset. Assets and asset groups that have no strong references are omitted from the notifications user information dictionary.

2010-04-19 | Copyright 2010 Apple Inc. All Rights Reserved.

55

ALAssetsLibrary Class Reference Constants

Error Domain
Constant for the AssetsLibrary domain.

NSString *const ALAssetsLibraryErrorDomain;

Constants
ALAssetsLibraryErrorDomain

Constant used by NSError to distinguish errors belonging to the AssetsLibrary domain. Available in iOS 4.0 and later. Declared in ALAssetsLibrary.h.

Error Codes
AssetsLibrary-related error codes

enum { ALAssetsLibraryUnknownError =

-1,

ALAssetsLibraryWriteFailedError = -3300, ALAssetsLibraryWriteBusyError = -3301, ALAssetsLibraryWriteInvalidDataError = -3302, ALAssetsLibraryWriteIncompatibleDataError = -3303, ALAssetsLibraryWriteDataEncodingError = -3304, ALAssetsLibraryWriteDiskSpaceError = -3305, ALAssetsLibraryDataUnavailableError = ALAssetsLibraryAccessUserDeniedError = ALAssetsLibraryAccessGloballyDeniedError = }; -3310, -3311, -3312,

Constants
ALAssetsLibraryUnknownError

The reason for the error is unknown. Available in iOS 4.0 and later. Declared in ALAssetsLibrary.h.

2010-04-19 | Copyright 2010 Apple Inc. All Rights Reserved.

56

ALAssetsLibrary Class Reference Constants

ALAssetsLibraryWriteFailedError

The attempt to write data failed. This error may be returned in the completion block for (page 46) and writeImageToSavedPhotosAlbum:orientation:completionBlock: (page 46) as well as the completion selector for UIImageWriteToSavedPhotosAlbum and UISaveVideoAtPathToSavedPhotosAlbum.
writeVideoAtPathToSavedPhotosAlbum:completionBlock:

Available in iOS 4.0 and later. Declared in ALAssetsLibrary.h.


ALAssetsLibraryWriteBusyError

Writing was already busy when the attempt to write was made. You should attempt the write again. This error may be returned in the completion block for (page 46) and writeImageToSavedPhotosAlbum:orientation:completionBlock: (page 46) as well as the completion selector for UIImageWriteToSavedPhotosAlbum and UISaveVideoAtPathToSavedPhotosAlbum.
writeVideoAtPathToSavedPhotosAlbum:completionBlock:

Available in iOS 4.0 and later. Declared in ALAssetsLibrary.h.


ALAssetsLibraryWriteInvalidDataError

The data was invalid. This error may be returned in the completion block for (page 46) and writeImageToSavedPhotosAlbum:orientation:completionBlock: (page 46) as well as the completion selector for UIImageWriteToSavedPhotosAlbum and UISaveVideoAtPathToSavedPhotosAlbum.
writeVideoAtPathToSavedPhotosAlbum:completionBlock:

Available in iOS 4.0 and later. Declared in ALAssetsLibrary.h.


ALAssetsLibraryWriteIncompatibleDataError

The data contained incompatible data. This error may be returned in the completion block for (page 46) and writeImageToSavedPhotosAlbum:orientation:completionBlock: (page 46) as well as the completion selector for UIImageWriteToSavedPhotosAlbum and UISaveVideoAtPathToSavedPhotosAlbum.
writeVideoAtPathToSavedPhotosAlbum:completionBlock:

Available in iOS 4.0 and later. Declared in ALAssetsLibrary.h.

2010-04-19 | Copyright 2010 Apple Inc. All Rights Reserved.

57

ALAssetsLibrary Class Reference Constants

ALAssetsLibraryWriteDataEncodingError

The data contained data with the wrong encoding. This error may be returned in the completion block for (page 46) and writeImageToSavedPhotosAlbum:orientation:completionBlock: (page 46) as well as the completion selector for UIImageWriteToSavedPhotosAlbum and UISaveVideoAtPathToSavedPhotosAlbum.
writeVideoAtPathToSavedPhotosAlbum:completionBlock:

Available in iOS 4.0 and later. Declared in ALAssetsLibrary.h.


ALAssetsLibraryWriteDiskSpaceError

There was not enough space on the disk to write the data. This error may be returned in the completion block for (page 46) and writeImageToSavedPhotosAlbum:orientation:completionBlock: (page 46) as well as the completion selector for UIImageWriteToSavedPhotosAlbum and UISaveVideoAtPathToSavedPhotosAlbum.
writeVideoAtPathToSavedPhotosAlbum:completionBlock:

Available in iOS 4.0 and later. Declared in ALAssetsLibrary.h.


ALAssetsLibraryDataUnavailableError

The data was not available. This error may be returned in the ALAssetsLibraryAccessFailureBlock (page 53) for enumerateGroupsWithTypes:usingBlock:failureBlock: (page 42) and assetForURL:resultBlock:failureBlock: (page 41); and in the completion blocks for writeImageToSavedPhotosAlbum:orientation:completionBlock: (page 46) and writeImageToSavedPhotosAlbum:orientation:completionBlock: (page 46); as well as in the completion selector for UIImageWriteToSavedPhotosAlbum and UISaveVideoAtPathToSavedPhotosAlbum. Available in iOS 4.0 and later. Declared in ALAssetsLibrary.h.
ALAssetsLibraryAccessUserDeniedError

The user denied access to the library. This error may be returned in the ALAssetsLibraryAccessFailureBlock (page 53) block for enumerateGroupsWithTypes:usingBlock:failureBlock: (page 42) and assetForURL:resultBlock:failureBlock: (page 41). Available in iOS 4.0 and later. Declared in ALAssetsLibrary.h.

2010-04-19 | Copyright 2010 Apple Inc. All Rights Reserved.

58

ALAssetsLibrary Class Reference Notifications

ALAssetsLibraryAccessGloballyDeniedError

Access to the library was denied globally. This error may be returned in the ALAssetsLibraryAccessFailureBlock (page 53) block for enumerateGroupsWithTypes:usingBlock:failureBlock: (page 42) and assetForURL:resultBlock:failureBlock: (page 41). Available in iOS 4.0 and later. Declared in ALAssetsLibrary.h.

Notifications
ALAssetsLibraryChangedNotification
Sent when the contents of the assets library have changed from under the app that is using the data. In iOS 4.0, the notifications object is nil. In iOS 4.1 and later, the notification object is the library object that posted the notification. In iOS 6.0 and later, the user information dictionary describes what changed: If the user information dictionary is nil, reload all assets and asset groups.

If the user information dictionary an empty dictionary, there is no need to reload assets and asset groups. If the user information dictionary is not empty, reload the effected assets and asset groups. For the keys used, see Notification Keys (page 55).

This notification is sent on an arbitrary thread. Availability Available in iOS 4.0 and later. Declared in
ALAssetsLibrary.h

2010-04-19 | Copyright 2010 Apple Inc. All Rights Reserved.

59

Document Revision History

This table describes the changes to Assets Library Framework Reference .

Date 2010-04-19

Notes First version of a document that describes the Objective-C API for accessing assets managed by the Photos application.

2010-04-19 | Copyright 2010 Apple Inc. All Rights Reserved.

60

Apple Inc. Copyright 2010 Apple Inc. All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, mechanical, electronic, photocopying, recording, or otherwise, without prior written permission of Apple Inc., with the following exceptions: Any person is hereby authorized to store documentation on a single computer for personal use only and to print copies of documentation for personal use provided that the documentation contains Apples copyright notice. No licenses, express or implied, are granted with respect to any of the technology described in this document. Apple retains all intellectual property rights associated with the technology described in this document. This document is intended to assist application developers to develop applications only for Apple-labeled computers. Apple Inc. 1 Infinite Loop Cupertino, CA 95014 408-996-1010 Apple, the Apple logo, iTunes, and Objective-C are trademarks of Apple Inc., registered in the U.S. and other countries. iOS is a trademark or registered trademark of Cisco in the U.S. and other countries and is used under license.
Even though Apple has reviewed this document, APPLE MAKES NO WARRANTY OR REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS DOCUMENT, ITS QUALITY, ACCURACY, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. AS A RESULT, THIS DOCUMENT IS PROVIDED AS IS, AND YOU, THE READER, ARE ASSUMING THE ENTIRE RISK AS TO ITS QUALITY AND ACCURACY. IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES RESULTING FROM ANY DEFECT OR INACCURACY IN THIS DOCUMENT, even if advised of the possibility of such damages. THE WARRANTY AND REMEDIES SET FORTH ABOVE ARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORAL OR WRITTEN, EXPRESS OR IMPLIED. No Apple dealer, agent, or employee is authorized to make any modification, extension, or addition to this warranty. Some states do not allow the exclusion or limitation of implied warranties or liability for incidental or consequential damages, so the above limitation or exclusion may not apply to you. This warranty gives you specific legal rights, and you may also have other rights which vary from state to state.