DiscLayout Class Reference

The DiscLayout object provides a way for recording all or a portion of DiscArchive content on a single disc. More...

Inherits IDisposable.

Public Member Functions
bool	Close ()
	Finalizes the write operations.
void	Dispose ()
	Disposes DiscLayout and reclaims the resources used by the object.
bool	Open ()
	Prepares the DiscLayout object for recording the selected content and footer to the target medium.
void	SetFooter (DataFile footer)
	The method sets a layout describing the "footer" to be recorded after the DiscLayout.WriteContent operation finishes.
bool	WriteContent ()
	Writes the selected content on the target medium.
bool	WriteFileSystem ()
	Writes the file system describing the content of the disc.
bool	WriteFileSystem (bool dismountVolume)
	Writes the file system describing the content of the disc.
bool	WriteFooter ()
	Writes the selected footer on the target medium.

Properties
DataFile	Content [get]
	Gets the layout that will be written on the target medium.
DataFile	ContentOnDisc [get]
	Gets the description of the layout already present on the target medium before the current layout is written to it.
Device	Device [get, set]
	Gets/Sets the device that this object will use.
ErrorInfo	Error [get]
	The error information for the last DiscLayout operation.
DataFile	Footer [get]
	Gets a DatFile object defining the content of the footer to be recorded after the layout content goes on disc.
Int32	ImageSize [get]
	Returns the number of blocks needed on the target medium to write the selected content and footer.
Int32	MediaFreeSpace [get]
	Returns the available space in blocks on the target medium before calling any of the write methods.
Int32	SessionStartAddress [get, set]
	Gets/sets the address at which content recording will begin on the target medium.
string	VolumeLabel [get, set]
	Gets/sets the new volume label that will be set on the target medium when DiscLayout.WriteFileSystem method is called.

Events
EventHandler< DiscLayoutContinueWriteEventArgs >	OnContinueWrite
	Raised to check if burning should continue.
EventHandler< DiscLayoutFileEventArgs >	OnFileComplete
	Raised when a specific file from the layout is written on the target medium.
EventHandler< DiscLayoutFileErrorEventArgs >	OnFileError
	Raised when a specific file from the layout cannot be written on the target medium due to file access/read errors.
EventHandler< DiscLayoutProgressEventArgs >	OnProgress
	Raised to report the number of blocks written to the target medium.

Detailed Description

The DiscLayout object provides a way for recording all or a portion of DiscArchive content on a single disc.

A DiscLayout object may be obtained only by calling DiscArchive.PrepareLayout method on a source DiscArchive object. Once obtained the DiscLayout is responsible for writing its content and footer on the target medium, as well as the file system that describes the recorded content and footer.

The following example is a simple demonstration of how DiscArchive and DiscLayout classes can be used:

// Get device from DeviceEnumerator object
Device device = deviceEnumerator.CreateDevice(deviceIndex, true);
 
// Add code that fills in the content and footer.
DataFile content = null;
DataFile footer = null;
 
// Create a new DiscArchive object
using (DiscArchive archive = new DiscArchive())
{
    // set archive content and footer
    archive.Content = content;
    archive.Footer = footer;
 
    // initialize archive process
    if (archive.PrepareArchive())
    {
        // while there is content to be written
        while(archive.HasNextDisc)
        {
            // refresh device
            device.Refresh();
                        
            // prepare a new layout to burn
            DiscLayout discLayout = archive.PrepareLayout(device, false);
                        
            // prepare layout for recording
            if (discLayout.Open())
            {
                // write content
                discLayout.WriteContent();
                        
                // write footer
                discLayout.WriteFooter();
 
                // write file system
                discLayout.WriteFileSystem();
                        
                // finalize layout recording
                discLayout.Close();
            }
                        
            // commit layout as recorded
            archive.CommitLayout(discLayout);
        }
    }
}
 

See also

PrimoSoftware.Burner.DiscArchive, DiscLayout.WriteContent, DiscLayout.WriteFooter, DiscLayout.WriteFileSystem

Member Function Documentation

Close()

bool Close

(

)

Finalizes the write operations.

Call this method after DiscLayout.WriteFileSystem to complete the write sequence.

Returns

true - the operation succeeded; false otherwise.

Exceptions

ObjectDisposedException

The DiscLayout object was previously disposed.

See also

DiscLayout.WriteFileSystem, DiscLayout.Open

Open()

bool Open

(

)

Prepares the DiscLayout object for recording the selected content and footer to the target medium.

Call this method before calling DiscLayout.WriteContent, DiscLayout.WriteFooter and DiscLayout.WriteFileSystem

Returns

true - Success.

false - Failure. Check DiscLayout.Error property.

See also

DiscLayout.WriteContent, DiscLayout.WriteFooter, DiscLayout.WriteFileSystem, DiscLayout.Close

Exceptions

ObjectDisposedException

The DiscLayout object was previously disposed.

SetFooter()

void SetFooter

(

DataFile

footer

)

The method sets a layout describing the "footer" to be recorded after the DiscLayout.WriteContent operation finishes.

Parameters

footer

A DataFile layout containing the desired footer content

Call this method before calling DiscLayout.Open

See also

DiscLayout.WriteContent, DiscLayout.Footer

Exceptions

ObjectDisposedException

The DiscLayout object was previously disposed.

WriteContent()

bool WriteContent

(

)

Writes the selected content on the target medium.

Returns

true - the operation succeeded; false otherwise.

Exceptions

ObjectDisposedException

The DiscLayout object was previously disposed.

See also

DiscLayout.Content

WriteFileSystem() [1/2]

bool WriteFileSystem

(

)

Writes the file system describing the content of the disc.

The file system is automatically determined based on the written content and footer as well as any previously loaded data
(from previous recording sessions). This method must be called after the content and footer are written (DiscLayout.WriteContent and DiscLayout.WriteFooter), otherwise unwanted results may occur.

The media volume will not be automatically dismounted after the write operation finishes.

Returns

true - the operation succeeded; false otherwise.

Exceptions

ObjectDisposedException

The DiscLayout object was previously disposed.

See also

DiscLayout.Content, DiscLayout.Footer, DiscLayout.WriteContent, DiscLayout.WriteFooter

References DiscLayout.WriteFileSystem().

Referenced by DiscLayout.WriteFileSystem().

WriteFileSystem() [2/2]

bool WriteFileSystem

(

bool

dismountVolume

)

Writes the file system describing the content of the disc.

Parameters

dismountVolume

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

The file system is automatically determined based on the written content and footer as well as any previously loaded data
(from previous recording sessions). This method must be called after the content and footer are written (DiscLayout.WriteContent and
DiscLayout.WriteFooter), otherwise unwanted results may occur.

Returns

true - the operation succeeded; false otherwise.

Exceptions

ObjectDisposedException

The DiscLayout object was previously disposed.

See also

DiscLayout.Content, DiscLayout.Footer, DiscLayout.WriteContent, DiscLayout.WriteFooter

WriteFooter()

bool WriteFooter

(

)

Writes the selected footer on the target medium.

If no footer is selected for the current layout this method has no effect.

Returns

true - the operation succeeded; false otherwise.

Exceptions

ObjectDisposedException

The DiscLayout object was previously disposed.

See also

DiscLayout.Footer

Property Documentation

Content

DataFile Content

get

Gets the layout that will be written on the target medium.

See also

DiscArchive.Content

Exceptions

ObjectDisposedException

The DiscLayout object was previously disposed.

ContentOnDisc

DataFile ContentOnDisc

get

Gets the description of the layout already present on the target medium before the current layout is written to it.

Exceptions

ObjectDisposedException

The DiscLayout object was previously disposed.

Error

ErrorInfo Error

get

The error information for the last DiscLayout operation.

See also

ErrorInfo, DiscLayoutError

Footer

DataFile Footer

get

Gets a DatFile object defining the content of the footer to be recorded after the layout content goes on disc.

When a DiscLayout object is created using DiscArchive.PrepareLayout method, its footer is a copy of the footer defined originally for the DiscArchive object. It is still possible to define a different footer for each DiscLayout object, despite the fact that one may already be set in the source DiscArchive object.

See also

DiscArchive.Footer, DiscLayout.SetFooter

Exceptions

ObjectDisposedException

The DiscLayout object was previously disposed.

ImageSize

Int32 ImageSize

get

Returns the number of blocks needed on the target medium to write the selected content and footer.

Use this property after calling DiscLayout.Open, otherwise it will return 0.

MediaFreeSpace

Int32 MediaFreeSpace

get

Returns the available space in blocks on the target medium before calling any of the write methods.

Use this property after calling DiscLayout.Open, otherwise it will return 0.

SessionStartAddress

Int32 SessionStartAddress

getset

Gets/sets the address at which content recording will begin on the target medium.

Modifying the value of this property (if necessary) should be done before calling DiscLayout.Open.

Exceptions

ObjectDisposedException

The DiscLayout object was previously disposed.

VolumeLabel

string VolumeLabel

getset

Gets/sets the new volume label that will be set on the target medium when DiscLayout.WriteFileSystem method is called.

See also

DiscLayout.WriteFileSystem

Exceptions

ObjectDisposedException

The DiscLayout object was previously disposed.

Event Documentation

OnContinueWrite

EventHandler<DiscLayoutContinueWriteEventArgs> OnContinueWrite

Raised to check if burning should continue.

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

Note: The event gets fired for each file from the layout after it is recorded on the target medium. While a file is being recorded this event not will fire.

See also

DiscLayoutContinueWriteEventArgs

OnFileComplete

EventHandler<DiscLayoutFileEventArgs> OnFileComplete

Raised when a specific file from the layout is written on the target medium.

See also

DiscLayoutFileEventArgs

OnFileError

EventHandler<DiscLayoutFileErrorEventArgs> OnFileError

Raised when a specific file from the layout cannot be written on the target medium due to file access/read errors.

See also

DiscLayoutFileEventArgs

OnProgress

EventHandler<DiscLayoutProgressEventArgs> OnProgress

Raised to report the number of blocks written to the target medium.

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

See also

DiscLayoutProgressEventArgs