Mac Developer Library

Developer

DRBurnSession.h Reference

Options
Deployment Target:

On This Page
Language:

DRBurnSession.h Reference

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Swift

import DiscRecordingUI

Objective-C

@import DiscRecordingUI;

Burn configuration and progress user interface for Carbon applications

Included Headers

  • <DiscRecording/DiscRecording.h>

  • <Carbon/Carbon.h>

  • <AvailabilityMacros.h>

Functions

  • Presents the progress interface as a non-modal dialog.

    Declaration

    Swift

    func DRBurnSessionBeginProgressDialog(_ burnSession: DRBurnSession!, _ layout: AnyObject!, _ options: UnsafeMutablePointer<DRBurnSessionProgressDialogOptions>, _ progressCallbacks: UnsafeMutablePointer<DRBurnSessionProgressCallbacks>)

    Objective-C

    void DRBurnSessionBeginProgressDialog ( DRBurnSessionRef burnSession, CFTypeRef layout, DRBurnSessionProgressDialogOptions *options, DRBurnSessionProgressCallbacks *progressCallbacks );

    Parameters

    burnSession

    The burn session object

    layout

    The track layout to be used for the burn.

    options

    A pointer to a structure of type DRBurnSessionSetupDialogOptions .

    progressCallbacks

    A pointer to a structure of type DRBurnSessionProgressCallbacks . This pointer may be NULL if no custom behavior is desired.

    Discussion

    This function present the user with a non-modal dialog that shows the burn progress.

    Import Statement

    Objective-C

    @import DiscRecordingUI;

    Swift

    import DiscRecordingUI

    Availability

    Available in OS X v10.3 and later.

  • Creates a new burn session.

    Declaration

    Swift

    func DRBurnSessionCreate() -> Unmanaged<DRBurnSession>!

    Objective-C

    DRBurnSessionRef DRBurnSessionCreate ( void );

    Return Value

    A reference to a new DRBurnSession.

    Import Statement

    Objective-C

    @import DiscRecordingUI;

    Swift

    import DiscRecordingUI

    Availability

    Available in OS X v10.3 and later.

  • Returns the burn object for this session.

    Declaration

    Swift

    func DRBurnSessionGetBurn(_ burnSession: DRBurnSession!) -> Unmanaged<DRBurn>!

    Objective-C

    DRBurnRef DRBurnSessionGetBurn ( DRBurnSessionRef burnSession );

    Parameters

    burnSession

    The burn session. If this parameter is not a valid DRBurnSessionRef , the behavior is undefined.

    Return Value

    A reference to the burn object for the session. If the setup dialog has not been run or a burn object has not been set with DRBurnSessionSetBurn , this function returns NULL.

    Import Statement

    Objective-C

    @import DiscRecordingUI;

    Swift

    import DiscRecordingUI

    Availability

    Available in OS X v10.3 and later.

  • Returns the type identifier of all DRBurnSession instances.

    Declaration

    Swift

    func DRBurnSessionGetTypeID() -> CFTypeID

    Objective-C

    CFTypeID DRBurnSessionGetTypeID ( void );

    Return Value

    A Core Foundation type ID.

    Import Statement

    Objective-C

    @import DiscRecordingUI;

    Swift

    import DiscRecordingUI

    Availability

    Available in OS X v10.3 and later.

  • Sets the burn object for this session.

    Declaration

    Swift

    func DRBurnSessionSetBurn(_ burnSession: DRBurnSession!, _ burn: DRBurn!)

    Objective-C

    void DRBurnSessionSetBurn ( DRBurnSessionRef burnSession, DRBurnRef burn );

    Parameters

    burnSession

    The burn session. If this parameter is not a valid DRBurnSessionRef , the behavior is undefined.

    burn

    The burn to use for the session. If this parameter is not a valid DRBurnRef , the behavior is undefined.

    Import Statement

    Objective-C

    @import DiscRecordingUI;

    Swift

    import DiscRecordingUI

    Availability

    Available in OS X v10.3 and later.

  • Presents the setup interface as a modal dialog.

    Declaration

    Swift

    func DRBurnSessionSetupDialog(_ burnSession: DRBurnSession!, _ options: UnsafeMutablePointer<DRBurnSessionSetupDialogOptions>, _ setupCallbacks: UnsafeMutablePointer<DRBurnSessionSetupCallbacks>) -> Int8

    Objective-C

    SInt8 DRBurnSessionSetupDialog ( DRBurnSessionRef burnSession, DRBurnSessionSetupDialogOptions *options, DRBurnSessionSetupCallbacks *setupCallbacks );

    Parameters

    burnSession

    The burn session object

    options

    A pointer to a structure of type DRBurnSessionSetupDialogOptions . This pointer may be NULL if no custom configuration is required.

    setupCallbacks

    A pointer to a structure of type DRBurnSessionSetupCallbacks . This pointer may be NULL if no custom behavior is desired.

    Return Value

    Returns one of the constants defined by Burn Session Dialog Result Codes .

    Discussion

    This function present the user with a modal dialog that allows them to configure a burn to their custom settings. These include: the device to use, whether or not to eject the media when finished, the burn speed and others. The function does not return until the user dismissed the dialog.

    Import Statement

    Objective-C

    @import DiscRecordingUI;

    Swift

    import DiscRecordingUI

    Availability

    Available in OS X v10.3 and later.

Callbacks

  • Callback notifying the application the burn has finished.

    Declaration

    Swift

    typealias DRBurnSessionBurnCompleteProcPtr = CFunctionPointer<((DRBurnSession!, DRBurn!) -> Boolean)>

    Objective-C

    typedef Boolean ( *DRBurnSessionBurnCompleteProcPtr )( DRBurnSessionRef burnSession, DRBurnRef burn);

    Parameters

    burnSession

    The burn session object.

    burn

    The burn instance that just finished.

    Return Value

    A Boolean value controlling the display of the burn session's error dialog.

    Discussion

    This callback is called when the burn operation completes, either successfully or with an error. This function can be used by the application to present it's own custom end-of-burn handling. Return a false return value to prevent the burn session from presenting it's own notification.

    Import Statement

    Objective-C

    @import DiscRecordingUI;

    Swift

    import DiscRecordingUI

    Availability

    Available in OS X v10.3 and later.

  • Callback used for checking the suitability of a device.

    Declaration

    Swift

    typealias DRBurnSessionDeviceCheckProcPtr = CFunctionPointer<((DRBurnSession!, DRDevice!) -> Boolean)>

    Objective-C

    typedef Boolean ( *DRBurnSessionDeviceCheckProcPtr )( DRBurnSessionRef burnSession, DRDeviceRef device);

    Parameters

    burnSession

    The burn session object.

    device

    The device to examine.

    Return Value

    A Boolean value indicating the suitability of the device.

    Discussion

    This callback is called whenever a new device appears. It's purpose is to allow the application to filter out devices which do not support the operation to be performed. for example, a device may filter our CD-R/Ws if it is a DVD creation appliacation.

    Import Statement

    Objective-C

    @import DiscRecordingUI;

    Swift

    import DiscRecordingUI

    Availability

    Available in OS X v10.3 and later.

  • Callback used to notify the application of a new device selected.

    Declaration

    Swift

    typealias DRBurnSessionDeviceSelectionNotificationProcPtr = CFunctionPointer<((DRBurnSession!, DRDevice!) -> Void)>

    Objective-C

    typedef void ( *DRBurnSessionDeviceSelectionNotificationProcPtr )( DRBurnSessionRef burnSession, DRDeviceRef device);

    Parameters

    burnSession

    The burn session object.

    device

    The newly selected device.

    Import Statement

    Objective-C

    @import DiscRecordingUI;

    Swift

    import DiscRecordingUI

    Availability

    Available in OS X v10.3 and later.

  • Callback used for checking the suitability of media in a device.

    Declaration

    Swift

    typealias DRBurnSessionMediaCheckProcPtr = CFunctionPointer<((DRBurnSession!, DRDevice!, UnsafeMutablePointer<Unmanaged<CFString>?>) -> Boolean)>

    Objective-C

    typedef Boolean ( *DRBurnSessionMediaCheckProcPtr )( DRBurnSessionRef burnSession, DRDeviceRef device, CFStringRef *prompt);

    Parameters

    burnSession

    The burn session object.

    device

    The device containing the media to examine.

    prompt

    A pointer to a CFStringRef. An application may return a custom message to display in the setup dialog.

    Return Value

    A Boolean value indicating the suitability of the media.

    Discussion

    This callback is called whenever the state of the media has changed. It's purpose is to allow the application to determine if the media is suitable for the operation to be performed. For example, the application an check to see if there is enough space on the media for the data to be written.

    Import Statement

    Objective-C

    @import DiscRecordingUI;

    Swift

    import DiscRecordingUI

    Availability

    Available in OS X v10.3 and later.

  • Callback notifying the application the burn progress is about to begin.

    Declaration

    Swift

    typealias DRBurnSessionProgressBeginNotificationProcPtr = CFunctionPointer<((DRBurnSession!) -> Void)>

    Objective-C

    typedef void ( *DRBurnSessionProgressBeginNotificationProcPtr )( DRBurnSessionRef burnSession);

    Parameters

    burnSession

    The burn session object.

    Discussion

    This callback is called when the burn progress is about to be displayed. This allows the application to do things such as disable the quit menu item, or the close menu for a document window.

    Import Statement

    Objective-C

    @import DiscRecordingUI;

    Swift

    import DiscRecordingUI

    Availability

    Available in OS X v10.3 and later.

  • Callback notifying the application the burn progress has finished.

    Declaration

    Swift

    typealias DRBurnSessionProgressFinishNotificationProcPtr = CFunctionPointer<((DRBurnSession!) -> Void)>

    Objective-C

    typedef void ( *DRBurnSessionProgressFinishNotificationProcPtr )( DRBurnSessionRef burnSession);

    Parameters

    burnSession

    The burn session object.

    Discussion

    This callback is called when the burn progress has been removed from view. This allows the application to do things such as re-enable the quit menu item, or the close menu for a document window.

    Import Statement

    Objective-C

    @import DiscRecordingUI;

    Swift

    import DiscRecordingUI

    Availability

    Available in OS X v10.3 and later.

Data Types

See the Overview for header-level documentation.

  • Specifies progress dialog configuration options.

    Declaration

    Swift

    typealias DRBurnSessionProgressDialogOptionFlags = UInt32

    Objective-C

    typedef UInt32 DRBurnSessionProgressDialogOptionFlags;

    Import Statement

    Objective-C

    @import DiscRecordingUI;

    Swift

    import DiscRecordingUI

    Availability

    Available in OS X v10.3 and later.

  • Declaration

    Swift

    typealias DRBurnSessionRef = DRBurnSession

    Objective-C

    typedef struct __DRBurnSession* DRBurnSessionRef;

    Discussion

    This is the type of a reference to DRBurnSession instances.

    Import Statement

    Objective-C

    @import DiscRecordingUI;

    Swift

    import DiscRecordingUI

    Availability

    Available in OS X v10.3 and later.

  • Specifies setup dialog configuration options.

    Declaration

    Swift

    typealias DRBurnSessionSetupDialogOptionFlags = UInt32

    Objective-C

    typedef UInt32 DRBurnSessionSetupDialogOptionFlags;

    Import Statement

    Objective-C

    @import DiscRecordingUI;

    Swift

    import DiscRecordingUI

    Availability

    Available in OS X v10.3 and later.

  • Callback functions passed to the progress dialog.

    Declaration

    Objective-C

    struct DRBurnSessionProgressCallbacks { UInt32 version; DRBurnSessionProgressBeginNotificationProcPtr progressWillBegin; DRBurnSessionProgressFinishNotificationProcPtr progressDidFinish; DRBurnSessionBurnCompleteProcPtr burnDidFinish; };

    Fields

    version

    Identifies the version of this structure.

    progressWillBegin

    Pointer to a DRBurnSessionProgressBeginNotificationProcPtr. The value of this field may be NULL.

    progressDidFinish

    Pointer to a DRBurnSessionProgressFinishNotificationProcPtr. The value of this field may be NULL.

    burnDidFinish

    Pointer to a DRBurnSessionBurnCompleteProcPtr. The value of this field may be NULL.

  • Options passed into the progress dialog to configure it.

    Declaration

    Objective-C

    struct DRBurnSessionProgressDialogOptions { UInt32 version; DRBurnSessionProgressDialogOptionFlags dialogOptionFlags; /* option flags for affecting the dialog's behavior */ CFStringRef description; /* optional description of the burn */ };

    Fields

    version

    Identifies the version of this structure.

    dialogOptionFlags

    One of several constants defined by the DRBurnSessionProgressDialogOptionFlags data type as described in Burn Progress Dialog Option Flags .

    description

    A CFStringRef that defines a custom description to be used for the dialog. If you do not provide this string (passing NULL), the normal description is used.

  • Callback functions passed to the setup dialog.

    Declaration

    Objective-C

    struct DRBurnSessionSetupCallbacks { UInt32 version; DRBurnSessionDeviceCheckProcPtr deviceShouldBeTarget; DRBurnSessionMediaCheckProcPtr containsSuitableMedia; DRBurnSessionDeviceSelectionNotificationProcPtr deviceSelectionChanged; };

    Fields

    version

    Identifies the version of this structure.

    deviceShouldBeTarget

    Pointer to a DRBurnSessionDeviceCheckProcPtr. The value of this field may be NULL.

    containsSuitableMedia

    Pointer to a DRBurnSessionMediaCheckProcPtr. The value of this field may be NULL.

    deviceSelectionChanged

    Pointer to a DRBurnSessionDeviceSelectionNotificationProcPtr. The value of this field may be NULL.

  • Options passed into the setup dialog to configure it.

    Declaration

    Objective-C

    struct DRBurnSessionSetupDialogOptions { UInt32 version; DRBurnSessionSetupDialogOptionFlags dialogOptionFlags; /* option flags for affecting the dialog's behavior */ CFStringRef defaultButtonTitle; /* title of default button */ };

    Fields

    version

    Identifies the version of this structure.

    dialogOptionFlags

    One of several constants defined by the DRBurnSessionSetupDialogOptionFlags data type as described in Burn Setup Dialog Option Flags .

    defaultButtonTitle

    A CFStringRef that defines a custom title to be used for the dialog's default button. If you do not provide this string (passing NULL), the normal button title is used.

Constants

See the Overview for header-level documentation.

  • Declaration

    Swift

    var kBurnSessionProgressDialogDefaultOptions: Int { get } var kBurnSessionProgressDialogDisplayVerboseProgress: Int { get }

    Objective-C

    enum { kBurnSessionProgressDialogDefaultOptions = 0x00000000 , /* use defaults for all the options */ kBurnSessionProgressDialogDisplayVerboseProgress = 0x00000001 /* Report all status changes in detail */ };

    Constants

    • kBurnSessionProgressDialogDefaultOptions

      kBurnSessionProgressDialogDefaultOptions

      Use defaults for all the options

      Available in OS X v10.3 and later.

    • kBurnSessionProgressDialogDisplayVerboseProgress

      kBurnSessionProgressDialogDisplayVerboseProgress

      Report all status changes in detail

      Available in OS X v10.3 and later.

    Discussion

    Flags used to configure the burn progress dialog behavior

  • Declaration

    Swift

    var kDRBurnSessionOK: Int { get } var kDRBurnSessionCancel: Int { get }

    Objective-C

    enum { kDRBurnSessionOK = 1, kDRBurnSessionCancel = 0, };

    Constants

    • kDRBurnSessionOK

      kDRBurnSessionOK

      Value returned by the setup dialog when the user has confirmed the burn setup.

      Available in OS X v10.3 and later.

    • kDRBurnSessionCancel

      kDRBurnSessionCancel

      Value returned by the setup dialog when the user has canceled the burn setup.

      Available in OS X v10.3 and later.

    Discussion

    Return codes for the burn session setup dialog.

  • Declaration

    Swift

    var kBurnSessionSetupDialogDefaultOptions: UInt32 { get } var kBurnSessionSetupDialogForceClosedDiscs: UInt32 { get } var kBurnSessionSetupDialogDontHandleReservations: UInt32 { get } var kBurnSessionSetupDialogAllowTestBurns: UInt32 { get }

    Objective-C

    enum { kBurnSessionSetupDialogDefaultOptions = 0x00000000 , /* use defaults for all the options */ kBurnSessionSetupDialogForceClosedDiscs = 0x00000001 , /* Force discs to be closed (not appendable ) */ kBurnSessionSetupDialogDontHandleReservations = 0x00000002 , /* Don't handle media reservations. Application handles them itself */ kBurnSessionSetupDialogAllowTestBurns = 0x80000004 /* Allow the user to perform a test burn */ };

    Constants

    • kBurnSessionSetupDialogDefaultOptions

      kBurnSessionSetupDialogDefaultOptions

      Use defaults for all the options

      Available in OS X v10.3 and later.

    • kBurnSessionSetupDialogForceClosedDiscs

      kBurnSessionSetupDialogForceClosedDiscs

      Force discs to be closed (not appendable)

      Available in OS X v10.3 and later.

    • kBurnSessionSetupDialogDontHandleReservations

      kBurnSessionSetupDialogDontHandleReservations

      Burn session does not handle media reservations. Application handles them itself

      Available in OS X v10.3 and later.

    • kBurnSessionSetupDialogAllowTestBurns

      kBurnSessionSetupDialogAllowTestBurns

      Allow the user to perform a test burn

      Available in OS X v10.3 and later.

    Discussion

    Flags used to configure the burn setup dialog behavior

  • Declaration

    Objective-C

    enum { kBurnSessionProgressDialogOptionsCurrentVersion = 1 };

  • Declaration

    Objective-C

    enum { kDRBurnSessionSetupCallbacksCurrentVersion = 1 };

  • Declaration

    Objective-C

    enum { kBurnSessionSetupDialogOptionsCurrentVersion = 1 };

  • Declaration

    Objective-C

    enum { kDRBurnProgressSetupCallbacksCurrentVersion = 1 };