StarBurn SDK (Software Development Kit)
ContentsIndexHome
PreviousUpNext
StarBurn_ISO9660JolietFileTree_AddMemory Function
C++
__stdcall STARBURN_IMPEX_API EXCEPTION_NUMBER StarBurn_ISO9660JolietFileTree_AddMemory(IN PVOID p__PVOID__ISO9660JolietFileTree, OUT PCHAR p__PCHAR__ExceptionText, IN ULONG p__ULONG__ExceptionTextSizeInUCHARs, OUT PULONG p__PULONG__SystemError, IN PUCHAR p__PUCHAR__MemoryRegion, IN LARGE_INTEGER p__LARGE_INTEGER__MemoryRegionSizeInUCHARs, IN PCHAR p__PCHAR__Name, IN FILE_TIME p__FILE_TIME, IN PVOID * p__PPVOID__ISO9660JolietFileTreeNode__Parent, OUT PVOID * p__PPVOID__ISO9660JolietFileTreeNode__NewChild);
Parameters 
Description 
IN PVOID p__PVOID__ISO9660JolietFileTree 
Pointer to the ISO9660 or Joliet file tree object.
 
OUT PCHAR p__PCHAR__ExceptionText 
Pointer to array of CHARs that will be used to store formatted exception description message.
 
IN ULONG p__ULONG__ExceptionTextSizeInUCHARs 
Size of the array of CHARs used to be formatted exception message storage.
 
OUT PULONG p__PULONG__SystemError 
Pointer to ULONG that will contain the system error (if some will occur).
 
IN PUCHAR p__PUCHAR__MemoryRegion 
Pointer to memory region to create node from.
 
IN LARGE_INTEGER p__LARGE_INTEGER__MemoryRegionSizeInUCHARs 
Memory region size in UCHARs.
 
IN FILE_TIME p__FILE_TIME 
File time that will be included in file system image (See FILE_TIME).
 
IN PVOID * p__PPVOID__ISO9660JolietFileTreeNode__Parent 
Pointer to pointer to the file tree node we'll use as parent. This is the result of either tree walking with StarBurn_ISO9660JolietFileTree_GetFirstKid() or StarBurn_ISO9660JolietFileTree_GetNextKid() or the result of call to StarBurn_ISO9660JolietFileTree_GetRoot(). NULL can be passed instead of the result of StarBurn_ISO9660JolietFileTree_GetRoot().
 
OUT PVOID * p__PPVOID__ISO9660JolietFileTreeNode__NewChild 
Pointer to pointer to the new created file tree node. 
p__PCHAR__RootDirectoryNewName 
Pointer to directory name to be stored in the ISO9660 or Joliet image as root name. Cannot be NULL in this case!
 

Execution status. EN_SUCCESS if the tree was reallocated successfuly, E_MEMORY_ALLOCATION_FAILED if there is not enough memory to reallocate the tree. If the exception number will be EN_SYSTEM_CALL_FAILED, variable that SystemError points to will be filled with system error. If something other then EN_SUCCESS will be returned buffer that ExceptionText will point to will be filled with formatted exception message.

This function adds the node created from the memory to already created ISO9660 or Joliet file tree from passed directory. Later this tree can be used to build "virtual" ISO96600 or Joliet file system image. Resulting "virtual" image can be either stored in the file on the disk or be burn directly to the CD/DVD/Blu-Ray/HD-DVD media w/o any other intermediate operations.

Please see the BuildImage sample that will demonstrate how memory node can be added to already created ISO9660 or Joliet file tree, progress indication can be build and what parameters in general are passed into the callback function during the operations with file tree object.

This example allocates Joliet file tree, adds memory node to it and destroys it after it's not needed any more. 

 

// Somewhere in the data region
PVOID l__PVOID__FileTree;
EXCEPTION_NUMBER l__EXCEPTION_NUMBER;
ULONG l__ULONG__TreeNodes;
ULONG l__ULONG__SystemError;
CHAR l__CHAR__ExceptionText[ 1024 ];
PVOID l__PVOID__Root;
UCHAR l__UCHAR__MemoryNode[ 4096 ];
LARGE_INTEGER l__LARGE_INTEGER__MemoryNodeSizeInUCHARs;

// Prepare exception text buffer
RtlZeroMemory(
    &l__CHAR__ExceptionText,
    sizeof( l__CHAR__ExceptionText )
    );

// Try to create Joliet file tree
l__EXCEPTION_NUMBER =
StarBurn_ISO9660JolietFileTree_Create(
    &l__PVOID__FileTree,
    ( PCHAR )( &l__CHAR__ExceptionText ),
    sizeof( l__CHAR__ExceptionText ),
    &l__ULONG__Status,
    ( PCALLBACK )( Callback ),
    ( PVOID )( &l__LONG__TreeNodes ),
    TRUE,
    FALSE,
    FILE_TREE_JOLIET
    );

// Check for correct reply
if (  l__EXCEPTION_NUMBER != EN_SUCCESS )
{
// Handle error here...
}

// Try to get root here
l__PVOID__Root =
StarBurn_ISO9660JolietFileTree_GetRoot( l__PVOID__FileTree );

// Check for correct reply
if ( l__PVOID__Root == NULL )
{
// Handle error here, keep in mind that root CAN be NULL if nothing was added to tree before...
}

// Try to add all from the root directory of the drive D: to already created Joliet file tree
l__EXCEPTION_NUMBER =
StarBurn_ISO9660JolietFileTree_Add(
    l__PVOID__FileTree,
    ( PCHAR )( &l__CHAR__ExceptionText ),
    sizeof( l__CHAR__ExceptionText ),
    &l__ULONG__Status,
    "D:\",
    NULL,
    FILE_TIME_LAST_WRITE,
    &l__PVOID__Root,
    &l__PVOID__NewNode
    );

// Check for correct reply
if (  l__EXCEPTION_NUMBER != EN_SUCCESS )
{
// Handle error here...
}

// Prepare memory node memory
RtlZeroMemory(
    &l__UCHAR__MemoryNode,
    sizeof( l__UCHAR__MemoryNode )
    );

// Format memory node here and store all required data into l__UCHAR__MemoryNode buffer

// Set size of memory node
l__LARGE_INTEGER__MemoryNodeSizeInUCHARs.QuadPart = sizeof( l__UCHAR__MemoryNode );

// Try to add memory node as "MemoryNodeName" to already created Joliet file tree
l__EXCEPTION_NUMBER =
StarBurn_ISO9660JolietFileTree_AddMemory(
    l__PVOID__FileTree,
    ( PCHAR )( &l__CHAR__ExceptionText ),
    sizeof( l__CHAR__ExceptionText ),
    &l__ULONG__Status,
    ( PUCHAR )( &l__UCHAR__MemoryNode ),
    l__LARGE_INTEGER__MemoryNodeSizeInUCHARs,
    "MemoryNodeName",
    FILE_TIME_LAST_WRITE,
    &l__PVOID__Root,
    &l__PVOID__NewNode
    );

// Check for correct reply
if (  l__EXCEPTION_NUMBER != EN_SUCCESS )
{
// Handle error here...
}

// Perform actions with Joliet tree here...

// Destroy the Joliet file tree
StarBurn_Destroy( &l__PVOID__FileTree );

// Just check for pointer (paranoid?)
if ( l__PVOID__FileTree != NULL )
{
// Handle error here...
}