Image Mastering API

https://learn.microsoft.com/en-us/windows/win32/imapi
Admin
IMAPI enables the creation of optical media using a variety of file systems, supporting features...
Tokens:13,414
Snippets:131
Trust Score:10
Update:3 months ago
Show doc for...
Tokens:
Raw
### Burn a boot image and data files to disc

Source: https://learn.microsoft.com/en-us/windows/win32/imapi/adding-a-boot-image

This VBScript example initializes a disc recorder, configures boot options with a binary stream from a boot file, and writes the resulting file system image to a disc.

```vb
' This script burns a boot image and 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 FsiFileSystemUDF  = 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
    Dim bootFile             ' Path and filename of boot image
    
    index = 1                ' Second drive on the system
    path = "g:\BurnDir"      
    bootFile = "g:\BootImg\etfsboot.com"

    ' Create a DiscMaster2 object to connect to CD/DVD 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 )

    ' -------- Adding Boot Image Code -----
    Dim bootOptions    
    WScript.Echo "Creating BootOptions"
    SET bootOptions = WScript.CreateObject("IMAPI2FS.BootOptions")
    bootOptions.Manufacturer = "Microsoft"
    bootOptions.PlatformId   = 0       ' x86 processor
    bootOptions.Emulation    = 0       ' EmulationType.EmulationNone
    
    ' Need a stream for the boot image file 
    Const adFileTypeBinary = 1
    DIM bootStream
    Set bootStream = CreateObject("ADODB.Stream")
    WScript.Echo "Creating IStream for file " + bootFile
    bootStream.Open
    bootStream.Type = adFileTypeBinary
    bootStream.LoadFromFile bootFile
    bootOptions.AssignBootImage(bootStream)
    
    ' Create disc file system image (ISO9660 in this example)
    Dim FSI
    SET FSI = WScript.CreateObject("IMAPI2FS.MsftFileSystemImage")
    FSI.ChooseImageDefaults(Recorder)
   
    ' Add the boot directory and its contents to the file system 
    FSI.BootImageOptions = bootOptions

    ' Add the content directory and files to the file system 
    FSI.root.AddTree path, FALSE

    Dim result
    Set result = FSI.CreateResultImage()
    stream = result.ImageStream

    ' Create and write stream to disc using the specified recorder.
    Dim dataWriter
    Set dataWriter = CreateObject("IMAPI2.MsftDiscFormat2Data")
    dataWriter.recorder = Recorder
    dataWriter.ClientName = "IMAPIv2 TEST"

    dataWriter.write(stream)
    WScript.Echo "----- Finished writing content -----"

    Main = 0
End Function
```

--------------------------------

### Initialize a Disc Recorder with IMAPI

Source: https://learn.microsoft.com/en-us/windows/win32/imapi/creating-a-multisession-disc

Initializes a disc recorder using the MsftDiscMaster2 and MsftDiscRecorder2 objects. This setup is required before adding files to a multisession disc.

```vb
' *** 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)
```

--------------------------------

### Connect Event Handler using WScript.CreateObject

Source: https://learn.microsoft.com/en-us/windows/win32/imapi/monitoring-progress-with-events

Demonstrates an alternative approach to instantiate an object and connect its event handler in a single step.

```vb
    ' Create object and connect the event handler in one step.
    '   Set dataWriter = _
    '   WScript.CreateObject("IMAPI2.MsftDiscFormat2Data","dwBurnEvent_")


' Event handler  
SUB dwBurnEvent_Update( byRef object, byRef progress )
    '--- Other code occurs here. 
END SUB
```

--------------------------------

### Create a Data Writer

Source: https://learn.microsoft.com/en-us/windows/win32/imapi/creating-a-multisession-disc

Initializes the MsftDiscFormat2Data object and binds it to a recorder.

```VB
    ' Create a DiscFormat2Data object and set the recorder
    Dim DataWriter
    Set DataWriter = CreateObject ("IMAPI2.MsftDiscFormat2Data")
    DataWriter.Recorder = Recorder
    DataWriter.ClientName = "IMAPIv2 TEST"
```

--------------------------------

### Import a File System

Source: https://learn.microsoft.com/en-us/windows/win32/imapi/creating-a-multisession-disc

Imports the file system from the last recorded session if the disc is not blank, or initializes defaults for a blank disc.

```VB
    ' 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
```

--------------------------------

### Examine Disc Device Characteristics with VBScript

Source: https://learn.microsoft.com/en-us/windows/win32/imapi/checking-drive-support

This script initializes a DiscRecorder object to query and output hardware-specific information such as vendor ID, supported features, and profiles.

```vb
' This script examines the burn device characteristics such as 
' product ID, product revision level, feature set, and profiles. 

' Copyright (C) Microsoft Corp. 2006

Option Explicit

' Constants
const IMAPI_FEATURE_PAGE_TYPE_DVD_DASH_WRITE = 47

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

    ' Create a DiscMaster2 object to connect to CD/DVD 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 )

    ' *** - Formatting to display recorder info
    WScript.Echo "--------------------------------------------------"
    Wscript.Echo " ActiveRecorderId: " & recorder.ActiveDiscRecorder
    Wscript.Echo "        Vendor Id: " & recorder.VendorId
    Wscript.Echo "       Product Id: " & recorder.ProductId
    Wscript.Echo " Product Revision: " & recorder.ProductRevision
    Wscript.Echo "       VolumeName: " & recorder.VolumeName
    Wscript.Echo "   Can Load Media: " & recorder.DeviceCanLoadMedia
    Wscript.Echo "    Device Number: " & recorder.LegacyDeviceNumber

    Dim mountPoint
    For Each mountPoint In recorder.VolumePathNames
        WScript.Echo "      Mount Point: " & mountPoint
    Next

    WScript.Echo "Supported Features"  'in _IMAPI_FEATURE_PAGE_TYPE 
    Dim supportedFeature
    For Each supportedFeature  in recorder.SupportedFeaturePages
        if supportedFeature = _
            IMAPI_FEATURE_PAGE_TYPE_DVD_DASH_WRITE then
                WScript.Echo "    Feature: " & supportedFeature & _
                    "  Drive supports DVD-RW."
        else
                     WScript.Echo "    Feature: " & supportedFeature
        end if
    Next
    
    WScript.Echo "Current Features"    'in _IMAPI_FEATURE_PAGE_TYPE
    Dim currentFeature
    For Each currentFeature  in recorder.CurrentFeaturePages
        WScript.Echo "    Feature: " & currentFeature
    Next
    
    WScript.Echo "Supported Profiles"  'in _IMAPI_PROFILE_TYPE
    Dim supportedProfile
    For Each supportedProfile  in recorder.SupportedProfiles
        WScript.Echo "    Profile: " & supportedProfile
    Next

    WScript.Echo "Current Profiles"    'in _IMAPI_PROFILE_TYPE
    Dim currentProfile
    For Each currentProfile    in recorder.CurrentProfiles
        WScript.Echo "    Profile: " & currentProfile
    Next
    
    WScript.Echo "Supported Mode Pages"  'in  _IMAPI_MODE_PAGE_TYPE
    Dim supportedModePage       
    For Each supportedModePage in recorder.SupportedModePages
        WScript.Echo "    Mode Page: " & supportedModePage
    Next

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

--------------------------------

### Check Media and Recorder Compatibility in VBScript

Source: https://learn.microsoft.com/en-us/windows/win32/imapi/checking-media-support

This script initializes a disc recorder, verifies if the recorder and media are supported, and checks the current media status using IMAPI2 constants.

```vb
' This script examines characteristics of the media loaded in the disc device.

' Copyright (C) Microsoft Corp. 2006

Option Explicit

' *** IMAPI2 Media Types 
Const IMAPI_MEDIA_TYPE_UNKNOWN            = 0  ' Media not present OR
                                               ' is unrecognized
Const IMAPI_MEDIA_TYPE_CDROM              = 1  ' CD-ROM
Const IMAPI_MEDIA_TYPE_CDR                = 2  ' CD-R
Const IMAPI_MEDIA_TYPE_CDRW               = 3  ' CD-RW
Const IMAPI_MEDIA_TYPE_DVDROM             = 4  ' DVD-ROM
Const IMAPI_MEDIA_TYPE_DVDRAM             = 5  ' DVD-RAM
Const IMAPI_MEDIA_TYPE_DVDPLUSR           = 6  ' DVD+R
Const IMAPI_MEDIA_TYPE_DVDPLUSRW          = 7  ' DVD+RW
Const IMAPI_MEDIA_TYPE_DVDPLUSR_DUALLAYER = 8  ' DVD+R dual layer
Const IMAPI_MEDIA_TYPE_DVDDASHR           = 9  ' DVD-R
Const IMAPI_MEDIA_TYPE_DVDDASHRW          = 10 ' DVD-RW
Const IMAPI_MEDIA_TYPE_DVDDASHR_DUALLAYER = 11 ' DVD-R dual layer
Const IMAPI_MEDIA_TYPE_DISK               = 12 ' Randomly writable

' *** IMAPI2 Data Media States
Const IMAPI_FORMAT2_DATA_MEDIA_STATE_UNKNOWN            = 0
Const IMAPI_FORMAT2_DATA_MEDIA_STATE_INFORMATIONAL_MASK = 15    
Const IMAPI_FORMAT2_DATA_MEDIA_STATE_UNSUPPORTED_MASK   = 61532 '0xfc00
Const IMAPI_FORMAT2_DATA_MEDIA_STATE_OVERWRITE_ONLY     = 1
Const IMAPI_FORMAT2_DATA_MEDIA_STATE_BLANK              = 2
Const IMAPI_FORMAT2_DATA_MEDIA_STATE_APPENDABLE         = 4     
Const IMAPI_FORMAT2_DATA_MEDIA_STATE_FINAL_SESSION      = 8
Const IMAPI_FORMAT2_DATA_MEDIA_STATE_DAMAGED            = 1024 '0x400
Const IMAPI_FORMAT2_DATA_MEDIA_STATE_ERASE_REQUIRED     = 2048 '0x800
Const IMAPI_FORMAT2_DATA_MEDIA_STATE_NON_EMPTY_SESSION  = 4096 '0x1000
Const IMAPI_FORMAT2_DATA_MEDIA_STATE_WRITE_PROTECTED    = 8192 '0x2000
Const IMAPI_FORMAT2_DATA_MEDIA_STATE_FINALIZED          = 16384 '0x4000
Const IMAPI_FORMAT2_DATA_MEDIA_STATE_UNSUPPORTED_MEDIA  = 32768 '0x8000


WScript.Quit(Main)

Function Main
    Dim Index                ' Index to recording drive.
    Dim recorder             ' Recorder object
    Dim Stream               ' Data stream for burning device
    
    Index = 1                ' Second drive on the system

    ' Create a DiscMaster2 object to connect to CD/DVD 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 )

    ' Define the new disc format and set the recorder
    Dim dataWriter
    Set dataWriter = CreateObject ("IMAPI2.MsftDiscFormat2Data")
    dataWriter.recorder = recorder

    Dim boolResult
    boolResult = dataWriter.IsRecorderSupported(recorder)
    If boolResult = True then
        WScript.Echo "--- Current recorder IS supported. ---"
    else
        WScript.Echo "Current recorder IS NOT supported."
    end if

    boolResult = dataWriter.IsCurrentMediaSupported(recorder)
    If boolResult = True then
        WScript.Echo "--- Current media IS supported. ---"
    else
        WScript.Echo "Current media IS NOT supported."
    end if

    WScript.Echo "ClientName = " & dataWriter.ClientName

    ' Check a few CurrentMediaStatus possibilities. Each status
    ' is associated with a bit and some combinations are legal.
    Dim curMediaStatus
    curMediaStatus = dataWriter.CurrentMediaStatus
    WScript.Echo "Checking Current Media Status"
    
    if IMAPI_FORMAT2_DATA_MEDIA_STATE_UNKNOWN AND curMediaStatus then
        WScript.Echo "    Media state is unknown."
    end if
```

--------------------------------

### Create a File System Object

Source: https://learn.microsoft.com/en-us/windows/win32/imapi/creating-a-multisession-disc

Instantiates the MsftFileSystemImage object to manage files and directories for the burn image.

```VB
    ' Create a new file system image object
    Dim FSI
    Set FSI = CreateObject("IMAPI2FS.MsftFileSystemImage")
```

--------------------------------

### Multisession Disc Creation Script

Source: https://learn.microsoft.com/en-us/windows/win32/imapi/creating-a-multisession-disc

A complete script that initializes a recorder, imports existing sessions if present, adds a directory tree, and writes the resulting stream to the disc.

```VB
' 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
```

--------------------------------

### Add a directory to the file system using VB

Source: https://learn.microsoft.com/en-us/windows/win32/imapi/creating-a-multisession-disc

Uses the AddTree method to include a directory and its contents in the file system image.

```vb
    ' Add the directory and its contents to the file system 
    WScript.Echo "Adding " & Path & " directory to the disc..."
    FSI.Root.AddTree Path, false
```

--------------------------------

### Burn a directory to disc using VBScript

Source: https://learn.microsoft.com/en-us/windows/win32/imapi/burning-a-disc

This script initializes a disc recorder and writes the contents of a specified directory to a blank disc. It assumes a compatible drive is available at index 1 and the source files are located at 'g:\burndir'.

```VBScript
' 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
```

--------------------------------

### Monitor Disc Burning Progress with VBScript

Source: https://learn.microsoft.com/en-us/windows/win32/imapi/monitoring-progress-with-events

This script initializes a disc recorder, creates a file system image, and attaches an event handler to monitor the writing process. The event handler provides status updates based on the current action reported by the IMAPI_FORMAT2_DATA_WRITE_ACTION enumerations.

```vb
' 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

' *** IFormat2Data Write Action Enumerations
Const IMAPI_FORMAT2_DATA_WRITE_ACTION_VALIDATING_MEDIA      = 0
Const IMAPI_FORMAT2_DATA_WRITE_ACTION_FORMATTING_MEDIA      = 1
Const IMAPI_FORMAT2_DATA_WRITE_ACTION_INITIALIZING_HARDWARE = 2
Const IMAPI_FORMAT2_DATA_WRITE_ACTION_CALIBRATING_POWER     = 3
Const IMAPI_FORMAT2_DATA_WRITE_ACTION_WRITING_DATA          = 4
Const IMAPI_FORMAT2_DATA_WRITE_ACTION_FINALIZATION          = 5
Const IMAPI_FORMAT2_DATA_WRITE_ACTION_COMPLETED             = 6
const IMAPI_FORMAT2_DATA_WRITE_ACTION_VERIFYING             = 7

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 = "c:\test\imt\data\2tracks"      ' Files to transfer to disc

    ' Create a DiscMaster2 object to connect to CD/DVD 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

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

    FSI.FreeMediaBlocks = dataWriter.FreeSectorsOnMedia
    FSI.FileSystemsToCreate = FsiFileSystemISO9660

    ' 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
    
    ' Attach event handler to the data writing object.
    WScript.ConnectObject  dataWriter, "dwBurnEvent_"

    ' Specify the recorder and write the stream to disc.
    WScript.Echo "Writing content to disc..."
    dataWriter.write(Stream)

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

' Event handler - Progress updates when writing data

SUB dwBurnEvent_Update( byRef object, byRef progress )
    DIM strTimeStatus
    strTimeStatus = "Time: " & progress.ElapsedTime & _
        " / " & progress.TotalTime
   
    SELECT CASE progress.CurrentAction
    CASE IMAPI_FORMAT2_DATA_WRITE_ACTION_VALIDATING_MEDIA
        WScript.Echo "Validating media " & strTimeStatus

    CASE IMAPI_FORMAT2_DATA_WRITE_ACTION_FORMATTING_MEDIA
        WScript.Echo "Formatting media " & strTimeStatus
        
    CASE IMAPI_FORMAT2_DATA_WRITE_ACTION_INITIALIZING_HARDWARE
        WScript.Echo "Initializing Hardware " & strTimeStatus

    CASE IMAPI_FORMAT2_DATA_WRITE_ACTION_CALIBRATING_POWER
        WScript.Echo "Calibrating Power (OPC) " & strTimeStatus

    CASE IMAPI_FORMAT2_DATA_WRITE_ACTION_WRITING_DATA
        DIM totalSectors, writtenSectors, percentDone
        totalSectors = progress.SectorCount
        writtenSectors = progress.LastWrittenLba - progress.StartLba
        percentDone = FormatPercent(writtenSectors/totalSectors)
        WScript.Echo "Progress:  " & percentDone & "  " & strTimeStatus

    CASE IMAPI_FORMAT2_DATA_WRITE_ACTION_FINALIZATION
        WScript.Echo "Finishing the writing " & strTimeStatus
    
    CASE IMAPI_FORMAT2_DATA_WRITE_ACTION_COMPLETED
        WScript.Echo "Completed the burn."

    CASE IMAPI_FORMAT2_DATA_WRITE_ACTION_VERIFYING
        WScript.Echo "Verifying the data."

    CASE ELSE
        WScript.Echo "Unknown action: " & progress.CurrentAction
    END SELECT
END SUB
```

--------------------------------

### Connect Event Handler using WScript.ConnectObject

Source: https://learn.microsoft.com/en-us/windows/win32/imapi/monitoring-progress-with-events

Uses WScript.ConnectObject to attach a subroutine as an event handler to an existing MsftDiscFormat2Data object.

```vb
    ' Create the MsftDiscFormat2Data object (see the IDiscFormat2Data interface).
    Set dataWriter = CreateObject ("IMAPI2.MsftDiscFormat2Data")

    ' Attach event handler (see the DDiscFormat2DataEvents interface).
    ' The "dwBurnEvent_" parameter identifies the handler (see the 
    ' dwBurnEvent_Update subroutine).
    WScript.ConnectObject  dataWriter, "dwBurnEvent_"

' Event handler for the MsftDiscFormat2Data.Write method.
' For details of the subroutine's parameters, see the 
' DDiscFormat2DataEvents::Update method.
SUB dwBurnEvent_Update( byRef object, byRef progress )
    ' --- Other code occurs here. 
END SUB
```

--------------------------------

### IEnumProgressItems::RemoteNext Syntax

Source: https://learn.microsoft.com/en-us/windows/win32/imapi/ienumprogressitems-remotenext

The method signature for retrieving progress items in a remote enumeration sequence.

```C++
HRESULT RemoteNext(
  [in]  ULONG         celt,
  [out] IProgressItem **rgelt,
  [out] ULONG         *pceltFetched
);
```

--------------------------------

### Check Media Status and Type in VBScript

Source: https://learn.microsoft.com/en-us/windows/win32/imapi/checking-media-support

Evaluates the current media state using bitwise flags and identifies the physical media type via a helper subroutine.

```vbscript
    if IMAPI_FORMAT2_DATA_MEDIA_STATE_OVERWRITE_ONLY AND curMediaStatus then
        WScript.Echo "    Currently, only overwriting is supported."
    end if
    
    if IMAPI_FORMAT2_DATA_MEDIA_STATE_APPENDABLE AND curMediaStatus then
        WScript.Echo "    Media is currently appendable."
    end if
    
    if IMAPI_FORMAT2_DATA_MEDIA_STATE_FINAL_SESSION AND curMediaStatus then
        WScript.Echo "    Media is in final writing session."
    end if
    
    if IMAPI_FORMAT2_DATA_MEDIA_STATE_DAMAGED AND curMediaStatus then
        WScript.Echo "    Media is damaged."
    end if
    
    Dim mediaType
    mediaType = dataWriter.CurrentPhysicalMediaType
    WScript.Echo "Current Media Type"
    DisplayMediaType(MediaType)

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

Sub DisplayMediaType(dMediaType)
    Select Case dmediaType 
        Case IMAPI_MEDIA_TYPE_UNKNOWN
            WScript.Echo "    Empty device or an unknown disc type."
        
        Case IMAPI_MEDIA_TYPE_CDROM
            WScript.Echo "    CD-ROM"
        
        Case IMAPI_MEDIA_TYPE_CDR
            WScript.Echo "    CD-R"
        
        Case IMAPI_MEDIA_TYPE_CDRW
            WScript.Echo "    CD-RW"
        
        Case IMAPI_MEDIA_TYPE_DVDROM
            WScript.Echo "    Read-only DVD drive and/or disc"
        
        Case IMAPI_MEDIA_TYPE_DVDRAM
            WScript.Echo "    DVD-RAM"
        
        Case IMAPI_MEDIA_TYPE_DVDPLUSR
            WScript.Echo "    DVD+R"
        
        Case IMAPI_MEDIA_TYPE_DVDPLUSRW
            WScript.Echo "    DVD+RW"
        
        Case IMAPI_MEDIA_TYPE_DVDPLUSR_DUALLAYER
            WScript.Echo "    DVD+R Dual Layer media"
        
        Case IMAPI_MEDIA_TYPE_DVDDASHR
            WScript.Echo "    DVD-R"
        
        Case IMAPI_MEDIA_TYPE_DVDDASHRW
            WScript.Echo "    DVD-RW"
        
        Case IMAPI_MEDIA_TYPE_DVDDASHR_DUALLAYER
            WScript.Echo "    DVD-R Dual Layer media"
        
        Case IMAPI_MEDIA_TYPE_DISK
            WScript.Echo "    Randomly-writable, hardware-defect " _
                + "managed media type "
            WScript.Echo "    that reports the ""Disc"" profile " _
                + "as current."
        End Select
End Sub
```

--------------------------------

### Create a Result Image

Source: https://learn.microsoft.com/en-us/windows/win32/imapi/creating-a-multisession-disc

Generates a data stream from a file system image object for use with a burning device.

```VB
    ' Create an image from the file system image object
    Dim Result
    Set Result = FSI.CreateResultImage()
    Stream = Result.ImageStream
```

--------------------------------

### IEnumFsiItems::RemoteNext Syntax

Source: https://learn.microsoft.com/en-us/windows/win32/imapi/ienumfsiitems-remotenext

The method signature for retrieving items in an enumeration sequence.

```C++
HRESULT RemoteNext(
  [in]  ULONG    celt,
  [out] IFsiItem **rgelt,
  [out] ULONG    *pceltFetched
);
```

--------------------------------

### HRESULT RemoteNext(ULONG celt, IProgressItem **rgelt, ULONG *pceltFetched)

Source: https://learn.microsoft.com/en-us/windows/win32/imapi/ienumprogressitems-remotenext

Retrieves a specified number of items in the enumeration sequence.

```APIDOC
## HRESULT RemoteNext(ULONG celt, IProgressItem **rgelt, ULONG *pceltFetched)

### Description
Retrieves a specified number of items in the enumeration sequence for a remote client.

### Parameters
- **celt** (ULONG) - [in] Number of items to retrieve.
- **rgelt** (IProgressItem**) - [out] Array of IProgressItem interfaces. You must release each interface in rgelt when done.
- **pceltFetched** (ULONG*) - [out] Number of elements returned in rgelt. You can set pceltFetched to NULL if celt is one. Otherwise, initialize the value of pceltFetched to 0 before calling this method.

### Return Value
- **S_OK**: Returned when the number of requested elements are returned successfully or the number of returned items is less than the number of requested elements.
- **E_POINTER**: Pointer is not valid.
- **E_OUTOFMEMORY**: Failed to allocate the required memory.
- **E_INVALIDARG**: One or more arguments are not valid.
- **E_UNEXPECTED**: An unexpected failure occurred.
```

--------------------------------

### IEnumFsiItems::RemoteNext

Source: https://learn.microsoft.com/en-us/windows/win32/imapi/ienumfsiitems-remotenext

Retrieves a specified number of items in the enumeration sequence.

```APIDOC
## HRESULT RemoteNext(ULONG celt, IFsiItem **rgelt, ULONG *pceltFetched)

### Description
Retrieves a specified number of items in the enumeration sequence for a remote client.

### Parameters
- **celt** (ULONG) - [in] Number of items to retrieve.
- **rgelt** (IFsiItem**) - [out] Array of IFsiItem interfaces. You must release each interface in rgelt when done.
- **pceltFetched** (ULONG*) - [out] Number of elements returned in rgelt. You can set pceltFetched to NULL if celt is one. Otherwise, initialize the value of pceltFetched to 0 before calling this method.

### Return Value
- **S_OK**: Returned when the number of requested elements are returned successfully or the number of returned items is less than the number of requested elements.
- **E_POINTER**: Pointer is not valid.
- **E_OUTOFMEMORY**: Failed to allocate the required memory.
- **E_INVALIDARG**: One or more arguments are not valid.
```

--------------------------------

### IMAPI ULONG Data Type Definitions

Source: https://learn.microsoft.com/en-us/windows/win32/imapi/imapi-data-types

These typedefs are used for IDL validation and to document upper limits for data transfer operations.

```C++
typedef ULONG ULONG_IMAPI2_DVD_STRUCTURE;
typedef ULONG ULONG_IMAPI2_ADAPTER_DESCRIPTOR;
typedef ULONG ULONG_IMAPI2_DEVICE_DESCRIPTOR;
typedef ULONG ULONG_IMAPI2_DISC_INFORMATION;
typedef ULONG ULONG_IMAPI2_TRACK_INFORMATION;
typedef ULONG ULONG_IMAPI2_FEATURE_PAGE;
typedef ULONG ULONG_IMAPI2_MODE_PAGE;
typedef ULONG ULONG_IMAPI2_ALL_FEATURE_PAGES;
typedef ULONG ULONG_IMAPI2_ALL_PROFILES;
typedef ULONG ULONG_IMAPI2_ALL_MODE_PAGES;
typedef ULONG ULONG_IMAPI2_NONZERO;
typedef ULONG ULONG_IMAPI2_NOT_NEGATIVE;
```
Tokens:
Raw