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

The Device interface provides methods for working with CD, DVD and Blu-ray Disc (BD) devices. More...

#include <PrimoBurnerAPI.h>

Inherits Reference.

Public Member Functions

virtual BDFeaturesbdFeatures ()=0
 Gets the Blu-ray Disc capabilities of the device. More...
 
virtual bool_t bdWriteVerify () const =0
 Returns a value indicating whether the device will do automatic verify-after-write cycle while writing data to BD media. More...
 
virtual double bgFormatProgress () const =0
 TGets the current background format progress as a percentage. More...
 
virtual BgFormatStatus::Enum bgFormatStatus () const =0
 Gets the background format status of the mounted disc. More...
 
virtual CDFeaturescdFeatures ()=0
 Gets an object describing the CD capabilities of the device. More...
 
virtual void clearOutputBuffer ()=0
 Clears the output buffer. More...
 
virtual bool_t closeDisc ()=0
 Closes a BD-R disc. More...
 
virtual bool_t closeLastSession ()=0
 The closeLastSession method closes the last open session on the disc. More...
 
virtual bool_t closeTrack (uint16_t trackNumber)=0
 Closes a track. More...
 
virtual QSubChannelcreateQSubChannel (SubChannelFormat::Enum scf, uint8_t *buffer)=0
 The createQSubChannel method returns the Q Sub-channel data from a raw audio CD block. More...
 
virtual ScsiInterface * createScsiInterface ()=0
 Creates and returns a new ScsiInterface object which can be used to send SCSI commands to the underlying hardware device. More...
 
virtual SpeedEnumcreateWriteSpeedEnumerator ()=0
 Enumerates supported write speeds (as reported by the device) into a collection of SpeedDescriptor objects. More...
 
virtual const char_t * description () const =0
 The description method retrieves the device description as it is set by its manufacturer.
 
virtual TrackType::Enum detectTrackType (int32_t trackStartLba, int32_t blocksToScan=10)=0
 Gets the type of a CD track. More...
 
virtual handle_t deviceHandle ()=0
 Call this method to get the OS handle of the underlying device object. More...
 
virtual bool_t disableMCN ()=0
 Disables media change notifications. More...
 
virtual bool_t dismount ()=0
 Tries to dismount the volume in the device. More...
 
virtual char driveLetter () const =0
 The driveLetter method retrieves the drive letter of the device. More...
 
virtual DVDFeaturesdvdFeatures ()=0
 Gets the DVD capabilities of the device. More...
 
virtual bool_t dvdWriteVerify () const =0
 Returns a value indicating whether the device will do automatic verify-after-write procedure while writing data to DVD media. More...
 
virtual bool_t eject (bool_t eject, bool_t unlockMedium=1)=0
 The eject method unlocks and ejects the tray of the device, if possible. More...
 
virtual bool_t enableMCN ()=0
 Enables media change notifications. More...
 
virtual bool_t endBDSession (bool_t closeSession=1, bool_t closeDisc=0)=0
 The endBDSession method finishes a Blu-ray Disc session that has been previously started with the startBDSession method. More...
 
virtual bool_t endBDTrack (bool_t closeTrack=1)=0
 The endBDTrack completes a Blu-ray Disc track. More...
 
virtual bool_t endCDSession ()=0
 Finishes a CD session which has been previously started with the startCDSession method. More...
 
virtual bool_t endCDTrack (bool_t closeTrack=1)=0
 Ends a CD track. More...
 
virtual bool_t endDVDSession (bool_t close=1)=0
 The endDVDSession method finishes a DVD session that has been previously started with the startDVDSession method. More...
 
virtual bool_t endDVDTrack (bool_t close=1)=0
 The endDVDTrack completes a DVD fragment (track). More...
 
virtual bool_t erase (bool_t quick=1)=0
 Attempts to erase a RW disc. More...
 
virtual bool_t eraseEx (EraseType::Enum eraseType)=0
 The erase method attempts to erase the media. More...
 
virtual double eraseProgress () const =0
 Returns a percentage showing the progress of an erase operation started with the eraseEx method.
 
virtual const ErrorInfoerror () const =0
 Gets error information about the last operation. More...
 
virtual bool_t flush ()=0
 Flushes the device internal cache buffer. More...
 
virtual bool_t format (FormatType::Enum formatType, uint32_t blocks=0, bool_t waitForBackground=0)=0
 The Format method formats a re-writable DVD media. More...
 
virtual bool_t formatBD (BDFormatType::Enum type, BDFormatSubType::Enum subType, const BDFormatParameters *formatParameters=NULL)=0
 The formatBD method formats BD-R SRM or BD-RE media. More...
 
virtual double formatProgress () const =0
 Returns a percentage showing the progress of a format operation started with the Device::format method.
 
virtual int internalCacheCapacity () const =0
 The internalCacheCapacity method retrieves the capacity of the device cache buffer in bytes. More...
 
virtual int internalCacheUsedSpace ()=0
 The internalCacheUsedSpace method retrieves the number of bytes used in the internal cache of the device. More...
 
virtual bool_t isMediaBD () const =0
 Indicates that the media in the device is BD-R or BD-RE. More...
 
virtual bool_t isMediaBlank () const =0
 Indicates that the media in the device is blank. More...
 
virtual bool_t isMediaCD () const =0
 Indicates that the media in the device is CD-ROM, CD-R or CD-RW. More...
 
virtual bool_t isMediaDVD () const =0
 The isMediaDVD method indicates whether the medium in the device is DVD-ROM, DVD-RAM, DVD-R/RW or DVD+R/RW. More...
 
virtual bool_t isMediaFormatted () const =0
 Indicates whether the media in the device is formatted. More...
 
virtual bool_t isMediaRewritable () const =0
 Indicates whether the media in the device is re-writable. More...
 
virtual bool_t lockMedia (bool_t bLock)=0
 The lockMedia method enables or disables the manual removal of the medium in the device. More...
 
virtual bool_t lockOutputBuffer (uint32_t blocks, uint8_t **buffer1, uint32_t *buffer1Blocks, uint8_t **buffer2, uint32_t *buffer2Blocks)=0
 Locks a portion of the Device output buffer for writing. More...
 
virtual bool_t lockOutputBufferEx (uint32_t blocks, uint8_t **buffer1, uint32_t *buffer1Blocks, uint8_t **buffer2, uint32_t *buffer2Blocks, uint32_t *blockSize)=0
 Locks a portion of the Device output buffer for writing. More...
 
virtual int maxReadSpeedKB () const =0
 Gets the maximum read speed supported by the device in Kbytes/s (1 Kbyte = 1000 bytes). More...
 
virtual int maxWriteSpeedKB () const =0
 Gets the maximum write speed supported by the device in Kbytes/s (1 Kbyte = 1000 bytes). More...
 
virtual uint32_t mediaCapacity () const =0
 Gets the capacity of the disc in the device. More...
 
virtual uint32_t mediaFreeSpace () const =0
 Gets the number of blocks available for writing. More...
 
virtual uint32_t mediaLayerCapacity () const =0
 Gets the layer 0 (L0) capacity, in blocks, of DVD-R DL and DVD+R DL media. More...
 
virtual
primo::burner::MediaProfile::Enum 
mediaProfile () const =0
 The mediaProfile method returns the type of the media currently inserted in the device. More...
 
virtual
primo::burner::MediaReady::Enum 
mediaState () const =0
 The mediaState method checks whether there is medium inserted in the device. More...
 
virtual int32_t newSessionStartAddress () const =0
 Gets the start address of the new disc session. More...
 
virtual int32_t newTrackStartAddress () const =0
 Get the start address of the next disc track. More...
 
virtual const char_t * productId () const =0
 Retrieves the the product id (the model) of the device as it is set by its manufacturer. More...
 
virtual bool_t rawCDRead (int32_t startLba, SubChannelFormat::Enum scf, uint32_t blockSize, void *buffer, uint32_t numberOfBlocksToRead, uint32_t *numberOfBlocksRead)=0
 Reads raw data from a CD. More...
 
virtual bool_t readAudio (TrackBuffer *trackBuffer, int32_t startBlock, int32_t blocks=primo::burner::BufferSize::DefaultReadBufferBlocks)=0
 The readAudio method reads audio data from an Audio CD the media. More...
 
virtual CDSessionreadCDSessionLayout (uint8_t sessionNumber, bool_t scanTracks=1, bool_t fastScan=1, int32_t fastScanBlocks=600)=0
 Extracts an CDSession object from a CD session. More...
 
virtual CDTextreadCDText ()=0
 The readCDText method reads the CD-TEXT data from the media. More...
 
virtual bool_t readData (TrackBuffer *trackBuffer, int32_t startBlock, int32_t blocks=primo::burner::BufferSize::DefaultReadBufferBlocks)=0
 The readData Method reads data from the media. More...
 
virtual DiscInforeadDiscInfo ()=0
 Reads information about the disc. More...
 
virtual MediaInforeadMediaInfo ()=0
 Creates an objects that provides extended media information. More...
 
virtual RawTocreadRawToc ()=0
 Reads the Full Table-Of-Content in raw format. More...
 
virtual SessionInforeadSessionInfo ()=0
 Returns information about the disc sessions. More...
 
virtual int readSpeedKB () const =0
 Gets the current read speed in Kbytes/s (1 KByte = 1000 bytes). More...
 
virtual TocreadToc ()=0
 The readToc Method reads the Table-Of-Content (TOC) of an audio CD. More...
 
virtual TocreadTocFromSession (uint8_t sessionNumber)=0
 The ReadToc method reads the Table-Of-Content of an audio CD. More...
 
virtual TrackInforeadTrackInfo (uint16_t trackNumber)=0
 Returns information about a given track. More...
 
virtual TrackInfoExreadTrackInfoEx (uint16_t trackNumber)=0
 Returns extended track information. More...
 
virtual void refresh ()=0
 The refresh method forces the device to refresh the CD/DVD disc info. More...
 
virtual bool_t reserveTrack (uint32_t blocks)=0
 Reserves a track. More...
 
virtual bool_t reserveTrackLBA (uint32_t endLBA)=0
 Reserves a track by specifying the end logical block address instead of size. More...
 
virtual bool_t reset ()=0
 The method resets the device firmware. More...
 
virtual const char_t * revision () const =0
 Retrieves the revision (the version) of the device firmware as it is set by its manufacturer. More...
 
virtual const char_t * scsiAddress () const =0
 Retrieves the SCSI bus address of the device as string in the form of (Host Adapter Number:Target ID:LUN) More...
 
virtual void setBDWriteVerify (bool_t writeVerify)=0
 Sets a value indicating whether the device should do automatic verify-after-write cycle while writing data to BD media. More...
 
virtual void setCallback (DeviceCallback *callback)=0
 The setCallback method sets notification callback object. More...
 
virtual bool_t setCDTextForWriting (CDText *cdText)=0
 The setCDTextForWriting method sets up the CD-TEXT data that should be written on the CD. More...
 
virtual void setDVDWriteVerify (bool_t writeVerify)=0
 Sets a value indicating whether the device should do automatic verify-after-write cycle while writing data to DVD media. More...
 
virtual void setNewSessionStartAddress (int32_t startAddress)=0
 Sets the start address at which the new session should be written. More...
 
virtual bool_t setReadSpeedKB (int value)=0
 Sets the current read speed in Kbytes/s (1 Kbyte = 1000 bytes). More...
 
virtual void setStreaming (bool_t streaming)=0
 Sets a flag indicating whether the device will use stream recording or not. More...
 
virtual bool_t setWriteSpeedKB (int value)=0
 Sets the current write speed in Kbytes/s (1 Kbyte = 1000 bytes). More...
 
virtual bool_t startBDSession ()=0
 The startBDSession method initializes a new Blu-ray Disc session. More...
 
virtual bool_t startBDTrack (uint32_t blocks)=0
 The startBDTrack method starts a new track or continues and existing track from a Blu-ray Disc session. More...
 
virtual bool_t startCDSession (bool_t simulate, CDSession *session, WriteMethod::Enum wm=WriteMethod::Sao, bool_t closeSession=1, bool_t closeDisc=1)=0
 Starts the recording of a new CD session. More...
 
virtual bool_t startCDTrack (CDTrack *cdTrack)=0
 Starts a new CD track on a TAO or Packet session. More...
 
virtual bool_t startDVDSession (bool_t simulate, WriteMethod::Enum wm=WriteMethod::DVDIncremental, bool_t closeDisc=1)=0
 Initializes a new DVD session. More...
 
virtual bool_t startDVDTrack (uint32_t blocks)=0
 Starts a new track or continues an existing track from a DVD session. More...
 
virtual bool_t streaming () const =0
 Returns a value indicating whether the device will use stream recording or not. More...
 
virtual const char_t * systemPath () const =0
 Gets the system path that identifies the device. More...
 
virtual uint32_t unitReadyState ()=0
 The unitReadyState method returns a device SCSI sense code. More...
 
virtual void unlockOutputBuffer (uint32_t blocks)=0
 Unlocks the Device output buffer and writes the data from the buffer to the disc. More...
 
virtual void unlockOutputBufferEx (uint32_t blocks, int32_t writeAddress)=0
 The unlockOutputBufferEx method releases a locked output buffer and writes the buffer data to a given disc address on CD/DVD. More...
 
virtual const char_t * vendor () const =0
 Retrieves the device vendor name. More...
 
virtual const char_t * vendorSpecific () const =0
 Retrieves the vendor specific information of the device as it is set by its manufacturer. More...
 
virtual bool_t writeData (int32_t startLba, uint8_t *buffer, int32_t blocks, int32_t blockSize)=0
 The writeData method writes data to a CD, DVD or BD starting at the logical block address indicated by the startLba parameter. More...
 
virtual int writeSpeedKB () const =0
 Gets the current write speed in Kbytes/s (1 KByte = 1000 bytes). More...
 
virtual int writeTransferRate () const =0
 Gets the actual write transfer rate (write speed) as measured by PrimoBurner. 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

The Device interface provides methods for working with CD, DVD and Blu-ray Disc (BD) devices.

Member Function Documentation

virtual BDFeatures* bdFeatures ( )
pure virtual

Gets the Blu-ray Disc capabilities of the device.

Returns
A pointer to a BDFeatures object.
virtual bool_t bdWriteVerify ( ) const
pure virtual

Returns a value indicating whether the device will do automatic verify-after-write cycle while writing data to BD media.

Valid only for BD-R.

Returns
1 The device will perform automatic verification.
0 The device will not perform automatic verification.
See Also
Device::setBDWriteVerify
virtual double bgFormatProgress ( ) const
pure virtual

TGets the current background format progress as a percentage.

If a background format is not running the function returns 0.0. This method always returns 0.0 for DVD-RW media.

Returns
progress percentage
See Also
Device::bgFormatStatus
Device::format
virtual BgFormatStatus::Enum bgFormatStatus ( ) const
pure virtual

Gets the background format status of the mounted disc.

See the BgFormatStatus::Enum enumeration for a list of the possible return values.

Returns
A constant from the BgFormatStatus enum.
See Also
BgFormatStatus::Enum
virtual CDFeatures* cdFeatures ( )
pure virtual

Gets an object describing the CD capabilities of the device.

Returns
A pointer to a CDFeatures object.
virtual void clearOutputBuffer ( )
pure virtual

Clears the output buffer.

The buffer is filled with zeros. This method should be called when the current burn operation is about to be canceled.

virtual bool_t closeDisc ( )
pure virtual

Closes a BD-R disc.

Last session on the disc must be closed before this method can be called.

Returns
1 Success.
0 Error.
virtual bool_t closeLastSession ( )
pure virtual

The closeLastSession method closes the last open session on the disc.

Returns
1 The last open session was closed successfully.
1 If the media is blank unformatted BD-R.
0 If the media is blank unformatted BD-RE.
0 An error occurred.
virtual bool_t closeTrack ( uint16_t  trackNumber)
pure virtual

Closes a track.

Parameters
trackNumberTrack to be closed. The track number is 1 based. To close the last track pass 0 for trackNumber.
Returns
TRUE if the operation is successful, FALSE otherwise.
virtual QSubChannel* createQSubChannel ( SubChannelFormat::Enum  scf,
uint8_t *  buffer 
)
pure virtual

The createQSubChannel method returns the Q Sub-channel data from a raw audio CD block.

The function reads the sub-channel information from the last BlockSize::PWChannelSize (96) bytes of the RAW CD block passed in the buffer parameter.

Parameters
scf[in] Expected format of the sub-channel data.
buffer[in] Pointer to a buffer that contains BlockSize::CDRaw (2448) bytes of RAW CD data. Use the RawCDRead method to read CD data in RAW mode.
Returns
QSubChannel object that contains Q Sub-channel data from the raw CD block. The object must be released using the QSubChannel::release method. If the sub-channel data is invalid or missing then the method returns NULL.
See Also
Device::rawCDRead
QSubChannel
SubChannelFormat::Enum
virtual ScsiInterface* createScsiInterface ( )
pure virtual

Creates and returns a new ScsiInterface object which can be used to send SCSI commands to the underlying hardware device.

Returns
A pointer to ScsiInterface object.
virtual SpeedEnum* createWriteSpeedEnumerator ( )
pure virtual

Enumerates supported write speeds (as reported by the device) into a collection of SpeedDescriptor objects.

If the device is not capable of reporting multiple speed descriptors, this method returns a collection with one object in it that describes the maximum write speed. This method sets the last error if the device does not support speed enumeration.

Speed descriptors are sorted by transfer rate in descending order - the maximum speed descriptor will be the first item in the collection.

Returns
SpeedEnum object that contains a collection of available write speeds. The returned object must be released with the SpeedEnum::release method.
virtual TrackType::Enum detectTrackType ( int32_t  trackStartLba,
int32_t  blocksToScan = 10 
)
pure virtual

Gets the type of a CD track.

To detect the track type the method actually scans several blocks from the disc that is in the device. This method requires a valid recorded CD/DVD disc to be present in the device.

Parameters
trackStartLba[in] Logical block address of the track start.
blocksToScan[in] Number of blocks to scan (read) from the disc. This parameter has a default value of 10.
Returns
A constant from the TrackType enumeration.
virtual handle_t deviceHandle ( )
pure virtual

Call this method to get the OS handle of the underlying device object.

Returns
A OS handle to the device object.
Remarks
This handle can be passed to Engine::createDeviceFromHandle. This way it is possible to pass a Device between different processes and library versions.
virtual bool_t disableMCN ( )
pure virtual

Disables media change notifications.

This prevents Windows from sending the GUID_IO_MEDIA_ARRIVAL and GUID_IO_MEDIA_REMOVAL events to applications. This method works only on Windows XP and above.

Returns
TRUE if the operation is successful, FALSE otherwise.
See Also
enableMCN
virtual bool_t dismount ( )
pure virtual

Tries to dismount the volume in the device.

That forces the operating system to invalidate its cache and to refresh the file system information.

Returns
1 Success.
0 Failure.
virtual char driveLetter ( ) const
pure virtual

The driveLetter method retrieves the drive letter of the device.

Returns
The letter of the device drive
virtual DVDFeatures* dvdFeatures ( )
pure virtual

Gets the DVD capabilities of the device.

Returns
A pointer to a DVDFeatures object.
virtual bool_t dvdWriteVerify ( ) const
pure virtual

Returns a value indicating whether the device will do automatic verify-after-write procedure while writing data to DVD media.

Valid only for DVD-RAM.

Returns
1 The device will perform automatic verification.
0 The device will not perform automatic verification.
See Also
Device::setDVDWriteVerify
virtual bool_t eject ( bool_t  eject,
bool_t  unlockMedium = 1 
)
pure virtual

The eject method unlocks and ejects the tray of the device, if possible.

Parameters
ejectIndicates whether to eject the tray of device. If this parameter is TRUE, the media is ejected. If this parameter is FALSE the device tray is closed. If the tray has been locked it will be unlocked and then ejected.
unlockMediumIndicates that the medium must be ejected even if the device tray is locked.
Returns
1 The call to eject the tray succeeded. It is unknown whether the tray actually ejected.
0 The device does not support the eject command.
virtual bool_t enableMCN ( )
pure virtual

Enables media change notifications.

This method works only on Windows XP and above.

Returns
TRUE if the operation is successful, FALSE otherwise.
See Also
disableMCN
virtual bool_t endBDSession ( bool_t  closeSession = 1,
bool_t  closeDisc = 0 
)
pure virtual

The endBDSession method finishes a Blu-ray Disc session that has been previously started with the startBDSession method.

Parameters
closeSessionIndicates that the session should be closed. This parameter is ignored if closeDisc is set to TRUE.
closeDiscIndicates that the disc should be closed.
Returns
1 Success.
0 Error.

Notes:

closeSession and closeDisc parameters are ignored when using BD-RE media.

See Also
startBDSession
virtual bool_t endBDTrack ( bool_t  closeTrack = 1)
pure virtual

The endBDTrack completes a Blu-ray Disc track.

Parameters
closeTrackIndicates whether the track should be closed.
Returns
1 Success.
0 Error.
virtual bool_t endCDSession ( )
pure virtual

Finishes a CD session which has been previously started with the startCDSession method.

Returns
1 The session has been closed successfully.
0 The session has not been closed successfully.
See Also
startCDSession
virtual bool_t endCDTrack ( bool_t  closeTrack = 1)
pure virtual

Ends a CD track.

Parameters
closeTrackIndicates whether the track should be closed. This parameter must be set to TRUE if a write method different than WriteMethod::Packet is used. In Packet mode the application may leave the track open to allow recording of data at the end of the track at a later time.
Returns
TRUE if the operation is successful, FALSE otherwise.
virtual bool_t endDVDSession ( bool_t  close = 1)
pure virtual

The endDVDSession method finishes a DVD session that has been previously started with the startDVDSession method.

Parameters
closeSpecifies whether to close the session. It is ignored when the media profile is DVD-R DL for sequential recording.
Remarks
The session is always closed when Disc-At-Once recording is performed regardless of the value of the close parameter.
Returns
1 The session has been closed successfully.
0 The session has not been closed successfully.

Notes:

Multi-session (a.k.a. multi-border) recording is not defined for DVD-R DL incremental recording because the session lead out (a.k.a. Border Out) cannot be written in the middle of the disc on just one of the layers.

On DVD-R DL, multi-session recording is possible only when the disc is recorded using the layer jump method.

See Also
Device::startDVDSession
virtual bool_t endDVDTrack ( bool_t  close = 1)
pure virtual

The endDVDTrack completes a DVD fragment (track).

Parameters
closeIndicates whether the track should be closed. If the Incremental (WriteMethod::DVDIncremental) method is used the application may leave the track open to allow recording of data at the end of the track at a later time by setting this parameter value to FALSE. This parameter must be set to TRUE if the Disc-At-Once (WriteMethod::DVDDao) write method is used. This parameter must be set to TRUE if the Device::startDVDSession method was previously called with closeDisc parameter set to TRUE.
Returns
TRUE if the operation is successful, FALSE otherwise.

Device::startDVDTrack

virtual bool_t erase ( bool_t  quick = 1)
pure virtual

Attempts to erase a RW disc.

Both full and quick erasing is supported.

Parameters
quickIf TRUE, a quick erase is performed; If FALSE, a full erase is performed.
Returns
1 The media in the recorder has been erased successfully.
0 The erase operation failed for some reason.
virtual bool_t eraseEx ( EraseType::Enum  eraseType)
pure virtual

The erase method attempts to erase the media.

Both full and quick erases are supported. This method reports progress through the DeviceCallback interface.

NOTE: DVD-RW Restricted Overwrite media

Parameters
eraseTypeIndicates the erase type.
Returns
1 The media in the recorder has been erased successfully.
0 The erase operation failed for some reason.
See Also
isMediaRewritable
EraseType::Enum
virtual const ErrorInfo* error ( ) const
pure virtual

Gets error information about the last operation.

Returns
A pointer to an ErrorInfo object.
virtual bool_t flush ( )
pure virtual

Flushes the device internal cache buffer.

Returns
TRUE if the operation is successful, FALSE otherwise.
virtual bool_t format ( FormatType::Enum  formatType,
uint32_t  blocks = 0,
bool_t  waitForBackground = 0 
)
pure virtual

The Format method formats a re-writable DVD media.

Depending on the media profile different formatting can be performed. See the FormatType::Enum enumeration for details about all the format types. See the MediaProfile enumeration for details about all media types.

NOTES:

DVD+RW: the format has two phases - "foreground" and "background". The foreground format is very short and is executed synchronously. After the foreground format is completed the background format continues until the whole DVD+RW disc is fully formatted. During the background format the DVD/CD writing is possible on the part of the disc that has been formatted.

DVD-RW: when used with FormatType::DVDMinusRWQuick you can set blocks to 0 to make it a really quick format.

Parameters
formatType[in] The type of the format that should be performed.
blocks[in] The number of blocks(sectors) that should be formatted. This parameter is ignored for DVD+RW media (i.e. if formatType parameter is FormatType::DVDPlusRWFull, FormatType::DVDPlusRWRestart or FormatType::DVDPlusRWStop).
waitForBackground[in] Use this parameter to block in the format method until the background format is completed. This parameter is ignored if the format type is other than FormatType::DVDPlusRWFull and FormatType::DVDPlusRWRestart. The default value of this parameter is FALSE.

When waitForBackground is set to TRUE the Format method will wait until the background format is completed and will use the DeviceCallback::onFormatProgress method to report the format progress.

Returns
TRUE if the operation is successful, FALSE otherwise.
See Also
Device::bgFormatProgress
Device::bgFormatStatus
FormatType::Enum
virtual bool_t formatBD ( BDFormatType::Enum  type,
BDFormatSubType::Enum  subType,
const BDFormatParameters formatParameters = NULL 
)
pure virtual

The formatBD method formats BD-R SRM or BD-RE media.

Depending on the media profile different formatting are available. See the BDFormatType::Enum and BDFormatSubType::Enum for details about the available BD formatting options.

Parameters
typeThe type of the format that should be performed.
subTypeThe format sub type. The value of this parameter depends on the value of the type parameter.
formatParametersShould be set to NULL.
Returns
1 Success.
0 Error.
See Also
BDFormatType::Enum
BDFormatSubType::Enum
virtual int internalCacheCapacity ( ) const
pure virtual

The internalCacheCapacity method retrieves the capacity of the device cache buffer in bytes.

The internal cache is a memory cache built in the CD-ROM device. Most modern devices have between 2 and 8 MB of RAM for cache.

Returns
number of bytes
See Also
internalCacheUsedSpace
virtual int internalCacheUsedSpace ( )
pure virtual

The internalCacheUsedSpace method retrieves the number of bytes used in the internal cache of the device.

The internal cache is a memory cache built in the CD-ROM device. Most of the modern devices use from 2 to 16MB of RAM for cache. The internalCacheUsedSpace method should be called only during burning.

Returns
number of bytes
 @see internalCacheCapacity
virtual bool_t isMediaBD ( ) const
pure virtual

Indicates that the media in the device is BD-R or BD-RE.

Returns
1 - Media is BD.
0 - Media is DVD or CD.
virtual bool_t isMediaBlank ( ) const
pure virtual

Indicates that the media in the device is blank.

NOTE: Formatted DVD-RAM, DVD+RW, and Restricted Overwrite DVD-RW are not blank.

Returns
1 if the media in the device is blank
0 if the media in the device is not blank
virtual bool_t isMediaCD ( ) const
pure virtual

Indicates that the media in the device is CD-ROM, CD-R or CD-RW.

Returns
1 - Media is CD.
0 - Media is DVD or BD.
virtual bool_t isMediaDVD ( ) const
pure virtual

The isMediaDVD method indicates whether the medium in the device is DVD-ROM, DVD-RAM, DVD-R/RW or DVD+R/RW.

Returns
1 - the media is a DVD.
0 - the media is a CD.
virtual bool_t isMediaFormatted ( ) const
pure virtual

Indicates whether the media in the device is formatted.

NOTES:

DVD-RW for Restricted Overwrite: returns 1 only when the DVD-RW disc is fully formatted.

DVD+RW: returns 1 only when the DVD+RW disc is fully formatted.

Returns
1 The media in the device is a fully formatted disc.
0 The media in the device is blank unformatted disc, or the media is partially formatted or a background format is currently pending.
virtual bool_t isMediaRewritable ( ) const
pure virtual

Indicates whether the media in the device is re-writable.

Returns
1 if the media in the device is re-writable
0 if the media in the device is not re-writable
virtual bool_t lockMedia ( bool_t  bLock)
pure virtual

The lockMedia method enables or disables the manual removal of the medium in the device.

Parameters
bLock[in] Indicates whether the device tray mechanism can be opened /closed by the device operator. Set this parameter to TRUE or FALSE to prevent or allow manual ejecting of the media respectively.
Returns
1 Media was locked/unlocked successfully.
0 An error occurred.
virtual bool_t lockOutputBuffer ( uint32_t  blocks,
uint8_t **  buffer1,
uint32_t *  buffer1Blocks,
uint8_t **  buffer2,
uint32_t *  buffer2Blocks 
)
pure virtual

Locks a portion of the Device output buffer for writing.

Parameters
blocksDesired portion of the output buffer to be locked. Note that the output buffer is conceptually circular. The number of blocks requested with this parameter should be aligned on track boundaries.
buffer1Address of a variable to receive a pointer to the first locked portion of the output buffer.
buffer1BlocksAddress of a variable to receive the size of the buffer1 buffer. If this value is less than the blocks parameter, buffer2 points to a second portion of the output buffer.
buffer2Address of a variable to receive a pointer to the second locked portion of the output buffer. If this value is NULL, buffer1 points to the entire locked portion of the output buffer.
buffer2BlocksAddress of a variable to receive the size of the buffer2 buffer. If buffer2 is NULL, this value will be 0.
Returns
1 Success
0 Could not lock a portion with size specified with the blocks parameter. This may happen when the blocks requested are too many.
See Also
unlockOutputBuffer
clearOutputBuffer
virtual bool_t lockOutputBufferEx ( uint32_t  blocks,
uint8_t **  buffer1,
uint32_t *  buffer1Blocks,
uint8_t **  buffer2,
uint32_t *  buffer2Blocks,
uint32_t *  blockSize 
)
pure virtual

Locks a portion of the Device output buffer for writing.

Parameters
blocksDesired portion of the output buffer to be locked. Note that the output buffer is conceptually circular. The number of blocks requested with this parameter should be aligned on track boundaries.
buffer1Address of a variable to receive a pointer to the first locked portion of the output buffer.
buffer1BlocksAddress of a variable to receive the size of the buffer1 buffer. If this value is less than blocks, buffer2 points to a second portion of the output buffer.
buffer2Address of a variable to receive a pointer to the second locked portion of the output buffer. If this value is NULL, buffer1 points to the entire locked portion of the output buffer.
buffer2BlocksAddress of a variable to receive the size of the buffer2 buffer. If buffer2 is NULL, this value will be 0.
blockSizeAddress of a variable to receive the current block size. If blockSize is NULL this method works as lockOutputBuffer.
Returns
TRUE if the operation is successful, FALSE otherwise.
virtual int maxReadSpeedKB ( ) const
pure virtual

Gets the maximum read speed supported by the device in Kbytes/s (1 Kbyte = 1000 bytes).

To get the speed relative to 1x divide the result to Speed1xKB::CD for CD, Speed1xKB::DVD for DVD and Speed1xKB::BD for BD.

Returns
Kilobytes per second
virtual int maxWriteSpeedKB ( ) const
pure virtual

Gets the maximum write speed supported by the device in Kbytes/s (1 Kbyte = 1000 bytes).

To get the speed relative to 1x divide the result to Speed1xKB::CD for CD, Speed1xKB::DVD for DVD and Speed1xKB::BD for BD.

Returns
Kilobytes per second
virtual uint32_t mediaCapacity ( ) const
pure virtual

Gets the capacity of the disc in the device.

The capacity is returned in blocks. The actual byte capacity depends on the block size that will be used during the burning. If the disc in the device is closed, the reported capacity may differ from the size of a blank disc.

To determine whether there is disc space available for writing use the mediaFreeSpace method.

NOTE: If the media is unformatted BD-RE and DVD+RW, this method returns the blank disc capacity.

Returns
number of blocks
virtual uint32_t mediaFreeSpace ( ) const
pure virtual

Gets the number of blocks available for writing.

NOTE: For formatted DVD+RW and BD-RE media all disc space is reported as free (available) regardless of what is recorded on the disc. That is because once formatted the DVD+RW and BD-RE discs become unrestricted-overwrite random-writable media.

For DVD-RW in Restricted Overwrite mode (a.k.a. DVD-RW RO) the reported value is the number of blocks that have not been formatted. If the disc is fully formatted DVD-RW the reported free space is 0. However, the disc can still be written to.

See Also
newSessionStartAddress
Returns
number of blocks
virtual uint32_t mediaLayerCapacity ( ) const
pure virtual

Gets the layer 0 (L0) capacity, in blocks, of DVD-R DL and DVD+R DL media.

Returns 0 for all other media types.

Returns
capacity in blocks
virtual primo::burner::MediaProfile::Enum mediaProfile ( ) const
pure virtual

The mediaProfile method returns the type of the media currently inserted in the device.

See the MediaProfile::Enum enumeration for details about all media types. This method works only if there is a disc in the device.

Returns
The type of the media in the device.
See Also
primo::burner::MediaProfile::Enum
virtual primo::burner::MediaReady::Enum mediaState ( ) const
pure virtual

The mediaState method checks whether there is medium inserted in the device.

Returns
A constant from the MediaReady enumeration.
See Also
MediaReady::Enum
virtual int32_t newSessionStartAddress ( ) const
pure virtual

Gets the start address of the new disc session.

This method makes sense only if there is free space available on the disc. To check if there is any free space on the disc use the mediaFreeSpace method.

If the last session is open (incomplete) this method returns the start address of the incomplete session.

DVD special cases: On DVD+RW disc, all space is available for writing. The newSessionStartAddress and newTrackStartAddress methods always return 0 for DVD+RW media. For DVD-RW which has been formatted for restricted overwrite (i.e. DVD-RW RO) newSessionStartAddress and newTrackStartAddress methods return 0.

Returns
LBA
See Also
DataDisc::setSessionStartAddress
mediaFreeSpace
virtual int32_t newTrackStartAddress ( ) const
pure virtual

Get the start address of the next disc track.

Calling this method makes sense only when there is some free space on the disc and when the last session on the disc is not complete (has been left open). To check if there is any free space on the disc call the mediaFreeSpace method. Use the DiscInfo method to see if the last session on the disc is incomplete.

If the last track in the last session is open (incomplete) this method returns the start address of the last incomplete track + the number of sectors recorded from the incomplete track.

DVD special cases: On DVD+RW disc, all space is available for writing. The newSessionStartAddress and newTrackStartAddress methods always return 0 for DVD+RW media. For DVD-RW which has been formatted for restricted overwrite (i.e. DVD-RW RO) newSessionStartAddress and newTrackStartAddress methods return 0.

Returns
LBA
See Also
DataDisc::setSessionStartAddress
virtual const char_t* productId ( ) const
pure virtual

Retrieves the the product id (the model) of the device as it is set by its manufacturer.

Returns
A null-terminated string.
virtual bool_t rawCDRead ( int32_t  startLba,
SubChannelFormat::Enum  scf,
uint32_t  blockSize,
void *  buffer,
uint32_t  numberOfBlocksToRead,
uint32_t *  numberOfBlocksRead 
)
pure virtual

Reads raw data from a CD.

Parameters
startLba[in] The logical block address from which the reading should start
scf[in] The expected format of the sub-channel data. The sub-channel data occupies the last BlockSize::PWChannelSize (96) bytes from a RAW CD block. The size of a RAW CD block is BlockSize::CDRaw (2448) bytes.
blockSize[in] The size of a raw block. This parameter should be set to BlockSize::CDDA if the selected sub-channel data format is SUBFMT_NONE and to BlockSize::CDRaw if the selected channel is set to SubChannelFormat::PWRaw or SubChannelFormat::PWDeinterleaved.
buffer[out] Pointer to the buffer that receives the data read from the disc.
numberOfBlocksToRead[in] Number of blocks to read.
numberOfBlocksRead[out] Pointer to the variable that receives the number of blocks read. RawCDRead sets this value to zero before doing any work or error checking.
Returns
1 Success.
0 Reading failed.
virtual bool_t readAudio ( TrackBuffer trackBuffer,
int32_t  startBlock,
int32_t  blocks = primo::burner::BufferSize::DefaultReadBufferBlocks 
)
pure virtual

The readAudio method reads audio data from an Audio CD the media.

Parameters
trackBuffer[out] Pointer to a buffer allocated with a call to Library::createTrackBuffer.
startBlockThe first block to be read from the CD.
blocksThe number of blocks to be read starting from the startBlock. The default argument guarantees that reading audio blocks will not fail on USB devices and also corresponds with the default capacity of the TrackBuffer created by calling Library::createTrackBuffer.
Returns
TRUE if the operation is successful, FALSE otherwise.
See Also
TrackBuffer
Library::createTrackBuffer
BufferSize::DefaultReadBufferBlocks
virtual CDSession* readCDSessionLayout ( uint8_t  sessionNumber,
bool_t  scanTracks = 1,
bool_t  fastScan = 1,
int32_t  fastScanBlocks = 600 
)
pure virtual

Extracts an CDSession object from a CD session.

Creates an CDSession object with the track and index information of the extracted session (also known as Cue Sheet information).

This method scans the entire CD session and reads the pre-gap and track index information from the sub-channel data.

If a callback object is set with the SetCallback method, the readCDSessionLayout will report the current position and progress.

Parameters
sessionNumber[in] The number of the session that should be scanned for index information. To obtain information about the disc sessions use the readSessionInfo method of the Device interface.
scanTracks[in] Indicates that the tracks should be scanned for UPC/EAN, ISRC, indexes, FORM1/FORM2 and MODE0/MODE1/MODE2 changes. The default value for this parameter is TRUE.
fastScan[in] Indicates that a fast scan should be performed. This parameter has no meaning if scan is set to FALSE. The default value for this parameter is TRUE.
fastScanBlocks[in] Number of blocks to scan from each track when scanning for ISRC and MCN information. This parameter has no meaning if fastScan is set to FALSE. The default value for this parameter is 600 blocks.
Returns
A pointer to return an CDSession object. You must call the CDSession::release method to free the returned object once it is not needed anymore. If the method returns NULL the session layout could not be retrieved, check Device::error for the actual reason.
virtual CDText* readCDText ( )
pure virtual

The readCDText method reads the CD-TEXT data from the media.

Returns
An instance of a CDText object. The calling application is responsible to free the CDText instance by calling CDText::release(). The method returns NULL if the CD-Text cannot be retrieved (use Device::error() method to check to reason).
See Also
CDText
virtual bool_t readData ( TrackBuffer trackBuffer,
int32_t  startBlock,
int32_t  blocks = primo::burner::BufferSize::DefaultReadBufferBlocks 
)
pure virtual

The readData Method reads data from the media.

The data is read in blocks. The logical block address from which the reading should be done, the number of blocks to be read and the block size should be set in buffer structure which pTrackBuffer points to.

Parameters
trackBuffer[out] Pointer to a buffer allocated with a call to Library::createTrackBuffer.
startBlockThe first block to be read from the Disc.
blocksThe number of blocks to be read starting from the startBlock. The default argument guarantees that reading on USB devices and also corresponds with the default capacity of the TrackBuffer created by calling Library::createTrackBuffer.
Returns
TRUE if the operation is successful, FALSE otherwise.
See Also
TrackBuffer
Library::createTrackBuffer
BufferSize::DefaultReadBufferBlocks
virtual DiscInfo* readDiscInfo ( )
pure virtual

Reads information about the disc.

This method works even when the last session on the disc is empty or incomplete.

Returns
A pointer to a DiscInfo structure that contains the disc information. The object must be released using the DiscInfo::release method. If the method returns NULL the disc information could not be retrieved, check the result of Device::lastError method for the actual reason.
See Also
DiscInfo
virtual MediaInfo* readMediaInfo ( )
pure virtual

Creates an objects that provides extended media information.

Returns
A pointer to a MediaInfo object. The object must be released using the release method.
virtual RawToc* readRawToc ( )
pure virtual

Reads the Full Table-Of-Content in raw format.

This method returns all Q sub-code data in the Lead-In (TOC) area. For multi-session discs, the TOC data for all sessions is returned.

Returns
A pointer to a RawToc instance that describes the raw Table-Of-Content. The object must be released using the RawToc::release method. If the method returns NULL the disc information could not be retrieved, check the result of Device::lastError method for the actual reason.
See Also
RawToc
RawTocTrack
virtual SessionInfo* readSessionInfo ( )
pure virtual

Returns information about the disc sessions.

This method reports only the complete sessions. If the last session on the disc is in an incomplete state, the session will be ignored. The method will fail if there is only one session on the disc and it is in an incomplete state.

Returns
A pointer to a SessionInfo instance contains details about the disc sessions. The object must be released using the SessionInfo::release method. If the method returns NULL the details could not be retrieved, check the result of Device::lastError method for the actual reason.
See Also
SessionInfo
virtual int readSpeedKB ( ) const
pure virtual

Gets the current read speed in Kbytes/s (1 KByte = 1000 bytes).

To get the speed relative to 1x divide the result to Speed1xKB::CD for CD, Speed1xKB::DVD for DVD and Speed1xKB::BD for BD.

Returns
Kilobytes per second
virtual Toc* readToc ( )
pure virtual

The readToc Method reads the Table-Of-Content (TOC) of an audio CD.

For multi-session discs, this command returns the TOC data for all complete sessions. This method reports only the tracks from the complete sessions. The track with index = AAh contains the start of the lead-out area of the last complete session on the disc. If the last session on the disc is incomplete that session is ignored. The method will fail if there is only one session on the disc and it is an incomplete one.

Returns
A pointer to a Toc instance that describes the Table-Of-Content. The object must be released using the Toc::release method. If the method returns NULL the TOC information could not be retrieved, check the result of Device::lastError method for the actual reason.
See Also
Toc
TocTrack
virtual Toc* readTocFromSession ( uint8_t  sessionNumber)
pure virtual

The ReadToc method reads the Table-Of-Content of an audio CD.

For multi-session discs, this command returns the TOC data for all sessions. The track with index = AAh contains the start of the lead-out area of the last complete session on the disc. This method reports only the tracks from the complete sessions. If the last session on the disc is incomplete that session is ignored. The method will fail if there is only one session on the disc and it is an incomplete one.

Parameters
sessionNumberspecifies the session number for which the data is returned. If this value is set to zero, the Table of Contents data will begin with the first track on the disc.
Returns
A pointer to a Toc instance that describes the Table-Of-Content. The object must be released using the Toc::release method. If the method returns NULL the TOC information could not be retrieved, check the result of Device::lastError method for the actual reason.
See Also
Toc
TocTrack
virtual TrackInfo* readTrackInfo ( uint16_t  trackNumber)
pure virtual

Returns information about a given track.

This methods works for any track present on the disc including the tracks that have not been closed and the tracks which are in open sessions.

Parameters
trackNumberThe number of the track to return information for. The value of this parameter should be a number between 1 and 99 for CD media.
Returns
A TrackInfo object that contains the requested track information. The returned object must be released with the TrackInfo::release method. If the method returns NULL then the information for the specified track could not be retrieved, check the result of Device::lastError method for the actual reason.
See Also
TrackInfo
virtual TrackInfoEx* readTrackInfoEx ( uint16_t  trackNumber)
pure virtual

Returns extended track information.

This methods works for any track present on disc including the tracks that have not been closed and the tracks which are in open sessions.

Parameters
trackNumberThe number of the track to return information for. The value of this parameter should be a number between 1 and 99 for CD media.
Returns
A pointer to a TrackInfoEx object that contains the track information. The returned object must be released with the TrackInfoEx::release method. If the method returns NULL then the information for the specified track could not be retrieved, check the result of Device::lastError method for the actual reason.
See Also
TrackInfoEx
virtual void refresh ( )
pure virtual

The refresh method forces the device to refresh the CD/DVD disc info.

Call this method right after the tray has been closed to refresh the disc status information.

virtual bool_t reserveTrack ( uint32_t  blocks)
pure virtual

Reserves a track.

For CD the track size must be 300 blocks or more. Use after startCDSession/startDVDSession

Parameters
blocksThe size in blocks of the reserved track.
Returns
TRUE if the operation is successful, FALSE otherwise.
virtual bool_t reserveTrackLBA ( uint32_t  endLBA)
pure virtual

Reserves a track by specifying the end logical block address instead of size.

For CD the LBA must be such that the size of the reserved track to be 300 or more. Use after startCDSession/startDVDSession

Parameters
endLBAThe end logical block address to use.
Returns
TRUE if the operation is successful, FALSE otherwise.
virtual bool_t reset ( )
pure virtual

The method resets the device firmware.

Use this method to reset the device when a writing operation failed.

Returns
TRUE if the operation is successful, FALSE otherwise.
virtual const char_t* revision ( ) const
pure virtual

Retrieves the revision (the version) of the device firmware as it is set by its manufacturer.

Returns
A null-terminated string.
virtual const char_t* scsiAddress ( ) const
pure virtual

Retrieves the SCSI bus address of the device as string in the form of (Host Adapter Number:Target ID:LUN)

Host Adapter Number - This field specifies which installed host adapter the request is intended for. Host adapter numbers are assigned by the SCSI manager layer, beginning with 0.

Target ID - This field indicates the SCSI ID of the target device.

LUN - This field indicates the Logical Unit Number (LUN) of the device.

Returns
A null-terminated string.
virtual void setBDWriteVerify ( bool_t  writeVerify)
pure virtual

Sets a value indicating whether the device should do automatic verify-after-write cycle while writing data to BD media.

Valid only for BD media. Calling this method has no effect if the media in the device is not a Blu-ray Disc. The default value is FALSE.

Parameters
writeVerify[in] Set to TRUE to enable automatic verification after write, otherwise set to FALSE
See Also
Device::bdWriteVerify
virtual void setCallback ( DeviceCallback callback)
pure virtual

The setCallback method sets notification callback object.

Parameters
callbackA pointer to an object that implements DeviceCallback interface.

Internally the DeviceCallback specified by setCallback is retained (if not NULL). The previous DeviceCallback is released (if not NULL). The DeviceCallback instance is released when the Device itself is being destroyed.

NOTE: If the user code inherits from DeviceCallback but does not override primo::Reference::release() and primo::Reference::retain() it must ensure that the callback instance is valid until it is used by the device. This is so because the default implementation of primo::Reference in DeviceCallback keeps a constant reference count of 1.

virtual bool_t setCDTextForWriting ( CDText cdText)
pure virtual

The setCDTextForWriting method sets up the CD-TEXT data that should be written on the CD.

This method must be called before the startCDSession method.

CD-TEXT data is encoded in the lead in area of the CD. CD_TEXT is not supported in TAO, RAW DAO and RAW SAO modes.

Parameters
cdTextPointer to a CDText instance. Set this parameter to NULL if you do not want any CD-TEXT to be written on the CD.
Returns
1 The write has been successfully done
0 There was an error
See Also
CDText
pb_create_cd_text
virtual void setDVDWriteVerify ( bool_t  writeVerify)
pure virtual

Sets a value indicating whether the device should do automatic verify-after-write cycle while writing data to DVD media.

Valid only for DVD-RAM. Calling this method has no effect if the media in the device is not DVD-RAM. The default value is FALSE.

Parameters
writeVerify[in] Set to TRUE to enable automatic verification after write, otherwise set to FALSE
See Also
Device::dvdWriteVerify
virtual void setNewSessionStartAddress ( int32_t  startAddress)
pure virtual

Sets the start address at which the new session should be written.

The start address should be set before calling startDVDSession or startDVDTrack methods.

This method should be used for random writable media like formatted DVD+RW, formatted DVD-RW or DVD-RAM, and formatted BD-RE media. For all other media types the engine determines and uses the correct start address internally.

For DVD+RW, DVD-RAM and BD-RE the calling application should set the start address because there is no other way to know what part of the media is written and what part is available.

On DVD+RW, DVD-RW RO, DVD-RAM and BD-RE the disc space is managed on a higher level by the file system used for the DVD disc, such as UDF, Joliet or ISO.

Parameters
startAddressThe start address of the new session in blocks.
See Also
newSessionStartAddress
DataDisc::setSessionStartAddress
virtual bool_t setReadSpeedKB ( int  value)
pure virtual

Sets the current read speed in Kbytes/s (1 Kbyte = 1000 bytes).

Parameters
valueKilobytes per second
Returns
TRUE if the operation is successful, FALSE otherwise.
virtual void setStreaming ( bool_t  streaming)
pure virtual

Sets a flag indicating whether the device will use stream recording or not.

Valid only for BD media. Calling this method has no effect if the media in the device is not a Blu-ray Disc. The default value is FALSE.

Parameters
streaming[in] Set to TRUE to use stream recording, otherwise set to FALSE.
See Also
Device::streaming
virtual bool_t setWriteSpeedKB ( int  value)
pure virtual

Sets the current write speed in Kbytes/s (1 Kbyte = 1000 bytes).

Parameters
valueKilobytes per second
Returns
TRUE if the operation is successful, FALSE otherwise.
virtual bool_t startBDSession ( )
pure virtual

The startBDSession method initializes a new Blu-ray Disc session.

Returns
1 Success.
0 Error.
See Also
endBDSession
virtual bool_t startBDTrack ( uint32_t  blocks)
pure virtual

The startBDTrack method starts a new track or continues and existing track from a Blu-ray Disc session.

This method should be called after the startBDSession method and before the endBDTrack method.

Parameters
blocksNumber of Blu-ray Disc blocks to be added to the track. The size of one Blu-ray Disc block is 2048 bytes. An open track may consume all remaining available blocks on the disc.
Returns
1 The track has been opened successfully.
0 There was an error.
See Also
endBDTrack
startBDSession
virtual bool_t startCDSession ( bool_t  simulate,
CDSession session,
WriteMethod::Enum  wm = WriteMethod::Sao,
bool_t  closeSession = 1,
bool_t  closeDisc = 1 
)
pure virtual

Starts the recording of a new CD session.

The following rules apply to the CDSession definition depending on the selected write method:

WriteMethod::Sao, WriteMethod::FullRawDao, WriteMethod::RawDao2352 and WriteMethod::RawDao: pSession determines the type and the structure of the session and should contain valid ICDTrack items for all tracks in the session.

WriteMethod::Tao and WriteMethod::Packet: pSession determines the type of the session only and should not contain any CDTrack items. Parameters of each track are additionally specified when a new track is initiated using the startCDTrack method.

Parameters
simulate[in] Indicates whether a simulated burn should be performed. The simulation is a good test of a device, because most of the operations are performed as in a real burn. If this parameter is TRUE, the burn is simulated and nothing is burned on the CD. If this parameter is set to FALSE the burn is real. On CD-R/RW media simulation is possible only for Track-At-Once or Session-At-Once recording.
session[in] CDSession instance that contains the session definition. CDSession is used to create a Table-Of-Content (TOC) record on the CD and to drive the burning process. As of Version 1.20 CDSession determines also the type of the session (e.g. like Audio, Data, CD-XA, RAW) and the mode of each track (by using the CDTrack::type method).
wm[in] Determines the write method that should be used while burning a CD session. See the WriteMethod::Enum enumeration for a list of the possible write methods.
closeSession[in] Indicates whether the session should be closed. Set to FALSE to leave the session open and to allow additional tracks to be added to the session at a later time. This parameter is ignored when the write method is WriteMethod::Sao. The session is always closed when any of the SAO write methods are used. This parameter is ignored if WriteMethod::FullRawDAO or WriteMethod::RawDao2352 methods are used.
closeDisc[in] Indicates whether the CD should be closed. Set this parameter to FALSE to allow additional sessions to be added at later time to the disc. This parameter is ignored if there is raw B0 point set in the session and the write method is set to WriteMethod::FullRawDao and in WriteMethod::RawDao2352.
Returns
1 The session has been opened successfully.
0 The session has not been opened successfully.
See Also
endCDSession
virtual bool_t startCDTrack ( CDTrack cdTrack)
pure virtual

Starts a new CD track on a TAO or Packet session.

This method does nothing if the write mode is different than WriteMethod::Tao or WriteMethod::Packet.

Parameters
cdTrack[in] A CD track object. The track will be added to the session passed with the startCDSession method.

The following limitations apply to cdTrack:

1) Track type cannot be TrackType::ModeRaw, when in startCDSession, the write method has been set to WriteMethod::Tao.

2) Track type cannot be TrackType::ModeRaw or TrackType::Audio, when in startCDSession, the write method has been set to WriteMethod::Packet.

3) No pre-gap or post-gap should be defined.

4) The track start should be 0.

5) The track end should be the length of the track in blocks.

Returns
TRUE if the operation is successful, FALSE otherwise.
virtual bool_t startDVDSession ( bool_t  simulate,
WriteMethod::Enum  wm = WriteMethod::DVDIncremental,
bool_t  closeDisc = 1 
)
pure virtual

Initializes a new DVD session.

Parameters
simulate[in] Indicates whether a simulated burn should be performed. The simulation is a good test of a device, because most of the operations are performed as in a real burn. If this parameter is TRUE, the burn is simulated and nothing is burned on the DVD. If this parameter is set to FALSE the burn is real. On DVD-R/DVD-RW media, simulation is possible only for Incremental or Disc-At-Once recording.
wm[in] Determines the write method that should be used while burning a DVD session. The valid write methods for DVD are: Incremental (WriteMethod::DVDIncre4mental) and Disc-At-Once (WriteMethod::DVDDao).

The WriteMethod::DVDIncremental method works with all DVD profiles. The burning is done in sessions and fragments (tracks) with one exception for DVD+RW media: DVD+RW disc needs to be formatted before any burning could be done and once formatted the disc contains one session and one track and the whole track could be written and rewritten randomly with no overwrite restrictions.

With WriteMethod::DVDDao the disc will contain one session with one track. No sessions could be added after the burning is completed. The WriteMethod::DVDDao can be used only with DVD-RW formatted for sequential writing and DVD-R media. It is recommended to use the WriteMethod::DVDDao and DVD-R media to burn DVD movies to ensure best compatibility with the consumer DVD players.

Parameters
closeDisc[in] Indicates whether the DVD disc should be closed. Set this parameter to FALSE to allow additional sessions to be added at later time to the disc. When burning DVD-Video always set closeDisc to TRUE to ensure best compatibility with all consumer DVD players. The closeDisc parameter is ignored on DVD-R when the Write Method is set to WriteMethod::DVDDao, the disc is always closed and a lead-out is written.
Returns
1 The session has been opened successfully.
0 There was an error.

Media Specific Details

DVD-R and DVD+R

It is possible to use both Disc-At-Once (WriteMethod::DVDDao) and Incremental (WriteMethod::DVDIncremental) methods with DVD-R. WriteMethod::DVDDao cannot be used with DVD+R media.

When using the WriteMethod::DVDIncremental the multi-session structure of the disc is similar to the one of the CD - you can have several sessions with multiple tracks in each session.

DVD-RW

It is possible to use both Disc-At-Once (WriteMethod::DVDDao) and Incremental (WriteMethod::DVDIncremental) methods with DVD-RW.

DVD-RW can be configured as sequential recording media or a restricted overwrite media. By default a new blank DVD-RW comes configured for sequential recording.

If a DVD-RW disc is formatted it becomes a Restricted Overwrite media and can only be written with the Incremental (WriteMethod::DVDIncremental) method. The Disc-At-Once (WriteMethod::DVDDao) method cannot be used on restricted overwrite media. Fully blanking a DVD-RW will make it a sequential and formatting it a restricted overwrite disc. Use the Device::format method to format a DVD-RW and eraseEx to erase/blank it.

When DVD-RW Restricted Overwrite media is burned using the WriteMethod::DVDIncremental method multiple sessions are possible but each session contains only one track and new data is added to the same track until the session is closed.

When DVD-RW Sequential media is burned using the WriteMethod::DVDIncremental method the sessions can have one or more tracks.

DVD+RW

Only Incremental (WriteMethod::DVDIncremental) method can be used with DVD+RW media. There is no multi-session in a traditional sense. The applications could write anywhere on the disc as long as it is formatted.

Notes:

The DVD-R specification describes entities called Lead-in, Lead-out, Border-in and Border-out. DVD- R always has zero or one Lead-in and zero or one Lead-out. The Lead-in, if recorded, is always at the beginning of the disc and the Lead-out, if recorded, is always at the end of the disc. No data can be recorded beyond the Lead-out. The information recording area is a collection of Lead-in/Border-in, Bordered Areas, and Border-out/Lead-out. The bordered area, when written, is called a complete session.

If only a Border-in and Border-out are to be written (after incrementally recording data), the calling application should set the closeDisc parameter to FALSE. If set to FALSE, and insufficient space exists on the medium for another Border, the device will permanently close the medium by recording a Lead-out.

To be consistent with the sessions and tracks concept, in PrimoBurner SDK, the standard Multi-session is used instead of Multi-Border, incomplete session is used instead of incomplete Border and complete session is used instead of complete Border for DVD-R devices.

DVD media is 2KB addressable but the actual writing is done using 32KB packets. The PrimoBurner and the device itself take care of data packing and alignment internally. For the application the size of DVD block is 2048 bytes and the DVD writing process is similar to the writing of a MODE1 CD (Data CD) except that the startDVDSession and the startDVDTrack methods should be used to initiate a DVD session and track and the endDVDTrack and endDVDSession methods to finalize it.

See Also
Device::endDVDSession
Device::eraseEx
Device::format
Device::mediaProfile
primo::burner::MediaProfile::Enum
virtual bool_t startDVDTrack ( uint32_t  blocks)
pure virtual

Starts a new track or continues an existing track from a DVD session.

This method should be called after the startDVDSession method and before the endDVDTrack method.

Parameters
blocksNumber of DVD blocks to be added to the track. The size of one DVD block is 2048 bytes. An open track may consume all remaining available blocks on the DVD.

NOTES:

DVD-R Sequential, DVD-RW in Sequential mode, and DVD-RW in Restricted Overwrite mode - if dwBlocks is less than 65264 blocks, for the first track only, the device will automatically pad the track to a size of 65264 blocks.

DVD-RW in Restricted Overwrite mode - if Required Space > Formatted Space, then the last formatted session will be expanded by (Required Space - Formatted Space) blocks, where Required Space = (newSessionStartAddress + dwBlocks), and Formatted Space = (mediaCapacity - mediaFreeSpace).

DVD-R DL in Layer Jump Mode - if the layer jump mode is set to manual then the track data is split in half between layer 0 and layer 1.

Returns
1 The track has been opened successfully.
0 There was an error.
See Also
Device::endDVDTrack
virtual bool_t streaming ( ) const
pure virtual

Returns a value indicating whether the device will use stream recording or not.

Valid only for BD media.

Returns
1 The device will use stream recording.
0 The device will not use stream recording.
See Also
Device::setStreaming
virtual const char_t* systemPath ( ) const
pure virtual

Gets the system path that identifies the device.

Returns
A null-terminated string
See Also
DeviceEnum::createDeviceFromSystemPath
virtual uint32_t unitReadyState ( )
pure virtual

The unitReadyState method returns a device SCSI sense code.

Returns
primo::scsi::ScsiSense::Success if the device is ready or a ScsiSense code indicating the device condition.
See Also
DeviceError
primo::scsi::ScsiSense::Enum
void WaitUnitReady(Device * device)
{
// Use the new unitReadyState method to detect when the device is ready.
uint32_t dwDeviceError = device->unitReadyState();
while (ScsiSense::Success != dwDeviceError)
{
_tprintf(_T("Unit not ready: 0x%06X\\n"), dwDeviceError);
::Sleep(1000);
dwDeviceError = device->unitReadyState();
}
_tprintf(_T("Unit is ready.\\n"));
}
.
.
.
// Close the device tray and refresh disc information
if (pDevice->eject(FALSE))
{
// Wait for the device to become ready
WaitUnitReady(pDevice);
// Refresh disc information. Call this method when media changes.
pDevice->refresh();
}
virtual void unlockOutputBuffer ( uint32_t  blocks)
pure virtual

Unlocks the Device output buffer and writes the data from the buffer to the disc.

Parameters
blocksNumber of blocks to be written to the disc. This number should not exceed the number of blocks requested with the lockOutputBuffer method.
See Also
lockOutputBuffer
clearOutputBuffer
virtual void unlockOutputBufferEx ( uint32_t  blocks,
int32_t  writeAddress 
)
pure virtual

The unlockOutputBufferEx method releases a locked output buffer and writes the buffer data to a given disc address on CD/DVD.

CAUTION:

Usage of this method requires thorough understanding of DVD physical format and specifications. Improper use may result in errors during writing or even data loss on DVD+RW/-RW media.

 @param blocks 
 Number of blocks actually written to the buffer1 and buffer2 returned by lockOutputBuffer.
 It should not exceed the number of blocks requested in blocks
              parameter of lockOutputBuffer method.<P>

 @param writeAddress the address to which the block of data should be written. 
                                     This parameter is ignored for CD-R and CD-RW media. 
                                     For CD-R and CD-RW media the engine always manages the disc 
                                     addresses automatically.

 @see lockOutputBuffer
 @see clearOutputBuffer
virtual const char_t* vendor ( ) const
pure virtual

Retrieves the device vendor name.

Returns
A null-terminated string.
virtual const char_t* vendorSpecific ( ) const
pure virtual

Retrieves the vendor specific information of the device as it is set by its manufacturer.

Returns
A null-terminated string.
virtual bool_t writeData ( int32_t  startLba,
uint8_t *  buffer,
int32_t  blocks,
int32_t  blockSize 
)
pure virtual

The writeData method writes data to a CD, DVD or BD starting at the logical block address indicated by the startLba parameter.

Parameters
startLba[in] The logical block address at which the writing should start
buffer[in] Pointer to a buffer that contains the data to be written.
blocks[in] the number of blocks that should be written.
blockSize[in] The size of the data block.
Returns
1 Success.
0 Writing failed.
virtual int writeSpeedKB ( ) const
pure virtual

Gets the current write speed in Kbytes/s (1 KByte = 1000 bytes).

To get the speed relative to 1x divide the result to Speed1xKB::CD for CD, Speed1xKB::DVD for DVD and Speed1xKB::BD for BD.

Returns
Kilobytes per second
virtual int writeTransferRate ( ) const
pure virtual

Gets the actual write transfer rate (write speed) as measured by PrimoBurner.

Returns
The write transfer rate in KB/s (kilobytes/sec). To calculate the actual write speed divide the result to 176 for CD and 1350 for DVD.