iOS Developer Library

Developer

AssetsLibrary Framework Reference ALAssetsLibrary Class Reference

Options
Deployment Target:

On This Page
Language:

ALAssetsLibrary

Inherits From


Conforms To


Import Statement


Swift

import AssetsLibrary

Objective-C

@import AssetsLibrary;

Availability


Available in iOS 4.0 and later

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.

  • Returns photo data authorization status for this application.

    Declaration

    Swift

    class func authorizationStatus() -> ALAuthorizationStatus

    Objective-C

    + (ALAuthorizationStatus)authorizationStatus

    Return Value

    Photo data authorization status for this application. For the constants returned, see ALAuthorizationStatus.

    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.

    Import Statement

    Objective-C

    @import AssetsLibrary;

    Swift

    import AssetsLibrary

    Availability

    Available in iOS 6.0 and later

  • Disables shared photo streams notifications and asset retrieval.

    Declaration

    Swift

    class func disableSharedPhotoStreamsSupport()

    Objective-C

    + (void)disableSharedPhotoStreamsSupport

    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.

    Import Statement

    Objective-C

    @import AssetsLibrary;

    Swift

    import AssetsLibrary

    Availability

    Available in iOS 6.0 and later

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

    Declaration

    Swift

    func assetForURL(_ assetURL: NSURL!, resultBlock resultBlock: ALAssetsLibraryAssetForURLResultBlock!, failureBlock failureBlock: ALAssetsLibraryAccessFailureBlock!)

    Objective-C

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

    failureBlock

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

    For a description of the block, see ALAssetsLibraryAccessFailureBlock.

    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.

    Import Statement

    Objective-C

    @import AssetsLibrary;

    Swift

    import AssetsLibrary

    Availability

    Available in iOS 4.0 and later

  • Invokes a given block passing as a parameter each of the asset groups that match the given asset group type.

    Declaration

    Swift

    func enumerateGroupsWithTypes(_ types: ALAssetsGroupType, usingBlock enumerationBlock: ALAssetsLibraryGroupsEnumerationResultsBlock!, failureBlock failureBlock: ALAssetsLibraryAccessFailureBlock!)

    Objective-C

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

    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.

    failureBlock

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

    For a description of the block, see ALAssetsLibraryAccessFailureBlock.

    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 if the user has not enabled Location Services (in Settings > General).

    Import Statement

    Objective-C

    @import AssetsLibrary;

    Swift

    import AssetsLibrary

    Availability

    Available in iOS 4.0 and later

  • Adds a new assets group to the library.

    Declaration

    Swift

    func addAssetsGroupAlbumWithName(_ name: String!, resultBlock resultBlock: ALAssetsLibraryGroupResultBlock!, failureBlock failureBlock: ALAssetsLibraryAccessFailureBlock!)

    Objective-C

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

    failureBlock

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

    Discussion

    The name of the new asset group is name, its type is ALAssetsGroupAlbum, and the editable property is YEStrue.

    This method is asynchronous. When the assets group is added, 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 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.

    Import Statement

    Objective-C

    @import AssetsLibrary;

    Swift

    import AssetsLibrary

    Availability

    Available in iOS 5.0 and later

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

    Declaration

    Swift

    func groupForURL(_ groupURL: NSURL!, resultBlock resultBlock: ALAssetsLibraryGroupResultBlock!, failureBlock failureBlock: ALAssetsLibraryAccessFailureBlock!)

    Objective-C

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

    failureBlock

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

    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 application’s 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.

    Import Statement

    Objective-C

    @import AssetsLibrary;

    Swift

    import AssetsLibrary

    Availability

    Available in iOS 5.0 and later

Data Types

  • A bitfield to identify types of asset.

    Declaration

    Swift

    typealias ALAssetsGroupType = Int

    Objective-C

    typedef NSUInteger ALAssetsGroupType;

    Discussion

    For possible values, see Types of Asset.

    Import Statement

    Objective-C

    @import AssetsLibrary;

    Swift

    import AssetsLibrary

    Availability

    Available in iOS 4.0 and later

  • Signature for the block executed when a match is found during enumeration using enumerateGroupsWithTypes:usingBlock:failureBlock:.

    Declaration

    Swift

    typealias ALAssetsLibraryGroupsEnumerationResultsBlock = (ALAssetsGroup!, UnsafeMutablePointer<ObjCBool>) -> Void

    Objective-C

    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 YEStrue to stop enumeration.

    Import Statement

    Objective-C

    @import AssetsLibrary;

    Swift

    import AssetsLibrary

    Availability

    Available in iOS 4.0 and later

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

    Declaration

    Swift

    typealias ALAssetsLibraryAssetForURLResultBlock = (ALAsset!) -> Void

    Objective-C

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

    If the asset is not found, asset is nil.

    Import Statement

    Objective-C

    @import AssetsLibrary;

    Swift

    import AssetsLibrary

    Availability

    Available in iOS 4.0 and later

  • Signature for the block executed when writeImageToSavedPhotosAlbum:orientation:completionBlock: completes.

    Declaration

    Swift

    typealias ALAssetsLibraryWriteImageCompletionBlock = (NSURL!, NSError!) -> Void

    Objective-C

    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.

    Import Statement

    Objective-C

    @import AssetsLibrary;

    Swift

    import AssetsLibrary

    Availability

    Available in iOS 4.0 and later

  • Signature for the block executed when writeVideoAtPathToSavedPhotosAlbum:completionBlock: completes.

    Declaration

    Swift

    typealias ALAssetsLibraryWriteVideoCompletionBlock = (NSURL!, NSError!) -> Void

    Objective-C

    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.

    Import Statement

    Objective-C

    @import AssetsLibrary;

    Swift

    import AssetsLibrary

    Availability

    Available in iOS 4.0 and later

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

    Declaration

    Swift

    typealias ALAssetsLibraryAccessFailureBlock = (NSError!) -> Void

    Objective-C

    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: and enumerateGroupsWithTypes:usingBlock:failureBlock:.

    Import Statement

    Objective-C

    @import AssetsLibrary;

    Swift

    import AssetsLibrary

    Availability

    Available in iOS 4.0 and later

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

    Declaration

    Swift

    typealias ALAssetsLibraryGroupResultBlock = (ALAssetsGroup!) -> Void

    Objective-C

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

    Discussion

    The block parameter is defined as follows:

    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: and groupForURL:resultBlock:failureBlock:.

    Import Statement

    Objective-C

    @import AssetsLibrary;

    Swift

    import AssetsLibrary

    Availability

    Available in iOS 5.0 and later

  • Constants to identify types of asset.

    Declaration

    Swift

    var ALAssetsGroupLibrary: UInt32 { get } var ALAssetsGroupAlbum: UInt32 { get } var ALAssetsGroupEvent: UInt32 { get } var ALAssetsGroupFaces: UInt32 { get } var ALAssetsGroupSavedPhotos: UInt32 { get } var ALAssetsGroupPhotoStream: UInt32 { get } var ALAssetsGroupAll: UInt32 { get }

    Objective-C

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

    Constants

    • ALAssetsGroupLibrary

      ALAssetsGroupLibrary

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

      Available in iOS 4.0 and later

    • ALAssetsGroupAlbum

      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

    • ALAssetsGroupEvent

      ALAssetsGroupEvent

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

      Available in iOS 4.0 and later

    • ALAssetsGroupFaces

      ALAssetsGroupFaces

      All the faces albums synced from iTunes.

      Available in iOS 4.0 and later

    • ALAssetsGroupSavedPhotos

      ALAssetsGroupSavedPhotos

      All the photos in the Camera Roll.

      Available in iOS 4.0 and later

    • ALAssetsGroupPhotoStream

      ALAssetsGroupPhotoStream

      The PhotoStream album.

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

      Available in iOS 5.0 and later

    • ALAssetsGroupAll

      ALAssetsGroupAll

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

      Available in iOS 4.0 and later

  • Constants to indicate the orientation of an asset.

    Declaration

    Swift

    enum ALAssetOrientation : Int { case Up case Down case Left case Right case UpMirrored case DownMirrored case LeftMirrored case RightMirrored }

    Objective-C

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

    Constants

    • Up

      ALAssetOrientationUp

      Indicates that the picture is in its default orientation, as shown here.image: ../Art/UIImageOrientationUp.jpg

      Available in iOS 4.0 and later

    • Down

      ALAssetOrientationDown

      Indicates that the picture has been rotated through 180 degrees with respect to ALAssetOrientationUp, as shown here.image: ../Art/UIImageOrientationDown.jpg

      Available in iOS 4.0 and later

    • Left

      ALAssetOrientationLeft

      Indicates that the picture has been rotated through 90 degrees counter-clockwise with respect to ALAssetOrientationUp, as shown here.image: ../Art/UIImageOrientationLeft.jpg

      Available in iOS 4.0 and later

    • Right

      ALAssetOrientationRight

      Indicates that the picture has been rotated through 90 degrees clockwise with respect to ALAssetOrientationUp, as shown here.image: ../Art/UIImageOrientationRight.jpg

      Available in iOS 4.0 and later

    • UpMirrored

      ALAssetOrientationUpMirrored

      Indicates that the picture has been flipped horizontally with respect to ALAssetOrientationUp, as shown here.image: ../Art/UIImageOrientationUpMirrored.jpg

      Available in iOS 4.0 and later

    • DownMirrored

      ALAssetOrientationDownMirrored

      Indicates that the picture has been rotated through 180 degrees with respect to ALAssetOrientationUp and then flipped horizontally, as shown here.image: ../Art/UIImageOrientationDownMirrored.jpg

      Available in iOS 4.0 and later

    • LeftMirrored

      ALAssetOrientationLeftMirrored

      Indicates that the picture has been rotated through 90 degrees counter-clockwise with respect to ALAssetOrientationUp and then flipped vertically, as shown here.image: ../Art/UIImageOrientationLeftMirrored.jpg

      Available in iOS 4.0 and later

    • RightMirrored

      ALAssetOrientationRightMirrored

      Indicates that the picture has been rotated through 90 degrees clockwise with respect to ALAssetOrientationUp and then flipped vertically, as shown here.image: ../Art/UIImageOrientationRightMirrored.jpg

      Available in iOS 4.0 and later

    Import Statement

    Objective-C

    @import AssetsLibrary;

    Swift

    import AssetsLibrary

    Availability

    Available in iOS 4.0 and later

  • Constants to indicate authorization status.

    Declaration

    Swift

    enum ALAuthorizationStatus : Int { case NotDetermined case Restricted case Denied case Authorized }

    Objective-C

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

    Constants

    • NotDetermined

      ALAuthorizationStatusNotDetermined

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

      Available in iOS 6.0 and later

    • Restricted

      ALAuthorizationStatusRestricted

      This application is not authorized to access photo data.

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

      Available in iOS 6.0 and later

    • Denied

      ALAuthorizationStatusDenied

      User has explicitly denied this application access to photos data.

      Available in iOS 6.0 and later

    • Authorized

      ALAuthorizationStatusAuthorized

      User has authorized this application to access photos data.

      Available in iOS 6.0 and later

    Import Statement

    Objective-C

    @import AssetsLibrary;

    Swift

    import AssetsLibrary

    Availability

    Available in iOS 6.0 and later

  • Keys used to get values from the user information dictionary of the ALAssetsLibraryChangedNotification notification.

    Declaration

    Swift

    let ALAssetLibraryUpdatedAssetsKey: String let ALAssetLibraryInsertedAssetGroupsKey: String let ALAssetLibraryUpdatedAssetGroupsKey: String let ALAssetLibraryDeletedAssetGroupsKey: String

    Objective-C

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

    Constants

    • ALAssetLibraryUpdatedAssetsKey

      ALAssetLibraryUpdatedAssetsKey

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

      Available in iOS 6.0 and later

    • ALAssetLibraryInsertedAssetGroupsKey

      ALAssetLibraryInsertedAssetGroupsKey

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

      Available in iOS 6.0 and later

    • ALAssetLibraryUpdatedAssetGroupsKey

      ALAssetLibraryUpdatedAssetGroupsKey

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

      Available in iOS 6.0 and later

    • ALAssetLibraryDeletedAssetGroupsKey

      ALAssetLibraryDeletedAssetGroupsKey

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

      Available in iOS 6.0 and later

    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 notification’s user information dictionary.

  • Constant for the AssetsLibrary domain.

    Declaration

    Swift

    let ALAssetsLibraryErrorDomain: String

    Objective-C

    NSString *const ALAssetsLibraryErrorDomain;

    Constants

    • ALAssetsLibraryErrorDomain

      ALAssetsLibraryErrorDomain

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

      Available in iOS 4.0 and later

  • AssetsLibrary-related error codes

    Declaration

    Swift

    var ALAssetsLibraryUnknownError: Int { get } var ALAssetsLibraryWriteFailedError: Int { get } var ALAssetsLibraryWriteBusyError: Int { get } var ALAssetsLibraryWriteInvalidDataError: Int { get } var ALAssetsLibraryWriteIncompatibleDataError: Int { get } var ALAssetsLibraryWriteDataEncodingError: Int { get } var ALAssetsLibraryWriteDiskSpaceError: Int { get } var ALAssetsLibraryDataUnavailableError: Int { get } var ALAssetsLibraryAccessUserDeniedError: Int { get } var ALAssetsLibraryAccessGloballyDeniedError: Int { get }

    Objective-C

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

    Constants

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

    This notification is sent on an arbitrary thread.

    Import Statement

    Objective-C

    @import AssetsLibrary;

    Swift

    import AssetsLibrary

    Availability

    Available in iOS 4.0 and later