DRBurn Class Reference

Inherits from
Conforms to
Availability
Available in OS X v10.2 and later.
Declared in
DRBurn.h
Related sample code

Overview

Handles the process of burning a CD or DVD disc.

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/.

Tasks

Miscellaneous

Class Methods

burnForDevice:

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.

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

Instance Methods

abort

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.

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

device

Returns the device being used for the burn.

- (DRDevice*) device;
Return Value

The DRDevice the burn will use.

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

initWithDevice:

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.

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

properties

Returns the properties dictionary of the burn.

- (NSDictionary*) properties;
Return Value

An NSDictionary containing the properties of the burn.

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

setProperties:

Sets the properties dictionary of the burn.

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

NSDictionary of the properties to set.

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

status

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

Availability
  • Available in OS X v10.2 and later.
Related Sample Code
Declared In
DRBurn.h

writeLayout:

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).

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