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

Defines one file or directory in a data image. More...

#include <PrimoBurnerAPI.h>

Inherits Reference.

Public Member Functions

virtual DataFileCallbackcallback () const =0
 Gets the callback set previously by setCallback. More...
 
virtual DataFileListchildren () const =0
 Gets the list of child DataFile objects associated with this file. More...
 
virtual DataFileclone (bool_t includeChildren)=0
 Creates a copy of the DataFile object. More...
 
virtual filetime_t creationTime () const =0
 Gets the file creation time. More...
 
virtual DataSource::Enum dataSource () const =0
 Gets the file data source. More...
 
virtual bool_t directory () const =0
 Indicates if this file is a directory. More...
 
virtual uint32_t discAddress () const =0
 Gets the file relative logical block address. More...
 
virtual int32_t excludeMask ()=0
 Gets the file systems from which this file / directory should be excluded. More...
 
virtual DataFilefind (const char_t *relativePath, bool_t caseSensitive=0) const =0
 Finds a file in a file tree. More...
 
virtual int32_t hiddenMask () const =0
 Gets the file systems in which this file / directory should be marked as hidden. More...
 
virtual const char_t * longFilename () const =0
 Gets the long filename. More...
 
virtual bool_t merge (DataFile *source)=0
 Merges two file trees. More...
 
virtual DataFileparent () const =0
 Gets the file parent. More...
 
virtual const char_t * path () const =0
 Gets the path which is set with the setPath method. More...
 
virtual void setCallback (DataFileCallback *callback)=0
 Sets the callback that receives notifications for this DataFile. More...
 
virtual void setCreationTime (filetime_t filetime)=0
 Sets the file creation time. More...
 
virtual void setDataSource (DataSource::Enum source)=0
 Sets the file data source. More...
 
virtual void setDirectory (bool_t directory)=0
 Sets whether DataFile is a directory. More...
 
virtual void setDiscAddress (uint32_t address)=0
 Sets the file logical block address. More...
 
virtual void setExcludeMask (int32_t imageTypeFlags)=0
 Sets the file systems from which this file / directory should be excluded. More...
 
virtual void setHiddenMask (int32_t imageTypeFlags)=0
 Sets in which file systems this file / directory should be marked as hidden. More...
 
virtual void setLongFilename (const char_t *filename)=0
 Sets the long filename. More...
 
virtual void setPath (const char_t *filepath)=0
 Sets the full path to the file from which this object should read its data. More...
 
virtual void setShortFilename (const char_t *filename)=0
 Sets the short filename. More...
 
virtual void setSize (int64_t filesize)=0
 Sets the file size in bytes. More...
 
virtual void setStream (primo::Stream *stream)=0
 Sets the source stream that should be used to access the file data during the data image creation. More...
 
virtual void setUserData (void *userData)=0
 Attaches user defined data to this object. More...
 
virtual const char_t * shortFilename () const =0
 Gets the short filename. More...
 
virtual int64_t size () const =0
 Gets the file size in bytes. More...
 
virtual primo::Streamstream () const =0
 Gets the source stream that should be used to access the file data during the data image creation. More...
 
virtual UdfFilePropsudfProps () const =0
 Gets an interface for setting and reading UDF file properties. More...
 
virtual void * userData () const =0
 Gets the user defined data attached to this object. 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

Defines one file or directory in a data image.

Use this class to create the logical tree of the data image that should be created / burned.

See Also
DataDisc::setImageLayout

Member Function Documentation

virtual DataFileCallback* callback ( ) const
pure virtual

Gets the callback set previously by setCallback.

Returns
A pointer to the callback object or NULL if no callback is set.
See Also
setCallback
virtual DataFileList* children ( ) const
pure virtual

Gets the list of child DataFile objects associated with this file.

Returns
A pointer to a DataFileList object. The returned object is owned by DataFile. It should not be used after the owning DataFile object is released.
virtual DataFile* clone ( bool_t  includeChildren)
pure virtual

Creates a copy of the DataFile object.

The new object will be a root item (i.e. not part of a tree regardless of whether the original object was in a tree or not).

Parameters
includeChildrenIndicates that the children should be included. If set to FALSE children are not included.
Returns
A copy of the DataFile. The new object should be released with the DataFile::release method.
See Also
Object Management
virtual filetime_t creationTime ( ) const
pure virtual

Gets the file creation time.

The time is returned as coordinated universal time (UTC).

Returns
On Windows this is a Win32 FILETIME structure representing the number of 100-nanosecond intervals since January 1, 1601 (UTC). On Mac OS X and Linux this is a POSIX time_t structure representing the number of seconds elapsed since 00:00:00 on January 1, 1970 (UTC).
virtual DataSource::Enum dataSource ( ) const
pure virtual

Gets the file data source.

Returns
A constant from the DataSOurce enumeration.
See Also
DataSource::Enum
DataFile::setStream
DataFile::setDataSource
virtual bool_t directory ( ) const
pure virtual

Indicates if this file is a directory.

Returns
TRUE if the DataFile represents a directory, FALSE if it's a file.
virtual uint32_t discAddress ( ) const
pure virtual

Gets the file relative logical block address.

When data source is set to DataSource::Disc this method returns the address at which the file starts on the disc. For ISO images this method returns the offset at which the file data starts in the image file.

This method can be used together with DataFile::size and Device::readData to read files from a disc or ISO image.

Returns
Logical block address or files offset.
virtual int32_t excludeMask ( )
pure virtual

Gets the file systems from which this file / directory should be excluded.

Returns
A combination of the constants defined in the ImageTypeFlags enumeration.
virtual DataFile* find ( const char_t *  relativePath,
bool_t  caseSensitive = 0 
) const
pure virtual

Finds a file in a file tree.

Parameters
relativePath[in] Relative path of the item. The path must start with "/". This method accepts only a forward slash ("/") for directory delimiter.
caseSensitiveIndicates whether the search should be case sensitive.
Returns
DataFile object that corresponds to the specified relative path.
NULL if an item with the specified relative path does not exists.
NULL if "/" is specified for relativePath.
virtual int32_t hiddenMask ( ) const
pure virtual

Gets the file systems in which this file / directory should be marked as hidden.

Returns
A combination of the constants defined in the ImageTypeFlags enumeration.
virtual const char_t* longFilename ( ) const
pure virtual

Gets the long filename.

The long filename determines how the file will appear in the file tree.

Returns
A null-terminated string containing the long filename or NULL if no long name is set.
virtual bool_t merge ( DataFile source)
pure virtual

Merges two file trees.

The merge method adds and replaces file nodes and adds directory nodes from the source tree to the destination tree. The merge method does not replace directory nodes in the destination tree.

In order for the merge to work both objects should represent directories (see setDirectory) and both objects should have one and the same long filename (see setLongFilename, longFilename).

During the merging the LongFilename property of each node is used to determine whether objects are the same file or not. The name comparison is not case sensitive.

Parameters
source[in] Instance of DataFile, that should be merged into the object on which the merge method is being called.
Returns
1 Success
0 One of the objects is not a directory.
0 The long filenames of the root objects do not match.
virtual DataFile* parent ( ) const
pure virtual

Gets the file parent.

Returns
NULL when this object is the root of a file tree.
NULL when this object is not part of a file tree.
A pointer to the parent DataFile object.
virtual const char_t* path ( ) const
pure virtual

Gets the path which is set with the setPath method.

Returns
A null-terminated string containing the file path or NULL if no path is set.
virtual void setCallback ( DataFileCallback callback)
pure virtual

Sets the callback that receives notifications for this DataFile.

Parameters
callback[in] A pointer to object that implements the DataFileCallback interface.
See Also
callback
virtual void setCreationTime ( filetime_t  filetime)
pure virtual

Sets the file creation time.

The value should be set as coordinated universal time (UTC).

Parameters
filetimeOn Windows this is a Win32 FILETIME structure representing the number of 100-nanosecond intervals since January 1, 1601 (UTC). On Mac OS X and Linux this is a POSIX time_t structure representing the number of seconds elapsed since 00:00:00 on January 1, 1970 (UTC).
virtual void setDataSource ( DataSource::Enum  source)
pure virtual

Sets the file data source.

The default value is DataSource::File.

Parameters
sourceSpecifies the data source.
See Also
DataSource::Enum
DataFile::setDataStream
virtual void setDirectory ( bool_t  directory)
pure virtual

Sets whether DataFile is a directory.

Parameters
directorySpecifies whether the DataFile is a directory.
virtual void setDiscAddress ( uint32_t  address)
pure virtual

Sets the file logical block address.

Parameters
addressLogical block address.
virtual void setExcludeMask ( int32_t  imageTypeFlags)
pure virtual

Sets the file systems from which this file / directory should be excluded.

This allows hybrid layouts to be built, in which some files are present in one file system and not present in another file system.

Parameters
imageTypeFlagsA combination of the constants defined in the ImageTypeFlags enumeration.
Remarks
When set for a directory the entire directory with all its children will be removed from the file system.
virtual void setHiddenMask ( int32_t  imageTypeFlags)
pure virtual

Sets in which file systems this file / directory should be marked as hidden.

Parameters
imageTypeFlagsA combination of the constants defined in the ImageTypeFlags enumeration.
virtual void setLongFilename ( const char_t *  filename)
pure virtual

Sets the long filename.

The long filename determines how the file will appear in the file tree.

Parameters
filenameThis name should not include any path information in it, just the name of the file and it's extension.
virtual void setPath ( const char_t *  filepath)
pure virtual

Sets the full path to the file from which this object should read its data.

Parameters
filepathA null-terminated string or NULL if no path is set.
virtual void setShortFilename ( const char_t *  filename)
pure virtual

Sets the short filename.

Parameters
filename[in] A null-terminated string containing the short filename.
Remarks
The short filename determines how the file will appear in the file tree when the image type is set to ISO9660 and the image constraint is set to ImageConstraintFlags::IsoLength8p3.

This name should not include any path information in it, just the name of the file and its extension. The short name should follow the DOS 8.3 filename convention. The file names and directory names must be 12 characters or less in length.
virtual void setSize ( int64_t  filesize)
pure virtual

Sets the file size in bytes.

This method should be used only if the data source is set to DataSource::ZeroPad. In all other cases the file size is detected automatically.

Parameters
filesizeThe file size in bytes.
virtual void setStream ( primo::Stream stream)
pure virtual

Sets the source stream that should be used to access the file data during the data image creation.

In order for this method to work DataSource::Stream should be set as a data source using the setDataSource method.

Parameters
streamA pointer to an object that implements primo::Stream.
See Also
stream
virtual void setUserData ( void *  userData)
pure virtual

Attaches user defined data to this object.

Parameters
userData[in] A pointer to user data. The application is responsible for managing this data.
virtual const char_t* shortFilename ( ) const
pure virtual

Gets the short filename.

Returns
A null-terminated string containing the short filename or NULL if no short name is set.
virtual int64_t size ( ) const
pure virtual

Gets the file size in bytes.

Returns
file size in bytes.
virtual primo::Stream* stream ( ) const
pure virtual

Gets the source stream that should be used to access the file data during the data image creation.

Returns
A pointer to the stream set by setStream or NULL if no stream is set.
See Also
setStream
virtual UdfFileProps* udfProps ( ) const
pure virtual

Gets an interface for setting and reading UDF file properties.

Returns
A pointer to a UdfFileProps object. The returned object is owned by DataFile. It should not be used after the owning DataFile object is released.
virtual void* userData ( ) const
pure virtual

Gets the user defined data attached to this object.

Returns
A pointer to user data or . The application is responsible for managing this data.