DRContentFile.h Reference

Declared in
DRContentFile.h

Overview

File objects used in filesystem creation.

Included Headers

  • <DiscRecording/DRContentObject.h>

  • <CoreFoundation/CFURL.h>

  • <AvailabilityMacros.h>

Functions

See the Overview section above for header-level documentation.

DRFileCreateReal

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
  • Available in OS X v10.2 and later.
Declared In
DRContentFile.h

DRFileCreateRealWithURL

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
  • Available in OS X v10.2 and later.
Declared In
DRContentFile.h

DRFileCreateVirtualLink

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
  • Available in OS X v10.2 and later.
Declared In
DRContentFile.h

DRFileCreateVirtualWithCallback

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
  • Available in OS X v10.2 and later.
Declared In
DRContentFile.h

DRFileCreateVirtualWithData

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
  • Available in OS X v10.2 and later.
Declared In
DRContentFile.h

DRFileGetTypeID

Returns the type identifier of all DRFile objects.

extern CFTypeID DRFileGetTypeID(
   void) ;
Availability
  • Available in OS X v10.2 and later.
Declared In
DRContentFile.h

Callbacks

See the Overview section above for header-level documentation.

DRFileProc

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
   				);
 

Your callback places the requested data

If your callback does not support a given function, it should return kDRFunctionNotSupportedErr .

Availability
  • Available in OS X v10.2 and later.
Declared In
DRContentFile.h

Data Types

See the Overview section above for header-level documentation.

DRFileForkIndex

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
DRContentFile.h

DRFileForkSizeQuery

Type used to define queries on the fork size.

typedef UInt32 DRFileForkSizeQuery;
Availability
  • Available in OS X v10.2 and later.
Declared In
DRContentFile.h

DRFileMessage

Messages sent to the DRFileProc callback during a burn.

typedef UInt32 DRFileMessage;
Availability
  • Available in OS X v10.2 and later.
Declared In
DRContentFile.h

DRLinkType

Link types available for the DRFileCreateVirtualLink function.

typedef UInt32 DRLinkType;
Availability
  • Available in OS X v10.2 and later.
Declared In
DRContentFile.h

DRFileForkSizeInfo

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

DRFileProductionInfo

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

Constants

See the Overview section above for header-level documentation.

DRFileFork indicies

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.

Available in OS X v10.2 and later.

Declared in DRContentFile.h.

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.

Available in OS X v10.2 and later.

Declared in DRContentFile.h.

Discussion

Index used for accessing the forks of a file.

DRFileForkSizeQuery contants

enum {
   kDRFileForkSizeActual = 0,
   kDRFileForkSizeEstimate = 1
};
Constants
kDRFileForkSizeActual

Indicates a request for actual size.

Available in OS X v10.2 and later.

Declared in DRContentFile.h.

kDRFileForkSizeEstimate

Indicates a request for estimated size.

Available in OS X v10.2 and later.

Declared in DRContentFile.h.

Discussion

Type used to define queries on the fork size.

DRFileMessage constants

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.

Available in OS X v10.2 and later.

Declared in DRContentFile.h.

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.

Available in OS X v10.2 and later.

Declared in DRContentFile.h.

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.

Available in OS X v10.2 and later.

Declared in DRContentFile.h.

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.

Available in OS X v10.2 and later.

Declared in DRContentFile.h.

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.

Available in OS X v10.2 and later.

Declared in DRContentFile.h.

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

Available in OS X v10.2 and later.

Declared in DRContentFile.h.

Discussion

Messages sent to the DRFileProc callback during a burn.

DRLinkType contants

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

Link type for hard links.

Available in OS X v10.2 and later.

Declared in DRContentFile.h.

kDRLinkTypeSymbolicLink

Link type for symbolic links.

Available in OS X v10.2 and later.

Declared in DRContentFile.h.

kDRLinkTypeFinderAlias

Link type for Finder aliases.

Available in OS X v10.2 and later.

Declared in DRContentFile.h.

Discussion

Link type constants used by the DRFileCreateVirtualLink function.