Burning a Disc Image

Mastering (burning a disc) using IMAPI consists of the following steps:

1. Construct a file system image that contains the directories and files to write disc.
2. Set up a disc recorder to communicate with the optical device.
3. Create a data writer and burn the image to disc.

For an example that burns a disc image, see VBScript example.

Construct a burn image

A burn image is a data stream that is ready to be written to optical media. The burn image for ISO9660, Joliet and UDF formats consists of a file system of individual files and directories. The CFileSystemImage object is the file system object that holds the files and directories to place on the optical media. The IFileSystemImage interface provides access to the file system object and settings.

After creating the file system object, call the IFileSystemImage::CreateFileItem and IFileSystemImage::CreateDirectoryItem methods to create the file and directory objects, respectively. The file and directory objects can be used to provide specific details about the file and directory. The event handler methods available for IFileSystemImage can identify 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.

Optionally, a boot image can be attached to the file system using the IFileSystemImage::put_BootImageOptions property. For an example, see Adding a Boot Image.

Finally, call IFileSystemImage::CreateResultImage to create a data stream and provides access through IFileSystemImageResult. The new data stream can then be provided directly to the IDiscFormat2Data::Write method or be saved to a file for later use.

Set up a disc recorder

The MsftDiscMaster2 object provides an enumeration of the optical devices on the system. The IDiscMaster2 interface provides access to the resultant device enumeration. Traverse the enumerations to locate an appropriate recording device. The MsftDiscMaster2 object also provides event notifications when optical devices are added to or deleted from a computer.

After finding an optical recorder and retrieving its ID, create an MsftDiscRecorder2 object and initialize the recorder using the device ID. The IDiscRecorder2 interface provides access to the recorder object as well as some basic device information such as vendor ID, product ID, product revision, and methods to eject the media and close the tray.

Create a data writer and write the burn image

The MsftDiscFormat2Data object provides the writing method, the properties about the write function and media-specific properties. The IDiscFormat2Data interface provides access to the MsftDiscFormat2Data object.

The disc recorder links to the format writer using the IDiscFormat2Data::put_Recorder property. After the recorder is bound to the format writer, you can perform queries regarding the media and update write-specific properties before writing the result image to disc using the IDiscFormat2Data::Write method.

Other format writing interfaces provided by IMAPI work similarly; additional format writing interfaces include:

• IDiscFormat2Erase erases rewritable optical media.
• IDiscFormat2RawCD writes a raw image to optical media.
• IDiscFormat2TrackAtOnce writes audio tracks to optical media.

VBScript example

This script example shows how to use the IMAPI objects to burn optical media; more specifically, write a directory to a blank disc. The code contains no error checking, and assumes the following:

• A compatible disc device is installed on the system.
• The disc device is the second drive on the system.
• A compatible disc is inserted in the disc device.
• The disc is blank.
• Files to write to disc are located in "g:\burndir".

Additional functionality such as error checking, device and media compatibility, event notification, and calculating free space on the disc can be added to this script.

' This script burns data files to disc in a single session 
' using files from a single directory tree.
 
' Copyright (C) Microsoft Corp. 2006

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 burn
    Dim Stream               ' Data stream for burning device
    
    Index = 1                ' Second drive on the system
    Path = "g:\BurnDir"      ' Files to transfer to disc

    ' Create a DiscMaster2 object to connect to optical drives.
    Dim g_DiscMaster
    Set g_DiscMaster = WScript.CreateObject("IMAPI2.MsftDiscMaster2")

    ' Create a DiscRecorder object for the specified burning device.
    Dim uniqueId
    set recorder = WScript.CreateObject("IMAPI2.MsftDiscRecorder2")
    uniqueId = g_DiscMaster.Item(index)
    recorder.InitializeDiscRecorder( uniqueId )

    ' Create an image stream for a specified directory.
    Dim FSI                  ' Disc file system
    Dim Dir                  ' Root directory of the disc file system
    Dim dataWriter    
        
    ' Create a new file system image and retrieve root directory
    Set FSI = CreateObject("IMAPI2FS.MsftFileSystemImage")
    Set Dir = FSI.Root

    'Create the new disc format and set the recorder
    Set dataWriter = CreateObject ("IMAPI2.MsftDiscFormat2Data")
    dataWriter.recorder = Recorder
    dataWriter.ClientName = "IMAPIv2 TEST"

    FSI.ChooseImageDefaults(recorder)
        
    ' Add the directory and its contents to the file system 
    Dir.AddTree Path, false
        
    ' Create an image from the file system
    Dim result
    Set result = FSI.CreateResultImage()
    Stream = result.ImageStream
    
    ' Write stream to disc using the specified recorder.
    WScript.Echo "Writing content to disc..."
    dataWriter.write(Stream)

    WScript.Echo "----- Finished writing content -----"
    Main = 0
End Function

Related topics

Using IMAPI

IDiscFormat2Data

IDiscFormat2Erase

IDiscFormat2RawCD

IDiscFormat2TrackAtOnce

IDiscMaster2

IDiscRecorder2

IFileSystemImage

IStream