ALAsset Class Reference

Inherits from	NSObject
Conforms to	NSObject (NSObject)
Framework	/System/Library/Frameworks/AssetsLibrary.framework
Availability	Available in iOS 4.0 and later.
Declared in	ALAsset.h
Related sample code	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

Accessing Representations

Setting New Image and Video Data

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

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 notification is posted.

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

Discussion

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

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 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 up”—you shouldn’t have to rotate the image).

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

Return Value

The value for property. If property is not a valid key, returns ALErrorInvalidProperty.

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

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;

Constants

ALAssetPropertyType

A key to retrieve the type of the asset.

Possible values are given in “Asset Types.”

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

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: is invalid.

NSString *const ALErrorInvalidProperty;

Constants

ALErrorInvalidProperty

Value returned by valueForProperty: if the property you tried to access is invalid.

Available in iOS 4.0 and later.

Declared in ALAsset.h.

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 doesn’t 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 property.

Did this document help you?

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.