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

#include <PrimoBurner.h>

Inherits Reference.

Public Member Functions
virtual DiscArchiveCallback *	callback () const =0
	Gets the current callback set in DiscArchive.
virtual bool_t	commitLayout (DiscLayout *layout)=0
	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().
virtual DataFile *	content () const =0
	Gets the layout defined for burning.
virtual const ErrorInfo *	error () const =0
	Gets error information about the last operation.
virtual DataFile *	footer () const =0
	Gets the footer content to be included on each disc being produced with the current archive.
virtual DiscArchiveFooterPolicy *	footerPolicy () const =0
	Gets the policy object that manages footer size.
virtual bool_t	hasNextDisc () const =0
	Check the value of this property to see if there are more files/folders that need to be recorded on a disc.
virtual bool_t	prepareArchive ()=0
	Initializes the archiving process and prepares the content for burning.
virtual DiscLayout *	prepareLayout (Device *device, bool_t keepExistingContent)=0
	Creates a layout for the next disc to be recorded.
virtual bool_t	rollbackLayout (DiscLayout *layout)=0
	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.
virtual void	setCallback (DiscArchiveCallback *callback)=0
	Sets a callback object to receive notifications from DiscArchive.
virtual void	setContent (DataFile *src)=0
	Sets the layout defined for burning.
virtual void	setFooter (DataFile *src)=0
	Sets the footer content to be included on each disc being produced with the current archive.
virtual void	setFooterPolicy (DiscArchiveFooterPolicy *callback)=0
	Sets a policy object for managing footer size.

Detailed Description

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

Remarks:: The client code may define the desired file tree to burn using the DiscArchive::setContent() method. 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 - see DiscArchive::setFooter().

The following example is a simple demonstration of how DiscArchive and DiscLayout may be used.

        ...
        // fetch desired device from a device enumerator (DeviceEnum)
        Device* device = deviceEnum.createDevice(deviceIndex, TRUE);
        ...
        DataFile* content = Library::createDateFile();
        DataFile* footer = Library::createDateFile();
        
        //call code that constructs the desired content and footer.
        ...
        // Create a new DiscArchive object
        DiscArchive* archive = Library::createDiscArchive();
                
        // Set archive content and footer
        archive->setContent(content);
        archive->setFooter(footer);
         
        // initialize archive process
        archive->prepareArchive();
         
        // while there is content to be written
        while(archive.hasNextDisc())
        {
                // refresh device
                device->Refresh();
                                
                // fetch new layout to burn
                DiscLayout* discLayout = archive->prepareLayout(device, FALSE);
                                
                // prepare layout for recording
                discLayout->open();
                                                
                discLayout->writeContent();
                                
                discLayout->writeFooter();
        
                discLayout->writeFileSystem();
                                
                // finalize layout recording
                discLayout.close();
                                
                // commit layout as recorded
                archive->commitLayout(discLayout);
        }
        archive->release();
        ...

See also:: DiscLayout

Member Function Documentation

virtual DiscArchiveCallback* callback ( ) const [pure virtual]

Gets the current callback set in DiscArchive.

Returns:: The callback previously set by setCallback or NULL if no callback is set.

See also:: setCallback

virtual bool_t commitLayout ( DiscLayout * layout ) [pure virtual]

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 [in] A DiscLayout object previously returned by a call to DiscArchive::prepareLayout().

Returns:: TRUE The operation is successful, a new layout may be requested from the archive (if available).; FALSE An error occurred. Check DiscArchive::error() for more details.

See also:: DiscArchive::error; DiscArchive::rollbackLayout; DiscLayout

virtual DataFile* content ( ) const [pure virtual]

Gets the layout defined for burning.

Returns:: A pointer to a DataFile object that describes the content layout.

See also:: DataFile; setContent

virtual const ErrorInfo* error ( ) const [pure virtual]

Gets error information about the last operation.

Returns:: A pointer to an ErrorInfo object.

virtual DataFile* footer ( ) const [pure virtual]

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

Returns:: A pointer to a DataFile object that describes the footer layout.

See also:: DataFile; setFooter

virtual DiscArchiveFooterPolicy* footerPolicy ( ) const [pure virtual]

Gets the policy object that manages footer size.

Returns:: The policy previously set by setFooterPolicy or NULL if no policy is set.

See also:: setFooterPolicy

virtual bool_t hasNextDisc ( ) const [pure virtual]

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

Returns:: TRUE - there are more discs to be recorded from the archive, FALSE - the whole archive is recorded.

virtual bool_t prepareArchive ( ) [pure virtual]

Initializes the archiving process and prepares the content for burning.

Must be called before DiscArchive::prepareLayout()

Returns:: TRUE The operation is successful. Can proceed with calls to DiscArchive::prepareLayout() method.; FALSE The operation has failed. Check DiscArchive::error() for more details.

virtual DiscLayout* prepareLayout	(	Device *	device,
		bool_t	keepExistingContent
	)		`[pure virtual]`

Creates a layout for the next disc to be recorded.

The files and the folders in the layout are selected from the remaining unrecorded content (including the footer).

Parameters:

device	A pointer to the device to use for recording the layout. The device should already contain a valid disc in it.
keepExistingContent	If TRUE the created layout will contain the previously recorded data on the target disc (device parameter) in addition to the new content.

Remarks:: The method selects files and folders from the archive content so that these can fit on the target disc. If a footer is set 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 disc. 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 pointer to a DiscLayout object. The layout can be recorded on the specified device.; NULL An error occurred or there are no more files/folders for recording. Check DiscArchive::error().

Remarks:: The DiscLayout object returned by this method may only be released by calling either DiscArchive::commitLayout() or DiscArchive::rollbackLayout() methods. The methods must be called once the DiscLayout object is not needed anymore.

See also:: DiscArchive::error(); DiscArchive commitLayout(); DiscArchive rollbackLayout(); DiscLayout; Device

virtual bool_t rollbackLayout ( DiscLayout * layout ) [pure virtual]

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.

Remarks:: If an unrecoverable error occurs while recording the current layout this method may be used to return the layout content to the pool of unrecorded content in DiscArchive.

Parameters:

layout A DiscLayout object previously returned by a call to DiscArchive::prepareLayout().

Returns:: TRUE The operation succeeded and a new layout may be requested from the archive (if available).; FALSE An error occurred. Check DiscArchive::error() for more details.

See also:: DiscArchive::error; DiscArchive::commitLayout; DiscLayout

virtual void setCallback ( DiscArchiveCallback * callback ) [pure virtual]

Sets a callback object to receive notifications from DiscArchive.

Parameters:

callback A pointer to an object that implements the DiscArchiveCallback interface.

See also:: callback

virtual void setContent ( DataFile * src ) [pure virtual]

Sets the layout defined for burning.

Parameters:

src	[in] A pointer to a DataFile object that describes the content layout.

See also:: DataFile; content

virtual void setFooter ( DataFile * src ) [pure virtual]

Sets the footer content to be included on each disc being produced with the current archive.

Parameters:

src	[in] A pointer to a DataFile object that describes the footer layout. The default value is NULL - no footer is defined.

See also:: DataFile; footer

virtual void setFooterPolicy ( DiscArchiveFooterPolicy * callback ) [pure virtual]

Sets a policy object for managing footer size.

Parameters:

callback A pointer to an object that implements the DiscArchiveFooterPolicy interface.

See also:: footerPolicy

Public Member Functions

Detailed Description

Member Function Documentation