Mac Developer Library

Developer

DRBurn Class Reference

Options
Deployment Target:

On This Page

DRBurn

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

  • Stops the burn.

    Declaration

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

  • Returns the device being used for the burn.

    Declaration

    - (DRDevice*) device;

    Return Value

    The DRDevice the burn will use.

  • Initializes the burn object.

    Declaration

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

    Declaration

    - (NSDictionary*) properties;

    Return Value

    An NSDictionary containing the properties of the burn.

  • Sets the properties dictionary of the burn.

    Declaration

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

    Parameters

    properties

    NSDictionary of the properties to set.

  • Returns a dictionary describing the status of the burn.

    Declaration

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

    Declaration

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

  • Creates an autoreleased burn object.

    Declaration

    + (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.