DiscArchive Class Reference

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

#include <pb_api.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.
Public Member Functions inherited from Reference
virtual int32_t	release () const =0
	Releases the instance.
virtual int32_t	retain () const =0
	Retains the instance.
virtual int32_t	retainCount () const =0
	Returns the current reference count.

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 can be used:

// Get device from a device enumerator (DeviceEnum)
Device* device = deviceEnum.createDevice(deviceIndex, TRUE);
 
DataFile* content = Library::createDataFile();
DataFile* footer = Library::createDataFile();
 
// Code that constructs the desired content and footer goes here.
 
// 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();
            
    // prepare a new layout to burn
    DiscLayout* discLayout = archive->prepareLayout(device, FALSE);
            
    // open layout
    discLayout->open();
                    
    discLayout->writeContent();
            
    discLayout->writeFooter();
 
    discLayout->writeFileSystem();
            
    // finalize layout
    discLayout->close();
            
    // commit layout as recorded
    archive->commitLayout(discLayout);
}
 
archive->release();

See also

DiscLayout

Member Function Documentation

callback()

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

commitLayout()

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

content()

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

error()

virtual const ErrorInfo * error ( ) const

pure virtual

Gets error information about the last operation.

Returns

A pointer to an ErrorInfo object.

footer()

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

footerPolicy()

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

hasNextDisc()

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.

prepareArchive()

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.

prepareLayout()

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

rollbackLayout()

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

setCallback()

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

setContent()

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

setFooter()

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

setFooterPolicy()

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