Assets Library IOS

Assets Library Framework Reference

Contents

Introduction 4

Classes 5

ALAsset Class Reference 6Overview 6Tasks 6Properties 7Instance Methods 8Constants 14

ALAssetRepresentation Class Reference 17Overview 17Tasks 17Instance Methods 19

ALAssetsFilter Class Reference 25Overview 25Tasks 25Class Methods 26

ALAssetsGroup Class Reference 28Overview 28Tasks 28Properties 29Instance Methods 30Constants 34

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

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

2

Notifications 59

Document Revision History 60


3

Contents

Framework /System/Library/Frameworks/AssetsLibrary.framework

Header file directories /System/Library/Frameworks/AssetsLibrary.framework/Headers

Declared in 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.


4

Introduction


5

Classes

Inherits from NSObject

Conforms to NSObject (NSObject)


Availability Available in iOS 4.0 and later.

Declared in ALAsset.h

Related sample code MyImagePicker

PhotosByLocation

PrintPhoto

OverviewAn 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. Differentrepresentations of the same asset may have different dimensions.

Tasks

Asset Properties

– valueForProperty: (page 12)Returns the value for a given property.

editable (page 7) propertyIndicates whether the asset is editable. (read-only)

originalAsset (page 8) propertyThe original version of the asset. (read-only)


6

ALAsset Class Reference

Accessing Representations

– defaultRepresentation (page 9)Returns an asset representation object for the default representation.

– representationForUTI: (page 9)Returns an an asset representation object for a given representation UTI.

– thumbnail (page 11)Returns a thumbnail representation of the asset.

– aspectRatioThumbnail (page 8)Returns an aspect ratio thumbnail of the asset.

Setting New Image and Video Data

– setImageData:metadata:completionBlock: (page 10)Replaces the image data in the receiver with given image data

– setVideoAtPath:completionBlock: (page 11)Replaces the video data in receiver with the video at a given URL.

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

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

ALAsset Class ReferenceProperties


7

AvailabilityAvailable in iOS 5.0 and later.

Declared inALAsset.h

originalAsset

The original version of the asset. (read-only)

@property(nonatomic, readonly) ALAsset *originalAsset

DiscussionThe property value is the original asset if the receiver was saved as a modified version of an asset. The propertyvalue is nil if the asset was not saved as a modified version of another asset.



Instance Methods

aspectRatioThumbnail

Returns an aspect ratio thumbnail of the asset.

- (CGImageRef)aspectRatioThumbnail

Return ValueAn aspect ratio thumbnail of the asset.

DiscussionReturns a CGImage with an aspect ratio thumbnail of the asset. The size of the thumbnail is the appropriatesize 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 assetbecomes available in the future, an ALAssetsLibraryChangedNotification (page 59) notification is posted.

ALAsset Class ReferenceInstance Methods


8



defaultRepresentation

Returns an asset representation object for the default representation.

- (ALAssetRepresentation *)defaultRepresentation

Return ValueAn asset representation object for the default representation.

DiscussionThis method returns nil for assets from a shared photo stream that are not yet available locally. If the assetbecomes available in the future, an ALAssetsLibraryChangedNotification (page 59) notification is posted.


Related Sample CodePhotosByLocation


representationForUTI:

Returns an an asset representation object for a given representation UTI.

- (ALAssetRepresentation *)representationForUTI:(NSString *)representationUTI

ParametersrepresentationUTI

A UTI describing a representation for the asset.

Return ValueAn an asset representation object for the representation specified by representationUTI, or nil if the assetdoes not support the representation.



9

DiscussionThis method returns nil for assets from a shared photo stream that are not yet available locally. If the assetbecomes available in the future, an ALAssetsLibraryChangedNotification (page 59) notification is posted.



setImageData:metadata:completionBlock:

Replaces the image data in the receiver with given image data

- (void)setImageData:(NSData *)imageData metadata:(NSDictionary *)metadatacompletionBlock:(ALAssetsLibraryWriteImageCompletionBlock)completionBlock

ParametersimageData

Image data for the asset.

metadataMetadata for the image.

completionBlockThe 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 anALAssetsLibraryWriteFailedError.

DiscussionBefore invoking this method, you should check the editable (page 7) property of the asset to determinewhether it is possible to replace the image data.





10

setVideoAtPath:completionBlock:

Replaces the video data in receiver with the video at a given URL.

- (void)setVideoAtPath:(NSURL *)videoPathURLcompletionBlock:(ALAssetsLibraryWriteVideoCompletionBlock)completionBlock

ParametersvideoPathURL

An URL that specifies the location of video data.


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 anALAssetsLibraryWriteFailedError.

DiscussionBefore invoking this method, you should check the editable (page 7) property of the asset to determinewhether it is possible to replace the video data.



thumbnail

Returns a thumbnail representation of the asset.

- (CGImageRef)thumbnail

Return ValueA thumbnail representation of the asset.

DiscussionThe size of the thumbnail is the appropriate for the platform. The image is returned in the correct orientation(that is, “pointing up”—you shouldn’t have to rotate the image).

This method returns NULL for assets from a shared photo stream that are not yet available locally. If the assetbecomes available in the future, an ALAssetsLibraryChangedNotification (page 59) notification is posted.



11


Related Sample CodeMyImagePicker


valueForProperty:

Returns the value for a given property.

- (id)valueForProperty:(NSString *)property

Parametersproperty

The property for which you want the value. For valid keys, see “Property Keys” (page 14).

Return ValueThe value for property. If property is not a valid key, returns ALErrorInvalidProperty (page 15).




writeModifiedImageDataToSavedPhotosAlbum:metadata:completionBlock:

Saves image data to the Saved Photos album.

- (void)writeModifiedImageDataToSavedPhotosAlbum:(NSData *)imageDatametadata:(NSDictionary *)metadatacompletionBlock:(ALAssetsLibraryWriteImageCompletionBlock)completionBlock

ParametersimageData

Image data for the asset.



12

metadataMetadata for the image.


DiscussionThis method saves imageData to the saved photos album as a new asset that is considered a modified versionof the receiver.



writeModifiedVideoAtPathToSavedPhotosAlbum:completionBlock:

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

- (void)writeModifiedVideoAtPathToSavedPhotosAlbum:(NSURL *)videoPathURLcompletionBlock:(ALAssetsLibraryWriteVideoCompletionBlock)completionBlock


An URL that specifies the location of video data.


DiscussionThis method saves the video at videoPathURL to the Saved Photos album as a new asset that is considereda modified version of the receiver.





13

Constants

Property Keys

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

NSString *const ALAssetPropertyType;NSString *const ALAssetPropertyLocation;NSString *const ALAssetPropertyDuration;NSString *const ALAssetPropertyOrientation;NSString *const ALAssetPropertyDate;NSString *const ALAssetPropertyRepresentations;NSString *const ALAssetPropertyURLs;NSString *const ALAssetPropertyAssetURL;

ConstantsALAssetPropertyType

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.

ALAssetPropertyLocationThe key to retrieve the location information of the asset.

The corresponding value is a CLLocation object. This is only available if location services are enabledfor the caller.



ALAssetPropertyDurationThe 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.



ALAssetPropertyOrientationThe key to retrieve the orientation of the asset.

The corresponding value is an NSNumber object containing an asset's orientation as described by theTIFF format.



ALAsset Class ReferenceConstants


14

ALAssetPropertyDateThe key to retrieve the creation date of the asset.

The corresponding value is an NSDate object.



ALAssetPropertyRepresentationsThe 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.



ALAssetPropertyURLsThe key to retrieve a dictionary that maps asset representations UTIs to URLs that uniquely identify theasset.

The corresponding value is an NSDictionary object.



ALAssetPropertyAssetURLThe 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 theALAssetRepresentation and ALAssetsGroup classes support this property.



Invalid Property Value

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

NSString *const ALErrorInvalidProperty;

ConstantsALErrorInvalidProperty

Value returned by valueForProperty: (page 12) if the property you tried to access is invalid.





15

Asset Types

Constants that specify the type of an asset.

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

ConstantsALAssetTypePhoto

Specifies that the asset is a photo.



ALAssetTypeVideoSpecifies that the asset is a video.



ALAssetTypeUnknownSpecifies that the asset's type cannot be determined.

The asset could be a sound file, a video or photo file that the system doesn’t know about or somethingelse. This is possible only for assets imported from a camera onto the device.



DiscussionThese constants represent the values you may get back for the ALAssetPropertyType (page 14) property.



16





Declared in ALAssetRepresentation.h


PhotosByLocation

PrintPhoto

OverviewAn 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 RAWand JPEG versions of an image, the resulting asset will have two representations—one for the RAW file andone for the JPEG file.

Tasks

Getting Image Representations

– CGImageWithOptions: (page 19)Returns a full resolution CGImage of the representation.

– fullResolutionImage (page 20)Returns a CGImage representation of the asset.

– fullScreenImage (page 20)Returns a CGImage of the representation that is appropriate for displaying full screen.


17

ALAssetRepresentation Class Reference

Getting Image Attributes

– orientation (page 22)Returns the representation’s orientation.

– scale (page 23)Returns the representation’s scale.

– dimensions (page 19)Returns the representation’s dimensions.

– filename (page 20)Returns a string representing the filename of the representation on disk.

Getting Raw Data

– size (page 23)Returns the size in bytes of the file for the representation.

– getBytes:fromOffset:length:error: (page 21)Copies a specified range of bytes into a given buffer.

Getting Metadata

– UTI (page 24)Returns the representation's UTI.

– metadata (page 22)Returns a dictionary of dictionaries of metadata for the representation.

Getting an URL

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

ALAssetRepresentation Class ReferenceTasks


18

Instance Methods

CGImageWithOptions:

Returns a full resolution CGImage of the representation.

- (CGImageRef)CGImageWithOptions:(NSDictionary *)options

Parametersoptions

A dictionary of options as described for CGImageSourceCreateWithData orCGImageSourceCreateWithURL.

Return ValueA full resolution CGImage of the representation.

DiscussionThis method provides a convenient way to obtain a CGImage representation of an asset. This method returnsthe biggest, best representation available, unadjusted in any way.


Declared inALAssetRepresentation.h

dimensions

Returns the representation’s dimensions.

- (CGSize)dimensions

Return ValueThe representation’s dimensions.

DiscussionIf the representation doesn’t have valid dimensions, this method will return CGSizeZero.



ALAssetRepresentation Class ReferenceInstance Methods


19

filename

Returns a string representing the filename of the representation on disk.

- (NSString *)filename

Return ValueA string representing the filename of the representation on disk.

DiscussionFor representations synced from iTunes, this will be the filename of the represenation on the host.



fullResolutionImage

Returns a CGImage representation of the asset.

- (CGImageRef)fullResolutionImage

Return ValueA CGImage representation of the asset, or NULL if a CGImage representation could not be generated.

DiscussionThis method returns the biggest, best representation available, unadjusted in any way.

To create a correctly-rotated UIImage object from the CGImage, you useimageWithCGImage:scale:orientation: or initWithCGImage:scale:orientation:, passing thevalues of orientation (page 22) and scale (page 23).



fullScreenImage

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



20

- (CGImageRef)fullScreenImage

Return ValueA CGImage of the representation that is appropriate for displaying full screen, or NULL if a CGImagerepresentation could not be generated.

DiscussionThe dimensions of the image are dependent on the device your application is running on; the dimensions maynot, however, exactly match the dimensions of the screen.

In iOS 5 and later, this method returns a fully cropped, rotated, and adjusted image—exactly as a user wouldsee in Photos or in the image picker.


Related Sample CodeMyImagePickerPrintPhoto


getBytes:fromOffset:length:error:

Copies a specified range of bytes into a given buffer.

- (NSUInteger)getBytes:(uint8_t *)buffer fromOffset:(long long)offsetlength:(NSUInteger)length error:(NSError **)error

Parametersbuffer

A buffer into which to copy the data.

You typically use size (page 23) to allocate a buffer of the right size.

offsetThe number of bytes from the beginning of the file to start copying.

lengthThe number of bytes to copy.

errorIf an error occurs, upon return contains an NSError object that describes the problem.

Pass NULL if you do not want error information.



21

Return ValueThe number of bytes actually written to buffer. The number of bytes read will be less than the requestedrange if the range exceeds the file's size. If an error occurs, returns 0.

DiscussionThis method returns the biggest, best representation available, unadjusted in any way.


See Also– size (page 23)



metadata

Returns a dictionary of dictionaries of metadata for the representation.

- (NSDictionary *)metadata

Return ValueA dictionary of dictionaries of metadata for the representation. Returns nil if the representation is one thatthe system cannot interpret.



orientation

Returns the representation’s orientation.

- (ALAssetOrientation)orientation

Return ValueThe representation’s orientation. For a list of possible values, see ALAssetOrientation (page 49).



22


Related Sample CodeMyImagePickerPhotosByLocationPrintPhoto


scale

Returns the representation’s scale.

- (float)scale

Return ValueThe representation’s scale.


Related Sample CodeMyImagePickerPhotosByLocation


size

Returns the size in bytes of the file for the representation.

- (long long)size

Return ValueThe size in bytes of the file for the representation.

DiscussionYou typically use this method to allocate a buffer of the right size forgetBytes:fromOffset:length:error: (page 21).



23




url

Returns a persistent URL uniquely identifying the representation.

- (NSURL *)url

Return ValueA persistent URL uniquely identifying the representation.




UTI

Returns the representation's UTI.

- (NSString *)UTI

Return ValueThe representation's UTI





24





Declared in ALAssetsFilter.h

Related sample code AVMovieExporter

AVPlayerDemo

MyImagePicker

OverviewALAssetsFilter 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.

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

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


25

ALAssetsFilter Class Reference

Class Methods

allAssets

Returns a filter that gets all assets in the assets group.

+ (ALAssetsFilter *)allAssets

Return ValueA filter that gets all assets in the assets group.


Declared inALAssetsFilter.h

allPhotos

Returns a filter that gets all photos in the assets group.

+ (ALAssetsFilter *)allPhotos

Return ValueA filter that gets all photos in the assets group.


Related Sample CodeMyImagePicker


allVideos

Returns a filter that gets all videos in the assets group.

+ (ALAssetsFilter *)allVideos

Return ValueA filter that gets all videos in the assets group.

ALAssetsFilter Class ReferenceClass Methods


26


Related Sample CodeAVMovieExporterAVPlayerDemo


ALAssetsFilter Class ReferenceClass Methods


27





Declared in ALAssetsGroup.h


PhotosByLocation

OverviewAn ALAssetsGroup object represents an ordered set of the assets managed by the Photos application. Theorder of the elements is the same as the user sees in the Photos application. An asset can belong to multipleassets groups.

Assets groups themselves are synced via iTunes, created to hold the user’s saved photos or created duringcamera import. You can indirectly modify the Saved Photos group by saving images or videos into it using theALAssetsLibrary class.

Tasks

Enumerating Assets

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

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


28

ALAssetsGroup Class Reference

– 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.

editable (page 29) propertyIndicates whether the application can edit the group. (read-only)

Filtering

– numberOfAssets (page 32)Returns the number of assets in the group that match the current filter.

– setAssetsFilter: (page 33)Sets the filter for the group.

Accessing Properties

– valueForProperty: (page 34)Returns the group’s value for a given property.

– posterImage (page 32)Returns the group’s poster image

Properties

editable

Indicates whether the application can edit the group. (read-only)

@property(nonatomic, readonly, getter=isEditable) BOOL editable

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

ALAssetsGroup Class ReferenceProperties


29


Declared inALAssetsGroup.h

Instance Methods

addAsset:

Adds an existing asset to the receiver.

- (BOOL)addAsset:(ALAsset *)asset

Parametersasset

The asset to add to the receiver.

Return ValueYES if asset was added successfully, otherwise NO.

DiscussionThe 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 thegroup.



enumerateAssetsAtIndexes:options:usingBlock:

Invokes a given block using each of the assets in the group at specified indexes.

- (void)enumerateAssetsAtIndexes:(NSIndexSet *)indexSetoptions:(NSEnumerationOptions)optionsusingBlock:(ALAssetsGroupEnumerationResultsBlock)enumerationBlock

ALAssetsGroup Class ReferenceInstance Methods


30

ParametersindexSet

The indexes of the assets to enumerate.

The index set must not specify any indexes exceeding numberOfAssets (page 32).

optionsOptions for the enumeration.

enumerationBlockThe block to invoke using each of the assets in the group at the indexes in indexSet.

Discussion



enumerateAssetsUsingBlock:

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

-(void)enumerateAssetsUsingBlock:(ALAssetsGroupEnumerationResultsBlock)enumerationBlock

ParametersenumerationBlock

The block to invoke using each of the assets in the group.

Discussion




enumerateAssetsWithOptions:usingBlock:

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



31

- (void)enumerateAssetsWithOptions:(NSEnumerationOptions)optionsusingBlock:(ALAssetsGroupEnumerationResultsBlock)enumerationBlock

Parametersoptions

Options for the enumeration.

enumerationBlockThe block to invoke using each of the assets in the group.

Discussion



numberOfAssets

Returns the number of assets in the group that match the current filter.

- (NSInteger)numberOfAssets

Return ValueThe number of assets in the group that match the current filter. If no filter is set, returns the count of all assetsin the group.

Discussion


See Also– setAssetsFilter: (page 33)


posterImage

Returns the group’s poster image



32

- (CGImageRef)posterImage

Return ValueThe group’s poster image.

DiscussionThe image is returned in the correct orientation (that is, “pointing up”—you shouldn’t have to rotate the image).




setAssetsFilter:

Sets the filter for the group.

- (void)setAssetsFilter:(ALAssetsFilter *)filter

Parametersfilter

The filter for the group.

DiscussionThis method sets the filter the group; it does not execute the filter. The filter is applied when you invokenumberOfAssets (page 32) or enumerate the contents.

If you don’t set the filter, or set it to nil, the enumeration returns all the assets in the group.

Special ConsiderationsOnly one filter is active at a time. Any enumeration currently in flight continues to completion using the previousfilter.





33

valueForProperty:

Returns the group’s value for a given property.

- (id)valueForProperty:(NSString *)property

Parametersproperty

The name of a group property. For valid values, see “Group Property Names” (page 35).

Return ValueThe group’s value for property.

Discussion




Constants

ALAssetsGroupEnumerationResultsBlock

Signature for the block executed during enumeration of assets.

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

DiscussionThe block takes the following arguments:

resultAn asset that matches the filter set by the caller.

ALAssetsGroup Class ReferenceConstants


34

indexThe index of the asset in the range being returned.

If no asset is found, index is set to NSNotFound.

stopA pointer to a Boolean value that indicates whether the enumeration should stop. Set the referencedvalue 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 toYES.



Group Property Names

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

NSString *const ALAssetsGroupPropertyName;NSString *const ALAssetsGroupPropertyType;NSString *const ALAssetsGroupPropertyPersistentID;NSString *const ALAssetsGroupPropertyURL;

ConstantsALAssetsGroupPropertyName

Key to retrieve the name of the group.

The corresponding value is an NSString object.


Declared in ALAssetsGroup.h.

ALAssetsGroupPropertyTypeKey to retrieve the group type.

The corresponding value is an ALAssetsGroupType constant wrapped in an NSNumber object.





35

ALAssetsGroupPropertyPersistentIDKey to retrieve the group’s persistent ID.

The corresponding value is an NSString object.



ALAssetsGroupPropertyURLKey to retrieve a URL that uniquely identifies the group.

The corresponding value is an NSURL object.





36





Declared in ALAssetsLibrary.h

Related sample code AVCam

AVMovieExporter

AVPlayerDemo

MyImagePicker

PhotosByLocation

OverviewAn instance of ALAssetsLibrary provides access to the videos and photos that are under the control of thePhotos application.

The library includes those that are in the Saved Photos album, those coming from iTunes, and those that weredirectly imported into the device. You use it to retrieve the list of all asset groups and to save images andvideos 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. Thesemethods are all asynchronous because the user may need to be asked to grant access to the data.


37

ALAssetsLibrary Class Reference

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 grouptype.

Saving Assets

– writeVideoAtPathToSavedPhotosAlbum:completionBlock: (page 46)Saves a video identified by a given URL to the Saved Photos album.

– videoAtPathIsCompatibleWithSavedPhotosAlbum: (page 44)Returns a Boolean value that indicates whether a video identified by a given URL is compatible with theSaved Photos album.

– writeImageToSavedPhotosAlbum:orientation:completionBlock: (page 46)Saves a given image to the Saved Photos album.

– writeImageDataToSavedPhotosAlbum:metadata:completionBlock: (page 44)Writes given image data and metadata to the Photos Album.

ALAssetsLibrary Class ReferenceTasks


38

– 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 ValuePhoto data authorization status for this application. For the constants returned, see“ALAuthorizationStatus” (page 54).

DiscussionThis 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.


Declared inALAssetsLibrary.h

disableSharedPhotoStreamsSupport

Disables shared photo streams notifications and asset retrieval.

+ (void)disableSharedPhotoStreamsSupport

ALAssetsLibrary Class ReferenceClass Methods


39

DiscussionShared photo streams can generate frequent notifications. Use this method to disable support if appropriatefor your app.

Apps compiled against versions of iOS prior to iOS 6.0 do not have support for shared photo streams.



Instance Methods

addAssetsGroupAlbumWithName:resultBlock:failureBlock:

Adds a new assets group to the library.

- (void)addAssetsGroupAlbumWithName:(NSString *)nameresultBlock:(ALAssetsLibraryGroupResultBlock)resultBlockfailureBlock:(ALAssetsLibraryAccessFailureBlock)failureBlock

Parametersname

The name for the new group.

If name conflicts with another assets group with the same name, then the group is not created andresultBlock returns a nil group.

resultBlockThe block invoked after the add operation completes.

For a description of the block, see ALAssetsLibraryAccessFailureBlock (page 53).

failureBlockThe block to invoke if the add operation fails—for example, if the user denies access to the application.

For a description of the block, see ALAssetsGroupFaces (page 48).

DiscussionThe name of the new asset group is name, its type is ALAssetsGroupAlbum (page 48), and the editable (page29) property is YES.

ALAssetsLibrary Class ReferenceInstance Methods


40

This method is asynchronous. When the assets group is added, the user may be asked to confirm the application’saccess to the data; the method, though, returns immediately. You should perform whatever work you wantwith 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 iscurrently unavailable, the failure block is called.



assetForURL:resultBlock:failureBlock:

Invokes a given block passing as a parameter an asset identified by a specified file URL.

- (void)assetForURL:(NSURL *)assetURLresultBlock:(ALAssetsLibraryAssetForURLResultBlock)resultBlockfailureBlock:(ALAssetsLibraryAccessFailureBlock)failureBlock

ParametersassetURL

An asset URL previously retrieved from an ALAsset object.

resultBlockThe block to invoke using the asset identified by assetURL.

For a description of the block, see ALAssetsLibraryAssetForURLResultBlock (page 51).

failureBlockThe block to invoke if the user denies access to the assets library.


DiscussionThis method is asynchronous. When the asset is requested, the user may be asked to confirm the application'saccess to the library; the method, though, returns immediately. You should perform whatever work you wantwith the asset in resultBlock.

If the user denies access to the application, or if no application is allowed to access the data, the failure blockis called.




41

Related Sample CodePrintPhoto


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)typesusingBlock:(ALAssetsLibraryGroupsEnumerationResultsBlock)enumerationBlockfailureBlock:(ALAssetsLibraryAccessFailureBlock)failureBlock

Parameterstypes

The types of asset group over which to enumerate.

The value is a bitfield; you can OR together values fromwriteImageDataToSavedPhotosAlbum:metadata:completionBlock: (page 44).

enumerationBlockThe 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).

failureBlockThe block to invoke if the user denies access to the assets library.


DiscussionThe 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'saccess to the data; the method, though, returns immediately. You should perform whatever work you wantwith the assets in enumerationBlock.

If the user denies access to the application, or if no application is allowed to access the data, the failureBlockis called.

Special ConsiderationsThis method will fail with error ALAssetsLibraryAccessGloballyDeniedError (page 59) if the user has notenabled Location Services (in Settings > General).



42


Related Sample CodeAVMovieExporterAVPlayerDemoMTAudioProcessingTap Audio Processor


groupForURL:resultBlock:failureBlock:

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

- (void)groupForURL:(NSURL *)groupURLresultBlock:(ALAssetsLibraryGroupResultBlock)resultBlockfailureBlock:(ALAssetsLibraryAccessFailureBlock)failureBlock

ParametersgroupURL

The URL for an ALAssetsGroup object.

resultBlockThe block invoked after the access operation completes.


failureBlockThe block to invoke if the access operation fails—for example, if the user denies access to the application.

For a description of the block, see ALAssetsGroupFaces (page 48).

DiscussionThis method is asynchronous: it returns immediately. You should perform whatever work you want with theassets group in resultBlock.

This method is asynchronous. When the assets group is requested, the user may be asked to confirm theapplication’s access to the data; the method, though, returns immediately. You should perform whatever workyou 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 iscurrently unavailable, the failure block is called.




43


videoAtPathIsCompatibleWithSavedPhotosAlbum:

Returns a Boolean value that indicates whether a video identified by a given URL is compatible with the SavedPhotos album.

- (BOOL)videoAtPathIsCompatibleWithSavedPhotosAlbum:(NSURL *)videoPathURL


An URL that points to a video file.

Return ValueYES if the video identified by videoPathURL is compatible with the Saved Photos album, otherwise NO.

DiscussionThis method returns the same value as UIVideoAtPathIsCompatibleWithSavedPhotosAlbum would forthe same URL.


See Also– writeVideoAtPathToSavedPhotosAlbum:completionBlock: (page 46)


writeImageDataToSavedPhotosAlbum:metadata:completionBlock:

Writes given image data and metadata to the Photos Album.

- (void)writeImageDataToSavedPhotosAlbum:(NSData *)imageData metadata:(NSDictionary*)metadata completionBlock:(ALAssetsLibraryWriteImageCompletionBlock)completionBlock

ParametersimageData

Data for the image to add to the album.

metadataThe metadata to associate with the image.



44


For a description of the block, see ALAssetsLibraryWriteImageCompletionBlock (page 52).

DiscussionIf there is a conflict between the metadata in the image data and the metadata dictionary, the image datametadata values will be overwritten.


Related Sample CodeSquareCam


writeImageToSavedPhotosAlbum:metadata:completionBlock:

Writes a given image and metadata to the Photos Album.

- (void)writeImageToSavedPhotosAlbum:(CGImageRef)imageRef metadata:(NSDictionary*)metadata completionBlock:(ALAssetsLibraryWriteImageCompletionBlock)completionBlock

ParametersimageRef

The image to add to the album.

metadataThe metadata to associate with the image.



DiscussionYou must specify the orientation key in the metadata dictionary to preserve the orientation of the image.





45

writeImageToSavedPhotosAlbum:orientation:completionBlock:

Saves a given image to the Saved Photos album.

- (void)writeImageToSavedPhotosAlbum:(CGImageRef)imageReforientation:(ALAssetOrientation)orientationcompletionBlock:(ALAssetsLibraryWriteImageCompletionBlock)completionBlock

ParametersimageRef

The image to save to the Saved Photos album.

orientationThe orientation at which to save the image.



DiscussionIf you want to save a UIImage object, you can use the UIImage method CGImage to get a CGImageRef, andcast the image’s imageOrientation to ALAssetOrientation.


See Also– writeVideoAtPathToSavedPhotosAlbum:completionBlock: (page 46)


writeVideoAtPathToSavedPhotosAlbum:completionBlock:

Saves a video identified by a given URL to the Saved Photos album.

- (void)writeVideoAtPathToSavedPhotosAlbum:(NSURL *)videoPathURLcompletionBlock:(ALAssetsLibraryWriteVideoCompletionBlock)completionBlock


An URL that points to a video file.



46


For a description of the block, see ALAssetsLibraryWriteVideoCompletionBlock (page 52).

Discussion


See Also– videoAtPathIsCompatibleWithSavedPhotosAlbum: (page 44)– writeImageToSavedPhotosAlbum:orientation:completionBlock: (page 46)

Related Sample CodeAVCamAVMovieExporterAVSimpleEditoriOSRosyWriterStopNGo for iOS


Constants

ALAssetsGroupType

A bitfield to identify types of asset.

typedef NSUInteger ALAssetsGroupType;

DiscussionFor possible values, see “Types of Asset” (page 48).



ALAssetsLibrary Class ReferenceConstants


47

Types of Asset

Constants to identify types of asset.

enum {ALAssetsGroupLibrary = (1 << 0),ALAssetsGroupAlbum = (1 << 1),ALAssetsGroupEvent = (1 << 2),ALAssetsGroupFaces = (1 << 3),ALAssetsGroupSavedPhotos = (1 << 4),ALAssetsGroupPhotoStream = (1 << 5),ALAssetsGroupAll = 0xFFFFFFFF,

};

ConstantsALAssetsGroupLibrary

The Library group that includes all assets that are synced from iTunes.


Declared in ALAssetsLibrary.h.

ALAssetsGroupAlbumAll the albums created on the device or synced from iTunes, not including Photo Stream or Shared Streams



ALAssetsGroupEventAll events, including those created during Camera Connection Kit import.



ALAssetsGroupFacesAll the faces albums synced from iTunes.



ALAssetsGroupSavedPhotosAll the photos in the Camera Roll.





48

ALAssetsGroupPhotoStreamThe PhotoStream album.

In iOS 6.0 and later, this also includes Shared Streams.



ALAssetsGroupAllThe same as ORing together all the group types except for ALAssetsGroupLibrary.



ALAssetOrientation

Constants to indicate the orientation of an asset.

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

} ALAssetOrientation;

ConstantsALAssetOrientationUp

Indicates that the picture is in its default orientation, as shown here.



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

ALAssetOrientationUp (page 49), as shown here.





49

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




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




ALAssetOrientationUpMirroredIndicates that the picture has been flipped horizontally with respect to ALAssetOrientationUp (page

49), as shown here.



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

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



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

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



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

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



ALAssetsLibraryGroupsEnumerationResultsBlock

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



50

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

DiscussionThe block parameters are defined as follows:

groupThe current asset group in the enumeration.

stopA pointer to a boolean value; set the value to YES to stop enumeration.



ALAssetsLibraryAssetForURLResultBlock

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

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

DiscussionThe block parameter is defined as follows:

assetThe asset identified by the URL parameter in assetForURL:resultBlock:failureBlock: (page 41).

If the asset is not found, asset is nil.





51

ALAssetsLibraryWriteImageCompletionBlock

SignaturefortheblockexecutedwhenwriteImageToSavedPhotosAlbum:orientation:completionBlock: (page46) completes.

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


assetURLAn URL that identifies the saved image file.

If the image is not saved, assetURL is nil.

errorIf the image is not saved, an error object that describes the reason for failure, otherwise nil.



ALAssetsLibraryWriteVideoCompletionBlock

Signature for the block executed when writeVideoAtPathToSavedPhotosAlbum:completionBlock: (page46) completes.

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


assetURLAn URL that identifies the saved video file.

If the video is not saved, assetURL is nil.

errorIf the video is not saved, an error object that describes the reason for failure, otherwise nil.



52



ALAssetsLibraryAccessFailureBlock

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

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


errorAn error object that describes why access to the library failed.

This block type is used by assetForURL:resultBlock:failureBlock: (page 41) andenumerateGroupsWithTypes:usingBlock:failureBlock: (page 42).



ALAssetsLibraryGroupResultBlock

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

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




53

groupThe 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) andgroupForURL:resultBlock:failureBlock: (page 43).



ALAuthorizationStatus

Constants to indicate authorization status.

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

ConstantsALAuthorizationStatusNotDetermined

User has not yet made a choice with regards to this application.



ALAuthorizationStatusRestrictedThis application is not authorized to access photo data.

The user cannot change this application’s status, possibly due to active restrictions such as parentalcontrols being in place.



ALAuthorizationStatusDeniedUser has explicitly denied this application access to photos data.





54

ALAuthorizationStatusAuthorizedUser has authorized this application to access photos data.



Notification Keys

KeysusedtogetvaluesfromtheuserinformationdictionaryoftheALAssetsLibraryChangedNotification (page59) notification.

NSString * const ALAssetLibraryUpdatedAssetsKey;NSString * const ALAssetLibraryInsertedAssetGroupsKey;NSString * const ALAssetLibraryUpdatedAssetGroupsKey;NSString * const ALAssetLibraryDeletedAssetGroupsKey;

ConstantsALAssetLibraryUpdatedAssetsKey

Value is a set of NSURL objects identifying the assets that were updated.



ALAssetLibraryInsertedAssetGroupsKeyValue is a set of NSURL objects identifying the assets that were inserted.



ALAssetLibraryUpdatedAssetGroupsKeyValue is a set of NSURL objects identifying the asset groups that were updated.



ALAssetLibraryDeletedAssetGroupsKeyValue is a set of NSURL objects identifying the asset groups that were deleted.



DiscussionAssets that are modified use the ALAssetLibraryUpdatedAssetsKey key. Assets that are inserted or deleteduse the ALAssetLibraryUpdatedAssetGroupsKey key for the asset group that contains the asset.

Assets and asset groups that have no strong references are omitted from the notification’s user informationdictionary.



55

Error Domain

Constant for the AssetsLibrary domain.

NSString *const ALAssetsLibraryErrorDomain;

ConstantsALAssetsLibraryErrorDomain

Constant used by NSError to distinguish errors belonging to the AssetsLibrary domain.



Error Codes

AssetsLibrary-related error codes

enum {ALAssetsLibraryUnknownError = -1,

ALAssetsLibraryWriteFailedError = -3300,ALAssetsLibraryWriteBusyError = -3301,ALAssetsLibraryWriteInvalidDataError = -3302,ALAssetsLibraryWriteIncompatibleDataError = -3303,ALAssetsLibraryWriteDataEncodingError = -3304,ALAssetsLibraryWriteDiskSpaceError = -3305,

ALAssetsLibraryDataUnavailableError = -3310,

ALAssetsLibraryAccessUserDeniedError = -3311,ALAssetsLibraryAccessGloballyDeniedError = -3312,

};

ConstantsALAssetsLibraryUnknownError

The reason for the error is unknown.





56

ALAssetsLibraryWriteFailedErrorThe attempt to write data failed.

This error may be returned in the completion block forwriteVideoAtPathToSavedPhotosAlbum:completionBlock: (page 46) andwriteImageToSavedPhotosAlbum:orientation:completionBlock: (page 46) as well as the completionselector for UIImageWriteToSavedPhotosAlbum and UISaveVideoAtPathToSavedPhotosAlbum.



ALAssetsLibraryWriteBusyErrorWriting was already busy when the attempt to write was made.

You should attempt the write again.




ALAssetsLibraryWriteInvalidDataErrorThe data was invalid.




ALAssetsLibraryWriteIncompatibleDataErrorThe data contained incompatible data.






57

ALAssetsLibraryWriteDataEncodingErrorThe data contained data with the wrong encoding.




ALAssetsLibraryWriteDiskSpaceErrorThere was not enough space on the disk to write the data.




ALAssetsLibraryDataUnavailableErrorThe data was not available.

This error may be returned in the ALAssetsLibraryAccessFailureBlock (page 53) forenumerateGroupsWithTypes:usingBlock:failureBlock: (page 42) andassetForURL:resultBlock:failureBlock: (page 41); and in the completion blocks forwriteImageToSavedPhotosAlbum:orientation:completionBlock: (page 46) andwriteImageToSavedPhotosAlbum:orientation:completionBlock: (page 46); as well as in the completionselector for UIImageWriteToSavedPhotosAlbum and UISaveVideoAtPathToSavedPhotosAlbum.



ALAssetsLibraryAccessUserDeniedErrorThe user denied access to the library.

This error may be returned in the ALAssetsLibraryAccessFailureBlock (page 53) block forenumerateGroupsWithTypes:usingBlock:failureBlock: (page 42) andassetForURL:resultBlock:failureBlock: (page 41).





58

ALAssetsLibraryAccessGloballyDeniedErrorAccess to the library was denied globally.

This error may be returned in the ALAssetsLibraryAccessFailureBlock (page 53) block forenumerateGroupsWithTypes:usingBlock:failureBlock: (page 42) andassetForURL:resultBlock:failureBlock: (page 41).



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 notification’s object is nil. In iOS 4.1 and later, the notification object is the library object thatposted 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 keysused, see “Notification Keys” (page 55).

This notification is sent on an arbitrary thread.



ALAssetsLibrary Class ReferenceNotifications


59

This table describes the changes to Assets Library Framework Reference .

NotesDate

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

2010-04-19


60

Document Revision History

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 anyform or by any means, mechanical, electronic,photocopying, recording, or otherwise, withoutprior written permission of Apple Inc., with thefollowing exceptions: Any person is herebyauthorized to store documentation on a singlecomputer for personal use only and to printcopies of documentation for personal useprovided that the documentation containsApple’s copyright notice.

No licenses, express or implied, are granted withrespect to any of the technology described in thisdocument. Apple retains all intellectual propertyrights associated with the technology describedin this document. This document is intended toassist application developers to developapplications only for Apple-labeled computers.

Apple Inc.1 Infinite LoopCupertino, CA 95014408-996-1010

Apple, the Apple logo, iTunes, and Objective-Care trademarks of Apple Inc., registered in theU.S. and other countries.

iOS is a trademark or registered trademark ofCisco in the U.S. and other countries and is usedunder license.

Even though Apple has reviewed this document,APPLE MAKES NO WARRANTY OR REPRESENTATION,EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THISDOCUMENT, ITS QUALITY, ACCURACY,MERCHANTABILITY, OR FITNESS FOR A PARTICULARPURPOSE.ASARESULT, THISDOCUMENT ISPROVIDED“AS IS,” AND YOU, THE READER, ARE ASSUMING THEENTIRE RISK AS TO ITS QUALITY AND ACCURACY.

IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT,INDIRECT, SPECIAL, INCIDENTAL, ORCONSEQUENTIALDAMAGES RESULTING FROM ANY DEFECT ORINACCURACY IN THIS DOCUMENT, even if advised ofthe possibility of such damages.

THE WARRANTY AND REMEDIES SET FORTH ABOVEARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORALOR WRITTEN, EXPRESS OR IMPLIED. No Apple dealer,agent, or employee is authorized to make anymodification, extension, or addition to this warranty.

Some states do not allow the exclusion or limitationof implied warranties or liability for incidental orconsequential damages, so the above limitation orexclusion may not apply to you. This warranty givesyou specific legal rights, and youmay also have otherrights which vary from state to state.

Assets Library IOS

Documents

Transcript of Assets Library IOS