| Includes: | <stdint.h>
<AvailabilityMacros.h> |
Overview
Base class for track handling
Discussion
About tracks
A DRTrack provides data to the for the burn and contains a description of the
track on disc (length, block type, data format, etc).
Data is provided for the burn in a real-time thread. It is up to the track to
provide this data in a timely manner, otherwise a burn underrun can occur and
ruin a disc.
Data Production
DRTracks do not typically store or cache the data to be written to disk, instead the
data is streamed to the disc from some data producer as it's needed. This is
accomplished through an object associated with the track when the track is created
called the track producer. A track producer is a class you create that implements
the DRTrackDataProduction informal protocol. This protocol defines all of
the methods that a track object will call during a burn to obtain data.
Track Properties
A DRTrack object contains several properties which define the track for the burn.
These properties are stored in an NSDictionary and are accessed through the properties
and setProperties: methods.
There are several properties that are required to be present and if they are not, will
cause the burn to fail. These are:
The possible values of these properties are defined in the Mt. Fuji (IFF-8090i)
specification for CD/DVD devices. It's up to you to understand the possble values
and meanings of each.
All other keys contained in the properties dictionary are optional and can be omitted.
Classes
- DRTrack
- The DRTrack class represents a track on the burned disc.
Protocols
- DRTrackDataProduction
- Informal protocol describing methods implemented by a track data producer.
Categories
- DRTrack(PropertyConvenience)
Constants
extern NSString* const DRAbstractFile;
Discussion
DRFile pointing to the abstract file for ISO and Joliet volumes. The file must be in the root directory.
- Availability
- Introduced in Mac OS X v10.2
extern NSString* const DRApplicationIdentifier;
Discussion
NSString indicating the application identifier for ISO, Joliet and UDF volumes.
- Availability
- Introduced in Mac OS X v10.2
extern NSString* const DRAudioFourChannelKey;
Discussion
For CD-DA audio tracks only. This key points to a BOOL value indicating
whether the track data has four channels, as opposed to the
two channels of normal stereo. If this key is not present, the engine
will use a default value of NO and standard two-channel stereo
is assumed.
Note that while four-channel is technically allowed in the Red Book,
it never caught on and is probably being replaced by SACD, so
you probably shouldn't attempt to use it.
On the media, this key corresponds to bit 3 of the control field in
sub-channel Q.
- Availability
- Introduced in Mac OS X v10.3.
extern NSString* const DRAudioPreEmphasisKey;
Discussion
For CD-DA audio tracks only. This key points to a BOOL value indicating
whether the track includes pre-emphasis of 50/15us. If this key is not
present, the engine will use a default value of NO. On the media, this
key corresponds to bit 0 of the control field in sub-channel Q.
- Availability
- Introduced in Mac OS X v10.3.
extern NSString* const DRBibliographicFile;
Discussion
DRFile pointing to the bibliographic file for ISO and Joliet volumes. The file must be in the root directory.
- Availability
- Introduced in Mac OS X v10.2
extern NSString* const DRBlockSize;
Discussion
NSNumber indicating the block size of the track. Currently always 2048. Do not change.
- Availability
- Introduced in Mac OS X v10.2
extern NSString* const DRBlockSizeKey;
Discussion
NSNumber containing the size in bytes of each track block.
See the Mt. Fuji (INF-8090i) specification for CD/DVD devices for possible
values for this property.
- Availability
- Introduced in Mac OS X v10.2
extern NSString* const DRBlockTypeKey;
Discussion
NSNumber containing the type of each track block.
See the Mt. Fuji (INF-8090i) specification for CD/DVD devices for possible
values for this property.
- Availability
- Introduced in Mac OS X v10.2
extern NSString* const DRCopyrightFile;
Discussion
DRFile pointing to the copyright file for ISO and Joliet volumes. The file must be in the root directory.
- Availability
- Introduced in Mac OS X v10.2
extern NSString* const DRDataFormKey;
Discussion
NSNumber containing the data form of each block in the track.
See the Mt. Fuji (INF-8090i) specification for CD/DVD devices for possible
values for this property.
- Availability
- Introduced in Mac OS X v10.2
extern NSString* const DRDataPreparer;
Discussion
NSString indicating the data preparer for ISO and Joliet volumes.
- Availability
- Introduced in Mac OS X v10.2
extern NSString* const DRDefaultDate;
Discussion
NSDate containing the default date to use for any unspecified dates in the filesystem. The current date and time is used if unspecified.
- Availability
- Introduced in Mac OS X v10.2
extern NSString* const DRDVDCopyrightInfoKey;
Discussion
For DVD tracks only. NSData containing the DVD copyright info structure
sent through the SEND DVD STRUCTURE command. The contents of this will
be sent directly to the drive.
- Availability
- Introduced in Mac OS X v10.2
extern NSString* const DRDVDTimestampKey;
Discussion
For DVD tracks only. NSData containing the DVD timestamp structure sent
through the SEND DVD STRUCTURE command. The contents of this will be
sent directly to the drive.
- Availability
- Introduced in Mac OS X v10.2
extern NSString* const DRFreeBlocksKey;
Discussion
NSNumber containing the length, in blocks, which is
still available in a writable track.
- Availability
- Introduced in Mac OS X v10.3.
extern NSString* const DRIndexPointsKey;
Discussion
For CD tracks only. This key points to an NSArray of NSNumbers, indicating
the index points inside the track. Each index point is specified as a number
of blocks (frames) relative to the start of the track. There are 75 blocks
in one second of CD audio. No more than 98 index points may be specified
for a track.
Not all drives are capable of writing index points, and not all consumer
CD players report or use them. If this key is present in any track and the
drive cannot write index points, the burn will fail with
kDRDeviceCantWriteIndexPointsErr .
- Availability
- Introduced in Mac OS X v10.3.
extern NSString* const DRISOLevel;
Discussion
NSNumber containing the ISO level of the ISO-9660 filesystem on the track. Currently should be 1 or 2.
- Availability
- Introduced in Mac OS X v10.2
extern NSString* const DRISOMacExtensions;
Discussion
NSBoolean indicating whether the track should have Mac extensions.
- Availability
- Introduced in Mac OS X v10.2
extern NSString* const DRISORockRidgeExtensions;
Discussion
NSBoolean indicating whether the track should have RockRidge (POSIX) extensions.
- Availability
- Introduced in Mac OS X v10.2
extern NSString* const DRMaxBurnSpeedKey;
Discussion
NSNumber containing the maximum burn speed at which data can be produced.
The speed is represented in KB/s (1 KB = 1000 bytes). This key can only
be used to limit the speed at which the burn runs.
- Availability
- Introduced in Mac OS X v10.2
extern NSString* const DRNextWritableAddressKey;
Discussion
NSNumber containing the LBA of the next writable address
in the track. This key is not present in closed tracks.
- Availability
- Introduced in Mac OS X v10.3.
extern NSString* const DRPreGapIsRequiredKey;
Discussion
For CD tracks only. NSNumber indicating whether the pregap listed for the
track is required. If this key is not present, the track will behave as
though the key were NO.
If this key's value is set to YES and the device does
not support the exact pregap length, the burn
will fail with a return value of kDRDevicePregapLengthNotAvailableErr .
If this key's value is set to YES and the device does
not support any of the suggested pregap length, the engine
will choose an alternate pregap length.
- Availability
- Introduced in Mac OS X v10.5.
extern NSString* const DRPreGapLengthKey;
Discussion
For CD tracks only. NSNumber containing the length of silence or data at the
beginning of the track. This defaults to 2 seconds of silence. If this
key is present, the track producer will be asked for the pregap data first.
If the producer implements the proper selector, then it's the responsibility
of the producer to provide data for the pregap, otherwise that length of
silence will be produced by Disc Recording.
- Availability
- Introduced in Mac OS X v10.2
extern NSString* const DRPublisher;
Discussion
NSString indicating the publisher for ISO and Joliet volumes.
- Availability
- Introduced in Mac OS X v10.2
extern NSString* const DRSCMSCopyrightFree;
Discussion
One possible value for the DRSerialCopyManagementStateKey . Indicates that
the track has no copying restrictions. Copies of this track should also be
copyright free.
- Availability
- Introduced in Mac OS X v10.3.
extern NSString* const DRSCMSCopyrightProtectedCopy;
Discussion
One possible value for the DRSerialCopyManagementStateKey . Indicates that
the track is a first-generation copy of an original that was subject to copy
protection. No further digital copying should be allowed.
- Availability
- Introduced in Mac OS X v10.3.
extern NSString* const DRSCMSCopyrightProtectedOriginal;
Discussion
One possible value for the DRSerialCopyManagementStateKey . Indicates that
the track is an original subject to copyright protection. Digital copying of
this track should be allowed, but copies should be marked with SCMS.
- Availability
- Introduced in Mac OS X v10.3.
extern NSString* const DRSerialCopyManagementStateKey;
Discussion
For CD tracks only. This key points to an NSString value indicating the
SCMS state of the track. If this key is not present, no SCMS data is
written.
Not all drives are capable of writing SCMS. If this key is present in
any track and the drive cannot write SCMS, the burn will fail with
kDRDeviceCantWriteSCMSErr .
- Availability
- Introduced in Mac OS X v10.3.
extern NSString* const DRSessionFormatKey;
Discussion
NSNumber containing the session format of the track.
See the Mt. Fuji (INF-8090i) specification for CD/DVD devices for possible
values for this property.
- Availability
- Introduced in Mac OS X v10.2
extern NSString* const DRSessionNumberKey;
Discussion
NSNumber containing the physical session number of a track.
- Availability
- Introduced in Mac OS X v10.3.
extern NSString* const DRSubchannelDataFormKey;
Discussion
The property whose value is the data mode of the subchannel data sent to the drive.
If this key is not present, the track will default to a value of DRSubchannelDataFormNone
and no subchannel information will be requested from the producer.
Subchannel data is returned from the producer in the same production method that produces normal user data.
Normally a producer returns user data in chunks of DRBlockSizeKey size. When subchannel
data is also produced, the producer is expected to return user data of DRBlockSizeKey in length with an additonal
96 bytes of subchannel data. Depending on the data form specified in this key, the format of this 96 bytes is
either in raw or pack format. When subchannel data is requested from the producer, the DRFlagSubchannelDataRequested flag is set in the flags parameter of
producePreGapForTrack:intoBuffer:length:atAddress:blockSize:ioFlags:
or produceDataForTrack:intoBuffer:length:atAddress:blockSize:ioFlags: and blockSize is increased by 96 bytes.
- Availability
- Introduced in Mac OS X v10.5.
extern NSString * const DRSubchannelDataFormNone;
Discussion
A value for DRSubchannelDataFormKey indicating that the
subchannel data will not be provided by the producer.
- Availability
- Introduced in Mac OS X v10.5.
extern NSString* const DRSubchannelDataFormPack;
Discussion
A value for DRSubchannelDataFormKey indicating that the
producer will be asked to provide pack format subchannel data for the track. If this form is selected,
the drive will perform P and Q parity calculations on each pack and interleave the packs before writing them to
disc.
This corresponds to a subchannel data form of 0xC0.
- Availability
- Introduced in Mac OS X v10.5.
extern NSString* const DRSubchannelDataFormRaw;
Discussion
A value for DRSubchannelDataFormKey indicating that the
producer will be asked to provide raw format subchannel data for the track. If this form is selected,
the producer must have performed P and Q parity calculations for each pack and done proper interleaving of the subchannel
data. The drive will fill in the P-Q subchannel information and write the R-W subchannel data as is to the disc.
This corresponds to a subchannel data form of 0x40.
- Availability
- Introduced in Mac OS X v10.5.
extern NSString* const DRSuppressMacSpecificFiles;
Discussion
NSBoolean indicating whether the track should suppress Mac-specific files from
non-HFS filesystems.
- Availability
- Introduced in Mac OS X v10.3.
extern NSString* const DRSystemIdentifier;
Discussion
NSString indicating the system identifier for ISO and Joliet volumes.
- Availability
- Introduced in Mac OS X v10.2
extern NSString* const DRTrackIsEmptyKey;
Discussion
NSNumber containing a BOOL value and indicates whether the track is empty.
- Availability
- Introduced in Mac OS X v10.3.
extern NSString* const DRTrackISRCKey;
Discussion
For CD-DA audio tracks only. This key points to an NSData containing
exactly 12 bytes, which will be written to the disc as the International
Standard Recording Code (ISRC). If this key is not present, no ISRC
is written.
The use of this value should conform to the specifications of the IFPI. See
http://www.ifpi.org/isrc/ for more details on the ISRC standard.
Not all drives are capable of the write modes necessary to write the ISRC.
If this key is present in any track and the drive cannot write the ISRC, the
burn will fail with kDRDeviceCantWriteISRCErr .
- Availability
- Introduced in Mac OS X v10.3.
extern NSString* const DRTrackLengthKey;
Discussion
NSNumber representing the length of the track
- Availability
- Introduced in Mac OS X v10.2
extern NSString* const DRTrackModeKey;
Discussion
NSNumber containing the track mode of the track.
See the Mt. Fuji (INF-8090i) specification for CD/DVD devices for possible
values for this property.
- Availability
- Introduced in Mac OS X v10.2
extern NSString* const DRTrackNumberKey;
Discussion
NSNumber containing the physical track number of a track.
- Availability
- Introduced in Mac OS X v10.3.
extern NSString* const DRTrackPacketSizeKey;
Discussion
NSNumber containing the number of blocks per packet for
the disc. It will only be present if the disc contains fixed packets. This key
will contain 16 for DVD media, and typically contains either 16 or 32 for CD media.
- Availability
- Introduced in Mac OS X v10.3.
extern NSString* const DRTrackPacketTypeFixed;
Discussion
If this is the value of the DRTrackPacketTypeKey then the disc is writen with
fixed sized packets. When this value is present the DRPacketSizeKey will also be
present.
- Availability
- Introduced in Mac OS X v10.3.
extern NSString* const DRTrackPacketTypeKey;
Discussion
NSString indicating the kind of packets being written.
- Availability
- Introduced in Mac OS X v10.3.
extern NSString* const DRTrackPacketTypeVariable;
Discussion
If this is the value of the DRTrackPacketTypeKey then the disc is written with
sequential variable sized packets. The presence of this value indicates the lack
of the DRPacketSizeKey.
- Availability
- Introduced in Mac OS X v10.3.
extern NSString* const DRTrackStartAddressKey;
Discussion
NSNumber containing the LBA of the start address for the
track.
- Availability
- Introduced in Mac OS X v10.3.
extern NSString* const DRTrackTypeClosed;
Discussion
If this is the value of the DRTrackTypeKey then the track has been
written and is closed.
- Availability
- Introduced in Mac OS X v10.3.
extern NSString* const DRTrackTypeIncomplete;
Discussion
If this is the value of the DRTrackTypeKey then the track is not invisible or
reserved and is available for writing.
- Availability
- Introduced in Mac OS X v10.3.
extern NSString* const DRTrackTypeInvisible;
Discussion
If this is the value of the DRTrackTypeKey then the track is invisible and
available to writing. If it is packet written and not closed, DRPacketTypeKey will
be present, along with DRTrackPacketType and DRTrackPacketSize keys.
- Availability
- Introduced in Mac OS X v10.3.
extern NSString* const DRTrackTypeKey;
Discussion
NSString indicating the type of track. Possible values are:
DRTrackTypeInvisible , DRTrackTypeIncomplete ,
DRTrackTypeReserved or DRTrackTypeClosed .
- Availability
- Introduced in Mac OS X v10.3.
extern NSString* const DRTrackTypeReserved;
Discussion
If this is the value of the DRTrackTypeKey then the track is reserved for writing.
- Availability
- Introduced in Mac OS X v10.3.
extern NSString * const DRVerificationTypeChecksum;
Discussion
One of the possible values of the DRVerificationTypeKey .
The engine will verify the track data with an internally calculated checksum.
- Availability
- Introduced in Mac OS X v10.4.
extern NSString* const DRVerificationTypeKey;
Discussion
NSString indicating the type of verification to be performed. If this is not
present, the track will not be verified.
- Availability
- Introduced in Mac OS X v10.2
extern NSString* const DRVerificationTypeNone;
Discussion
One of the possible values of the DRVerificationTypeKey .
No verification is desired, so verification will be skipped.
- Availability
- Introduced in Mac OS X v10.2
extern NSString* const DRVerificationTypeProduceAgain;
Discussion
One of the possible values of the DRVerificationTypeKey .
The engine will simply begin another production cycle and start calling
<produceDataForTrack:intoBuffer:length:atAddress:blockSize:ioFlags: again.
- Availability
- Introduced in Mac OS X v10.2
extern NSString* const DRVerificationTypeReceiveData;
Discussion
One of the possible values of the DRVerificationTypeKey .
The engine will begin reading data from the disc and calling
verifyDataForTrack:inBuffer:length:atAddress:blockSize:ioFlags: .
- Availability
- Introduced in Mac OS X v10.2
extern NSString* const DRVolumeCheckedDate;
Discussion
NSDate containing the volume-checked date for HFS+ volumes. DRDefaultDate is used if unspecified.
- Availability
- Introduced in Mac OS X v10.2
extern NSString* const DRVolumeCreationDate;
Discussion
NSDate containing the volume creation date. DRDefaultDate is used if unspecified.
- Availability
- Introduced in Mac OS X v10.2
extern NSString* const DRVolumeEffectiveDate;
Discussion
NSDate containing the date and time at which the volume is effective for ISO and Joliet volumes.
- Availability
- Introduced in Mac OS X v10.2
extern NSString* const DRVolumeExpirationDate;
Discussion
NSDate containing the volume expiration date for ISO and Joliet volumes.
- Availability
- Introduced in Mac OS X v10.2
extern NSString* const DRVolumeModificationDate;
Discussion
NSDate containing the volume modification date. DRDefaultDate is used if unspecified.
- Availability
- Introduced in Mac OS X v10.2
extern NSString* const DRVolumeSet;
Discussion
NSString indicating the volume set name for ISO and Joliet volumes.
- Availability
- Introduced in Mac OS X v10.2
Enumerations
#if MAC_OS_X_VERSION_MAX_ALLOWED >= MAC_OS_X_VERSION_10_5
enum {
DRFlagSubchannelDataRequested = (
1 << 1)
};
#endif
Constants
DRFlagSubchannelDataRequested- Indicates that the blockSize passed in includes room for subchannel data.
Data producers should check this flag and perform subchannel data production
in addition to user fata production. Each block requested from the producer in
this case will be formatted as
[user data (as specified in track properties)][subchannel data(96 bytes)].
For example an audio producer callback should repeatedly produce 2352 bytes
of audio data into bytes 0-2351 of the block and an additional 96 bytes of
subchannel data into bytes 2352-2447.
Discussion
These flags are options for the flags parameter of
producePreGapForTrack:intoBuffer:length:atAddress:blockSize:ioFlags:
and produceDataForTrack:intoBuffer:length:atAddress:blockSize:ioFlags:.
Last Updated: 2008-04-01
