ADC Home > Reference Library > Reference > Audio > Carbon > Disc Recording Framework Reference
|
DRCoreBurn.h |
Includes: | <CoreServices/CoreServices.h> <DiscRecording/DRCoreObject.h> <DiscRecording/DRCoreTrack.h> <DiscRecording/DRCoreDevice.h> <AvailabilityMacros.h> |
Burn object interfaces for Disc Recording.
DRBurnAbort |
Stops the burn.
extern void DRBurnAbort( DRBurnRef burn) ;
burn
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.
DRBurnCopyStatus |
Obtains the progress and status of the burn.
extern CFDictionaryRef DRBurnCopyStatus( DRBurnRef burn) ;
burn
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.
Returns a CFDictionary object containing the progress and status of the burn. This dictionary will contain the state, percentage complete, and any errors reported.
DRBurnCreate |
Creates a new burn.
extern DRBurnRef DRBurnCreate( DRDeviceRef device) ;
device
Returns reference to a new DRBurn instance.
DRBurnGetDevice |
Obtains a reference to the device associated with a burn.
extern DRDeviceRef DRBurnGetDevice( DRBurnRef burn) ;
burn
Returns a reference of type DRDeviceRef . The caller does not implicitly retain the reference and is not responsible for releasing it.
DRBurnGetProperties |
Obtains properties of the burn.
extern CFDictionaryRef DRBurnGetProperties( DRBurnRef burn) ;
burn
Returns a reference to a CFDictionary object. The caller does not implicitly retain the reference and is not responsible for releasing it.
DRBurnGetTypeID |
Obtains the type identifier of all DRBurn objects.
extern CFTypeID DRBurnGetTypeID( void) ;
A Core Foundation type identifier.
DRBurnSetProperties |
Sets the properties of the burn.
extern void DRBurnSetProperties( DRBurnRef burn, CFDictionaryRef properties) ;
burn
properties
DRBurnWriteLayout |
Writes the specified track layout to disc.
extern OSStatus DRBurnWriteLayout( DRBurnRef burn, CFTypeRef layout) ;
burn
layout
An error code indicating if the burn could begin.
The object passed into this function describes the layout of the disc. There are three possible layout configurations:
DRBurnDoubleLayerL0DataZoneBlocksKey |
- kDRBurnDoubleLayerL0DataZoneBlocksKey
extern const CFStringRef 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.
kDRBurnAppendableKey |
Flag indicating whether or not the disc should remain appendable after the burn.
extern const CFStringRef kDRBurnAppendableKey ;
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.
kDRBurnCompletionActionEject |
A CFString object indicating that the drive should eject the disc when the burn completes.
extern const CFStringRef kDRBurnCompletionActionEject ;
kDRBurnCompletionActionKey |
The action to take upon burn completion, with a default of eject.
extern const CFStringRef kDRBurnCompletionActionKey ;
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.
kDRBurnCompletionActionMount |
A CFString object indicating that the Disc Recording engine should mount the disc on the desktop when the burn completes.
extern const CFStringRef kDRBurnCompletionActionMount ;
kDRBurnDoubleLayerL0DataZoneBlocksKey |
- DRBurnDoubleLayerL0DataZoneBlocksKey
extern const CFStringRef 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.
kDRBurnFailureActionEject |
A CFString object indicating that the drive should eject the disc if the burn fails.
extern const CFStringRef kDRBurnFailureActionEject ;
kDRBurnFailureActionKey |
The action to take upon burn failure, with a default of eject.
extern const CFStringRef kDRBurnFailureActionKey ;
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.
kDRBurnFailureActionNone |
A CFString object indicating that the drive should do nothing with the disc if the burn fails.
extern const CFStringRef kDRBurnFailureActionNone ;
kDRBurnOverwriteDiscKey |
Flag indicating whether the disc should be appended to or overwritten.
extern const CFStringRef kDRBurnOverwriteDiscKey ;
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.
kDRBurnRequestedSpeedKey |
The requested speed of the burn.
extern const CFStringRef kDRBurnRequestedSpeedKey ;
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.
kDRBurnStatusChangedNotification |
extern const CFStringRef kDRBurnStatusChangedNotification ;
The notification sent when a DRBurn object has updated status.
kDRBurnStrategyBDDAO |
A CFString object representing the disc-at-once (DAO) burn strategy for BD.
extern const CFStringRef kDRBurnStrategyBDDAO ;
This strategy applies only to BDs (Blu-ray).
kDRBurnStrategyCDRaw |
A CFString object representing the CD raw mode burn strategy used for CD.
extern const CFStringRef kDRBurnStrategyCDRaw ;
A raw mode burn writes client-defined lead-in, program area, and lead-out data to CD media in a single pass. It supports options such as single-pass writing of a multisession disc. The Multi-Media Command Set (MMC) standard name for this strategy is "raw" but it is often called disc-at-once (DAO).
kDRBurnStrategyCDSAO |
A CFString object representing the session-at-once (SAO) burn strategy for CD.
extern const CFStringRef kDRBurnStrategyCDSAO ;
kDRBurnStrategyCDTAO |
A CFString object representing the track-at-once (TAO) burn strategy for CD.
extern const CFStringRef kDRBurnStrategyCDTAO ;
kDRBurnStrategyDVDDAO |
A CFString object representing the disc-at-once (DAO) burn strategy for DVD.
extern const CFStringRef kDRBurnStrategyDVDDAO ;
This strategy applies only to DVDs. It is not valid when burning to CD media.
kDRBurnStrategyIsRequiredKey |
Flag indicating whether to attempt to enforce the specified burn strategies.
extern const CFStringRef kDRBurnStrategyIsRequiredKey ;
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.
kDRBurnStrategyKey |
One or more suggested burn strategies.
extern const CFStringRef kDRBurnStrategyKey ;
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.
kDRBurnTestingKey |
Flag indicating whether to perform a test or normal burn.
extern const CFStringRef kDRBurnTestingKey ;
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.
kDRBurnUnderrunProtectionKey |
Flag indicating whether burn underrun protection will be on or off.
extern const CFStringRef kDRBurnUnderrunProtectionKey ;
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.
kDRBurnVerifyDiscKey |
Flag indicating whether the disc will be verified after the burn.
extern const CFStringRef kDRBurnVerifyDiscKey ;
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.
kDRCDTextKey |
extern const CFStringRef 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 .
kDRMediaCatalogNumberKey |
The Media Catalog Number (MCN) to write to disc.
extern const CFStringRef kDRMediaCatalogNumberKey ;
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.
kDRSynchronousBehaviorKey |
Flag indicating whether to burn synchronously or asynchronously.
extern const CFStringRef kDRSynchronousBehaviorKey ;
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.
DRBurnRef |
typedef struct __DRBurn* DRBurnRef;
A reference to DRBurn instances.
|