ADC Home > Reference Library > Reference > Audio > Carbon > Disc Recording Framework Reference

DRDevice

Inherits from:	NSObject
Declared In:	DRDevice.h

Overview

Represents a CD or DVD burner connected to the computer.

Discussion

About Devices

A DRDevice DRDevice represents a physical CD/DVD drive connected to the computer. This class is mainly for informational purposes since the device is configured by the burn engine before beginning to optimally handle the burn. The basis for obtaining the device information is through two methods info and status . info returns information pertaining to the drive as a whole and is not affected by the state of any media in the drive. status returns information about the media in the drive as well as those bits of information directly affected by the media (maximum burn speed, BSD dev node name, etc.)

Obtaining Device instances

The programmer cannot directly create DRDevices. Devices are managed by the burn engine and are asked for by client code. The preferred way of obtaining an instance is by registering with the DRNotificationCenter and listening for the DRDeviceAppearedNotification . This notification is sent to all observers when a device is first detected by the burn engine (such as when a device is plugged in or turned on). A registered observer is guaranteed to receive all DRDeviceAppearedNotifications . When a client registers for the DRDeviceAppearedNotification , the engine will ensure that the client gets notified of all devices currently connected to the machine. When a device is removed, registed observers will receive a DRDeviceDisappearedNotification .

It's also possible to obtain a device instance from its IORegistry path (deviceForIORegistryEntryPath: ) or the BSD /dev node name (deviceForBSDName: ). If you have a reference to a device instance, you can determine if the physical device is still valid and connected by sending the isValid method to the instance.

Device Control

There is a limited set of operations that can be performed on a device. The most important of these is media reservation. Reserving media is a process by which applications arbitrate for blank media. An application registers interest in obtaining a media reservation by caling acquireMediaReservation and gives up its interest by calling releaseMediaReservation . Asking to acquire a reservation does not mean you will get it! Another application may already have the reservation and will refuse to give it up to you. In this case, the only thing to do is to play fair and wait until the DRDeviceMediaIsReservedKey indicates that your app has obtained the reservation.

The device tray can be opened (openTray ) or closed (closeTray ) and media can be ejected (ejectMedia ).

Methods

-acquireExclusiveAccess: Attempts to acquire an exclusive access session with the device.
-acquireMediaReservation: Indicate an interest in the blank media reservation.
-closeTray: Commands the device to close its tray.
+deviceForBSDName:: Obtains a DRDevice for the device corresponding to the bsd /dev node.
+deviceForIORegistryEntryPath:: Obtains a DRDevice for the device at the path.
+devices: Obtains a static list of devices connected to the computer.
-ejectMedia: Commands the device to eject the media.
-info: Returns a dictionary of information describing the device.
-isEqualToDevice:: Compares the receiver to another device.
-isValid: Returns whether or not the device represented by the receiver is still attached to the computer.
-openTray: Commands the device to open its tray.
-releaseExclusiveAccess: Releases the latest exclusive access request for the device.
-releaseMediaReservation: Releases any media reservation that might be in place for the device.
-status: Returns a dictionary of information describing the media in the device.

acquireExclusiveAccess

Attempts to acquire an exclusive access session with the device.

- (BOOL) acquireExclusiveAccess;

Return Value

Returns YES if the exclusinve access is acquired and NO if not.

Discussion

Acquiring exclusive access to the device prevents any process other than the one acquiring access from communicating with the device. So once exclusive access is granted, the device is unusable by any other process. Because of this all volumes mounted from media in the drive must be unmounted before exclusive access can be granted.

Exclusive access can be acquired multiple times. Each time this method is called, a call to releaseExclusiveAccess > must be made at a later time, otherwise the process will never release its exclusive access.

acquireMediaReservation

Indicate an interest in the blank media reservation.

- (void) acquireMediaReservation;

Discussion

Blank media participates in a reservation system that allows applications to express their claim on blank media to other applications. Indicating an interest in the reservation isn't enough to assume it's been acquired, as there are likely to be other applications in the system who have also indicated an interest in the blank media reservation. You will receive a DRDeviceStatusChangedNotification with a value of TRUE for the DRDeviceMediaIsReservedKey when the blank media reservation has been acquired.

This function may be called multiple times. Each time it is called, a call to releaseMediaReservation must be made at a later time, otherwise the process will never fully rescind its interest in the blank media reservation.

closeTray

Commands the device to close its tray.

- (BOOL) closeTray;

Return Value

Returns YES if the tray could be closed and NO if not.

Discussion

Does nothing if the device does not have a tray (slotload).

deviceForBSDName:

Obtains a DRDevice for the device corresponding to the bsd /dev node.

+ (DRDevice*) deviceForBSDName:(NSString*)bsdName;

Parameters

bsdName: The bsd /dev node name.

Return Value

An autoreleased DRDevice object.

Discussion

If the device is not an authoring device (i.e., CDR, CDRW, DVR-R, etc), returns nil.

deviceForIORegistryEntryPath:

Obtains a DRDevice for the device at the path.

+ (DRDevice*) deviceForIORegistryEntryPath:(NSString*)path;

Parameters

path: The IORegistry path to the device you wish to obtain a DRDEvice for.

Return Value

An autoreleased DRDevice object.

Discussion

If the device is not an authoring device (i.e., CDR, CDRW, DVR-R, etc), returns nil.

devices

Obtains a static list of devices connected to the computer.

+ (NSArray*) devices;

Return Value

An NSArray of DRDevices.

Discussion

Returns all CD/DVD devices connected to the computer at the time this method is called. Since devices can come and go at any time, the output of this method is simply a snapshot of the set of devices connected.

ejectMedia

Commands the device to eject the media.

- (BOOL) ejectMedia;

Return Value

Returns YES if the media could be ejected and NO if not.

Discussion

This command first unmounts any volumes associated with the media and then ejects the media from the drive. If the media could not be ejected, most likely this is because a volume associated with the media could not be unmounted.

info

Returns a dictionary of information describing the device.

- (NSDictionary*) info;

Return Value

An NSDictionary containing device information.

Discussion

The information returned include the types of media the device can write to, how it's connected and its identifying information such as the vendor and product name.

isEqualToDevice:

Compares the receiver to another device.

- (BOOL) isEqualToDevice:(DRDevice*) otherDevice;

Parameters

otherDevice: Another DRDevice instance to compare to the receiver.

Return Value

Returns YES if the receiver is equal to otherDevice.

isValid

Returns whether or not the device represented by the receiver is still attached to the computer.

- (BOOL) isValid;

Return Value

Returns YES if device is valid and NO if not.

Discussion

Because of the way some physical interconnects work, a device which is unplugged and replugged in does not necessarily look like the same device to the computer and would be invalid in that instance.

openTray

Commands the device to open its tray.

- (BOOL) openTray;

Return Value

Returns YES if the tray could be opened and NO if not.

Discussion

Does nothing if the device does not have a tray (slotload). If there is media in the drive this method will do nothing and return false. In this case use ejectMedia to eject the media and open the tray.

releaseExclusiveAccess

Releases the latest exclusive access request for the device.

- (void) releaseExclusiveAccess;

Discussion

A call to this method must be made for every call to acquireExclusiveAccess , otherwise the process will never release its exclusive access.

releaseMediaReservation

Releases any media reservation that might be in place for the device.

- (void) releaseMediaReservation;

Discussion

If media is inserted and reserved, then the reservation will be passed on to the next process with a reservation request.

status

Returns a dictionary of information describing the media in the device.

- (NSDictionary*) status;

Return Value

An NSDictionary containing media information.

Discussion

In addition to information about the media (type, space available/used, etc), the dictionary returned includes those pieces of information about the device itself which are in part determined by the media (i.e., maximum burn speed).

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