Next Page >

Hide TOC

QTCaptureConnection Class Reference

Inherits from	NSObject
Conforms to	NSObject (NSObject)
Framework	/System/Library/Frameworks/QTKit.framework
Availability	Available in QuickTime 7.2.1 and later; QuickTime 7.2.1.
Declared in	QTCaptureConnection.h
Related sample code	QTRecorder

Overview

This class represents a connection over which a single stream of media data is sent from a QTCaptureInput to a QTCaptureSession and from a QTCaptureSession to a QTCaptureOutput.

Instances of QTCaptureConnection wrap individual media streams that can be provided by QTCaptureInput objects and received by QTCaptureOutput objects. Connections can have a QuickTime media type, such as QTMediaTypeVideo and QTMediaTypeSound, and a format description that describes the media sent or received across the connection. Individual connections belonging to an input can be enabled or disabled to restrict what media enters a capture session, while connections belonging to an output can be enabled or disabled to restrict what media enters the output from the capture session. In addition, if a QTCaptureConnection wraps a stream of audio media, it provides a number of attributes to control the volume, mix, and enabled channels of the audio passing through it.

QTCaptureConnection objects can have extended attributes that applications can read using the attributeForKey: and connectionAttributes methods. Some attributes, for which the attributeIsReadOnly: method returns NO, can be edited using the setAttribute:forKey: and setConnectionAttributes: methods. In addition to these explicit methods, applications can use key-value coding to get and set extended attributes. For an object that supports a given attribute, valueForKey:will be functionally identical to attributeForKey:, and setValue:forKey: will be identical to setAttribute:forKey:. Applications wishing to observe changes for a given attribute can add a key-value observer where the key path is the attribute key.

Tasks

Getting and Setting Connection Attributes

Instance Methods

attributeForKey:

Returns the current value of the connection attribute for key.

- (id)attributeForKey:(NSString *)attributeKey

Discussion

Use this method to get attributes of a connection. The keys that can be used with this method are described in the Constants section. Applications using key-value coding can also get an attribute for a given key by passing that key to the NSObject valueForKey: method.

Availability

Mac OS X v10.5 and later; QuickTime 7.2.1.

Related Sample Code

QTRecorder

Declared In

QTCaptureConnection.h

attributeIsReadOnly:

Returns a Boolean value indicating whether the given attribute for the connection cannot be modified.

- (BOOL)attributeIsReadOnly:(NSString *)attributeKey

Return Value

Returns YES if the attribute cannot be modified; otherwise, NO.

Availability

Mac OS X v10.5 and later; QuickTime 7.2.1.

Declared In

QTCaptureConnection.h

connectionAttributes

Returns a dictionary of all attributes set for the receiver.

- (NSDictionary *)connectionAttributes

Discussion

Applications can use this method to determine what attributes a specific connection supports.

Availability

Mac OS X v10.5 and later; QuickTime 7.2.1.

Declared In

QTCaptureConnection.h

formatDescription

Returns the format description of the receiver.

- (QTFormatDescription *)formatDescription

Discussion

This method returns the format description of the connection, allowing applications to monitor various attributes of the media being sent or received by the connection (the display size of video media, for example). Applications can be notified of changes to the connection’s format by registering to receive QTCaptureConnectionFormatDescriptionWillChangeNotification and QTCaptureConnectionFormatDescriptionDidChangeNotification notifications or by adding a key-value observer to the connection for the key @"formatDescription".

Availability

Mac OS X v10.5 and later; QuickTime 7.2.1.

Related Sample Code

QTRecorder

Declared In

QTCaptureConnection.h

isEnabled

Returns a Boolean value indicating whether the receiver is enabled.

- (BOOL)isEnabled

Discussion

This method returns a Boolean indicating whether the receiver is enabled to send or receive media data. Individual connections can be enabled or disabled using the setEnabled: method.

Availability

Mac OS X v10.5 and later; QuickTime 7.2.1.

Declared In

QTCaptureConnection.h

mediaType

Returns the QuickTime media type of the receiver.

- (NSString *)mediaType

Return Value

A QuickTime media type, as defined in QTMedia.h.

Discussion

This method returns the QuickTime media type, such as QTMediaTypeVideo and QTMediaTypeSound, of the receiver.

Availability

Mac OS X v10.5 and later; QuickTime 7.2.1.

Declared In

QTCaptureConnection.h

owner

Returns the QTCaptureInput or QTCaptureOutput object that owns the receiver.

- (id)owner

Return Value

A QTCaptureInput or QTCaptureOutput object that uses the receiver as a media connection.

Discussion

This method returns the input or output to which the receiver belongs. The returned input or output uses the receiver as a connection for sending or receiving a media stream.

Availability

Mac OS X v10.5 and later; QuickTime 7.2.1.

Declared In

QTCaptureConnection.h

setAttribute:forKey:

Sets a connection attribute for the given key.

- (void)setAttribute:(id)attribute forKey:(NSString *)key

Discussion

Use this method to set attributes of a capture connection. The keys that can be used with this method are described in the Constants section. This method raises an NSInvalidArgumentException if the attribute is read-only or not supported by the receiver. Applications using key-value coding can also set an attribute for a given key by passing that key to the NSObject setValue:forKey: method.

Availability

Mac OS X v10.5 and later; QuickTime 7.2.1.

Declared In

QTCaptureConnection.h

setConnectionAttributes:

Sets the connection’s attributes from the key-value pairs specified in the given dictionary.

- (void)setConnectionAttributes:(NSDictionary *)connectionAttributes

Discussion

This method allows application to set multiple attributes on a connection at once. This method raises an NSInvalidArgumentException if any of the attributes in the dictionary are read-only or not supported by the receiver. Applications using key-value coding can also set multiple attributes using the NSObject setValuesForKeysWithDictionary: method using attribute keys as keys in the dictionary.

Availability

Mac OS X v10.5 and later; QuickTime 7.2.1.

Declared In

QTCaptureConnection.h

setEnabled:

Sets whether the receiver is enabled.

- (void)setEnabled:(BOOL)enabled

Discussion

This method sets whether the receiver is enabled to send or receive media data.

Availability

Mac OS X v10.5 and later; QuickTime 7.2.1.

Declared In

QTCaptureConnection.h

Constants

Audio Attributes

Applications can use the following constants to display audio level meters for specific connections and to specify the volumes of audio channels. These string values can be used in key paths for key-value coding, key-value observing, and bindings.

NSString * const QTCaptureConnectionAudioAveragePowerLevelsAttribute;
NSString * const QTCaptureConnectionAudioPeakHoldLevelsAttribute;
NSString * const QTCaptureConnectionAudioMasterVolumeAttribute;
NSString * const QTCaptureConnectionAudioVolumesAttribute;
NSString * const QTCaptureConnectionEnabledAudioChannelsAttribute;

Constants

QTCaptureConnectionAudioAveragePowerLevelsAttribute

An NSArray of NSNumbers that correspond to the average power, in decibels, of each audio stream sent through the connection.

Applications that wish to display audio level meters for a specific connection can periodically check the value of this attribute. Average power levels change quickly and appear jumpy on a level meter. This string value can be used in key paths for key-value coding, key-value observing, and bindings.

Available in Mac OS X v10.5 and later.