DiscArchive Class Reference

DiscArchive object provides a way for constructing large file trees and scheduling them for burning over multiple discs. More...

Public Member Functions
	DiscArchive ()
	Creates a new instance of DiscArchive class.
bool	CommitLayout (DiscLayout layout)
	If the recording of the selected layout is successful, call this method to inform DiscArchive that the layout content should not be selected again in when calling DiscArchive.PrepareLayout.
void	Dispose ()
	Disposes DiscLayout and reclaims the resources used by the object.
bool	PrepareArchive ()
	Call this method to initialize the archiving process and prepare the content for burning.
DiscLayout	PrepareLayout (Device device, bool keepExistingContent)
	Call this method to select a portion of or the entire archive for burning.
bool	RollbackLayout (DiscLayout layout)
	Call this method to return the layout content to the archive so that it can be selected again when a call to DiscArchive.PrepareLayout method is made.

Properties
DataFile	Content [get, set]
	Gets/sets the layout defined for burning.
ErrorInfo	Error [get]
	The error information for the last DiscArchive operation.
DataFile	Footer [get, set]
	Gets/sets the footer content to be included on each disc being produced with the current archive.
bool	HasNextDisc [get]
	Check the value of this property to see if there are more files/folders that need to be recorded on a medium.

Events
EventHandler< DiscArchiveAddFileToLayoutEventArgs >	OnAddFileToLayout
	The event is sent during a call to DiscArchive.PrepareLayout method.
EventHandler< DiscArchiveFooterSizeEventArgs >	OnFooterSize
	Use this event to define the footer size each time DiscAcrhive needs it while constructing a DiscLayout object in DiscArchive.PrepareLayout.
EventHandler< DiscArchiveRequestRenameEventArgs >	OnRequestRename
	Raised to query the client code if a specific file can be renamed to a specific name within the layout.
EventHandler< DiscArchiveFileErrorEventArgs >	OnSourceFileError
	Raised when a specific file could not be accessed or read from while executing DiscArchive.PrepareArchive method.

Detailed Description

DiscArchive object provides a way for constructing large file trees and scheduling them for burning over multiple discs.

The client code may define the desired file tree to burn using DiscArchive.Content property. DiscArchive will try to distribute that content over multiple disc (if needed). Each file from the content will be present on no more than one disc. Additionally the client code may specify content that needs to be present on each disc - DiscArchive.Footer property.

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

DiscLayout

Member Function Documentation

CommitLayout()

bool CommitLayout

(

DiscLayout

layout

)

If the recording of the selected layout is successful, call this method to inform DiscArchive that the layout content should not be selected again in when calling DiscArchive.PrepareLayout.

Parameters

layout

A DiscLayout object previously returned by a call to DiscArchive.PrepareLayout method.

Returns

true - the operation succeeded and new layout may be requested from the archive (if available). false - an error occurred. Check DiscArchive.Error for more details.

See also

DiscArchive.Error, DiscLayout

PrepareArchive()

bool PrepareArchive

(

)

Call this method to initialize the archiving process and prepare the content for burning.

Must be called before DiscArchive.PrepareLayout

Returns

The result of the operation: true - success. Can proceed with calls to DiscArchive.PrepareLayout method. false - the initialization process has failed. Check DiscArchive.Error for more details.

Exceptions

System.ObjectDisposedException

PrepareLayout()

DiscLayout PrepareLayout	(	Device	device,
		bool	keepExistingContent
	)

Call this method to select a portion of or the entire archive for burning.

Parameters

device	The device to use for burning. Please note that the device should already contain a valid medium in it.
keepExistingContent	Set this parameter to true to merge previously recorded data on the target medium (device parameter) with the prepared content.

The method selects files and folders from the archive content so that these can fit on the target medium. If a footer was specified for the entire archive then its size is also accounted for since it will be present on every disc. In general files are selected until DiscArchive estimates there won't be enough space anymore on the target medium. However, if a file cannot be added to the layout then DiscArchive will try to select files only from that file's path but will not try files from other folders.

Returns

A DiscLayout object that is ready for burning or null if an error occurred or there are no more files/folders for burning. If null is returned then check DiscArchive.Error property.

NOTE: The DiscLayout object returned by this method may only be released by calling either DiscArchive.CommitLayout or DiscArchive.RollbackLayout methods. Call these methods once you are done using the DiscLayout object.

See also

DiscArchive.Error, DiscLayout, Device

Exceptions

System.ObjectDisposedException

RollbackLayout()

bool RollbackLayout

(

DiscLayout

layout

)

Call this method to return the layout content to the archive so that it can be selected again when a call to DiscArchive.PrepareLayout method is made.

If an unrecoverable error occurs while burning the current layout this method may be used to reschedule the layout content for archiving.

Parameters

layout

A DiscLayout object previously returned by a call to DiscArchive.PrepareLayout method.

Returns

true - the operation succeeded and new layout may be requested from the archive (if available). false - an error occurred. Check DiscArchive.Error for more details.

See also

DiscArchive.Error, DiscLayout

Property Documentation

Content

DataFile Content

getset

Gets/sets the layout defined for burning.

See also

DataFile

Exceptions

System.ObjectDisposedException

Error

ErrorInfo Error

get

The error information for the last DiscArchive operation.

See also

ErrorInfo, DiscArchiveError

Footer

DataFile Footer

getset

Gets/sets the footer content to be included on each disc being produced with the current archive.

The default value is null - no footer is defined.

See also

DataFile

Exceptions

System.ObjectDisposedException

HasNextDisc

bool HasNextDisc

get

Check the value of this property to see if there are more files/folders that need to be recorded on a medium.

Exceptions

System.ObjectDisposedException

Event Documentation

OnAddFileToLayout

EventHandler<DiscArchiveAddFileToLayoutEventArgs> OnAddFileToLayout

The event is sent during a call to DiscArchive.PrepareLayout method.

It is possible that each file added to the layout will result in the footer size increasing. Use this event to reflect such changes. The event informs the client code which file is to be added to the layout and how much free space on the target medium could be used for the footer size to grow (

See also

DiscArchiveAddFileToLayoutEventArgs.MaxFooterIncrement

).

See also

DiscArchiveAddFileToLayoutEventArgs

OnFooterSize

EventHandler<DiscArchiveFooterSizeEventArgs> OnFooterSize

Use this event to define the footer size each time DiscAcrhive needs it while constructing a DiscLayout object in DiscArchive.PrepareLayout.

This event should be used if the footer may change after each file is added to the layout to burn (DiscArchive.Content);.

See also

DiscArchiveFooterSizeEventArgs, DiscArchive.OnAddFileToLayout

OnRequestRename

EventHandler<DiscArchiveRequestRenameEventArgs> OnRequestRename

Raised to query the client code if a specific file can be renamed to a specific name within the layout.

This event is raised when an file's original name is longer than the maximum length possible (127 16-bit code units) or another file already exists with that name. In those cases DiscLayout generates a new file name and sends OnRequestRename event. The new name is constructed using the following template: "TruncatedOriginalName_RenameIndex.OriginalExtension",
where the rename_index starts from 1 and is increased each time the proposed name is declined by the client code. The original file name on the hard drive/network location/etc. will not be modified if the rename operation is approved. The event handler receives an argument of type DiscArchiveRequestRenameEventArgs containing data related to this event.

See also

DiscArchiveRequestRenameEventArgs

OnSourceFileError

EventHandler<DiscArchiveFileErrorEventArgs> OnSourceFileError

Raised when a specific file could not be accessed or read from while executing DiscArchive.PrepareArchive method.

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

See also

DiscArchiveFileErrorEventArgs