ADC Home > Reference Library > Reference > Audio > Carbon > Disc Recording Framework Reference

 


DRFileDataProduction

Declared In:

Overview

Informal protocol describing methods implemented by the file data producer.

Discussion

This protocol defines those methods that a file data producer instance must implement. A file data producer is the object that resposible for providing the file data to the burn engine on request



Methods

-calculateSizeOfFile:fork:estimating:
Calculates the size of the specified fork of a file.
-cleanupFileAfterBurn:
Cleanup the file object once the burn is complete.
-prepareFileForBurn:
Prepare the file object for burning.
-prepareFileForVerification:
Prepare the file object for verification.
-produceFile:fork:intoBuffer:length:atAddress:blockSize:
Produces the specified fork contents for burning.

calculateSizeOfFile:fork:estimating:


Calculates the size of the specified fork of a file.

- (uint64_t) calculateSizeOfFile:(DRFile*)file fork:(DRFileFork)fork 
        estimating:(BOOL)estimate; 
Parameters
file
The file object.
fork
The fork of the file whose size is to be calculated.
estimate
If the file size should be estimated or exact.
Return Value

The length of the file's fork.

Discussion

This method may be sent at any time after the file object has been instantiated. Requests that the recevier calculate the byte size of a file's fork (for instance, data fork or resource fork).

If estimate is YES, you are being asked for an estimate of the final fork size, perhaps to provide an estimate of the track size, and do not have to be exact. Estimates should err on the high side; it's better to overestimate than underestimate. An estimate call may be made at any time.

If estimate is NO, you are being asked for the actual fork size, to be used in the burn. This call is only made in the burn phase.


cleanupFileAfterBurn:


Cleanup the file object once the burn is complete.

- (void) cleanupFileAfterBurn:(DRFile*)file; 
Parameters
file
The file object.
Discussion

Sent to the receiver after the burn completes. This would be an appropriate place to close files, or do any other teardown work needed. This message will always be sent regardless of whether the burn succeeded or failed


prepareFileForBurn:


Prepare the file object for burning.

- (BOOL) prepareFileForBurn:(DRFile*)file; 
Parameters
file
The file object.
Return Value

YES if the burn should proceed.

Discussion

Sent to the recevier before the burn begins. This would be an appropriate method to open files, or do any other prep work needed. The disc's entire hierarchy is completely in place and can be queried if needed.

After this call, the burn's content is locked down, and you should be able to respond to the calculateSizeOfFile:fork:estimating: messages with exact values.


prepareFileForVerification:


Prepare the file object for verification.

- (BOOL) prepareFileForVerification:(DRFile*)file; 
Parameters
file
The file object.
Return Value

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

Discussion

Sent during the burn (after production and before the cleanupFileAfterBurn: message) to indicate that verification is about to begin. Now would be a good time to rewind to the start of the file, reset state machines, or do whatever else is needed to prepare to produce again.


produceFile:fork:intoBuffer:length:atAddress:blockSize:


Produces the specified fork contents for burning.

- (uint32_t) produceFile:(DRFile*)file fork:(DRFileFork)fork 
        intoBuffer:(char*)buffer length:(uint32_t)bufferLength 
        atAddress:(uint64_t)address blockSize:(uint32_t)blockSize; 
Parameters
file
The file object.
fork
The fork of the file to produce.
buffer
The buffer to produce data into.
bufferLength
The length of the buffer to produce data into
address
The byte address in the file that the burn engine is requesting
blockSize
The size of the track blocks
Return Value

The number of bytes produced.

Discussion

Sent during the burn (after the prepareFileForBurn message) requesting that the receiver produce the specified fork contents.

The recevier should fill up the buffer passed in as full as possible and then return control to the caller. While burning keeping the drive's buffer full is of utmost importance, so 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.

You may be asked to produce twice, once during the actual burn and once during verification depending on the verification type of the track.


Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.
Last Updated: 2008-04-01