DataDisc Class Reference

Creates and burns data images to CD, DVD and Blu-ray Discs. More...

Inherits IDisposable.

Public Member Functions
	DataDisc ()
	Creates a DataDisc instance. More...
bool	CreateImageFile (string imageFilename)
	Creates an ISO image file. More...
void	Dispose ()
	Disposes AudioCD and reclaims the resources used by the object. More...
bool	LoadFromDisc (Int32 trackNumber)
	Loads a file system from existing track on a CD/DVD/BD. More...
bool	LoadFromFile (string imageFilename)
	Loads the directory structure of an image from ISO image file. More...
bool	Merge (DataDisc right, MergeDirection mergeDirection)
	Merges the file trees of two DataDisc objects. More...
bool	Merge (DataDisc right)
	Merges the file trees of two DataDisc objects. More...
bool	SetImageLayout (DataFile rootFolder, bool sortByFilename)
	Sets the file tree of a data image. More...
bool	SetImageLayout (DataFile rootFolder)
	Sets the file tree of a data image. More...
bool	SetImageLayoutFromFolder (string folder, bool sortByFilename)
	Sets the file system of a data image from a folder. More...
bool	SetImageLayoutFromFolder (string folder)
	Sets the file system of a data image from a folder. More...
bool	WriteImageToDisc (string imageFile, bool dismountVolume)
	Writes an image file to a disc. More...
bool	WriteImageToDisc (string imageFile)
	Writes an image file to a disc. More...
bool	WriteImageToDisc (System.IO.Stream image, bool dismountVolume)
	Writes an image stream to a disc. More...
bool	WriteImageToDisc (System.IO.Stream image)
	Writes an image stream to a disc. More...
bool	WriteToDisc (bool dismountVolume)
	Writes a data track to a disc. More...
bool	WriteToDisc ()
	Writes a data track to a disc. More...

Properties
bool	Bootable [get, set]
	Indicates whether a bootable image should be created. More...
BootProps	BootProps [get]
	Returns an object that provides access to the boot properties. More...
CachePolicy	CachePolicy [get]
	Returns an object that provides access to the cache properties. More...
bool	CdRomXa [get, set]
	Indicates whether to use Mode2 Form 1 XA sectors during the burning. More...
bool	CloseDisc [get, set]
	Instructs DataDisc to close the disc after the session is written to the disc. More...
bool	CloseSession [get, set]
	Indicates whether to close the session after the burning is completed. More...
bool	CloseTrack [get, set]
	Indicates whether the track should be closed after the burning is completed. More...
DataOverwriteFlags	DataOverwrite [get, set]
	Specifies whether files from the image layout should physically overwrite files that already exist on the disc. More...
Device	Device [get, set]
	Gets/Sets the device that this object will use. More...
bool	DvdVideo [get, set]
	Indicates that DataDisc should create a DVD-Video compatible image. More...
ErrorInfo	Error [get]
	The error information for the last DataDisc operation. More...
Int32	ImageConstraints [get, set]
	Gets/Sets filename constraints. More...
DataFile	ImageLayout [get]
	Gets the current image file tree. More...
Int32	ImageSizeInBlocks [get]
	Gets the size of the image layout in blocks. More...
Int64	ImageSizeInBytes [get]
	Gets the size of the image layout in bytes. More...
ImageType	ImageType [get, set]
	Gets/Sets the image file system. More...
IsoVolumeProps	IsoVolumeProps [get]
	Returns an object that provides access to ISO volume properties. More...
JolietVolumeProps	JolietVolumeProps [get]
	Returns an object that provides access to Joliet volume properties. More...
Int32	LoadedImageSizeInBlocks [get]
	Gets the size, in blocks, of a image which has been loaded with the LoadFromDisc method. More...
Int32	LoadTrackLayout [get, set]
	Gets/Sets the number of a track that should be loaded from the disc before the burning starts. More...
Int32	SessionStartAddress [get, set]
	Gets/Sets the start address of the new data session in blocks. More...
bool	SimulateBurn [get, set]
	Indicates that burning should be simulated. More...
bool	TranslateFilenames [get, set]
	Enables the default translation of the file names during the image creation. More...
UdfVolumeProps	UdfVolumeProps [get]
	Returns an object that provides access to UDF volume properties. More...
DataWriteAttributes	WriteAttributes [get, set]
	Obsolete. More...
WriteMethod	WriteMethod [get, set]
	Gets/Sets the disc write method. More...
DataWriteStrategy	WriteStrategy [get, set]
	Gets/Sets the write strategy. More...

Events
EventHandler < DataDiscContinueEventArgs >	OnContinueBurn
	Raised to check if burning should continue. More...
EventHandler < DataDiscFileStatusEventArgs >	OnFileStatus
	Raised to report the burning progress of individual files. More...
EventHandler < DataDiscProgressEventArgs >	OnProgress
	Raised to report the number of bytes written to a disc or image file. More...
EventHandler < DataDiscStatusEventArgs >	OnStatus
	Raised to report the burning status. More...

Detailed Description

Creates and burns data images to CD, DVD and Blu-ray Discs.

Constructor & Destructor Documentation

DataDisc

(

)

Creates a DataDisc instance.

When the DataDisc object is not needed anymore it should be disposed in order to deterministically reclaim the allocated resources.

Member Function Documentation

bool CreateImageFile

(

string

imageFilename

)

Creates an ISO image file.

The ISO image file can be written to a disc using the WriteImageToDisc method.

Parameters

imageFilename

Full path to the image file. If the image file already exists it will be overwritten.

Returns

true if the image is successfully created; false otherwise.

void Dispose

(

)

Disposes AudioCD and reclaims the resources used by the object.

bool LoadFromDisc

(

Int32

trackNumber

)

Loads a file system from existing track on a CD/DVD/BD.

Parameters

trackNumber

The track number from which to load the image path tables. The track must exist on the disc inserted in the device specified with the DataDisc.Device property.

This method reads only the directory tables of the data image without the user data. The directory tables map files and directories to logical block addresses on the disc.

When creating a multi-session data disc the calling application should merge the layouts of the new image and the last track on the disc.

Before using this method a Device object must be set using the DataDisc.Device property.

Returns

true if the operation is successful; false otherwise.

bool LoadFromFile

(

string

imageFilename

)

Loads the directory structure of an image from ISO image file.

The method works with Mode1 (2048 bytes/sector) data images created using the WriteToImageFile method.

Parameters

imageFilename

Full path to an ISO image file. The file should be a ISO9660, Joliet or UDF image that can be recorded in Mode1 (2048 bytes/sector). Loading of HFS images is currently not supported.

Returns

true if the image is successfully loaded; false otherwise

See Also

DataDisc.CreateImageFile

bool Merge	(	DataDisc	right,
		MergeDirection	mergeDirection
	)

Merges the file trees of two DataDisc objects.

This method is usually used together with the LoadFromDisc method to create multi-session data discs.

Parameters

right	A DataDisc object, that should be merged into this object.
mergeDirection	This parameter has a default value of MergeDirection.Left. It affects the way files with same virtual path are handled: MergeDirection.Left: If a file with the same virtual path exists both in 'right' and in 'this', the file from 'right' replaces the file from 'this'. MergeDirection.Right: If a file with the same virtual path exists both in 'right' and in 'this', the file from 'right' is ignored.

Returns

true if the operation successful; false otherwise.

bool Merge

(

DataDisc

right

)

Merges the file trees of two DataDisc objects.

Parameters

right

A DataDisc object, that should be merged into this object. This method does a right-to-left merging (MergeDirection.Left).

Returns

true if the operation successful; false otherwise.

See Also

Merge(DataDisc, MergeDirection)

Merge(DataDisc right, MergeDirection mergeDirection)

bool SetImageLayout	(	DataFile	rootFolder,
		bool	sortByFilename
	)

Sets the file tree of a data image.

Parameters

rootFolder

A DataFile object representing the root folder (directory) of the file system.

sortByFilename

Indicates whether to perform case sensitive ASCII sorting of the file entries based on the LongFilename property. For example assume that you have two files with names JOHNSTON and JOHN_HENRY. The string JOHN_HENRY will be greater than JOHNSTON because the "_" has a greater ASCII value than an uppercase S. The file entry for JOHN_HENRY will be placed physically on the disc after the file entry for JOHNSTON.

Returns

true if the layout is successfully set; false otherwise.

See Also

DataFile

bool SetImageLayout

(

DataFile

rootFolder

)

Sets the file tree of a data image.

Parameters

rootFolder

A DataFile object representing the root folder (directory) of the file system.

Returns

true if the layout is successfully set; false otherwise.

remarks> Filenames are not sorted: sortByFilename is false. /remarks>

See Also

SetImageLayout(DataFile,bool)

SetImageLayout(DataFile rootFolder,bool sortByFilename)

bool SetImageLayoutFromFolder	(	string	folder,
		bool	sortByFilename
	)

Sets the file system of a data image from a folder.

The directory and file structure of the data image will be identical to the file tree under the folder specified with the folder parameter.

Parameters

folder

The folder name that should be used to create the image layout. The name must specify the full path to the folder.

sortByFilename

Indicates whether to perform case sensitive ASCII sorting of the file entries based on the LongFilename property. For example assume that you have two files with names JOHNSTON and JOHN_HENRY. The string JOHN_HENRY will be greater than JOHNSTON because the "_" has a greater ASCII value than an uppercase S. The file entry for JOHN_HENRY will be placed physically on the Disc after the file entry for JOHNSTON.

Returns

true if the layout is successfully set; false otherwise.

bool SetImageLayoutFromFolder

(

string

folder

)

Sets the file system of a data image from a folder.

Parameters

folder

The folder that should be used to create the image layout.

Filenames are not sorted: sortByFilename is false.

Returns

true if the layout is successfully set; false otherwise.

See Also

DataDisc.SetImageLayoutFromFolder(string,bool)

DataDisc.SetImageLayoutFromFolder(string folder,bool sortByFilename)

bool WriteImageToDisc	(	string	imageFile,
		bool	dismountVolume
	)

Writes an image file to a disc.

Parameters

imageFile	The full path to a source image file.
dismountVolume	Indicates whether to dismount the volume after the burning. The default value of this parameter is false.

The operating system tries to mount an unmounted volume as soon as an attempt is made to access it. For example, a call to GetLogicalDrives triggers the operating system to mount unmounted volumes. Dismounting a volume is useful when a volume needs to disappear for a while. For example, when an application changes a volume file system it needs to dismount it to clear the volume information cache.

Returns

true if the operation is successful; false otherwise.

bool WriteImageToDisc

(

string

imageFile

)

Writes an image file to a disc.

Parameters

imageFile

The full path to a source image file.

dismountVolume is false.

Returns

true if the operation is successful; false otherwise.

See Also

WriteImageToDisc(string, bool)

WriteImageToDisc(string imageFile, bool dismountVolume)

bool WriteImageToDisc	(	System.IO.Stream	image,
		bool	dismountVolume
	)

Writes an image stream to a disc.

The method uses a System.IO.Stream stream object to read the image data.

Parameters

image	An object that inherits from System.IO.Stream.
dismountVolume	Indicates whether to dismount the volume after the burning. The default value of this parameter is false.

The operating system tries to mount an unmounted volume as soon as an attempt is made to access it. For example, a call to GetLogicalDrives triggers the operating system to mount unmounted volumes. Dismounting a volume is useful when a volume needs to disappear for a while. For example, when an application changes a volume file system it needs to dismount it to clear the volume information cache.

Returns

true if the operation is successful; false otherwise.

References PrimoSoftware.Burner.System.

bool WriteImageToDisc

(

System.IO.Stream

image

)

Writes an image stream to a disc.

The method uses a System.IO.Stream stream object to read the image data.

Parameters

image

An object that inherits from System.IO.Stream.

dismountVolume is false.

Returns

true if the operation is successful; false otherwise.

See Also

WriteImageToDisc(System.IO.Stream, bool)

WriteImageToDisc(System.IO.Stream image, bool dismountVolume)

References PrimoSoftware.Burner.System.

bool WriteToDisc

(

bool

dismountVolume

)

Writes a data track to a disc.

The image layout must be set with the SetImageLayoutFromFolder or SetImageLayout methods before this method can be used.

Parameters

dismountVolume

Indicates whether to dismount the volume after the burning. The default value of this parameter is false.

The operating system tries to mount an unmounted volume as soon as an attempt is made to access it. For example, a call to GetLogicalDrives triggers the operating system to mount unmounted volumes. Dismounting a volume is useful when a volume needs to disappear for a while. For example, when an application changes a volume file system it needs to dismount it to clear the volume information cache.

Returns

true if the operation is successful; false otherwise.

bool WriteToDisc

(

)

Writes a data track to a disc.

Returns

true if the operation is successful; false otherwise.

See Also

WriteToDisc(bool)

WriteToDisc(bool dismountVolume)

Property Documentation

bool Bootable

getset

Indicates whether a bootable image should be created.

If this property is not set a non-bootable image will be created.

The Bootable, BootImageFile and BootEmulation properties must be set before using the WriteToDisc or WriteToImageFile methods.

See Also

PrimoSoftware.Burner.BootProps.ImageFile

BootProps.ImageFile

See Also

PrimoSoftware.Burner.BootProps.Emulation

BootProps.Emulation

BootProps BootProps

get

Returns an object that provides access to the boot properties.

CachePolicy CachePolicy

get

Returns an object that provides access to the cache properties.

bool CdRomXa

getset

Indicates whether to use Mode2 Form 1 XA sectors during the burning.

If set to true the resulting CD will become a CD-ROM XA CD.

In multi-session / multi-track discs XA (Mode2 Form 1 XA) and normal (Mode1) track types cannot be mixed together. This property has effect only when the write method is set to Session-At-Once (WriteMethod.Sao).

bool CloseDisc

getset

Instructs DataDisc to close the disc after the session is written to the disc.

If you never set this property the disc will be closed by default. Setting CloseDisc has no effect for DVD-RAM.

bool CloseSession

getset

Indicates whether to close the session after the burning is completed.

Setting CloseSession has no effect for DVD-RAM.

If this property is set to true, the session is closed. If this property is false, the session is left open and additional tracks may be added to the session later. If you do not set this property to true the session is always closed by default.

This property has no effect if the burn mode is set to DAO or if the DataDisc.CloseDisc property is set to true.

bool CloseTrack

getset

Indicates whether the track should be closed after the burning is completed.

The default value of this property is true.

Setting CloseTrack has no effect for DVD-RAM.

This setting is overridden by the CloseSession and CloseDisc properties.

A track is always closed when the session is set to be closed. A session is always closed when the disk is set to be closed.

DataOverwriteFlags DataOverwrite

getset

Specifies whether files from the image layout should physically overwrite files that already exist on the disc.

When a file is physically overwritten the new file data is written to the same disc address as the old file, effectively replacing the data but not increasing the image size.

This property works only with DVD+RW media and is ignored for all other media profiles.

This property must be set before calling WriteToDisc or Merge methods in order to have any effect.

Device Device

getset

Gets/Sets the device that this object will use.

bool DvdVideo

getset

Indicates that DataDisc should create a DVD-Video compatible image.

When DvdVideo is set to true the following properties will be automatically changed: ImageType to ImageType.UdfIso, UdfVolumeProps.AllocDescType to UdfAllocDescType.Short>, UdfVolumeProps.TextEncoding to UdfTextEncoding.Ansi.

ErrorInfo Error

get

The error information for the last DataDisc operation.

See Also

ErrorInfo

Int32 ImageConstraints

getset

Gets/Sets filename constraints.

This is a combination of one or more flags defined in the ImageConstraints enumeration. The default value of this property is ImageConstraints.None and no validation of the filenames is performed by default.

The constraints are used by the SetImageLayout and SetImageLayoutFromFolder methods.

See Also

TranslateFilenames, ImageConstraints

DataFile ImageLayout

get

Gets the current image file tree.

See Also

DataDisc.LoadFromDisc, DataDisc.Merge

Int32 ImageSizeInBlocks

get

Gets the size of the image layout in blocks.

See Also

SetImageLayoutFromFolder, SetImageLayout

Int64 ImageSizeInBytes

get

Gets the size of the image layout in bytes.

See Also

SetImageLayoutFromFolder, SetImageLayout

ImageType ImageType

getset

Gets/Sets the image file system.

The supported image types are defined in the ImageType enumeration.

See Also

PrimoSoftware.Burner.ImageType

IsoVolumeProps IsoVolumeProps

get

Returns an object that provides access to ISO volume properties.

JolietVolumeProps JolietVolumeProps

get

Returns an object that provides access to Joliet volume properties.

Int32 LoadedImageSizeInBlocks

get

Gets the size, in blocks, of a image which has been loaded with the LoadFromDisc method.

The size of a data block is 2048 bytes.

Int32 LoadTrackLayout

getset

Gets/Sets the number of a track that should be loaded from the disc before the burning starts.

To disable track loading and merging set this property to 0.

NOTE: Loading of the image layout from HFS discs is not supported.

Int32 SessionStartAddress

getset

Gets/Sets the start address of the new data session in blocks.

The start address is saved in the directory structure of the image before it is burnt to a disc. The OS uses that information to find the data on multi-session discs.

IMPORTANT: When creating multi-track, multi session discs this property must be set before using any of the following methods: LoadFromDisc, Merge, SetImageLayoutFromFolder and SetImageLayout. Those methods adjust the ISO/Joliet/UDF directory structure according to the start address set with SessionStartAddress. Failing to set the session start address before using the image layout methods may lead to unreadable discs. Device.GetNewSessionStartAddress to get the correct start address for the next session.

bool SimulateBurn

getset

Indicates that burning should be simulated.

The simulation is a good test of a disc recorder, because most of the operations are performed as in a real recording.

Simulation is only supported for CD-R/RW and DVD-R/RW media. On CD-R/RW media simulation is possible only for Track-At-Once or Session-At-Once recording. On DVD-R/RW media simulation is possible for Disc-At-Once recording.

bool TranslateFilenames

getset

Enables the default translation of the file names during the image creation.

If set to true, the engine will replace the long file names with shorter ones without reporting an error. If set to false the engine will report an error for any constraint that is violated. The default setting for this property is false.

The file names are translated according to the following rules:

• If there is an extension the first three characters of the extension are kept as extension for the short filename.
• The name part only (the part without the extension) is truncated so its length plus 4 (the length of the extension and the dot '.') equals the maximum filename length allowed for the image type that is to be created.

This property is ignored if no constraints have been set.

See Also

DataFile.ShortFilename, ImageConstraints

UdfVolumeProps UdfVolumeProps

get

Returns an object that provides access to UDF volume properties.

DataWriteAttributes WriteAttributes

getset

Obsolete.

WriteMethod WriteMethod

getset

Gets/Sets the disc write method.

The following write methods are currently supported:

CD Media: WriteMethod.Packet WriteMethod.Tao WriteMethod.Sao and WriteMethod.RawDao

DVD Media: WriteMethod.DvdIncremental and 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.

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

BD Media: WriteMethod.BluRay

DataWriteStrategy WriteStrategy

getset

Gets/Sets the write strategy.

The write strategy affect the way WriteToDisc method works. This property should be used only when burning multi-track incremental UDF sessions.

NOTE: The write strategy works only when the write method is set to WriteMethod.Packet or WriteMethod.DvdIncremental and when the image type is set to ImageType.Udf. The strategy is ignored in all other cases.

Event Documentation

EventHandler<DataDiscContinueEventArgs> OnContinueBurn

Raised to check if burning should continue.

The event handler receives an argument of type DataDiscContinueEventArgs containing data related to this event.

See Also

DataDiscContinueEventArgs

EventHandler<DataDiscFileStatusEventArgs> OnFileStatus

Raised to report the burning progress of individual files.

The event handler receives an argument of type DataDiscFileStatusEventArgs containing data related to this event.

See Also

DataDiscFileStatusEventArgs

EventHandler<DataDiscProgressEventArgs> OnProgress

Raised to report the number of bytes written to a disc or image file.

The event handler receives an argument of type DataDiscProgressEventArgs containing data related to this event.

See Also

DataDiscProgressEventArgs

EventHandler<DataDiscStatusEventArgs> OnStatus

Raised to report the burning status.

The event handler receives an argument of type DataDiscStatusEventArgs containing data related to this event.

See Also

DataDiscStatusEventArgs