Mac Developer Library

Developer

DRTrack.h Reference

Options
Deployment Target:

On This Page
Language:

DRTrack.h Reference

Base class for track handling

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 possible values and meanings of each.

All other keys contained in the properties dictionary are optional and can be omitted.

Included Headers

  • <Foundation/Foundation.h>

  • <DiscRecording/DRCoreTrack.h>

  • <DiscRecording/DRDevice.h>

  • <stdint.h>

  • <AvailabilityMacros.h>

Constants

See the Overview section above for header-level documentation.

  • Declaration

    Swift

    let DRAbstractFile: NSString! let DRApplicationIdentifier: NSString! let DRAudioFourChannelKey: NSString! let DRAudioPreEmphasisKey: NSString! let DRBibliographicFile: NSString! let DRBlockSize: NSString! let DRBlockSizeKey: NSString! let DRBlockTypeKey: NSString! let DRCopyrightFile: NSString! let DRDataFormKey: NSString! let DRDataPreparer: NSString! let DRDefaultDate: NSString! let DRDVDCopyrightInfoKey: NSString! let DRDVDTimestampKey: NSString! let DRFreeBlocksKey: NSString! let DRIndexPointsKey: NSString! let DRISOLevel: NSString! let DRISOMacExtensions: NSString! let DRISORockRidgeExtensions: NSString! let DRMaxBurnSpeedKey: NSString! let DRNextWritableAddressKey: NSString! let DRPreGapIsRequiredKey: NSString! let DRPreGapLengthKey: NSString! let DRPublisher: NSString! let DRSCMSCopyrightFree: NSString! let DRSCMSCopyrightProtectedCopy: NSString! let DRSCMSCopyrightProtectedOriginal: NSString! let DRSerialCopyManagementStateKey: NSString! let DRSessionFormatKey: NSString! let DRSessionNumberKey: NSString! let DRSubchannelDataFormKey: NSString! let DRSubchannelDataFormNone: NSString! let DRSubchannelDataFormPack: NSString! let DRSubchannelDataFormRaw: NSString! let DRSuppressMacSpecificFiles: NSString! let DRSystemIdentifier: NSString! let DRTrackIsEmptyKey: NSString! let DRTrackISRCKey: NSString! let DRTrackLengthKey: NSString! let DRTrackModeKey: NSString! let DRTrackNumberKey: NSString! let DRTrackPacketSizeKey: NSString! let DRTrackPacketTypeFixed: NSString! let DRTrackPacketTypeKey: NSString! let DRTrackPacketTypeVariable: NSString! let DRTrackStartAddressKey: NSString! let DRTrackTypeClosed: NSString! let DRTrackTypeIncomplete: NSString! let DRTrackTypeInvisible: NSString! let DRTrackTypeKey: NSString! let DRTrackTypeReserved: NSString! let DRVerificationTypeChecksum: NSString! let DRVerificationTypeKey: NSString! let DRVerificationTypeNone: NSString! let DRVerificationTypeProduceAgain: NSString! let DRVerificationTypeReceiveData: NSString! let DRVolumeCheckedDate: NSString! let DRVolumeCreationDate: NSString! let DRVolumeEffectiveDate: NSString! let DRVolumeExpirationDate: NSString! let DRVolumeModificationDate: NSString! let DRVolumeSet: NSString!

    Objective-C

    extern NSString* const DRAbstractFile; extern NSString* const DRApplicationIdentifier; extern NSString* const DRAudioFourChannelKey; extern NSString* const DRAudioPreEmphasisKey; extern NSString* const DRBibliographicFile; extern NSString* const DRBlockSize; extern NSString* const DRBlockSizeKey; extern NSString* const DRBlockTypeKey; extern NSString* const DRCopyrightFile; extern NSString* const DRDataFormKey; extern NSString* const DRDataPreparer; extern NSString* const DRDefaultDate; extern NSString* const DRDVDCopyrightInfoKey; extern NSString* const DRDVDTimestampKey; extern NSString* const DRFreeBlocksKey; extern NSString* const DRIndexPointsKey; extern NSString* const DRISOLevel; extern NSString* const DRISOMacExtensions; extern NSString* const DRISORockRidgeExtensions; extern NSString* const DRMaxBurnSpeedKey; extern NSString* const DRNextWritableAddressKey; extern NSString* const DRPreGapIsRequiredKey; extern NSString* const DRPreGapLengthKey; extern NSString* const DRPublisher; extern NSString* const DRSCMSCopyrightFree; extern NSString* const DRSCMSCopyrightProtectedCopy; extern NSString* const DRSCMSCopyrightProtectedOriginal; extern NSString* const DRSerialCopyManagementStateKey; extern NSString* const DRSessionFormatKey; extern NSString* const DRSessionNumberKey; extern NSString* const DRSubchannelDataFormKey; extern NSString * const DRSubchannelDataFormNone; extern NSString* const DRSubchannelDataFormPack; extern NSString* const DRSubchannelDataFormRaw; extern NSString* const DRSuppressMacSpecificFiles; extern NSString* const DRSystemIdentifier; extern NSString* const DRTrackIsEmptyKey; extern NSString* const DRTrackISRCKey; extern NSString* const DRTrackLengthKey; extern NSString* const DRTrackModeKey; extern NSString* const DRTrackNumberKey; extern NSString* const DRTrackPacketSizeKey; extern NSString* const DRTrackPacketTypeFixed; extern NSString* const DRTrackPacketTypeKey; extern NSString* const DRTrackPacketTypeVariable; extern NSString* const DRTrackStartAddressKey; extern NSString* const DRTrackTypeClosed; extern NSString* const DRTrackTypeIncomplete; extern NSString* const DRTrackTypeInvisible; extern NSString* const DRTrackTypeKey; extern NSString* const DRTrackTypeReserved; extern NSString * const DRVerificationTypeChecksum; extern NSString* const DRVerificationTypeKey; extern NSString* const DRVerificationTypeNone; extern NSString* const DRVerificationTypeProduceAgain; extern NSString* const DRVerificationTypeReceiveData; extern NSString* const DRVolumeCheckedDate; extern NSString* const DRVolumeCreationDate; extern NSString* const DRVolumeEffectiveDate; extern NSString* const DRVolumeExpirationDate; extern NSString* const DRVolumeModificationDate; extern NSString* const DRVolumeSet;

    Constants

    • DRAbstractFile

      DRAbstractFile

      DRFile pointing to the abstract file for ISO and Joliet volumes. The file must be in the root directory.

      Available in OS X v10.2 and later.

    • DRApplicationIdentifier

      DRApplicationIdentifier

      NSString indicating the application identifier for ISO, Joliet and UDF volumes.

      Available in OS X v10.2 and later.

    • DRAudioFourChannelKey

      DRAudioFourChannelKey

      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.

      Available in OS X v10.3 and later.

    • DRAudioPreEmphasisKey

      DRAudioPreEmphasisKey

      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.

      Available in OS X v10.3 and later.

    • DRBibliographicFile

      DRBibliographicFile

      DRFile pointing to the bibliographic file for ISO and Joliet volumes. The file must be in the root directory.

      Available in OS X v10.2 and later.

    • DRBlockSize

      DRBlockSize

      NSNumber indicating the block size of the track. Currently always 2048. Do not change.

      Available in OS X v10.2 and later.

    • DRBlockSizeKey

      DRBlockSizeKey

      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.

      Available in OS X v10.2 and later.

    • DRBlockTypeKey

      DRBlockTypeKey

      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.

      Available in OS X v10.2 and later.

    • DRCopyrightFile

      DRCopyrightFile

      DRFile pointing to the copyright file for ISO and Joliet volumes. The file must be in the root directory.

      Available in OS X v10.2 and later.

    • DRDataFormKey

      DRDataFormKey

      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.

      Available in OS X v10.2 and later.

    • DRDataPreparer

      DRDataPreparer

      NSString indicating the data preparer for ISO and Joliet volumes.

      Available in OS X v10.2 and later.

    • DRDefaultDate

      DRDefaultDate

      NSDate containing the default date to use for any unspecified dates in the filesystem. The current date and time is used if unspecified.

      Available in OS X v10.2 and later.

    • DRDVDCopyrightInfoKey

      DRDVDCopyrightInfoKey

      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.

      Available in OS X v10.2 and later.

    • DRDVDTimestampKey

      DRDVDTimestampKey

      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.

      Available in OS X v10.2 and later.

    • DRFreeBlocksKey

      DRFreeBlocksKey

      NSNumber containing the length, in blocks, which is still available in a writable track.

      Available in OS X v10.3 and later.

    • DRIndexPointsKey

      DRIndexPointsKey

      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 .

      Available in OS X v10.3 and later.

    • DRISOLevel

      DRISOLevel

      NSNumber containing the ISO level of the ISO-9660 filesystem on the track. Currently should be 1 or 2.

      Available in OS X v10.2 and later.

    • DRISOMacExtensions

      DRISOMacExtensions

      NSBoolean indicating whether the track should have Mac extensions.

      Available in OS X v10.2 and later.

    • DRISORockRidgeExtensions

      DRISORockRidgeExtensions

      NSBoolean indicating whether the track should have RockRidge (POSIX) extensions.

      Available in OS X v10.2 and later.

    • DRMaxBurnSpeedKey

      DRMaxBurnSpeedKey

      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.

      Available in OS X v10.2 and later.

    • DRNextWritableAddressKey

      DRNextWritableAddressKey

      NSNumber containing the LBA of the next writable address in the track. This key is not present in closed tracks.

      Available in OS X v10.3 and later.

    • DRPreGapIsRequiredKey

      DRPreGapIsRequiredKey

      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.

      Available in OS X v10.5 and later.

    • DRPreGapLengthKey

      DRPreGapLengthKey

      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.

      Available in OS X v10.2 and later.

    • DRPublisher

      DRPublisher

      NSString indicating the publisher for ISO and Joliet volumes.

      Available in OS X v10.2 and later.

    • DRSCMSCopyrightFree

      DRSCMSCopyrightFree

      One possible value for the DRSerialCopyManagementStateKey . Indicates that the track has no copying restrictions. Copies of this track should also be copyright free.

      Available in OS X v10.3 and later.

    • DRSCMSCopyrightProtectedCopy

      DRSCMSCopyrightProtectedCopy

      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.

      Available in OS X v10.3 and later.

    • DRSCMSCopyrightProtectedOriginal

      DRSCMSCopyrightProtectedOriginal

      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.

      Available in OS X v10.3 and later.

    • DRSerialCopyManagementStateKey

      DRSerialCopyManagementStateKey

      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 .

      Available in OS X v10.3 and later.

    • DRSessionFormatKey

      DRSessionFormatKey

      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.

      Available in OS X v10.2 and later.

    • DRSessionNumberKey

      DRSessionNumberKey

      NSNumber containing the physical session number of a track.

      Available in OS X v10.3 and later.

    • DRSubchannelDataFormKey

      DRSubchannelDataFormKey

      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.

      Available in OS X v10.5 and later.

    • DRSubchannelDataFormNone

      DRSubchannelDataFormNone

      A value for DRSubchannelDataFormKey indicating that the subchannel data will not be provided by the producer.

      Available in OS X v10.5 and later.

    • DRSubchannelDataFormPack

      DRSubchannelDataFormPack

      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.

      Available in OS X v10.5 and later.

    • DRSubchannelDataFormRaw

      DRSubchannelDataFormRaw

      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.

      Available in OS X v10.5 and later.

    • DRSuppressMacSpecificFiles

      DRSuppressMacSpecificFiles

      NSBoolean indicating whether the track should suppress Mac-specific files from non-HFS filesystems.

      Available in OS X v10.3 and later.

    • DRSystemIdentifier

      DRSystemIdentifier

      NSString indicating the system identifier for ISO and Joliet volumes.

      Available in OS X v10.2 and later.

    • DRTrackIsEmptyKey

      DRTrackIsEmptyKey

      NSNumber containing a BOOL value and indicates whether the track is empty.

      Available in OS X v10.3 and later.

    • DRTrackISRCKey

      DRTrackISRCKey

      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 .

      Available in OS X v10.3 and later.

    • DRTrackLengthKey

      DRTrackLengthKey

      NSNumber representing the length of the track

      Available in OS X v10.2 and later.

    • DRTrackModeKey

      DRTrackModeKey

      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.

      Available in OS X v10.2 and later.

    • DRTrackNumberKey

      DRTrackNumberKey

      NSNumber containing the physical track number of a track.

      Available in OS X v10.3 and later.

    • DRTrackPacketSizeKey

      DRTrackPacketSizeKey

      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.

      Available in OS X v10.3 and later.

    • DRTrackPacketTypeFixed

      DRTrackPacketTypeFixed

      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.

      Available in OS X v10.3 and later.

    • DRTrackPacketTypeKey

      DRTrackPacketTypeKey

      NSString indicating the kind of packets being written.

      Available in OS X v10.3 and later.

    • DRTrackPacketTypeVariable

      DRTrackPacketTypeVariable

      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.

      Available in OS X v10.3 and later.

    • DRTrackStartAddressKey

      DRTrackStartAddressKey

      NSNumber containing the LBA of the start address for the track.

      Available in OS X v10.3 and later.

    • DRTrackTypeClosed

      DRTrackTypeClosed

      If this is the value of the DRTrackTypeKey then the track has been written and is closed.

      Available in OS X v10.3 and later.

    • DRTrackTypeIncomplete

      DRTrackTypeIncomplete

      If this is the value of the DRTrackTypeKey then the track is not invisible or reserved and is available for writing.

      Available in OS X v10.3 and later.

    • DRTrackTypeInvisible

      DRTrackTypeInvisible

      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.

      Available in OS X v10.3 and later.

    • DRTrackTypeKey

      DRTrackTypeKey

      NSString indicating the type of track. Possible values are: DRTrackTypeInvisible , DRTrackTypeIncomplete , DRTrackTypeReserved or DRTrackTypeClosed .

      Available in OS X v10.3 and later.

    • DRTrackTypeReserved

      DRTrackTypeReserved

      If this is the value of the DRTrackTypeKey then the track is reserved for writing.

      Available in OS X v10.3 and later.

    • DRVerificationTypeChecksum

      DRVerificationTypeChecksum

      One of the possible values of the DRVerificationTypeKey . The engine will verify the track data with an internally calculated checksum.

      Available in OS X v10.4 and later.

    • DRVerificationTypeKey

      DRVerificationTypeKey

      NSString indicating the type of verification to be performed. If this is not present, the track will not be verified.

      Available in OS X v10.2 and later.

    • DRVerificationTypeNone

      DRVerificationTypeNone

      One of the possible values of the DRVerificationTypeKey . No verification is desired, so verification will be skipped.

      Available in OS X v10.2 and later.

    • DRVerificationTypeProduceAgain

      DRVerificationTypeProduceAgain

      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.

      Available in OS X v10.2 and later.

    • DRVerificationTypeReceiveData

      DRVerificationTypeReceiveData

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

      Available in OS X v10.2 and later.

    • DRVolumeCheckedDate

      DRVolumeCheckedDate

      NSDate containing the volume-checked date for HFS+ volumes. DRDefaultDate is used if unspecified.

      Available in OS X v10.2 and later.

    • DRVolumeCreationDate

      DRVolumeCreationDate

      NSDate containing the volume creation date. DRDefaultDate is used if unspecified.

      Available in OS X v10.2 and later.

    • DRVolumeEffectiveDate

      DRVolumeEffectiveDate

      NSDate containing the date and time at which the volume is effective for ISO and Joliet volumes.

      Available in OS X v10.2 and later.

    • DRVolumeExpirationDate

      DRVolumeExpirationDate

      NSDate containing the volume expiration date for ISO and Joliet volumes.

      Available in OS X v10.2 and later.

    • DRVolumeModificationDate

      DRVolumeModificationDate

      NSDate containing the volume modification date. DRDefaultDate is used if unspecified.

      Available in OS X v10.2 and later.

    • DRVolumeSet

      DRVolumeSet

      NSString indicating the volume set name for ISO and Joliet volumes.

      Available in OS X v10.2 and later.

  • Declaration

    Swift

    var DRFlagSubchannelDataRequested: Int { get }

    Objective-C

    enum { DRFlagSubchannelDataRequested = ( 1 << 1) };

    Constants

    • DRFlagSubchannelDataRequested

      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.

      Available in OS X v10.5 and later.

    Discussion

    These flags are options for the flags parameter of producePreGapForTrack:intoBuffer:length:atAddress:blockSize:ioFlags: and produceDataForTrack:intoBuffer:length:atAddress:blockSize:ioFlags:.