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
{
discFormatData = new MsftDiscFormat2Data();
if (!discFormatData.IsCurrentMediaSupported(discRecorder))
{
labelMediaType.Text = "Media not supported!";
_totalDiscSize = 0;
return;
}
else
{
discFormatData.Recorder = discRecorder;
IMAPI_MEDIA_PHYSICAL_TYPE mediaType = discFormatData.CurrentPhysicalMediaType;
labelMediaType.Text = GetMediaTypeString(mediaType);
fileSystemImage = new MsftFileSystemImage();
fileSystemImage.ChooseImageDefaultsForMediaType(mediaType);
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
{
string Path { get; }
Int64 SizeOnDisc { get; }
System.Drawing.Image FileIconImage { get; }
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 (multisessionInterfaces != null)
{
fileSystemImage.MultisessionInterfaces = multisessionInterfaces;
fileSystemImage.ImportFileSystem();
}
IFsiDirectoryItem rootItem = fileSystemImage.Root;
foreach (IMediaItem mediaItem in listBoxFiles.Items)
{
if (backgroundBurnWorker.CancellationPending)
{
break;
}
mediaItem.AddToFileSystem(rootItem);
}
fileSystemImage.Update -=
new DFileSystemImage_EventHandler(fileSystemImage_Update);
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
{
discRecorder = new MsftDiscRecorder2();
var burnData = (BurnData)e.Argument;
discRecorder.InitializeDiscRecorder(burnData.uniqueRecorderId);
discFormatData = new MsftDiscFormat2Data
{
Recorder = discRecorder,
ClientName = ClientName,
ForceMediaToBeClosed = _closeMedia
};
var burnVerification = (IBurnVerification)discFormatData;
burnVerification.BurnVerificationLevel = _verificationLevel;
object[] multisessionInterfaces = null;
if (!discFormatData.MediaHeuristicallyBlank)
{
multisessionInterfaces = discFormatData.MultisessionInterfaces;
}
IStream fileSystem;
if (!CreateMediaFileSystem(discRecorder, multisessionInterfaces, out fileSystem))
{
e.Result = -1;
return;
}
discFormatData.Update += discFormatData_Update;
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);
}
}
discFormatData.Update -= discFormatData_Update;
if (_ejectMedia)
{
discRecorder.EjectMedia();
}
}
catch (COMException exception)
{
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)
{
if (backgroundBurnWorker.CancellationPending)
{
var format2Data = (IDiscFormat2Data)sender;
format2Data.CancelWrite();
return;
}
var eventArgs = (IDiscFormat2DataEventArgs)progress;
_burnData.task = BURN_MEDIA_TASK.BURN_MEDIA_TASK_WRITING;
_burnData.elapsedTime = eventArgs.ElapsedTime;
_burnData.remainingTime = eventArgs.RemainingTime;
_burnData.totalTime = eventArgs.TotalTime;
_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;
backgroundBurnWorker.ReportProgress(0, _burnData);
}
Formatting/Erasing RW Discs
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
{
discRecorder = new MsftDiscRecorder2();
var activeDiscRecorder = (string)e.Argument;
discRecorder.InitializeDiscRecorder(activeDiscRecorder);
discFormatErase = new MsftDiscFormat2Erase
{
Recorder = discRecorder,
ClientName = ClientName,
FullErase = !checkBoxQuickFormat.Checked
};
discFormatErase.Update += discFormatErase_Update;
try
{
discFormatErase.EraseMedia();
e.Result = 0;
}
catch (COMException ex)
{
e.Result = ex.ErrorCode;
MessageBox.Show(ex.Message, "IDiscFormat2.EraseMedia failed",
MessageBoxButtons.OK, MessageBoxIcon.Stop);
}
discFormatErase.Update -= discFormatErase_Update;
if (checkBoxEjectFormat.Checked)
{
discRecorder.EjectMedia();
}
}
catch (COMException exception)
{
MessageBox.Show(exception.Message);
}
finally
{
if (discRecorder != null)
{
Marshal.ReleaseComObject(discRecorder);
}
if (discFormatErase != null)
{
Marshal.ReleaseComObject(discFormatErase);
}
}
}
History
- March 21, 2008
- 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.