Creating a Multisession Disc
The Image Mastering API (IMAPI) supports the addition and removal of files to, or from, the following multisession disc types:
- CD-R/CD-RW
- Single-Layer DVD+R/DVD-R
- DVD+R Dual Layer
- BD-R
- DVD-RW/DVD+RW (Windows 7 Only)
- DVD-RAM (Windows 7 Only)
- BD-RE (Windows 7 Only)
Creation of a multisession disc using IMAPI consists of the following steps. Each of these documented steps contains the relevant portion of the complete Visual Basic script example provided in the final section.
Initializing the Disc Recorder
Prior to device initialization, the MsftDiscMaster2 object provides an enumeration of the optical devices on the system. The IDiscMaster2 interface provides access to this device enumeration to facilitate the location of the appropriate recording device. The MsftDiscMaster2 object also provides event notifications when optical devices are added to or removed from a machine.
After locating an optical recorder and retrieving the ID assigned to it, create a new MsftDiscMaster2 object and initialize the recorder using the specific device ID.
The IDiscRecorder2 interface provides access to basic device information such as vendor ID, product ID, product revision, as well as the methods to eject media or close the tray.
Note
The additional constants and dimensions declared in the following sample are used later in the complete sample script located in the final section of this document. These elements are not required for the act of initializing a disc recorder.
' *** CD/DVD disc file system types
Const FsiFileSystemISO9660 = 1
Const FsiFileSystemJoliet = 2
Const FsiFileSystemUDF102 = 4
WScript.Quit(Main)
Function Main
Dim Index ' Index to recording drive.
Dim Recorder ' Recorder object
Dim Path ' Directory of files to add
Dim Stream ' Data stream for burning device
Index = 0 ' First drive on the system
Path = "G:\BurnDir" ' Files to add to the disc
' Create a DiscMaster2 object to connect to optical drives.
Dim DiscMaster
Set DiscMaster = WScript.CreateObject("IMAPI2.MsftDiscMaster2")
' Create a DiscRecorder2 object for the specified burning device.
Dim UniqueId
set Recorder = WScript.CreateObject("IMAPI2.MsftDiscRecorder2")
UniqueId = DiscMaster.Item(Index)
Recorder.InitializeDiscRecorder(UniqueId)
Creating a Data Writer
The MsftDiscFormat2Data object provides the writing method, its properties, as well as the media-specific properties. The IDiscFormat2Data interface provides access to this object.
The disc recorder binds to the format writer using the IDiscFormat2Data::put_Recorder property. After the recorder is bound to the format writer, media and write-specific property queries can be performed prior to writing the result image to disc using the IDiscFormat2Data::Write method.
Note
The client name string specified in the sample code below should be adjusted as appropriate for the specific application.
' Create a DiscFormat2Data object and set the recorder
Dim DataWriter
Set DataWriter = CreateObject ("IMAPI2.MsftDiscFormat2Data")
DataWriter.Recorder = Recorder
DataWriter.ClientName = "IMAPIv2 TEST"
Creating the File System Object
In order to record a new session, a burn image must be generated for it first. A burn image for ISO9660, Joliet and UDF formats consist of file systems of individual files and directories. The MsftFileSystemImage object is the file system object that contains the files and directories to be placed on the optical media. The IFileSystemImage interface provides access to the file system object and settings.
' Create a new file system image object
Dim FSI
Set FSI = CreateObject("IMAPI2FS.MsftFileSystemImage")
Importing a File System
Before proceeding, ensure that the disc is not blank by checking the IDiscFormat2::get_MediaHeuristicallyBlank property.
After creating the MsftFileSystemImage object, the IFileSystemImage::put_MultisessionInterfaces property should be initialized prior to a call to either the IFileSystemImage::ImportFileSystem or IFileSystemImage::ImportSpecificFileSystem method to import the file system from the last recorded session. These methods will automatically populate the MsftFileSystemImage object with information describing the previously recorded files and directories.
Note
The IFileSystemImage::put_MultisessionInterfaces property is typically initialized with the multisession interfaces provided by the data writer via the IDiscFormat2Data::get_MultisessionInterfaces property.
Attempts to set the IFileSystemImage::put_MultisessionInterfaces property will fail if IMAPI does not support multisession for the currently inserted media or the media cannot be appended for some other reason (e.g. because it is closed).
If the previous burn session contained more than one file system type, the IFileSystemImage::ImportFileSystem method will import information from the most advanced file system type present. For example, in the example provided in this topic, UDF is the imported file system. However, use of the IFileSystemImage::ImportSpecificFileSystem method allows the specific selection of the file system to import.
Note
The IFileSystemImage::IdentifyFileSystemsOnDisc method can be used to determine which file systems are available on the disc.
' Import the last session, if the disc is not empty, or initialize
' the file system, if the disc is empty
If Not DataWriter.MediaHeuristicallyBlank _
Then
On Error Resume Next
FSI.MultisessionInterfaces = DataWriter.MultisessionInterfaces
If Err.Number <> 0 _
Then
WScript.Echo "Multisession is not supported for this disc"
Main = 1
Exit Function
End If
On Error Goto 0
WScript.Echo "Importing data from the previous session..."
FSI.ImportFileSystem()
Else
FSI.ChooseImageDefaults(Recorder)
End If
Adding or Removing Files to the File System
After creating the file system object and importing the file system from the previous session, call the IFileSystemImage::CreateFileItem and IFileSystemImage::CreateDirectoryItem methods to create new file and directory objects, respectively. The file and directory objects provide specific details about the files and directories. Alternatively, the IFsiDirectoryItem::AddTree method of a directory object, represented via the IFsiDirectoryItem interface, can be used to add existing files and directories from another storage device (i.e. a hard drive).
The event handler update method available for IFileSystemImage identifies the current file being added to the file system image, the number of sectors already copied, and the total number of sectors to be copied.
To remove existing files and directories from the file system, use the IFsiDirectoryItem::Remove and IFsiDirectoryItem::RemoveTree methods of the directory objects represented via the IFsiDirectoryItem interface. The IFileSystemImage::get_Root property is used to get a pointer to the root directory of the file system and the IFsiDirectoryItem interface to traverse through the directory tree.
Note
Files and directories removed via the IFsiDirectoryItem::Remove and IFsiDirectoryItem::RemoveTree methods are not physically removed from the disc, and advanced software can easily recover the deleted information.
' Add the directory and its contents to the file system
WScript.Echo "Adding " & Path & " directory to the disc..."
FSI.Root.AddTree Path, false
Constructing a File System Image
The final step is to call IFileSystemImage::CreateResultImage to create a data stream for the burn image and provide access to it through the IFileSystemImageResult interface. This data stream can either be provided directly to the IDiscFormat2Data::Write method or be saved to a file for later use.
' Create an image from the file system image object
Dim Result
Set Result = FSI.CreateResultImage()
Stream = Result.ImageStream
Example Summary
The following Visual Basic script example shows how to use IMAPI objects to create multisession discs. The example creates a new session and adds a directory to the disc. For the sake of simplicity, the code does not perform extensive error checking, and assumes the following:
- A compatible disc device is installed on the system.
- The disc device is the first drive on the system.
- A compatible disc is inserted in the disc device.
- Files to add to the disc are located in "g:\burndir".
Additional functionality such as extensive error checking, device and media compatibility, event notification, and calculation of free space on the disc can be added to the script.
' This script adds data files from a single directory tree to a
' disc (a new session is added, if the disc already contains data)
' Copyright (C) Microsoft. All rights reserved.
Option Explicit
' *** CD/DVD disc file system types
Const FsiFileSystemISO9660 = 1
Const FsiFileSystemJoliet = 2
Const FsiFileSystemUDF102 = 4
WScript.Quit(Main)
Function Main
Dim Index ' Index to recording drive.
Dim Recorder ' Recorder object
Dim Path ' Directory of files to add
Dim Stream ' Data stream for burning device
Index = 0 ' First drive on the system
Path = "G:\BurnDir" ' Files to add to the disc
' Create a DiscMaster2 object to connect to optical drives.
Dim DiscMaster
Set DiscMaster = WScript.CreateObject("IMAPI2.MsftDiscMaster2")
' Create a DiscRecorder2 object for the specified burning device.
Dim UniqueId
set Recorder = WScript.CreateObject("IMAPI2.MsftDiscRecorder2")
UniqueId = DiscMaster.Item(Index)
Recorder.InitializeDiscRecorder(UniqueId)
' Create a DiscFormat2Data object and set the recorder
Dim DataWriter
Set DataWriter = CreateObject ("IMAPI2.MsftDiscFormat2Data")
DataWriter.Recorder = Recorder
DataWriter.ClientName = "IMAPIv2 TEST"
' Create a new file system image object
Dim FSI
Set FSI = CreateObject("IMAPI2FS.MsftFileSystemImage")
' Import the last session, if the disc is not empty, or initialize
' the file system, if the disc is empty
If Not DataWriter.MediaHeuristicallyBlank _
Then
On Error Resume Next
FSI.MultisessionInterfaces = DataWriter.MultisessionInterfaces
If Err.Number <> 0 _
Then
WScript.Echo "Multisession is not supported for this disc"
Main = 1
Exit Function
End If
On Error Goto 0
WScript.Echo "Importing data from the previous session..."
FSI.ImportFileSystem()
Else
FSI.ChooseImageDefaults(Recorder)
End If
' Add the directory and its contents to the file system
WScript.Echo "Adding " & Path & " directory to the disc..."
FSI.Root.AddTree Path, false
' Create an image from the file system image object
Dim Result
Set Result = FSI.CreateResultImage()
Stream = Result.ImageStream
' Write stream to disc using the specified recorder
WScript.Echo "Writing content to the disc..."
DataWriter.Write(Stream)
WScript.Echo "Finished writing content."
Main = 0
End Function
Related topics