Mac Developer Library

Developer

DRTrackDataProduction Class Reference

Options
Deployment Target:

On This Page
Language:

DRTrackDataProduction

Informal protocol describing methods implemented by a track data producer.

The DRTrackDataProduction informal protocol defines those methods that a track data producer instance can implement. A track data producer is the object that is resposible for providing the track data to the burn engine on request.

In concept a track data producer similar to an NSTable data source in Cocoa. Each producer method receives a pointer to the track it should produce data for. There is one method that must be implemented - produceDataForTrack:intoBuffer:length:atAddress:blockSize:ioFlags: .

The methods of this protocol will be called in roughly this order:

  1. prepareTrackForBurn:

  2. producePreGapForTrack:intoBuffer:length:atAddress:blockSize:ioFlags:

  3. produceDataForTrack:intoBuffer:length:atAddress:blockSize:ioFlags:

  4. prepareTrackForVerification:

  5. verifyDataForTrack:inBuffer:length:atAddress:blockSize:ioFlags:

  6. cleanupTrackAfterVerification:

  7. cleanupTrackAfterBurn:

If verification of the disc is not requested, or a track omits or defines DRVerificationTypeKey to be DRVerificationTypeNone , then prepareTrackForVerification: , verifyDataForTrack:inBuffer:length:atAddress:blockSize:ioFlags: and cleanupTrackAfterVerification: will not be called.

During a burn, produceDataForTrack:intoBuffer:length:atAddress:blockSize:ioFlags: is called very frequently in a real-time thread. Because of this, it is of utmost importance that this method very effficient and does not perform any long task, since by doing so, the burn may fail because data is not available to write to the disc.

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Swift

import DiscRecording

Objective-C

@import DiscRecording;

Availability


Available in OS X v10.2 and later.
  • Cleans up the track after the burn completes. (required)

    Declaration

    Swift

    func cleanupTrackAfterBurn(_ track: DRTrack!)

    Objective-C

    - (void)cleanupTrackAfterBurn:(DRTrack *)track

    Parameters

    track

    The track object being burned

    Return Value

    YES to indicate that the burn should proceed and NO to indicate a failure occurred.

    Discussion

    Called after burning is complete. Typically you'll clean up what was setup in prepareTrackForBurn. Since this method is called after the laser is turned off and the burn is finished, this method can perform time consuming tasks.

    Import Statement

    Objective-C

    @import DiscRecording;

    Swift

    import DiscRecording

    Availability

    Available in OS X v10.2 and later.

  • Cleans up the track after the verification completes. (required)

    Declaration

    Swift

    func cleanupTrackAfterVerification(_ track: DRTrack!) -> Bool

    Objective-C

    - (BOOL)cleanupTrackAfterVerification:(DRTrack *)track

    Parameters

    track

    The track object being burned

    Return Value

    Return YES to indicate success, NO to indicate failure.

    Discussion

    Once the verification phase is complete, this method is called. The class implementing the method has a chance to do anything up to and including failing the verification.

    Import Statement

    Objective-C

    @import DiscRecording;

    Swift

    import DiscRecording

    Availability

    Available in OS X v10.2 and later.

  • Estimates the size of the track to be burned. (required)

    Declaration

    Swift

    func estimateLengthOfTrack(_ track: DRTrack!) -> UInt64

    Objective-C

    - (uint64_t)estimateLengthOfTrack:(DRTrack *)track

    Parameters

    track

    The track object for which to estimate the size

    Return Value

    The number of blocks of data that the track will occupy. The estimate should be reasonably accurate, and no smaller than the actual size that will be needed.

    Discussion

    This message is sent outside of a burn cycle in response to a -estimateLength message sent to the track.

    Import Statement

    Objective-C

    @import DiscRecording;

    Swift

    import DiscRecording

    Availability

    Available in OS X v10.3 and later.

  • Prepares the track for burning. (required)

    Declaration

    Swift

    func prepareTrack(_ track: DRTrack!, forBurn burn: DRBurn!, toMedia mediaInfo: [NSObject : AnyObject]!) -> Bool

    Objective-C

    - (BOOL)prepareTrack:(DRTrack *)track forBurn:(DRBurn *)burn toMedia:(NSDictionary *)mediaInfo

    Parameters

    track

    The track object being burned

    burn

    The burn object controlling the burn

    mediaInfo

    The media being burned to. This is the same dictionary as returned by -[DRDevice status] .

    Return Value

    YES to indicate that the burn should proceed and NO to indicate a failure occurred.

    Discussion

    Called before any burning starts. Do any sort of setup that needs to be performed (such as opening files). This method can calculate and update the exact track length that will be burned.

    Since this method is called before the laser is turned on, this method can perform time consuming tasks.

    Import Statement

    Objective-C

    @import DiscRecording;

    Swift

    import DiscRecording

    Availability

    Available in OS X v10.2 and later.

  • Prepare the track to be verified. (required)

    Declaration

    Swift

    func prepareTrackForVerification(_ track: DRTrack!) -> Bool

    Objective-C

    - (BOOL)prepareTrackForVerification:(DRTrack *)track

    Parameters

    track

    The track object being burned

    Return Value

    YES to indicate that the verification should proceed and NO to indicate a failure occurred.

    Discussion

    This method is called after the burn complets writing data to disc and before verification phase starts. Now would be a good time to prepare to produce data again by rewinding to the start of files, etc.

    Import Statement

    Objective-C

    @import DiscRecording;

    Swift

    import DiscRecording

    Availability

    Available in OS X v10.2 and later.

  • Produces the track data. (required)

    Declaration

    Swift

    func produceDataForTrack(_ track: DRTrack!, intoBuffer buffer: UnsafeMutablePointer<Int8>, length bufferLength: UInt32, atAddress address: UInt64, blockSize blockSize: UInt32, ioFlags flags: UnsafeMutablePointer<UInt32>) -> UInt32

    Objective-C

    - (uint32_t)produceDataForTrack:(DRTrack *)track intoBuffer:(char *)buffer length:(uint32_t)bufferLength atAddress:(uint64_t)address blockSize:(uint32_t)blockSize ioFlags:(uint32_t *)flags

    Parameters

    track

    The track object being burned

    buffer

    The buffer to place data into

    bufferLength

    The length of buffer

    address

    The on-disc address of where data will be written

    blockSize

    the size of each block on the disc. It's best to return a multiple of this size.

    flags

    flags

    Return Value

    The number of bytes produced.

    Discussion

    This method is called many times over the course of a burn to obtain data for the track. The buffer passed in will be a multiple of blockSize (bufferLength == blockSize * N, where N > 1) and should be filled as full as possible with data. address is the sector address on the disc from the start of the track that is the buffer will be written to.

    Since while burning, keeping the drive's buffer full is of utmost importance, you should not perform lengthy operations or block for data in this method. This method should return the number of bytes actually in the buffer or 0 to indicate that there was an error producing the data..

    Import Statement

    Objective-C

    @import DiscRecording;

    Swift

    import DiscRecording

    Availability

    Available in OS X v10.2 and later.

  • Produces the pregap data. (required)

    Declaration

    Swift

    func producePreGapForTrack(_ track: DRTrack!, intoBuffer buffer: UnsafeMutablePointer<Int8>, length bufferLength: UInt32, atAddress address: UInt64, blockSize blockSize: UInt32, ioFlags flags: UnsafeMutablePointer<UInt32>) -> UInt32

    Objective-C

    - (uint32_t)producePreGapForTrack:(DRTrack *)track intoBuffer:(char *)buffer length:(uint32_t)bufferLength atAddress:(uint64_t)address blockSize:(uint32_t)blockSize ioFlags:(uint32_t *)flags

    Parameters

    track

    The track object being burned

    buffer

    The buffer to place data into

    bufferLength

    The length of buffer

    address

    The on-disc address of where data will be written

    blockSize

    the size of each block on the disc. It's best to return a multiple of this size.

    flags

    flags

    Return Value

    The number of bytes produced.

    Discussion

    This method is called to obtain data for the track's pregap. If the DRPreGapLengthKey key is present in the track properties, the track producer will be asked for the pregap data first. If the producer implements this selector, then it's the responsibility of the producer to provide data for the pregap, otherwise that length of silence will be produced by DiscRecording.

    The buffer passed in will be a multiple of blockSize (bufferLength == blockSize * N, where N > 1) and should be filled as full as possible with data. address is the sector address on the disc from the start of the track that is the buffer will be written to.

    Since while burning, keeping the drive's buffer full is of utmost importance, you should not perform lengthy operations or block for data in this method. This method should return the number of bytes actually in the buffer or 0 to indicate that there was an error producing the data..

    Import Statement

    Objective-C

    @import DiscRecording;

    Swift

    import DiscRecording

    Availability

    Available in OS X v10.3 and later.

  • Cleans up the track after the burn completes. (required)

    Declaration

    Swift

    func verifyDataForTrack(_ track: DRTrack!, inBuffer buffer: UnsafePointer<Int8>, length bufferLength: UInt32, atAddress address: UInt64, blockSize blockSize: UInt32, ioFlags flags: UnsafeMutablePointer<UInt32>) -> Bool

    Objective-C

    - (BOOL)verifyDataForTrack:(DRTrack *)track inBuffer:(const char *)buffer length:(uint32_t)bufferLength atAddress:(uint64_t)address blockSize:(uint32_t)blockSize ioFlags:(uint32_t *)flags

    Parameters

    track

    The track object being burned

    buffer

    The data read in from the track to compare with

    bufferLength

    The length of buffer

    address

    The on-disc address of where data will was read from.

    blockSize

    the size of each block on the disc. It's best to return a multiple of this size.

    flags

    flags

    Return Value

    YES to indicate that the data compared successfully and NO to indicate a failure occurred.

    Discussion

    If the class implementing this method asks for a verification type of DRVerificationTypeReceiveData , then a series of calls to this method will start. It's up to the class to reproduce the data again and compare it to the data passed in buffer. The buffer passed in will be a multiple of blockSize (bufferLength == blockSize * N, where N > 1). address is the sector address on the disc from the start of the track that is the buffer was written to.

    Import Statement

    Objective-C

    @import DiscRecording;

    Swift

    import DiscRecording

    Availability

    Available in OS X v10.2 and later.

  • Checks the integrity track pregap after a burn. (required)

    Declaration

    Swift

    func verifyPreGapForTrack(_ track: DRTrack!, inBuffer buffer: UnsafePointer<Int8>, length bufferLength: UInt32, atAddress address: UInt64, blockSize blockSize: UInt32, ioFlags flags: UnsafeMutablePointer<UInt32>) -> Bool

    Objective-C

    - (BOOL)verifyPreGapForTrack:(DRTrack *)track inBuffer:(const char *)buffer length:(uint32_t)bufferLength atAddress:(uint64_t)address blockSize:(uint32_t)blockSize ioFlags:(uint32_t *)flags

    Parameters

    track

    The track object being burned

    buffer

    The data read in from the track to compare with

    bufferLength

    The length of buffer

    address

    The on-disc address of where data will was read from.

    blockSize

    the size of each block on the disc. It's best to return a multiple of this size.

    flags

    flags

    Return Value

    YES to indicate that the data compared successfully and NO to indicate a failure occurred.

    Discussion

    If the class implementing this method asks for a verification type of DRVerificationTypeReceiveData , then a series of calls to this method will start. It's up to the class to reproduce the pregap again and compare it to the data passed in buffer. The buffer passed in will be a multiple of blockSize (bufferLength == blockSize * N, where N > 1). address is the sector address on the disc from the start of the track that is the buffer was written to.

    Import Statement

    Objective-C

    @import DiscRecording;

    Swift

    import DiscRecording

    Availability

    Available in OS X v10.4 and later.