DRCoreBurn.h Reference

Declared in
DRBurn.h
DRCoreBurn.h

Overview

Burn object interfaces for Disc Recording.

Included Headers

  • <CoreServices/CoreServices.h>

  • <DiscRecording/DRCoreObject.h>

  • <DiscRecording/DRCoreTrack.h>

  • <DiscRecording/DRCoreDevice.h>

  • <AvailabilityMacros.h>

Functions

See the Overview section above for header-level documentation.

DRBurnAbort

Stops the burn.

extern void DRBurnAbort(
   DRBurnRef burn) ;
Parameters
burn

The burn that should be stopped. If this parameter does not contain a valid DRBurn object, the behavior is undefined.

Discussion

Aborting a burn may make CD unusable depending on the amount of data written. If nothing has been written then the disc can be reused as a blank. If all the data has been written (and a verification is in progress, for example) then the disc will be usable and the data will be intact, unless the verification would have failed. Otherwise, the disc will be unusable.

If the burn has not started or has already completed, this function does nothing.

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

DRBurnCopyStatus

Obtains the progress and status of the burn.

extern CFDictionaryRef DRBurnCopyStatus(
   DRBurnRef burn) ;
Parameters
burn

The burn for which status is wanted. If this parameter is not a valid DRBurn object, the behavior is undefined.

Return Value

Returns a reference to a CFDictionary object. The reference is implicitly retained by the caller. This is the same dictionary sent to observers of the kDRBurnStatusChangedNotification notification.

Discussion

Returns a CFDictionary object containing the progress and status of the burn. This dictionary will contain the state, percentage complete, and any errors reported.

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

DRBurnCreate

Creates a new burn.

extern DRBurnRef DRBurnCreate(
   DRDeviceRef device) ;
Parameters
device

A reference to the device to burn to. If this parameter is not a valid DRDevice, the behavior is undefined.

Return Value

Returns reference to a new DRBurn instance.

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

DRBurnGetDevice

Obtains a reference to the device associated with a burn.

extern DRDeviceRef DRBurnGetDevice(
   DRBurnRef burn) ;
Parameters
burn

The burn for which to get the device reference. If this parameter is not a valid DRBurn object, the behavior is undefined.

Return Value

Returns a reference of type DRDeviceRef . The caller does not implicitly retain the reference and is not responsible for releasing it.

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

DRBurnGetProperties

Obtains properties of the burn.

extern CFDictionaryRef DRBurnGetProperties(
   DRBurnRef burn) ;
Parameters
burn

The burn for which to get properties. If this parameter is NULL the behavior is undefined.

Return Value

Returns a reference to a CFDictionary object. The caller does not implicitly retain the reference and is not responsible for releasing it.

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

DRBurnGetTypeID

Obtains the type identifier of all DRBurn objects.

extern CFTypeID DRBurnGetTypeID(
   void) ;
Return Value

A Core Foundation type identifier.

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

DRBurnSetProperties

Sets the properties of the burn.

extern void DRBurnSetProperties(
   DRBurnRef burn,
   CFDictionaryRef properties) ;
Parameters
burn

The burn for which to set the properties. If this parameter is not a valid DRBurn object, the behavior is undefined.

properties

A reference to a CFDictionary object. If this parameter does not reference a valid CFDictionary object the behavior is undefined.

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

DRBurnWriteLayout

Writes the specified track layout to disc.

extern OSStatus DRBurnWriteLayout(
   DRBurnRef burn,
   CFTypeRef layout) ;
Parameters
burn

The burn that should be started. If this parameter is not a valid DRBurn object, the behavior is undefined.

layout

An object describing the layout of the data on disc. The most common layout consists of a CFArray object whose elements are DRTrack objects. The other layout options are a lone DRTrack object, and a CFArray of homogeneous CFArrays of DRTracks. If the layout is not one of these kinds, or if any of the objects is not valid, this function's behavior is undefined.

Return Value

An error code indicating if the burn could begin.

Discussion

The object passed into this function describes the layout of the disc. There are three possible layout configurations:

  • For a multisession burn, the layout must be a valid CFArray object containing multiple CFArrays, each of which contains one or more valid DRTrack objects.

  • For a single-session, multitrack burn, the layout must be a valid CFArray object containing one or more valid DRTrack objects.

  • For a single-session, single-track burn, the layout must be a valid DRTrack object.

If either of these configurations are not met or the values contained in the array(s) are not valid DRTrack objects, the behavior is undefined.

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

Data Types

See the Overview section above for header-level documentation.

DRBurnRef

typedef struct __DRBurn* DRBurnRef;
Discussion

A reference to DRBurn instances.

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

Constants

See the Overview section above for header-level documentation.

Global Constants

extern const CFStringRef kDRBurnDoubleLayerL0DataZoneBlocksKey ;
extern const CFStringRef kDRBurnAppendableKey ;
extern const CFStringRef kDRBurnCompletionActionEject ;
extern const CFStringRef kDRBurnCompletionActionKey ;
extern const CFStringRef kDRBurnCompletionActionMount ;
extern const CFStringRef kDRBurnDoubleLayerL0DataZoneBlocksKey ;
extern const CFStringRef kDRBurnFailureActionEject ;
extern const CFStringRef kDRBurnFailureActionKey ;
extern const CFStringRef kDRBurnFailureActionNone ;
extern const CFStringRef kDRBurnOverwriteDiscKey ;
extern const CFStringRef kDRBurnRequestedSpeedKey ;
extern const CFStringRef kDRBurnStatusChangedNotification ;
extern const CFStringRef kDRBurnStrategyBDDAO ;
extern const CFStringRef kDRBurnStrategyCDSAO ;
extern const CFStringRef kDRBurnStrategyCDTAO ;
extern const CFStringRef kDRBurnStrategyDVDDAO ;
extern const CFStringRef kDRBurnStrategyIsRequiredKey ;
extern const CFStringRef kDRBurnStrategyKey ;
extern const CFStringRef kDRBurnTestingKey ;
extern const CFStringRef kDRBurnUnderrunProtectionKey ;
extern const CFStringRef kDRBurnVerifyDiscKey ;
extern const CFStringRef kDRCDTextKey ;
extern const CFStringRef kDRMediaCatalogNumberKey ;
extern const CFStringRef kDRSynchronousBehaviorKey ;
Constants
DRBurnDoubleLayerL0DataZoneBlocksKey

This burn property key corresponds to a CFNumber containing the number of blocks desired for the layer 0 data zone on a double layer writable disc.

The size of the layer 0 data zone dictates where the transition point is from layer 0 to layer 1. If this key is present, the data zone size will be set prior to the start of the burn using the value for this key. If it is not present, the default layer 0 data zone will be used (half the available blocks on an empty disc).

The transition point can be specified two ways. If the value specified in this key is greater than 1.0, then it will designate an absolute block number for the transition point. In this case, the block number should be a multiple of 16 and at least 40000h per specification. If the value is less than 1.0, it will specify the percentage of the burn that should reside on layer 0. A typical value is 0.5, designating half the burn for each layer. A value of 0.0 or 1.0 will not change the layer 0 transition point.

Available in OS X v10.4 and later.

Declared in DRBurn.h.

kDRBurnAppendableKey

Flag indicating whether or not the disc should remain appendable after the burn.

This burn property key corresponds to a CFBoolean object containing a flag indicating if the disc should still be appendable after the burn. If this key is not present, the burn will default to a value of false and the disc will be closed.

Most CD formats do not allow unclosed discs, and many types of CD readers will not work with discs that are left appendable. Don't change the value of this key unless you understand the consequences.

Available in OS X v10.2 and later.

Declared in DRCoreBurn.h.

kDRBurnCompletionActionEject

A CFString object indicating that the drive should eject the disc when the burn completes.

Available in OS X v10.2 and later.

Declared in DRCoreBurn.h.

kDRBurnCompletionActionKey

The action to take upon burn completion, with a default of eject.

This burn property key corresponds to a CFString object containing one of the available completion actions for disc handling.

If this key is not present, the burn will default to a value of kDRBurnCompletionActionEject and the disc will be ejected.

Available in OS X v10.2 and later.

Declared in DRCoreBurn.h.

kDRBurnCompletionActionMount

A CFString object indicating that the Disc Recording engine should mount the disc on the desktop when the burn completes.

Available in OS X v10.2 and later.

Declared in DRCoreBurn.h.

kDRBurnDoubleLayerL0DataZoneBlocksKey

This burn property key corresponds to a CFNumber containing the number of blocks desired for the layer 0 data zone on a double layer writable disc.

The size of the layer 0 data zone dictates where the transition point is from layer 0 to layer 1. If this key is present, the data zone size will be set prior to the start of the burn using the value for this key. If it is not present, the default layer 0 data zone will be used (half the available blocks on an empty disc).

The transition point can be specified two ways. If the value specified in this key is greater than 1.0, then it will designate an absolute block number for the transition point. In this case, the block number should be a multiple of 16 and at least 40000h per specification. If the value is less than 1.0, it will specify the percentage of the burn that should reside on layer 0. A typical value is 0.5, designating half the burn for each layer. A value of 0.0 or 1.0 will not change the layer 0 transition point.

Available in OS X v10.4 and later.

Declared in DRCoreBurn.h.

kDRBurnFailureActionEject

A CFString object indicating that the drive should eject the disc if the burn fails.

Available in OS X v10.3 and later.

Declared in DRCoreBurn.h.

kDRBurnFailureActionKey

The action to take upon burn failure, with a default of eject.

This burn property key corresponds to a CFString object containing one of the available failure actions for disc handling.

If this key is not present, the burn will default to a value of kDRBurnFailureActionEject and the disc will be ejected.

Available in OS X v10.3 and later.

Declared in DRCoreBurn.h.

kDRBurnFailureActionNone

A CFString object indicating that the drive should do nothing with the disc if the burn fails.

Available in OS X v10.3 and later.

Declared in DRCoreBurn.h.

kDRBurnOverwriteDiscKey

Flag indicating whether the disc should be appended to or overwritten.

This burn property key corresponds to a CFBoolean object containing a flag indicating if the disc will be overwritten from block zero for the burn. If this key is not present, the burn will default to a value of false and the disc will be appended.

Overwriting requires the media either be blank or erasable, and is functionally equivalent to an erase followed by a burn.

Available in OS X v10.3 and later.

Declared in DRCoreBurn.h.

kDRBurnRequestedSpeedKey

The requested speed of the burn.

This burn property key corresponds to a CFNumber object containing the speed at which the burn should run, expressed as a floating point value in kilobytes per second where 1 kilobyte = 1,000 bytes. If this key is not present, the requested maximum burn speed defaults to kDRDeviceBurnSpeedMax .

The speed at which the burn will run depends on several factors including the speed of the bus to which the drive is connected, the data rate capacity of the, disc, the sustained rate at which data can be produced, and the limit your application sets in the kDRMaxBurnSpeedKey track property keys. For example, a 16x drive connected over USB 1.0 results in a maximum sustainable throughput to the drive of just 2x due to the bandwidth limitation of the bus.

Some faster drives have a minimum burn speed. In the case of a drive whose minimum speed is 4x, for example, requesting a 1x burn will result in an actual burn speed of 4x.

Available in OS X v10.2 and later.

Declared in DRCoreBurn.h.

kDRBurnStatusChangedNotification

The notification sent when a DRBurn object has updated status.

Available in OS X v10.2 and later.

Declared in DRCoreBurn.h.

kDRBurnStrategyBDDAO

A CFString object representing the disc-at-once (DAO) burn strategy for BD.

This strategy applies only to BDs (Blu-ray).

Available in OS X v10.5 and later.

Declared in DRCoreBurn.h.

kDRBurnStrategyCDSAO

A CFString object representing the session-at-once (SAO) burn strategy for CD.

Available in OS X v10.3 and later.

Declared in DRCoreBurn.h.

kDRBurnStrategyCDTAO

A CFString object representing the track-at-once (TAO) burn strategy for CD.

Available in OS X v10.3 and later.

Declared in DRCoreBurn.h.

kDRBurnStrategyDVDDAO

A CFString object representing the disc-at-once (DAO) burn strategy for DVD.

This strategy applies only to DVDs. It is not valid when burning to CD media.

Available in OS X v10.3 and later.

Declared in DRCoreBurn.h.

kDRBurnStrategyIsRequiredKey

Flag indicating whether to attempt to enforce the specified burn strategies.

This burn property key corresponds to a CFBoolean object indicating whether the burn strategy or strategies listed for the kDRBurnStrategyKey key are the only ones allowed. If this key is not present, the burn will behave as though the key were false.

If this key's value is set to true and the device does not support any of the suggested burn strategies, the burn will fail with a return value of kDRDeviceBurnStrategyNotAvailableErr .

If this key's value is set to false and the device does not support any of the suggested burn strategies, the engine will choose an alternate burn strategy. The burn strategy used will provide an equivalent disc.

Available in OS X v10.3 and later.

Declared in DRCoreBurn.h.

kDRBurnStrategyKey

One or more suggested burn strategies.

This burn property key corresponds to a CFString object, or to a CFArray object containing CFString objects, indicating the suggested burn strategy or strategies. If this key is not present, the burn engine picks an appropriate burn strategy automatically--so most clients do not need to specify a burn strategy.

When more than one strategy is suggested, the burn engine attempts to use the first strategy in the list which is available. A burn strategy will never be used if it cannot write the required data. For example, the track-at-once (TAO) strategy cannot write CD-Text.

This presence of this key alone is just a suggestion--if the burn engine cannot fulfill the request it will burn using whatever strategy is available. To convert the suggestion into a requirement, add the kDRBurnStrategyIsRequiredKey key with a value of true.

Before using this key you should ensure that the device supports the strategy or strategies requested. Do this by checking the burn strategy keys in the device's write capabilities dictionary.

Available in OS X v10.3 and later.

Declared in DRCoreBurn.h.

kDRBurnTestingKey

Flag indicating whether to perform a test or normal burn.

This burn property key corresponds to a CFBoolean object containing a flag indicating whether the burn will be a test or not.

If testing is set and your application calls the DRBurnWriteLayout function, the burn process proceeds as if data would be written to the disc--but the laser is not turned on to full power so the disc is not modified.

If this key is not present or the selected burning device does not support test burning, the burn will default to a value of false and a normal burn will occur.

Available in OS X v10.2 and later.

Declared in DRCoreBurn.h.

kDRBurnUnderrunProtectionKey

Flag indicating whether burn underrun protection will be on or off.

This burn property key corresponds to a CFBoolean object containing a flag indicating whether burn underrun protection will be on or off, for devices which support it.

Burn underrun protection is on by default for drives which support it. Clients do need to set this value except to explicitly disable underrun protection.

If this key is not present, the burn will default to a value of true and burn underrun protection will enabled, if the drive supports it.

Available in OS X v10.2 and later.

Declared in DRCoreBurn.h.

kDRBurnVerifyDiscKey

Flag indicating whether the disc will be verified after the burn.

This burn property key corresponds to a CFBoolean object containing a flag indicating if the disc will be verified after being burned. If this key is not present, the burn will default to a value of true and the disc will be verified.

Verification requires each DRTrack object to specify its verification method by way of the kDRVerificationTypeKey key in the track properties dictionary. If none of the DRTrack objects in the burn have specified a verification method, verification will not occur.

Available in OS X v10.2 and later.

Declared in DRCoreBurn.h.

kDRCDTextKey

This burn property key corresponds to a DRCDTextBlockRef object, or to an array of DRCDTextBlockRef objects, containing the CD-Text information for the disc. If this key is not present, the burn will not write CD-Text.

Before using this key you should ensure that the device supports CD-Text by checking the value of the kDRDeviceCanWriteCDTextKey key in the device's write capabilities dictionary.

If this value is set to true and the device does not support writing CD-Text, the burn will fail with a value of kDRDeviceCantWriteCDTextErr .

Available in OS X v10.4 and later.

Declared in DRCoreBurn.h.

kDRMediaCatalogNumberKey

The Media Catalog Number (MCN) to write to disc.

This burn property key corresponds to a CFData object containing exactly 13 bytes of data to be written to the disc as the Media Catalog Number (MCN). If this key is not present it will default to all zeroes, indicating that an MCN is not supplied.

This value is the standard UPC/EAN product number, and should conform to the specifications of the UCC and EAN. See http://www.ean-int.org and http://www.uc-council.org for more information.

Available in OS X v10.3 and later.

Declared in DRCoreBurn.h.

kDRSynchronousBehaviorKey

Flag indicating whether to burn synchronously or asynchronously.

This burn property key corresponds to a CFBoolean object containing a flag indicating if burn operations will behave synchronously. If this key is not present, it will default to a value of false and burn operations will behave asynchronously.

Synchronous operations do not post status notifications and do not return until they are completed. Status can be queried at any time using the DRBurnCopyStatus function, and will remain valid even after the burn operation has finished.

Available in OS X v10.2 and later.

Declared in DRCoreBurn.h.