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

#include <PrimoBurnerAPI.h>

Public Member Functions
virtual BDFeatures *	bdFeatures ()=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 CDFeatures *	cdFeatures ()=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 QSubChannel *	createQSubChannel (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 SpeedEnum *	createWriteSpeedEnumerator ()=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 DVDFeatures *	dvdFeatures ()=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 ErrorInfo *	error () 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 CDSession *	readCDSessionLayout (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 CDText *	readCDText ()=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 DiscInfo *	readDiscInfo ()=0
	Reads information about the disc. More...

virtual MediaInfo *	readMediaInfo ()=0
	Creates an objects that provides extended media information. More...

virtual RawToc *	readRawToc ()=0
	Reads the Full Table-Of-Content in raw format. More...

virtual SessionInfo *	readSessionInfo ()=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 Toc *	readToc ()=0
	The readToc Method reads the Table-Of-Content (TOC) of an audio CD. More...

virtual Toc *	readTocFromSession (uint8_t sessionNumber)=0
	The ReadToc method reads the Table-Of-Content of an audio CD. More...

virtual TrackInfo *	readTrackInfo (uint16_t trackNumber)=0
	Returns information about a given track. More...

virtual TrackInfoEx *	readTrackInfoEx (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

trackNumber Track 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

eject	Indicates 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.
unlockMedium	Indicates 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

closeSession	Indicates that the session should be closed. This parameter is ignored if closeDisc is set to TRUE.
closeDisc	Indicates 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

closeTrack Indicates 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

closeTrack Indicates 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

close Specifies 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

close Indicates 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

quick If 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

eraseType Indicates 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

type	The type of the format that should be performed.
subType	The format sub type. The value of this parameter depends on the value of the type parameter.
formatParameters	Should 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

blocks	Desired 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.
buffer1	Address of a variable to receive a pointer to the first locked portion of the output buffer.
buffer1Blocks	Address 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.
buffer2	Address 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.
buffer2Blocks	Address 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

blocks	Desired 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.
buffer1	Address of a variable to receive a pointer to the first locked portion of the output buffer.
buffer1Blocks	Address 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.
buffer2	Address 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.
buffer2Blocks	Address of a variable to receive the size of the buffer2 buffer. If buffer2 is NULL, this value will be 0.
blockSize	Address 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.
startBlock	The first block to be read from the CD.
blocks	The 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.
startBlock	The first block to be read from the Disc.
blocks	The 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

sessionNumber specifies 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

trackNumber The 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

trackNumber The 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

blocks The 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

endLBA The 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

callback A 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

cdText Pointer 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

startAddress The 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

value Kilobytes 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

value Kilobytes 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

blocks Number 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

blocks Number 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

blocks Number 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.

Public Member Functions

Detailed Description

Member Function Documentation