DRBurn

Overview

Handles the process of burning a CD or DVD disc.

Discussion

Each time you want to burn to a disc, an instance of this class 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/.

Methods

-abort

Stops the burn.

+burnForDevice:

Creates an autoreleased burn object.

-device

Returns the device being used for the burn.

-initWithDevice:

Initializes the burn object.

-properties

Returns the properties dictionary of the burn.

-setProperties:

Sets the properties dictionary of the burn.

-status

Returns a dictionary describing the status of the burn.

-writeLayout:

Begin the process of burning a disc layout.

Stops the burn.

- (void) abort; 

Discussion

When this method returns the burn might not actually be fully stopped but it has been cancelled and only cleanup is going on. If a burn has not completed writing data to disc, you just made a coaster.

Typically this method is only used as a result of the user hitting a cancel/stop button somewhere in the user interface.

Creates an autoreleased burn object.

+ (DRBurn*) burnForDevice:(DRDevice*)device; 

Parameters

device

Device to use for the burn

Return Value

An autoreleased DRBurn object.

Discussion

Once a burn is created with this method, the object is ready to write data to the disc.

Returns the device being used for the burn.

- (DRDevice*) device; 

Return Value

The DRDevice the burn will use.

Initializes the burn object.

- (id) initWithDevice:(DRDevice*)device; 

Parameters

device

Device to use for the burn

Return Value

A DRBurn object.

Discussion

Once a burn is initialized with this method, the object is ready to write data to the disc.

Returns the properties dictionary of the burn.

- (NSDictionary*) properties; 

Return Value

An NSDictionary containing the properties of the burn.

Sets the properties dictionary of the burn.

- (void) setProperties:(NSDictionary*)properties; 

Parameters

properties

NSDictionary of the properties to set.

Returns a dictionary describing the status of the burn.

- (NSDictionary*) status; 

Return Value

An NSDictionary reporting the status of the burn.

Discussion

The same dictionary is returned through the DRBurnStatusChangedNotification notification

Begin the process of burning a disc layout.

- (void) writeLayout:(id)layout; 

Parameters

layout

The data to be burned to disc.

There are three configurations of the object passed in:

1. For a multi-session burn, layout must be a valid NSArray containing one or more NSArrays, each of which contains one or more valid DRTrack objects.
2. For a single-session multi-track burn, layout must be a valid NSArray containing one or more valid DRTrack objects.
3. For a single-session single-track burn, layout must be a valid DRTrack object.

If none of these configurations are met or the leaf values contained in layout are not valid DRTrack objects, an exception is thrown.

Discussion

This method only begins the burning process. Once the burn has been started, control returns to the caller and it is up to the caller to monitor the progress of the burn (by listening for DRBurnStatusChangedNotification or polling status ) to know when the burn completes (either successfully or with an error).

Did this document help you? Yes: Tell us what works for you. It’s good, but: Report typos, inaccuracies, and so forth. It wasn’t helpful: Tell us what would have helped.

Last Updated: 2008-04-01