Click here to Skip to main content
65,938 articles
CodeProject is changing. Read more.
Articles
(untagged)

Burning and Erasing CD/DVD/Blu-ray Media with C# and IMAPI2

0.00/5 (No votes)
23 Mar 2010 13  
Using the Image Mastering API in C#.

Introduction

Windows introduced the new IMAPIv2.0 with the release of the Vista Operating System which was a big improvement over the original IMAPI. The original IMAPI is great for CDROMs, but it has some huge limitations like not being able to write to DVD media. I am sure this limitation is due to almost nobody having a DVD writer when Windows XP was released back in 2001. IMAPIv2 allows you to write to CD, DVD, and even Blu-ray media, as well as read and write ISO files. IMAPIv2.0 had a problem since it was only available with Windows Vista. But in June of 2007, Microsoft released update packages for Windows XP and Windows 2003. You can download the updates here.

To use the features added in the Windows Feature Pack for Storage 1.0, you need to download the update here. Windows Vista Service Pack 2 already includes the update.

I wrote this article as a sequel to my C++ article, Burning CD/DVD Media with the Image Mastering API Version 2.0. Most of the IMAPI2 samples seem to be in scripting languages. The only C# sample I found was the IBurn console project that came with the Windows Vista SDK, and more recently, the article: How to Create Optical File Images using IMAPIv2.0 by dmihailescu, which shows you how to create an ISO file.

This article was more difficult than I had thought it would be. Normally, .NET applications are supposed to be easier, but there were a number of issues that I needed to figure out to get this to work. If you're not interested in hearing me rant and rave, you can skip over the next section.

The Problems

IMAPI2 was implemented using two separate COM DLLs: imapi2.dll and imapi2fs.dll. imapi2.dll handles most of the device and recording APIs, and imapi2fs.dll handles all of the file system and IStream APIs. This may not seem like much of a problem, especially if you are using C++. This does become a huge problem with .NET, because you need to take an IStream created from IMAPI2FS and use it in IMAPI2 to write to the media. You end up getting an error message, something like this:

Unable to cast object of type 'IMAPI2FS.FsiStreamClass' to type 'IMAPI2.IStream'

Microsoft realized this problem, and created a project called IBurn that they released in the Windows Vista SDK. They created an Interop namespace that combined many classes, enums, and interfaces of IMAPI2 and IMAPI2FS into one namespace in a file Interop.cs. This fixed the problem of not being able to cast an IStream from IMAPI2FS to IMAPI2.

Unfortunately, their implementation did not completely fix my problems. I was having other COM problems, like having the application throw exceptions whenever I would try to use any method that returned an Array. I later discovered that this problem could have been fixed by changing the Array to object[]. I was also having null reference exceptions when trying to burn multiple CDs. Microsoft admits that Interop.cs is not a complete solution and is only used to demonstrate how to use IMAPI2 using C#.

So, off I went on my journey to create a complete solution.

I created two .NET Interop assemblies from the COM DLLs by using the Microsoft Type Library to Assembly Converter, tlbimp.exe. I created the two assemblies by using the following commands:

tlbimp imapi2.dll /out:imapi2int.dll
tlbimp imapi2fs.dll /out:imapi2fsint.dll

Once I had the .NET assemblies, I used Reflector to disassemble the interops and create C# source code. I combined the two files and made many modifications to the interfaces and helper classes, and added support for all interfaces of IMAPI2. That sounds a lot easier than it really was.

One of the biggest issues I had that seemed to take forever to figure out was the reversing of the get, set properties. The auto-generated code from Reflector always placed the get before the set. Many properties in IMAPI2 require that the properties be defined with set before get. If they are not in the proper order, then it causes the application to crash and instantly exit. It doesn't throw an exception to give you any kind of clue as to what the problem might be. It just kills the app. So, after I finally figured out what was wrong, I opened up the COM DLLs with the OLE/COM Object Viewer and went through the actual TypeLib for every property and made sure they were in the correct order.

I also chose not to implement the AStream interface as they did in Interop.cs. I use the System.Runtime.InteropServices.ComTypes.IStream Interface directly.

Lastly, in order to receive notifications for all events, I had to go through the SDK and find all of the Dispatch IDs for all of the events. Without these values, the event handlers are unable to receive notifications.

New IMAPI2 Interop - Imapi2interop.cs

My replacement for Interop.cs is Imapi2Interop.cs, included in the source code. It defines the following classes and interfaces:

  • IBootOptions - Specifies the boot image to add to the optical disc
  • IEnumFsiItems - Enumerates the child directory and file items for an FsiDirectoryItem object
  • IEnumProgressItems - Enumerates a collection of progress items
  • IFileSystemImageResult - Gets information about the burn image, the image data stream, and progress information
  • IFsiDirectoryItem - Adds items to or removes items from the file-system image
  • IFsiFileItem - Identifies the file size and data stream of the file contents
  • IDiscFormat2Data - Writes a data stream to a disc
  • IDiscFormat2DataEventArgs - Retrieves information about the current write operation
  • IDiscFormat2Erase - Erases data from a disc
  • IDiscFormat2RawCD - Writes raw images to a disc device using Disc At Once (DAO) mode
  • IDiscFormat2RawCDEventArgs - Retrieves information about the current write operation
  • IDiscFormat2TrackAtOnce - Writes audio to blank CD-R or CD-RW media in Track-At-Once mode
  • IDiscFormat2TrackAtOnceEventArgs - Retrieves information about the current write operation
  • IDiscMaster2 - Enumerates the CD and DVD devices installed on the computer
  • IDiscRecorder2 - Represents a physical device
  • IDiscRecorder2Ex - Retrieves information not available through the IDiscRecorder2 interface
  • IProgressItem - Retrieves block information for one segment of the result file image
  • IProgressItems - Enumerates the progress items in a result image
  • IWriteEngine2 - Writes a data stream to a device
  • IWriteEngine2EventArgs - Retrieves information about the current write operation
  • IWriteSpeedDescriptor - Retrieves detailed write configurations supported by the disc recorder and current media

The Windows Feature Pack for Storage 1.0 also adds the following Interfaces:

  • IBurnVerification - Sets the verification level of the burn operation
  • IFileSystemImage - Builds, imports, and exports a file system image
  • IFileSystemImage2 - Extends the IFileSystemImage interface by writing multiple boot entries or boot images required for the EFI/UEFI support
  • IFileSystemImage3 - Extends the IFileSystemImage2 interface by setting or checking the metadata and metadata mirror files in a UDF file system (rev 2.50 and later) to determine redundancy
  • IFsiNamedStreams - Enumerates the named streams associated with a file in a file system image
  • IIsoImageManager - Verifies if an existing ISO file contains a valid image for burning
  • IMultiSession - Base interface containing the properties common to the derived multi-session interfaces.
  • IMultiSessionSequential - Extends the IMultiSession interface by retrieving information about the previous import session on a sequentially recorded media
  • IRawCDImageCreator - Creates a raw CD image for writing in Disc-at-once mode.
  • IRawCDImageTrackInfo - Tracks per-track properties that are applied to CD Media

It also defines the following events:

  • DDiscFormat2DataEvents
    • DiscFormat2Data_EventHandler
  • DDiscFormat2EraseEvents
    • DiscFormat2Erase_EventHandler
  • DDiscFormat2RawCDEvents
    • DiscFormat2RawCD_UpdateEventHandler
  • DDiscFormat2TrackAtOnceEvents
    • DiscFormat2TrackAtOnce_EventHandler
  • DDiscMaster2Events
    • DiscMaster2_NotifyDeviceAddedEventHandler
    • DiscMaster2_NotifyDeviceRemovedEventHandler
  • DFileSystemImageEvents
    • DFileSystemImage_EventHandler
  • DWriteEngine2Events
    • DWriteEngine2_EventHandler

Using the Code

Make sure that XP and 2003 have the IMAPI2 updates mentioned at the top of the article.

Do not add the imapi2.dll and imapi2fs.dll COM DLLs to your project. That will cause the problems listed above.

Add the file imapi2interop.cs to your project and define the namespace in your app:

using IMAPI2.Interop;

In order to receive notification to your event handler from COM, you need to open up the file AssemblyInfo.cs and change the ComVisible attribute to true:

[assembly: ComVisible(true)]

Determining the Media Type

To determine the media type and the available space on the hard drive, you create a MsftDiscFormat2Data object and set the current recorder in the Recorder property. You can then get the media type from the IDiscFormat2Data CurrentPhysicalMediaType property.

Once you have the media type, create a MsftFileSystemImage object and call the ChooseImageDefaultsForMediaType method with the media type.

To determine if any sessions have already been recorded on the media, check the IDiscFormatData2 MediaHeuristicallyBlank property.

If it is false, then other sessions have been recorded and you need to set the MsftFileSystemImage's MultisessionInterfaces property with the IDiscFormat2Data MultisessionInterfaces property, then call the IDiscFormat2Data ImportFileSystem() method.

Then, get the free media blocks by multiplying the MsftFileSystemImage's FreeMediaBlocks with the sector size (2048). If there were previous sessions recorded on the media, that space will be subtracted from the total size of the media.

private void buttonDetectMedia_Click(object sender, EventArgs e)
{
    if (devicesComboBox.SelectedIndex == -1)
    {
        return;
    }

    var discRecorder =
        (IDiscRecorder2)devicesComboBox.Items[devicesComboBox.SelectedIndex];

    MsftFileSystemImage fileSystemImage = null;
    MsftDiscFormat2Data discFormatData = null;

    try
    {
        //
        // Create and initialize the IDiscFormat2Data
        //
        discFormatData = new MsftDiscFormat2Data();
        if (!discFormatData.IsCurrentMediaSupported(discRecorder))
        {
            labelMediaType.Text = "Media not supported!";
            _totalDiscSize = 0;
            return;
        }
        else
        {
            //
            // Get the media type in the recorder
            //
            discFormatData.Recorder = discRecorder;
            IMAPI_MEDIA_PHYSICAL_TYPE mediaType = discFormatData.CurrentPhysicalMediaType;
            labelMediaType.Text = GetMediaTypeString(mediaType);

            //
            // Create a file system and select the media type
            //
            fileSystemImage = new MsftFileSystemImage();
            fileSystemImage.ChooseImageDefaultsForMediaType(mediaType);

            //
            // See if there are other recorded sessions on the disc
            //
            if (!discFormatData.MediaHeuristicallyBlank)
            {
                fileSystemImage.MultisessionInterfaces = 
				discFormatData.MultisessionInterfaces;
                fileSystemImage.ImportFileSystem();
            }

            Int64 freeMediaBlocks = fileSystemImage.FreeMediaBlocks;
            _totalDiscSize = 2048 * freeMediaBlocks;
        }
    }
    catch (COMException exception)
    {
        MessageBox.Show(this, exception.Message, "Detect Media Error",
            MessageBoxButtons.OK, MessageBoxIcon.Error);
    }
    finally
    {
        if (discFormatData != null)
        {
            Marshal.ReleaseComObject(discFormatData);
        }

        if (fileSystemImage != null)
        {
            Marshal.ReleaseComObject(fileSystemImage);
        }
    }

    UpdateCapacity();
}

Adding Files and Directories to the Listbox

I created a generic interface called IMediaItem. IMediaItem contains three properties and one method:

interface IMediaItem
{
    /// <summary>
    /// Returns the full path of the file or directory
    /// </summary>
    string Path { get; }

    /// <summary>
    /// Returns the size of the file or directory to the next largest sector
    /// </summary>
    Int64 SizeOnDisc { get; }

    /// <summary>
    /// Returns the Icon of the file or directory
    /// </summary>
    System.Drawing.Image FileIconImage { get; }

    // Adds the file or directory to the directory item, usually the root.
    bool AddToFileSystem(IFsiDirectoryItem rootItem);
}

For file items, I created the FileItem class. This class basically creates an IStream by PInvoking the SHCreateStreamOnFile Windows API call, and adds it to IFsiDirectoryItem.

For directory items, I created the DirectoryItem class. This uses a much simpler technique of calling the IFsiDirectoryItem.AddTree method to add the directory and all subdirectories to the IStream.

These classes and interfaces are located in the IMediaItem.cs file.

Creating the Image

I use the CreateMediaFileSystem method in the MainForm class to create the IStream image to write to the media. I enumerate through the files and directories that were added to the file listbox.

private bool CreateMediaFileSystem(IDiscRecorder2 discRecorder, out IStream dataStream)
{
    MsftFileSystemImage fileSystemImage = null;
    try
    {
        fileSystemImage = new MsftFileSystemImage();
        fileSystemImage.ChooseImageDefaults(discRecorder);
        fileSystemImage.FileSystemsToCreate =
            FsiFileSystems.FsiFileSystemJoliet | FsiFileSystems.FsiFileSystemISO9660;
        fileSystemImage.VolumeName = textBoxLabel.Text;

        fileSystemImage.Update +=
        new DFileSystemImage_EventHandler(fileSystemImage_Update);

        //
        // If multisessions, then import previous sessions
        //
        if (multisessionInterfaces != null)
        {
            fileSystemImage.MultisessionInterfaces = multisessionInterfaces;
            fileSystemImage.ImportFileSystem();
        }

        //
        // Get the image root
        //
        IFsiDirectoryItem rootItem = fileSystemImage.Root;

        //
        // Add Files and Directories to File System Image
        //
        foreach (IMediaItem mediaItem in listBoxFiles.Items)
        {
            //
            // Check if we've cancelled
            //
            if (backgroundBurnWorker.CancellationPending)
            {
                break;
            }

            //
            // Add to File System
            //
            mediaItem.AddToFileSystem(rootItem);
        }

        fileSystemImage.Update -=
        new DFileSystemImage_EventHandler(fileSystemImage_Update);

        //
        // did we cancel?
        //
        if (backgroundBurnWorker.CancellationPending)
        {
            dataStream = null;
            return false;
        }

        dataStream = fileSystemImage.CreateResultImage().ImageStream;
    }
    catch (COMException exception)
    {
        MessageBox.Show(this, exception.Message,
            "Create File System Error",
            MessageBoxButtons.OK, MessageBoxIcon.Error);
        dataStream = null;
        return false;
    }
    finally
    {
        if (fileSystemImage != null)
        {
            Marshal.ReleaseComObject(fileSystemImage);
        }
    }

    return true;
}

Multithreading

Burning or formatting media can take some time, so we do not want to perform these actions on the main UI thread. I use the BackgroundWorker class to handle the multithreading of these lengthy tasks. The BackgroundWorker class allows you to set values within the thread and then call the ReportProgress method which fires a ProgressChanged event in the calling thread. When you are finished with your worker thread, it fires the RunWorkerCompleted event to notify the calling thread that it is finished. I won't go into much detail on the whole threading process since that is not the main topic of this article.

Writing Data to Media

I write the data in the MainForm's backgroundBurnWorker_DoWork which is the DoWork event for the BackgroundWorker backgroundBurnWorker.

private void backgroundBurnWorker_DoWork(object sender, DoWorkEventArgs e)
{
    MsftDiscRecorder2 discRecorder = null;
    MsftDiscFormat2Data discFormatData = null;

    try
    {
        //
        // Create and initialize the IDiscRecorder2 object
        //
        discRecorder = new MsftDiscRecorder2();
        var burnData = (BurnData)e.Argument;
        discRecorder.InitializeDiscRecorder(burnData.uniqueRecorderId);

        //
        // Create and initialize the IDiscFormat2Data
        //
        discFormatData = new MsftDiscFormat2Data
            {
                Recorder = discRecorder,
                ClientName = ClientName,
                ForceMediaToBeClosed = _closeMedia
            };

        //
        // Set the verification level
        //
        var burnVerification = (IBurnVerification)discFormatData;
        burnVerification.BurnVerificationLevel = _verificationLevel;

        //
        // Check if media is blank, (for RW media)
        //
        object[] multisessionInterfaces = null;
        if (!discFormatData.MediaHeuristicallyBlank)
        {
            multisessionInterfaces = discFormatData.MultisessionInterfaces;
        }

        //
        // Create the file system
        //
        IStream fileSystem;
        if (!CreateMediaFileSystem(discRecorder, multisessionInterfaces, out fileSystem))
        {
            e.Result = -1;
            return;
        }

        //
        // add the Update event handler
        //
        discFormatData.Update += discFormatData_Update;

        //
        // Write the data here
        //
        try
        {
            discFormatData.Write(fileSystem);
            e.Result = 0;
        }
        catch (COMException ex)
        {
            e.Result = ex.ErrorCode;
            MessageBox.Show(ex.Message, "IDiscFormat2Data.Write failed",
                MessageBoxButtons.OK, MessageBoxIcon.Stop);
        }
        finally
        {
            if (fileSystem != null)
            {
                Marshal.FinalReleaseComObject(fileSystem);
            }
        }

        //
        // remove the Update event handler
        //
        discFormatData.Update -= discFormatData_Update;

        if (_ejectMedia)
        {
            discRecorder.EjectMedia();
        }
    }
    catch (COMException exception)
    {
        //
        // If anything happens during the format, show the message
        //
        MessageBox.Show(exception.Message);
        e.Result = exception.ErrorCode;
    }
    finally
    {
        if (discRecorder != null)
        {
            Marshal.ReleaseComObject(discRecorder);
        }

        if (discFormatData != null)
        {
            Marshal.ReleaseComObject(discFormatData);
        }
    }
}

Progress Update Events

The IDiscFormat2Data supports cancelling with the CancelWrite method. When I receive the Update Event from IDiscFormatData2, I check to see if the user pressed the Cancel button. If the user has cancelled, the BackgroundWorker's CancellationPending property will be true, and I cancel the write operation and immediately return. Otherwise, I collect the data from the IDiscFormat2DataEventArgs object, then call the backgroundBurnWorker.ReportProgress so the UI thread can update the data and progress bar.

void discFormatData_Update([In, MarshalAs(UnmanagedType.IDispatch)] object sender,
                           [In, MarshalAs(UnmanagedType.IDispatch)] objectprogress)
{
    //
    // Check if we've cancelled
    //
    if (backgroundBurnWorker.CancellationPending)
    {
        var format2Data = (IDiscFormat2Data)sender;
        format2Data.CancelWrite();
        return;
    }

    var eventArgs = (IDiscFormat2DataEventArgs)progress;

    _burnData.task = BURN_MEDIA_TASK.BURN_MEDIA_TASK_WRITING;

    // IDiscFormat2DataEventArgs Interface
    _burnData.elapsedTime = eventArgs.ElapsedTime;
    _burnData.remainingTime = eventArgs.RemainingTime;
    _burnData.totalTime = eventArgs.TotalTime;

    // IWriteEngine2EventArgs Interface
    _burnData.currentAction = eventArgs.CurrentAction;
    _burnData.startLba = eventArgs.StartLba;
    _burnData.sectorCount = eventArgs.SectorCount;
    _burnData.lastReadLba = eventArgs.LastReadLba;
    _burnData.lastWrittenLba = eventArgs.LastWrittenLba;
    _burnData.totalSystemBuffer = eventArgs.TotalSystemBuffer;
    _burnData.usedSystemBuffer = eventArgs.UsedSystemBuffer;
    _burnData.freeSystemBuffer = eventArgs.FreeSystemBuffer;

    //
    // Report back to the UI
    //
    backgroundBurnWorker.ReportProgress(0, _burnData);
}

Formatting/Erasing RW Discs

burnmedia_format.png

I format the disc in the MainForm's backgroundFormatWorker_DoWork which is the DoWork event for the BackgroundWorker backgroundFormatWorker.

private void backgroundFormatWorker_DoWork(object sender, DoWorkEventArgs e)
{
    MsftDiscRecorder2 discRecorder = null;
    MsftDiscFormat2Erase discFormatErase = null;

    try
    {
        //
        // Create and initialize the IDiscRecorder2
        //
        discRecorder = new MsftDiscRecorder2();
        var activeDiscRecorder = (string)e.Argument;
        discRecorder.InitializeDiscRecorder(activeDiscRecorder);

        //
        // Create the IDiscFormat2Erase and set properties
        //
        discFormatErase = new MsftDiscFormat2Erase
            {
                Recorder = discRecorder,
                ClientName = ClientName,
                FullErase = !checkBoxQuickFormat.Checked
            };

        //
        // Setup the Update progress event handler
        //
        discFormatErase.Update += discFormatErase_Update;

        //
        // Erase the media here
        //
        try
        {
            discFormatErase.EraseMedia();
            e.Result = 0;
        }
        catch (COMException ex)
        {
            e.Result = ex.ErrorCode;
            MessageBox.Show(ex.Message, "IDiscFormat2.EraseMedia failed",
                MessageBoxButtons.OK, MessageBoxIcon.Stop);
        }

        //
        // Remove the Update progress event handler
        //
        discFormatErase.Update -= discFormatErase_Update;

        //
        // Eject the media
        //
        if (checkBoxEjectFormat.Checked)
        {
            discRecorder.EjectMedia();
        }

    }
    catch (COMException exception)
    {
        //
        // If anything happens during the format, show the message
        //
        MessageBox.Show(exception.Message);
    }
    finally
    {
        if (discRecorder != null)
        {
            Marshal.ReleaseComObject(discRecorder);
        }

        if (discFormatErase != null)
        {
            Marshal.ReleaseComObject(discFormatErase);
        }
    }
}

History

  • March 21, 2008
    • Initial release
  • March 25, 2008 
    • Added the Visual Studio 2005 project
  • March 29, 2008 
    • Detects media type and size, supports multi-session
  • May 2, 2009 
    • Added support for Windows Feature Pack for Storage, and bug fixes
  • December 13, 2009 
    • Removed calls to the AcquireExclusiveAccess and ReleaseExclusiveAccess methods as they are not needed
    • Calls IDiscRecorder2.SupportedProfiles to enumerate supported disk types
  • March 2, 2010
    • Fixed some incorrect method parameters in the IDiscRecorder2Ex class
    • Fixed a potential threading issue
    • Added an icon
  • March 22, 2010
    • Fixed a very bad Windows XP bug found by Leroe where the MsftFileSystemImageClass was always unnecessarily using the IFileSystemImage3 Interface when just using the IFileSystemImage interface would suffice. Also did a little code refactoring.

License

This article has no explicit license attached to it but may contain usage terms in the article text or the download files themselves. If in doubt please contact the author via the discussion board below.

A list of licenses authors might use can be found here