Mac Developer Library

Developer

DRContentFile.h Reference

Options
Deployment Target:

On This Page
Language:

DRContentFile.h Reference

File objects used in filesystem creation.

Included Headers

  • <DiscRecording/DRContentObject.h>

  • <CoreFoundation/CFURL.h>

  • <AvailabilityMacros.h>

Functions

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

    Declaration

    Swift

    func DRFileCreateReal(_ fsRef: UnsafePointer<FSRef>) -> Unmanaged<DRFile>!

    Objective-C

    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.

    Import Statement

    import DiscRecording

    Availability

    Available in OS X v10.2 and later.

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

    Declaration

    Swift

    func DRFileCreateRealWithURL(_ urlRef: CFURL!) -> Unmanaged<DRFile>!

    Objective-C

    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.

    Import Statement

    import DiscRecording

    Availability

    Available in OS X v10.2 and later.

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

    Declaration

    Swift

    func DRFileCreateVirtualLink(_ original: DRFSObject!, _ linkType: DRLinkType, _ fsKey: CFString!) -> Unmanaged<DRFile>!

    Objective-C

    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.

    Import Statement

    import DiscRecording

    Availability

    Available in OS X v10.2 and later.

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

    Declaration

    Swift

    func DRFileCreateVirtualWithCallback(_ baseName: CFString!, _ fileProc: DRFileProc, _ fileProcRefCon: UnsafeMutablePointer<Void>) -> Unmanaged<DRFile>!

    Objective-C

    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 in DRContentObject.h Reference and DRFSObjectSetSpecificName in DRContentObject.h Reference .

    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.

    Import Statement

    import DiscRecording

    Availability

    Available in OS X v10.2 and later.

  • Creates a virtual file object with the specified data.

    Declaration

    Swift

    func DRFileCreateVirtualWithData(_ baseName: CFString!, _ fileData: UnsafeMutablePointer<Void>, _ fileDataLength: UInt32) -> Unmanaged<DRFile>!

    Objective-C

    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.

    Import Statement

    import DiscRecording

    Availability

    Available in OS X v10.2 and later.

  • Returns the type identifier of all DRFile objects.

    Declaration

    Swift

    func DRFileGetTypeID() -> CFTypeID

    Objective-C

    CFTypeID DRFileGetTypeID ( void );

    Import Statement

    import DiscRecording

    Availability

    Available in OS X v10.2 and later.

Callbacks

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

    Declaration

    Objective-C

    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 in DRCoreErrors.h Reference 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 in DRCoreErrors.h Reference .

    Import Statement

    import DiscRecording

    Availability

    Available in OS X v10.2 and later.

Data Types

See the Overview section above for header-level documentation.

  • Index used for accessing the forks of a file.

    Declaration

    Swift

    typealias DRFileForkIndex = UInt32

    Objective-C

    typedef UInt32 DRFileForkIndex;

    Discussion

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

    Import Statement

    import DiscRecording

    Availability

    Available in OS X v10.2 and later.

  • Type used to define queries on the fork size.

    Declaration

    Swift

    typealias DRFileForkSizeQuery = UInt32

    Objective-C

    typedef UInt32 DRFileForkSizeQuery;

    Import Statement

    import DiscRecording

    Availability

    Available in OS X v10.2 and later.

  • Messages sent to the DRFileProc callback during a burn.

    Declaration

    Swift

    typealias DRFileMessage = UInt32

    Objective-C

    typedef UInt32 DRFileMessage;

    Import Statement

    import DiscRecording

    Availability

    Available in OS X v10.2 and later.

  • Link types available for the DRFileCreateVirtualLink function.

    Declaration

    Swift

    typealias DRLinkType = UInt32

    Objective-C

    typedef UInt32 DRLinkType;

    Import Statement

    import DiscRecording

    Availability

    Available in OS X v10.2 and later.

  • Structure used when requesting fork sizes.

    Declaration

    Objective-C

    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.

    Declaration

    Objective-C

    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.

  • Declaration

    Swift

    var kDRFileForkData: Int { get } var kDRFileForkResource: Int { get }

    Objective-C

    enum { kDRFileForkData = 0, kDRFileForkResource = 1 };

    Constants

    • kDRFileForkData

      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.

    • kDRFileForkResource

      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.

    Discussion

    Index used for accessing the forks of a file.

    Import Statement

  • Declaration

    Swift

    var kDRFileForkSizeActual: Int { get } var kDRFileForkSizeEstimate: Int { get }

    Objective-C

    enum { kDRFileForkSizeActual = 0, kDRFileForkSizeEstimate = 1 };

    Constants

    • kDRFileForkSizeActual

      kDRFileForkSizeActual

      Indicates a request for actual size.

      Available in OS X v10.2 and later.

    • kDRFileForkSizeEstimate

      kDRFileForkSizeEstimate

      Indicates a request for estimated size.

      Available in OS X v10.2 and later.

    Discussion

    Type used to define queries on the fork size.

    Import Statement

  • Declaration

    Swift

    var kDRFileMessageForkSize: Int { get } var kDRFileMessagePreBurn: Int { get } var kDRFileMessageProduceData: Int { get } var kDRFileMessageVerificationStarting: Int { get } var kDRFileMessagePostBurn: Int { get } var kDRFileMessageRelease: Int { get }

    Objective-C

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

    Constants

    • kDRFileMessageForkSize

      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.

    • kDRFileMessagePreBurn

      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.

    • kDRFileMessageProduceData

      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.

    • kDRFileMessageVerificationStarting

      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.

    • kDRFileMessagePostBurn

      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.

    • kDRFileMessageRelease

      kDRFileMessageRelease

      Sent when the DRFileRef in DRContentObject.h Reference 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.

    Discussion

    Messages sent to the DRFileProc callback during a burn.

    Import Statement

  • Declaration

    Swift

    var kDRLinkTypeHardLink: Int { get } var kDRLinkTypeSymbolicLink: Int { get } var kDRLinkTypeFinderAlias: Int { get }

    Objective-C

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

    Constants

    • kDRLinkTypeHardLink

      kDRLinkTypeHardLink

      Link type for hard links.

      Available in OS X v10.2 and later.

    • kDRLinkTypeSymbolicLink

      kDRLinkTypeSymbolicLink

      Link type for symbolic links.

      Available in OS X v10.2 and later.

    • kDRLinkTypeFinderAlias

      kDRLinkTypeFinderAlias

      Link type for Finder aliases.

      Available in OS X v10.2 and later.

    Discussion

    Link type constants used by the DRFileCreateVirtualLink function.

    Import Statement