Mac Developer Library

Developer

DRBurn.h Reference

Options
Deployment Target:

On This Page
Language:

DRBurn.h Reference

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Swift

import DiscRecording

Objective-C

@import DiscRecording;

Perform and monitor the burning of a CD or DVD disc.

Each time you want to burn to a disc, an instance of DRBurn needs to be created.

When an instance is created, you pass in an instance of DRDevice to let the DRBurn object know what device to use. This object is retained for the life of the DRBurn instance. Before burning, you can set several options that control the behavior of the burn and the handling of the disc once the burn completes.

A DRBurn object will send out notifications through the DRNotificationCenter mechanism to broadcast the burn state to any interested observers. However, if for some reason you don't want to use notifications, you can poll the burn object at any time for the current status using status . This is not recommended in any application using a run loop, because it involves polling.

For examples of how to use this class see the on-disk sample code projects at /Developer/Examples/DiscRecording/ObjectiveC/.

Included Headers

  • <Foundation/Foundation.h>

  • <DiscRecording/DRCoreBurn.h>

  • <DiscRecording/DRDevice.h>

  • <DiscRecording/DRTrack.h>

  • <AvailabilityMacros.h>

Constants

See the Overview section above for header-level documentation.

  • Declaration

    Swift

    let DRBurnAppendableKey: String let DRBurnCompletionActionEject: String let DRBurnCompletionActionKey: String let DRBurnCompletionActionMount: String let DRBurnDoubleLayerL0DataZoneBlocksKey: String let DRBurnFailureActionEject: String let DRBurnFailureActionKey: String let DRBurnFailureActionNone: String let DRBurnOverwriteDiscKey: String let DRBurnRequestedSpeedKey: String let DRBurnStatusChangedNotification: String let DRBurnStrategyBDDAO: String let DRBurnStrategyCDSAO: String let DRBurnStrategyCDTAO: String let DRBurnStrategyDVDDAO: String let DRBurnStrategyIsRequiredKey: String let DRBurnStrategyKey: String let DRBurnTestingKey: String let DRBurnUnderrunProtectionKey: String let DRBurnVerifyDiscKey: String let DRCDTextKey: String let DRMediaCatalogNumberKey: String let DRSynchronousBehaviorKey: String

    Objective-C

    extern NSString* const DRBurnAppendableKey; extern NSString* const DRBurnCompletionActionEject; extern NSString* const DRBurnCompletionActionKey; extern NSString* const DRBurnCompletionActionMount; extern NSString* const DRBurnDoubleLayerL0DataZoneBlocksKey; extern NSString* const DRBurnFailureActionEject; extern NSString* const DRBurnFailureActionKey; extern NSString* const DRBurnFailureActionNone; extern NSString* const DRBurnOverwriteDiscKey; extern NSString* const DRBurnRequestedSpeedKey; extern NSString* const DRBurnStatusChangedNotification; extern NSString* const DRBurnStrategyBDDAO; extern NSString* const DRBurnStrategyCDSAO; extern NSString* const DRBurnStrategyCDTAO; extern NSString* const DRBurnStrategyDVDDAO; extern NSString* const DRBurnStrategyIsRequiredKey; extern NSString* const DRBurnStrategyKey; extern NSString* const DRBurnTestingKey; extern NSString* const DRBurnUnderrunProtectionKey; extern NSString* const DRBurnVerifyDiscKey; extern NSString* const DRCDTextKey; extern NSString* const DRMediaCatalogNumberKey; extern NSString* const DRSynchronousBehaviorKey;

    Constants

    • DRBurnAppendableKey

      DRBurnAppendableKey

      The burn property whose value is a BOOL indicating if the disc will still be appendable after the burn. If this key is not present, the burn will default to a value of NO and the disc will be marked as not appendable.

      Available in OS X v10.2 and later.

    • DRBurnCompletionActionEject

      DRBurnCompletionActionEject

      An NSString value for DRBurnCompletionActionKey indicating that the burn object should eject the disc from the drive when the burn completes.

      Available in OS X v10.2 and later.

    • DRBurnCompletionActionKey

      DRBurnCompletionActionKey

      The burn property whose value is an NSString containing one of the completion actions possible for the disc handling. If this key is not present, the burn will default to a value of DRBurnCompletionActionEject and the disc will be ejected.

      Available in OS X v10.2 and later.

    • DRBurnCompletionActionMount

      DRBurnCompletionActionMount

      An NSString value for DRBurnCompletionActionKey indicating that the burn object should mount the disc on the desktop when the burn completes.

      Available in OS X v10.2 and later.

    • DRBurnDoubleLayerL0DataZoneBlocksKey

      DRBurnDoubleLayerL0DataZoneBlocksKey

      The burn property key whose value is an NSNumber 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.

    • DRBurnFailureActionEject

      DRBurnFailureActionEject

      An NSString value for DRBurnFailureActionKey indicating that the burn object should eject the disc from the drive if the burn fails.

      Available in OS X v10.3 and later.

    • DRBurnFailureActionKey

      DRBurnFailureActionKey

      The burn property whose value is an NSString containing a one of the failure actions possible for the disc handling.

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

      Available in OS X v10.3 and later.

    • DRBurnFailureActionNone

      DRBurnFailureActionNone

      An NSString value for DRBurnFailureActionKey indicating that the burn object should do nothing with the disc if the burn fails.

      Available in OS X v10.3 and later.

    • DRBurnOverwriteDiscKey

      DRBurnOverwriteDiscKey

      The burn property whose value is a BOOL 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 NO and the disc will be appended.

      Available in OS X v10.3 and later.

    • DRBurnRequestedSpeedKey

      DRBurnRequestedSpeedKey

      The burn property whose value is an NSNumber containing the speed at which the burn should run, expressed as a float value of kilobytes per second. If this key is not present, the speed will default to DRDeviceBurnSpeedMax .

      Available in OS X v10.2 and later.

    • DRBurnStatusChangedNotification

      DRBurnStatusChangedNotification

      Posted by a DRNotificationCenter when the status of the burn operation has changed.

      The object associated with this notification is the DRBurn object sending it and the userInfo contains the same dictionary as returned by status which details the current state of the burn.

      Available in OS X v10.2 and later.

    • DRBurnStrategyBDDAO

      DRBurnStrategyBDDAO

      An NSString value for DRBurnStrategyKey representing the DAO (disc-at-once) burn strategy for BD (Blu-ray). This strategy applies only to BDs.

      Available in OS X v10.5 and later.

    • DRBurnStrategyCDSAO

      DRBurnStrategyCDSAO

      An NSString value for DRBurnStrategyKey representing the SAO (session-at-once) burn strategy for CD.

      Available in OS X v10.3 and later.

    • DRBurnStrategyCDTAO

      DRBurnStrategyCDTAO

      An NSString value for DRBurnStrategyKey representing the TAO (track-at-once) burn strategy for CD.

      Available in OS X v10.3 and later.

    • DRBurnStrategyDVDDAO

      DRBurnStrategyDVDDAO

      An NSString value for DRBurnStrategyKey representing the DAO (disc-at-once) burn strategy for DVD. This strategy applies only to DVDs; it is invalid when burning to CD media.

      Available in OS X v10.3 and later.

    • DRBurnStrategyIsRequiredKey

      DRBurnStrategyIsRequiredKey

      The burn property whose value is a BOOL indicating whether the burn strategy/strategies listed for DRBurnStrategyKey are the only strategies allowed. If this key is not present, the burn will default to a value of NO.

      If this value is set to YES, and the device does not support the type(s) of burn requested, the burn will fail with kDRDeviceBurnStrategyNotAvailableErr .

      If this value is set to NO, and the device does not support the type(s) of burn requested, the engine will choose an alternate burn strategy automatically - one that will provide an equivalent disc.

      Available in OS X v10.3 and later.

    • DRBurnStrategyKey

      DRBurnStrategyKey

      The burn property whose value is an NSString, or array of NSStrings, indicating the burn strategy or strategies that are suggested. If this key is not present, the burn engine picks an appropriate burn strategy automatically. Most clients will not need to specify a specific burn strategy.

      When more than one strategy is suggested, the burn engine will attempt 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, TAO cannot be used to write CD-Text.

      The presence of this key by itself is just a suggestion, and if the burn engine cannot fulfill the request it will burn using whatever strategy is available. To make the suggestion into a requirement, add DRBurnStrategyIsRequiredKey with a value of YES.

      Available in OS X v10.3 and later.

    • DRBurnTestingKey

      DRBurnTestingKey

      The burn property whose value is a BOOL indicating if the burn will run as a test burn.

      When this is set and the burn object is sent writeLayout: , the entire burn process proceeds as if data would be written to the disc, but the laser is not turned on to full power, so the physical 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 NO and a normal burn will occur.

      Available in OS X v10.2 and later.

    • DRBurnUnderrunProtectionKey

      DRBurnUnderrunProtectionKey

      The burn property whose value is a BOOL indicating if burn underrun protection will be on or off for devices which support it.

      For those devices which support it, burn underrun protection is enabled by default.

      If the device supports burn underrun protection and this key is not present, the burn will default to a value of YES and burn underrun protection will be enabled.

      Available in OS X v10.2 and later.

    • DRBurnVerifyDiscKey

      DRBurnVerifyDiscKey

      The burn property whose value is a BOOL indicating if the disc will be verified after being burned. If this key is not present, the burn will default to a value of YES and the disc will be verified.

      Available in OS X v10.2 and later.

    • DRCDTextKey

      DRCDTextKey

      This key points to a DRCDTextBlock , or array of DRCDTextBlocks 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 to make sure that the device supports CD-Text by checking the value of DRDeviceCanWriteCDTextKey in the device's write capabilities dictionary.

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

      Available in OS X v10.4 and later.

    • DRMediaCatalogNumberKey

      DRMediaCatalogNumberKey

      The burn property whose value is an NSData containing exactly 13 bytes of data, which will be written to the disc as the Media Catalog Number. If this key is not present, it will default to all zeroes, indicating that a MCN is not supplied.

      This value is the 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 details on the UPC/EAN standard.

      Available in OS X v10.3 and later.

    • DRSynchronousBehaviorKey

      DRSynchronousBehaviorKey

      The burn property whose value is a BOOL indicating if burn operations will behave synchronously. If this key is not present, it will default to a value of NO and burn operations will behave asynchronously.

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

      Available in OS X v10.2 and later.