PrimoBurner(tm) for C++  4.6
CD, DVD and Blu-ray Software Development Kit
 All Classes Namespaces Files Functions Variables Enumerations Enumerator Pages
DiscArchive Class Referenceabstract

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

#include <PrimoBurnerAPI.h>

Inherits Reference.

Public Member Functions

virtual DiscArchiveCallbackcallback () const =0
 Gets the current callback set in DiscArchive. More...
 
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(). More...
 
virtual DataFilecontent () const =0
 Gets the layout defined for burning. More...
 
virtual const ErrorInfoerror () const =0
 Gets error information about the last operation. More...
 
virtual DataFilefooter () const =0
 Gets the footer content to be included on each disc being produced with the current archive. More...
 
virtual DiscArchiveFooterPolicyfooterPolicy () const =0
 Gets the policy object that manages footer size. More...
 
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. More...
 
virtual bool_t prepareArchive ()=0
 Initializes the archiving process and prepares the content for burning. More...
 
virtual DiscLayoutprepareLayout (Device *device, bool_t keepExistingContent)=0
 Creates a layout for the next disc to be recorded. More...
 
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. More...
 
virtual void setCallback (DiscArchiveCallback *callback)=0
 Sets a callback object to receive notifications from DiscArchive. More...
 
virtual void setContent (DataFile *src)=0
 Sets the layout defined for burning. More...
 
virtual void setFooter (DataFile *src)=0
 Sets the footer content to be included on each disc being produced with the current archive. More...
 
virtual void setFooterPolicy (DiscArchiveFooterPolicy *callback)=0
 Sets a policy object for managing footer size. More...
 
- Public Member Functions inherited from Reference
virtual int32_t release () const =0
 Releases the instance. More...
 
virtual int32_t retain () const =0
 Retains the instance. More...
 
virtual int32_t retainCount () const =0
 Returns the current reference count. More...
 

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);
// 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

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
deviceA pointer to the device to use for recording the layout. The device should already contain a valid disc in it.
keepExistingContentIf 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
layoutA 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
callbackA 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
callbackA pointer to an object that implements the DiscArchiveFooterPolicy interface.
See Also
footerPolicy