Mac Dev Center Mac OS X Reference Library Drivers, Kernel, & Hardware: User-Space Device Access Disc Recording UI Framework Reference

Overview

Erase configuration and progress user interface for Carbon applications

Functions

DREraseSessionBeginProgressDialog

Presents the progress interface as a non-modal dialog.

DREraseSessionCreate

Creates a new erase session.

DREraseSessionGetErase

Returns the erase object for this session.

DREraseSessionGetTypeID

Returns the type identifier of all DREraseSession instances.

DREraseSessionSetErase

Sets the erase object for this session.

DREraseSessionSetupDialog

Presents the setup interface as a modal dialog.

Presents the progress interface as a non-modal dialog.

extern void DREraseSessionBeginProgressDialog( 
    DREraseSessionRef eraseSession, 
    DREraseSessionProgressDialogOptions *options, 
    DREraseSessionProgressCallbacks *progressCallbacks);  

Parameters

Discussion

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

Availability

Introduced in Mac OS X v10.3.

Creates a new erase session.

extern DREraseSessionRef DREraseSessionCreate(
    void);  

Return Value

A reference to a new DREraseSession.

Availability

Introduced in Mac OS X v10.3.

Returns the erase object for this session.

extern DREraseRef DREraseSessionGetErase( 
    DREraseSessionRef eraseSession);  

Parameters

Return Value

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

Availability

Introduced in Mac OS X v10.3.

Returns the type identifier of all DREraseSession instances.

extern CFTypeID DREraseSessionGetTypeID(
    void);  

Return Value

A Core Foundation type ID.

Availability

Introduced in Mac OS X v10.3.

Sets the erase object for this session.

extern void DREraseSessionSetErase( 
    DREraseSessionRef eraseSession, 
    DREraseRef erase);  

Parameters

Availability

Introduced in Mac OS X v10.3.

Presents the setup interface as a modal dialog.

extern SInt8 DREraseSessionSetupDialog( 
    DREraseSessionRef eraseSession, 
    DREraseSessionSetupDialogOptions *options, 
    DREraseSessionSetupCallbacks *setupCallbacks);  

Parameters

Return Value

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

Discussion

This function present the user with a modal dialog that allows them to configure an erase to their custom settings. These include: the device to use and the type of erase to perform. and others. The function does not return until the user dismissed the dialog.

Availability

Introduced in Mac OS X v10.3.

Typedefs

DREraseSessionDeviceCheckProcPtr

Callback used for checking the suitability of a device.

DREraseSessionDeviceSelectionNotificationProcPtr

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

DREraseSessionEraseCompleteProcPtr

Callback notifying the application the erase has finished.

DREraseSessionMediaCheckProcPtr

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

DREraseSessionProgressBeginNotificationProcPtr

Callback notifying the application the erase progress is about to begin.

DREraseSessionProgressDialogOptionFlags

Specifies progress dialog configuration options.

DREraseSessionProgressFinishNotificationProcPtr

Callback notifying the application the erase progress has finished.

DREraseSessionRef

DREraseSessionSetupDialogOptionFlags

Specifies setup dialog configuration options.

Callback used for checking the suitability of a device.

typedef Boolean ( *DREraseSessionDeviceCheckProcPtr )(
    DREraseSessionRef eraseSession,
    DRDeviceRef device);  

Parameters

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.

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

typedef void ( *DREraseSessionDeviceSelectionNotificationProcPtr )(
    DREraseSessionRef eraseSession,
    DRDeviceRef selectedDevice);  

Fields

Callback notifying the application the erase has finished.

typedef Boolean ( *DREraseSessionEraseCompleteProcPtr )(
    DREraseSessionRef eraseSession,
    DREraseRef erase);  

Parameters

Return Value

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

Discussion

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

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

typedef Boolean ( *DREraseSessionMediaCheckProcPtr )(
    DREraseSessionRef eraseSession,
    DRDeviceRef device,
    CFStringRef *prompt);  

Parameters

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.

Callback notifying the application the erase progress is about to begin.

typedef void ( *DREraseSessionProgressBeginNotificationProcPtr )(
    DREraseSessionRef eraseSession);  

Fields

Discussion

This callback is called when the erase 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.

Specifies progress dialog configuration options.

typedef UInt32 DREraseSessionProgressDialogOptionFlags;  

Callback notifying the application the erase progress has finished.

typedef void ( *DREraseSessionProgressFinishNotificationProcPtr )(
    DREraseSessionRef eraseSession);  

Fields

Discussion

This callback is called when the erase 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.

typedef struct __DREraseSession* DREraseSessionRef;  

Discussion

This is the type of a reference to DREraseSession instances.

Specifies setup dialog configuration options.

typedef UInt32 DREraseSessionSetupDialogOptionFlags;  

Structs and Unions

DREraseSessionProgressCallbacks

Callback functions passed to the progress dialog.

DREraseSessionProgressDialogOptions

Options passed into the progress dialog to configure it.

DREraseSessionSetupCallbacks

Callback functions passed to the setup dialog.

DREraseSessionSetupDialogOptions

Options passed into the setup dialog to configure it.

Callback functions passed to the progress dialog.

struct DREraseSessionProgressCallbacks { 
    UInt32 version; 
    DREraseSessionProgressBeginNotificationProcPtr progressWillBegin; 
    DREraseSessionProgressFinishNotificationProcPtr progressDidFinish; 
    DREraseSessionEraseCompleteProcPtr eraseDidFinish; 
};  

Fields

Options passed into the progress dialog to configure it.

struct DREraseSessionProgressDialogOptions { 
    UInt32 version; 
    DREraseSessionProgressDialogOptionFlags dialogOptionFlags; /* 
        option flags for affecting the dialog's behavior */
    CFStringRef description; /* optional description of the erase */
};  

Fields

Callback functions passed to the setup dialog.

struct DREraseSessionSetupCallbacks { 
    UInt32 version; 
    DREraseSessionDeviceCheckProcPtr deviceShouldBeTarget; 
    DREraseSessionMediaCheckProcPtr containsSuitableMedia; 
    DREraseSessionDeviceSelectionNotificationProcPtr deviceSelectionChanged; 
};  

Fields

Options passed into the setup dialog to configure it.

struct DREraseSessionSetupDialogOptions { 
    UInt32 version; 
    DREraseSessionSetupDialogOptionFlags dialogOptionFlags; /* option flags for affecting the dialog's behavior */
};  

Fields

Enumerated Types

DREraseSessionProgressDialogOptions struct version

DREraseSessionSetupCallbacks struct version

DREraseSessionSetupDialogOptions struct version

Erase Progress Dialog Option Flags

Erase Session Dialog Result Codes

Erase Setup Dialog Option Flags

kDREraseProgressSetupCallbacksCurrentVersion struct version

enum { 
    kEraseSessionProgressDialogOptionsCurrentVersion = 1 
};  

enum { 
    kDREraseSessionSetupCallbacksCurrentVersion = 1 
};  

enum { 
    kEraseSessionSetupDialogOptionsCurrentVersion = 1 
};  

enum { 
    kEraseSessionProgressDialogDefaultOptions = 0x00000000 /* use defaults for all the options */
};  

Constants

Discussion

Flags used to configure the erase progress dialog behavior

enum { 
    kDREraseSessionOK = 1, 
    kDREraseSessionCancel = 0 
};  

Constants

Discussion

Return codes for the erase session setup dialog.

enum { 
    kEraseSessionSetupDialogDefaultOptions = 0x00000000, /* use defaults for all the options */
    kEraseSessionSetupDialogDontHandleReservations = 0x00000001, /* 
        Don't handle media reservations. Application handles them itself */
};  

Constants

Discussion

Flags used to configure the erase setup dialog behavior

enum { 
    kDREraseProgressSetupCallbacksCurrentVersion = 1 
};