AVAsynchronousKeyValueLoading Protocol Reference

Framework
/System/Library/Frameworks/AVFoundation.framework
Availability
Available in iOS 4.0 and later.
Declared in
AVAsynchronousKeyValueLoading.h

Overview

The AVAsynchronousKeyValueLoading protocol defines methods that let you use an AVAsset or AVAssetTrack object without blocking a thread. 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:.

Tasks

Protocol Methods

Instance Methods

loadValuesAsynchronouslyForKeys:completionHandler:

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

- (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 the error 
    }
 
}];

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

Availability
  • Available in iOS 4.0 and later.
Declared In
AVAsynchronousKeyValueLoading.h

statusOfValueForKey:error:

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

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

Availability
  • Available in iOS 4.0 and later.
Declared In
AVAsynchronousKeyValueLoading.h

Constants

AVKeyValueStatus

Constants that specify the load status of a property.

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

Indicates that the property status is unknown.

Available in iOS 4.0 and later.

Declared in AVAsynchronousKeyValueLoading.h.

AVKeyValueStatusLoading

Indicates that the property is not fully loaded.

Available in iOS 4.0 and later.

Declared in AVAsynchronousKeyValueLoading.h.

AVKeyValueStatusLoaded

Indicates that the property is ready for use.

Available in iOS 4.0 and later.

Declared in AVAsynchronousKeyValueLoading.h.

AVKeyValueStatusFailed

Indicates that the attempt to load the property failed.

Available in iOS 4.0 and later.

Declared in AVAsynchronousKeyValueLoading.h.

AVKeyValueStatusCancelled

Indicates that the attempt to load the property was cancelled.

Available in iOS 4.0 and later.

Declared in AVAsynchronousKeyValueLoading.h.

Discussion

See also statusOfValueForKey:error:.