PrimoBurner(tm) for C++  4.6
CD, DVD and Blu-ray Software Development Kit
 All Classes Namespaces Files Functions Variables Enumerations Enumerator Pages
DeviceEnum Class Referenceabstract

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

#include <PrimoBurnerAPI.h>

Inherits Reference.

Public Member Functions

virtual const char * callerName ()=0
 Gets the name of the application that will require exclusive device access. More...
 
virtual int count ()=0
 The count method retrieves the number of CD devices installed on the system.
 
virtual DevicecreateDevice (int index, bool_t exclusiveAccess=0)=0
 Creates and returns a new Device object. More...
 
virtual DevicecreateDeviceFromSystemPath (const char_t *systemPath, bool_t exclusiveAccess=0)=0
 Creates and returns a new Device object. More...
 
virtual const ErrorInfoerror () const =0
 Gets error information about the last operation. More...
 
virtual void setCallerName (const char *callerName)=0
 Sets the name of the application that will require exclusive device access. More...
 
- Public Member Functions inherited from Reference
virtual int32_t release () const =0
 Releases the instance. More...
 
virtual int32_t retain () const =0
 Retains the instance. More...
 
virtual int32_t retainCount () const =0
 Returns the current reference count. More...
 

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
indexThe index of the device. The value should be between 0 and the value returned from DeviceEnum::count().
exclusiveAccessIndicates 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.
@return  A new instance of the Device class. The Device::release method must be used to free the device instance.

@see DeviceEnum::setCallerName

@see \ref ObjectManagement
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
systemPathThe device path identifying the requested optical drive.
exclusiveAccessIndicates 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
callerNameApplication 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