iOS Developer Library

Developer

AVFoundation Framework Reference AVAsynchronousKeyValueLoading Protocol Reference

Options
Deployment Target:

On This Page
Language:

AVAsynchronousKeyValueLoading

Inherits From


Not Applicable

Conforms To


Not Applicable

Import Statement


Swift

import AVFoundation

Objective-C

@import AVFoundation;

Availability


Available in iOS 4.0 and later

The AVAsynchronousKeyValueLoading protocol defines methods that let you use an AVAsset or AVAssetTrack object without blocking a thread. A “key” is any property in a class that implements this protocol. Using methods in the protocol, you can find out the current status of a key (for example, whether the corresponding value has been loaded); and ask the object to load values asynchronously, informing you when the operation has completed.

Because of the nature of timed audiovisual media, successful initialization of an asset does not necessarily mean that all its data is immediately available. Instead, an asset will wait to load data until an operation is performed on it (for example, directly invoking any relevant AVAsset methods, playback via an AVPlayerItem object, export using AVAssetExportSession, reading using an instance of AVAssetReader, and so on). This means that although you can request the value of any key at any time, and its value will be returned synchronously, the calling thread may be blocked until the request can be satisfied. To avoid blocking, you can:

Even for use cases that may typically support ready access to some keys (such as for assets initialized with URLs for files in the local filesystem), slow I/O may require AVAsset to block before returning their values. Although blocking may be acceptable in cases in which you are preparing assets on background threads or in operation queues, in all cases in which blocking should be avoided you should use loadValuesAsynchronouslyForKeys:completionHandler:.

  • Tells the asset to load the values of any of the specified keys that are not already loaded. (required)

    Declaration

    Swift

    func loadValuesAsynchronouslyForKeys(_ keys: [AnyObject]!, completionHandler handler: (() -> Void)!)

    Objective-C

    - (void)loadValuesAsynchronouslyForKeys:(NSArray *)keys completionHandler:(void (^)(void))handler

    Parameters

    keys

    An array of strings containing the required keys.

    The keys are the properties in a class that adopts the protocol.

    handler

    The block to be invoked when loading succeeds, fails, or is cancelled.

    Discussion

    The completion handler will be invoked exactly once per invocation of this method:

    • Synchronously if an I/O error or other format-related error occurs immediately.

    • Asynchronously at a subsequent time if a loading error occurs at a later stage of processing, if cancelLoading is invoked on an AVAsset instance, or when the values of all of the specified keys become loaded.

    The completion states of the keys you specify in keys are not necessarily the same—some may be loaded, and others may have failed. You must check the status of each key individually.

    You can call this method at any time, even after an asset has begun to load data for operations in progress or already completed. Whenever any module requires a certain collection of key-values, it can call this method and be assured of receiving its specified callback as soon as possible.

    An example block is shown below.

    • [asset loadValuesAsynchronouslyForKeys:[NSArray keyWithObject:@"duration"] completionHandler:^{
    • NSError *error = nil;
    • switch ([asset statusOfValueForKey:@"duration" error:&error]) {
    • case AVKeyValueStatusLoaded:
    • // duration is now known, so we can fetch it without blocking
    • CMTime duration = [asset duration];
    • // dispatch a block to the main thread that updates the display of asset duration in my user interface,
    • // or do something else interesting with it
    • default:
    • // something went wrong; depending on what it was, we may want to dispatch a
    • // block to the main thread to report th e error
    • }
    • }];

    If a fatal error has already occurred, the completion handler is invoked synchronously.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.0 and later

  • Reports whether the value for a given key is immediately available without blocking. (required)

    Declaration

    Swift

    func statusOfValueForKey(_ key: String!, error outError: NSErrorPointer) -> AVKeyValueStatus

    Objective-C

    - (AVKeyValueStatus)statusOfValueForKey:(NSString *)key error:(NSError **)outError

    Parameters

    key

    The key whose status you want. See AVKeyValueStatus for the defined keys.

    outError

    If the status of the value for the key is AVKeyValueStatusFailed, upon passes by-reference an NSError object that describes the failure that occurred.

    Return Value

    The current loading status of the value for key. See AVKeyValueStatus for the defined keys.

    Discussion

    You use this method to determine the availability of the value for a key. This method does not cause an asset to load the value of a key that’s not yet available. To request values for keys that may not already be loaded without blocking, use loadValuesAsynchronouslyForKeys:completionHandler: and wait for invocation of the completion handler to be informed of availability.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.0 and later

  • Constants that specify the load status of a property.

    Declaration

    Swift

    enum AVKeyValueStatus : Int { case Unknown case Loading case Loaded case Failed case Cancelled }

    Objective-C

    enum { AVKeyValueStatusUnknown, AVKeyValueStatusLoading, AVKeyValueStatusLoaded, AVKeyValueStatusFailed, AVKeyValueStatusCancelled }; typedef NSInteger AVKeyValueStatus;

    Constants

    • Unknown

      AVKeyValueStatusUnknown

      Indicates that the property status is unknown.

      Available in iOS 4.0 and later

    • Loading

      AVKeyValueStatusLoading

      Indicates that the property is not fully loaded.

      Available in iOS 4.0 and later

    • Loaded

      AVKeyValueStatusLoaded

      Indicates that the property is ready for use.

      Available in iOS 4.0 and later

    • Failed

      AVKeyValueStatusFailed

      Indicates that the attempt to load the property failed.

      Available in iOS 4.0 and later

    • Cancelled

      AVKeyValueStatusCancelled

      Indicates that the attempt to load the property was cancelled.

      Available in iOS 4.0 and later

    Discussion

    See also statusOfValueForKey:error:.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.0 and later