Image Mastering API (IMAPI)

The Image Mastering API (IMAPI) allows an application to stage and burn a simple audio or data image to CD-R and CD-RW devices. The API supports the following formats: Redbook audio and data discs with both Joliet and ISO 9660. The architecture allows for future expansion of the supported format set.

There can be multiple MSDiscMasterObj objects instantiated on a system, but only one application can access a recorder at a time. The MSDiscMasterObj implements multiple interfaces, as shown in the following object diagram.

The IJolietDiscMaster and IRedbookDiscMaster interfaces are returned to an application through the IDiscMaster interface when a format is selected. These interfaces control the content of a data or audio disc, respectively. It is not expected that every application understand the specific format interfaces. Applications can access generic properties of the IJolietDiscMaster interface, such as volume name or legacy file name.

MSDiscRecorderObj objects are accessed through the IDiscRecorder interface. Every CD-R or CD-RW device that is compatible with IMAPI has a corresponding MSDiscRecorderObj object. An application uses pointers to the IDiscRecorder interface on those objects to select which device will be used by IMAPI to record a CD. In addition, applications can access generic properties of a recorder through IDiscRecorder. This includes such properties as writer speed or other burn parameters.

Preventing Logoff During a Burn

It is a good idea to prevent the user from logging off during a burn operation. Otherwise, the system will stop the burn and log the user off, ruining the disc.

To avoid this problem, your application should process the WM_QUERYENDSESSION message. If it receives this message while executing a burn operation, return FALSE to cancel the logoff procedure. If you allow the user to decide whether to continue logging off, provide a warning that the user will lose data.

Documentation: Image Mastering API

Requires Windows XP.

Download

TB_IMAPI.ZIP (11 Kb) (12 Mar 2006)

® Include file with all the constants and wrapper functions, and a template for events sink.

IMAPI Interfaces

IDiscMaster

IDiscMasterProgressEvents
IDiscRecorder

IEnumDiscRecorders

IJolietDiscMaster

IRedbookDiscMaster

IMAPI Enumerations and Constants

MEDIA_TYPES Enumerated Type

%MEDIA_CDDA_CDROM = 1
%MEDIA_CD_ROM_XA = %MEDIA_CDDA_CDROM + 1
%MEDIA_CD_I = %MEDIA_CD_ROM_XA + 1
%MEDIA_CD_EXTRA = %MEDIA_CD_I + 1
%MEDIA_CD_OTHER = %MEDIA_CD_EXTRA + 1
%MEDIA_SPECIAL = %MEDIA_CD_OTHER + 1

MEDIA_FLAGS Enumerated Type

%MEDIA_BLANK = &H1
%MEDIA_RW = &H2
%MEDIA_WRITABLE = &H4
%MEDIA_FORMAT_UNUSABLE_BY_IMAPI = &H8

RECORDER_TYPES Enumerated Type

%RECORDER_CDR = &H1
%RECORDER_CDRW = &H2

Recorder States

%RECORDER_DOING_NOTHING = 0
%RECORDER_OPENED = &H1
%RECORDER_BURNING = &H2

IMAPI Result Codes

The following result codes are returned from methods of the IMAPI interfaces.

%IMAPI_S_PROPERTIESIGNORED = &H80040200
%IMAPI_S_BUFFER_TO_SMALL = &H80040201
%IMAPI_E_NOTOPENED = &H8004020B
%IMAPI_E_NOTINITIALIZED = &H8004020C
%IMAPI_E_USERABORT = &H8004020D
%IMAPI_E_GENERIC = &H8004020E
%IMAPI_E_MEDIUM_NOTPRESENT = &H8004020F
%IMAPI_E_MEDIUM_INVALIDTYPE = &H80040210
%IMAPI_E_DEVICE_NOPROPERTIES = &H80040211
%IMAPI_E_DEVICE_NOTACCESSIBLE = &H80040212
%IMAPI_E_DEVICE_NOTPRESENT = &H80040213
%IMAPI_E_DEVICE_INVALIDTYPE = &H80040214
%IMAPI_E_INITIALIZE_WRITE = &H80040215
%IMAPI_E_INITIALIZE_ENDWRITE = &H80040216
%IMAPI_E_FILESYSTEM = &H80040217
%IMAPI_E_FILEACCESS = &H80040218
%IMAPI_E_DISCINFO = &H80040219
%IMAPI_E_TRACKNOTOPEN = &H8004021A
%IMAPI_E_TRACKOPEN = &H8004021B
%IMAPI_E_DISCFULL = &H8004021C
%IMAPI_E_BADJOLIETNAME = &H8004021D
%IMAPI_E_INVALIDIMAGE = &H8004021E
%IMAPI_E_NOACTIVEFORMAT = &H8004021F
%IMAPI_E_NOACTIVERECORDER = &H80040220
%IMAPI_E_WRONGFORMAT = &H80040221
%IMAPI_E_ALREADYOPEN = &H80040222
%IMAPI_E_WRONGDISC = &H80040223
%IMAPI_E_FILEEXISTS = &H80040224
%IMAPI_E_STASHINUSE = &H80040225
%IMAPI_E_DEVICE_STILL_IN_USE = &H80040226
%IMAPI_E_LOSS_OF_STREAMING = &H80040227
%IMAPI_E_COMPRESSEDSTASH = &H80040228
%IMAPI_E_ENCRYPTEDSTASH = &H80040229
%IMAPI_E_NOTENOUGHDISKFORSTASH = &H8004022A
%IMAPI_E_REMOVABLESTASH = &H8004022B
%IMAPI_E_CANNOT_WRITE_TO_MEDIA = &H8004022C
%IMAPI_E_TRACK_NOT_BIG_ENOUGH = &H8004022D
%IMAPI_E_BOOTIMAGE_AND_NONBLANK_DISC = &H8004022E

Constant	Description
S_OK	The method was successful.
IMAPI_S_PROPERTIESIGNORED	An unknown property was passed in a property set and it was ignored.
IMAPI_S_BUFFER_TO_SMALL	The output buffer is too small.
IMAPI_E_NOTOPENED	A call to IDiscMaster::Open has not been made.
IMAPI_E_NOTINITIALIZED	A recorder object has not been initialized.
IMAPI_E_USERABORT	The user canceled the operation.
IMAPI_E_GENERIC	A generic error occurred.
IMAPI_E_MEDIUM_NOTPRESENT	There is no disc in the device.
IMAPI_E_MEDIUM_INVALIDTYPE	The media is not a type that can be used.
IMAPI_E_DEVICE_NOPROPERTIES	The recorder does not support any properties.
IMAPI_E_DEVICE_NOTACCESSIBLE	The device cannot be used or is already in use.
IMAPI_E_DEVICE_NOTPRESENT	The device is not present or has been removed.
IMAPI_E_DEVICE_INVALIDTYPE	The recorder does not support an operation.
IMAPI_E_INITIALIZE_WRITE	The drive interface could not be initialized for writing.
IMAPI_E_INITIALIZE_ENDWRITE	The drive interface could not be initialized for closing.
IMAPI_E_FILESYSTEM	An error occurred while enabling/disabling file system access or during auto-insertion detection.
IMAPI_E_FILEACCESS	An error occurred while writing the image file.
IMAPI_E_DISCINFO	An error occurred while trying to read disc data from the device.
IMAPI_E_TRACKNOTOPEN	An audio track is not open for writing.
IMAPI_E_TRACKOPEN	An open audio track is already being staged.
IMAPI_E_DISCFULL	The disc cannot hold any more data.
IMAPI_E_BADJOLIETNAME	The application tried to add a badly named element to a disc.
IMAPI_E_INVALIDIMAGE	The staged image is not suitable for a burn. It has been corrupted or cleared and has no usable content.
IMAPI_E_NOACTIVEFORMAT	An active format master has not been selected using IDiscMaster::SetActiveDiscMasterFormat.
IMAPI_E_NOACTIVERECORDER	An active disc recorder has not been selected using IDiscMaster::SetActiveDiscRecorder.
IMAPI_E_WRONGFORMAT	A call to IJolietDiscMaster has been made when IRedbookDiscMaster is the active format, or vice versa. To use a different format, change the format and clear the image file contents.
IMAPI_E_ALREADYOPEN	A call to IDiscMaster::Open has already been made against this object by your application.
IMAPI_E_WRONGDISC	The IMAPI multi-session disc has been removed from the active recorder.
IMAPI_E_FILEEXISTS	The file to add is already in the image file and the overwrite flag was not set.
IMAPI_E_STASHINUSE	Another application is already using the IMAPI stash file required to stage a disc image. Try again later.
IMAPI_E_DEVICE_STILL_IN_USE	Another application is already using this device, so IMAPI cannot access the device.
IMAPI_E_LOSS_OF_STREAMING	Content streaming was lost; a buffer under-run may have occurred.
IMAPI_E_COMPRESSEDSTASH	The stash is located on a compressed volume and cannot be read.
IMAPI_E_ENCRYPTEDSTASH	The stash is located on an encrypted volume and cannot be read.
IMAPI_E_NOTENOUGHDISKFORSTASH	There is not enough free space to create the stash file on the specified volume.
IMAPI_E_REMOVABLESTASH	The selected stash location is on a removable media.
IMAPI_E_CANNOT_WRITE_TO_MEDIA	The media cannot be written to.
IMAPI_E_TRACK_NOT_BIG_ENOUGH	The track is not big enough.

Page last updated on Monday, 27 March 2006 13:09:14 +0100