DeviceEnum Class Reference

Provides methods for enumerating and creating Device objects. More...

#include <PrimoBurner.h>

Inherits Reference.

List of all members.

Public Member Functions
virtual const char *	callerName ()=0
	Gets the name of the application that will require exclusive device access.
virtual int	count ()=0
	The count method retrieves the number of CD devices installed on the system.
virtual Device *	createDevice (int index, bool_t exclusiveAccess=0)=0
	Creates and returns a new Device object.
virtual Device *	createDeviceFromSystemPath (const char_t *systemPath, bool_t exclusiveAccess=0)=0
	Creates and returns a new Device object.
virtual const ErrorInfo *	error () const =0
	Gets error information about the last operation.
virtual void	setCallerName (const char *callerName)=0
	Sets the name of the application that will require exclusive device access.

---

Detailed Description

Provides methods for enumerating and creating Device objects.

---

Member Function Documentation

virtual const char* callerName

(

)

[pure virtual]

Gets the name of the application that will require exclusive device access.

This is either the name set with setCallerName or the default value "PrimoBurner SDK".

Returns:

A null-terminated string. The default value is "PrimoBurner SDK".

Remarks:

The caller name is used when a device is created with exclusive access by PrimoBurner. Other processes in the system can get information about the exclusive owner of a specific device. This is OS-specific behavior and functions only on Windows (Vista and above). The caller name is not used on Mac OS X and Linux.

See also:

DeviceEnum::setCallerName

DeviceEnum::createDevice

virtual Device* createDevice	(	int	index,
		bool_t	exclusiveAccess = 0
	)		[pure virtual]

Creates and returns a new Device object.

This method also resets and initializes the device before the device object is returned to the application.

This method should not be called after the Device::startCDSession(), Device::startDVDSession() or Device::startBDSession() methods have been called or during a burning process initiated by the Device::writeToDisc() and Device::writeImageToDisc() methods.

Parameters:

index	The index of the device. The value should be between 0 and the value returned from DeviceEnum::count().
exclusiveAccess	Indicates whether exclusive access to the device is needed.

Remarks:

On Mac OS X v10.4 and above device access is always exclusive regardless of the value of the exclusiveAccess parameter.

Returns:

A new instance of the Device class. The Device::release method must be used to free the device instance.

See also:

DeviceEnum::setCallerName

Object Management

virtual Device* createDeviceFromSystemPath	(	const char_t *	systemPath,
		bool_t	exclusiveAccess = 0
	)		[pure virtual]

Creates and returns a new Device object.

This method also resets and initializes the device before the device object is returned to the application.

This method should not be called after the Device::startCDSession(), Device::startDVDSession() or Device::startBDSession() methods have been called or during a burning process initiated by the Device::writeToDisc() and Device::writeImageToDisc() methods.

Parameters:

systemPath	The device path identifying the requested optical drive.
exclusiveAccess	Indicates whether exclusive access to the device is needed.

NOTE:

On Windows the systemPath parameter stands for the device interface path of the requested device.

On Mac the systemPath parameter represents the IORegistry entry path corresponding to the requested device.

On Linux the systemPath parameter represents the device file associated with the requested device.

Remarks:

On Mac OS X v10.4 and above device access is always exclusive regardless of the value of the exclusiveAccess parameter.

Returns:

A new instance of the Device class. The Device::release method must be used to free the device instance.

See also:

Device::systemPath

Object Management

virtual const ErrorInfo* error

(

)

const [pure virtual]

Gets error information about the last operation.

Returns:

A pointer to an ErrorInfo object.

virtual void setCallerName

(

const char *

callerName

)

[pure virtual]

Sets the name of the application that will require exclusive device access.

Call this method before trying to obtain exclusive access to a device and to set custom caller name. The default caller name is "PrimoBurner SDK".

Parameters:

callerName

Application name. The name must contain alphanumerics (A - Z, a - z, 0 - 9), spaces, periods, commas, colons (:), semi-colons (;), hyphens (-), and underscores (_). It must be less than or equal to 64 bytes in length, including the NULL character at the end of the string.

Remarks:

The caller name is used when a device is created with exclusive access by PrimoBurner. Other processes in the system can get information about the exclusive owner of a specific device. This is OS-specific behavior and functions only on Windows (Vista and above). The caller name is not used on Mac OS X and Linux.

See also:

DeviceEnum::callerName

DeviceEnum::createDevice