DRContentFile.h

Overview

File objects used in filesystem creation.

Functions

DRFileCreateReal

Creates a new real file object corresponding to a given FSRef.

DRFileCreateRealWithURL

Creates a new real file object corresponding to a given file URL.

DRFileCreateVirtualLink

Creates a virtual file or folder object in the form of a link to another file or folder in the hierarchy.

DRFileCreateVirtualWithCallback

Creates a virtual file object that will be filled in during data production by a callback function.

DRFileCreateVirtualWithData

Creates a virtual file object with the specified data.

DRFileGetTypeID

Returns the type identifier of all DRFile objects.

Creates a new real file object corresponding to a given FSRef.

extern DRFileRef DRFileCreateReal( 
    const FSRef *fsRef) ;  

Parameters

fsRef

An FSRef reference to a file on-disk.

Return Value

The newly-created file, or NULL.

Discussion

A real file object is a file object which corresponds to a real file on disk. The content of the file object corresponds to the actual on-disk content of the file.

Availability

Introduced in Mac OS X v10.2

Creates a new real file object corresponding to a given file URL.

extern DRFileRef DRFileCreateRealWithURL( 
    const CFURLRef urlRef) ;  

Parameters

urlRef

CFURLRef reference to a file on-disk.

Return Value

Returns a reference to the newly-created real file object, or NULL.

Discussion

A real file object is a file object which corresponds to a real file on disk. The content of the file object corresponds to the actual on-disk content of the file.

Availability

Introduced in Mac OS X v10.2

Creates a virtual file or folder object in the form of a link to another file or folder in the hierarchy.

extern DRFileRef DRFileCreateVirtualLink( 
    DRFSObjectRef original, 
    DRLinkType linkType, 
    CFStringRef fsKey) ;  

Parameters

original

The file or folder to link to.

linkType

The type of link to create. See the DRLinkType enumeration.

fsKey

The target file system for the link. The various keys are defined in DRContentProperties.h.

Return Value

A reference to the newly-created virtual file or folder object.

Discussion

Disc Recording currently supports four link types: symbolic links, hard links, Finder aliases, and combination symbolic link/Finder aliases.

Links often include relative path information. Since the relative path between two objects can be different depending on the target file system, you must specify a target file system when requesting a link. The file system mask on the newly-created link will automatically be set to ensure the file appears only in that file system.

Availability

Introduced in Mac OS X v10.2

Creates a virtual file object that will be filled in during data production by a callback function.

extern DRFileRef DRFileCreateVirtualWithCallback( 
    CFStringRef baseName, 
    DRFileProc fileProc, 
    void *fileProcRefCon) ;  

Parameters

baseName

The base name to assign to the new virtual file. For information on base names and how Disc Recording works with them, see DRFSObjectSetBaseName and DRFSObjectSetSpecificName .

fileProc

Your application-implemented callback function to generate file data.

fileProcRefCon

An optional reference context for the callback to use.

Return Value

Returns a reference to the newly-created virtual file object, or NULL.

Discussion

A virtual file is a file object which does not correspond to any real file on disk, but represents a file you want to appear in the file structure of the disc you are burning. It is created and modified using Disc Recording's 'content' functions -- see the documentation for DRContentObject.h.

The Disc Recording framework may invoke the callback at any time, and the calls may be made in any order, until the file object has been disposed.

Availability

Introduced in Mac OS X v10.2

Creates a virtual file object with the specified data.

extern DRFileRef DRFileCreateVirtualWithData( 
    CFStringRef baseName, 
    void *fileData, 
    UInt32 fileDataLength) ;  

Parameters

baseName

The base name to assign to the new virtual file.

fileData

A pointer to the data for the file. May be NULL if inFileLength is zero.

fileDataLength

The length of data in bytes.

Return Value

Returns a reference to the newly-created virtual file object, or NULL.

Discussion

A virtual file is a file object which does not correspond to any real file on disk, but represents a file you want to appear in the file structure of the disc you are burning. It is created and modified using Disc Recording's 'content' functions -- see the documentation for DRContentObject.h.

The file data passed in to this function is copied internally. Although it's possible to create files of arbitrary size with this function, you should limit files created in this way to a reasonable size, such as 100K or less, because each file consumes a corresponding amount of memory.

On multi-fork file systems the file data is used for the data fork.

Availability

Introduced in Mac OS X v10.2

Returns the type identifier of all DRFile objects.

extern CFTypeID DRFileGetTypeID(
    void) ;  

Availability

Introduced in Mac OS X v10.2

Typedefs

Index used for accessing the forks of a file.

typedef UInt32 DRFileForkIndex;  

Discussion

The data fork and resource fork always have fixed indices. Other forks may be allowed in the future.

Type used to define queries on the fork size.

typedef UInt32 DRFileForkSizeQuery;  

Messages sent to the DRFileProc callback during a burn.

typedef UInt32 DRFileMessage;  

Callback function to produce and manage a file for recording a track.

typedef OSStatus ( *DRFileProc)( 
    void *refCon, 
    DRFileRef file, 
    DRFileMessage message, 
    void *ioParam);  

Parameters

refCon

Reference context for your use, established when the callback is registered.

file

The file object being produced.

message

Sent by the Disc Recording engine to indicate the type of data it needs your application to supply. The various messages are defined in the DRFileMessage enumeration.

ioParam

Parameters are message-specific. See the DRFileMessage enumeration.

Return Value

Your application should return kDRFunctionNotSupportedErr when a message was passed that it doesn't respond to.

Discussion

Your application needs to implement a callback to create files representing tracks to burn, and to interact with those tracks by responding to the messages in the DRFileMessage enumeration.

If you name your function MyDRFileCallback, you would declare it like this:

					OSStatus MyDRFileCallback (
						void			*refCon,
						DRFileRef		file,
						DRFileMessage	message,
						void			*ioParam
					);

Link types available for the DRFileCreateVirtualLink function.

typedef UInt32 DRLinkType;  

Structs and Unions

Structure used when requesting fork sizes.

struct DRFileForkSizeInfo { 
    DRFileForkIndex fork; 
    DRFileForkSizeQuery query; 
    UInt64 size; 
};  

Fields

fork

(in) which fork is being requested

query

(in) type of query, estimate or actual

size

(out) returned size

Structure used by the DRFileProc callback during production of a track.

struct DRFileProductionInfo { 
    UInt64 requestedAddress; 
    void *buffer; 
    UInt32 reqCount; 
    UInt32 actCount; 
    UInt32 blockSize; 
    DRFileForkIndex fork; 
};  

Fields

requestedAddress

(out) byte address that the burn engine is requesting

buffer

(out) buffer to produce into

reqCount

(out) number of bytes requested

actCount

(in) number of bytes you actually produced

blockSize

(out) current block size, you must always return multiples of this

fork

(out) which fork is being requested

Enumerations

enum { 
    kDRFileForkData = 0, 
    kDRFileForkResource = 1 
};  

Constants

kDRFileForkData

Typically, the data fork contains the primary information for the file and is the fork used for files such as JPEGs, text files, etc.

kDRFileForkResource

Typically, the resource fork contains secondary meta-data, which is not important to the primary content of the file and may safely be ignored when the file is sent to a filesystem or OS which does not support multiple forks. See Inside Macintosh: Resources for more information on the format of a resource fork.

Discussion

Index used for accessing the forks of a file.

enum { 
    kDRFileForkSizeActual = 0, 
    kDRFileForkSizeEstimate = 1 
};  

Constants

kDRFileForkSizeActual

Indicates a request for actual size.

kDRFileForkSizeEstimate

Indicates a request for estimated size.

Discussion

Type used to define queries on the fork size.

enum { 
    kDRFileMessageForkSize = 'fsiz', 
    kDRFileMessagePreBurn = 'pre ', 
    kDRFileMessageProduceData = 'prod', 
    kDRFileMessageVerificationStarting = 'vrfy', 
    kDRFileMessagePostBurn = 'post', 
    kDRFileMessageRelease = 'bye ' 
};  

Constants

kDRFileMessageForkSize

Indicates a request for your DRFileProc callback to supply a file track size.

Your DRFileProc callback should respond to this message by placing the requested file fork size into the DRFileForkSizeInfo structure, which is pointed to by the callback's ioParam parameter. Your callback may receive this message at any time after the file object has been created.

On input, the structure's fork field indicates which fork you are being asked about, as defined in the DRFileForkIndex enumeration.

Also on input, the structure's query field indicates whether you are being asked for an estimated or actual fork size, as defined in the DRFileForkSizeQuery enumeration.

When the query field is DRFileForkSizeQuery , you are being asked for an estimate of the final fork size, perhaps for the burn engine to estimate the track size. You do not have to be exact, but your estimate should err on the high side. This call may be made at any time.

When the query field is kDRFileForkSizeActual , you are being asked for the actual fork size to be used in the burn. This call is made only in the burn phase.

kDRFileMessagePreBurn

Indicates that your application should perform all necessary preparation for the burn.

Your DRFileProc callback should respond to this message by telling your application to open files, or to do any other pre-burn preparation work needed. The burn engine sends this message before the burn but after the disc's entire hierarchy is completely in place. You can query the hierarchy

After this call, the burn's content is locked down, and you should be able to respond to the kDRFileMessageForkSize message with exact values.

Sent before the burn. The callback's ioParam parameter is ignored.

kDRFileMessageProduceData

Sent during the burn (after the pre-burn call). The callback's ioParam parameter points to a DRFileProductionInfo structure. Speed is critical during this call. You should produce the data as fast as possible, and try not to perform any time-consuming tasks.

You may be asked to produce twice, once during the actual burn and once during verification.

kDRFileMessageVerificationStarting

Sent during the burn (after the pre-burn call, after production, before the post-burn call) to indicate that verification is about to begin. The callback's ioParam parameter is ignored.

This would be an appropriate place to seek back to the beginning of files, reset state machines, or do whatever else is needed to prepare to produce again.

kDRFileMessagePostBurn

Sent at the end of the burn. The callback's ioParam parameter is ignored.

This would be an appropriate place to close files, or do any other teardown work needed. This call will always be made regardless of whether the burn succeeded or failed.

kDRFileMessageRelease

Sent when the DRFileRef is released. The callback's ioParam parameter is ignored.

No further messages will be sent for this object. This would be an appropriate time to release any memory allocated by the object (whether in the refCon or anywhere else).

Discussion

Messages sent to the DRFileProc callback during a burn.

enum { 
    kDRLinkTypeHardLink = 1, 
    kDRLinkTypeSymbolicLink = 2, 
    kDRLinkTypeFinderAlias = 3 
};  

Constants

kDRLinkTypeHardLink

Link type for hard links.

kDRLinkTypeSymbolicLink

Link type for symbolic links.

kDRLinkTypeFinderAlias

Link type for Finder aliases.

Discussion

Link type constants used by the DRFileCreateVirtualLink function.

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