imapispec-v09

Windows Platform Design NotesDesigning Hardware for the Microsoft Windows Family of Operating Systems

Image Mastering API (IMAPI)

Abstract: This document describes the Image Master API (IMAPI) provided under the next version of the Microsoft® Windows® 2000 operating system, code-named “Whistler.” IMAPI allows an application to “stage” and “burn” a simple audio or data image to on a CD-R or CD-R/W devices. The specific formats to be supported are Redbook audio and data discs with both Joliet and ISO 9660. The API architecture allows for future expansion of the supported format set.

PREVIEW Draft Version 0.9 — March 1, 2001

Disclaimer: The information contained in this document represents the current view of Microsoft Corporation on the issues discussed as of the date of publication. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information presented. This document is for informational purposes only. MICROSOFT MAKES NO WARRANTIES, EXPRESS OR IMPLIED, IN THIS DOCUMENT.

Microsoft Corporation may have patents or pending patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. The furnishing of this document does not give you any license to the patents, trademarks, copyrights, or other intellectual property rights except as expressly provided in any written license agreement from Microsoft Corporation.

Microsoft does not make any representation or warranty regarding specifications in this document or any product or item developed based on these specifications. Microsoft disclaims all express and implied warranties, including but not limited to the implied warranties or merchantability, Fitness for a particular purpose and freedom from infringement. Without limiting the generality of the foregoing, Microsoft does not make any warranty of any kind that any item developed based on these specifications, or any portion of a specification, will not infringe any copyright, patent, trade secret or other intellectual property right of any person or entity in any country. It is your responsibility to seek licenses for such intellectual property rights where appropriate. Microsoft shall not be liable for any damages arising out of or in connection with the use of these specifications, including liability for lost profit, business interruption, or any other damages whatsoever. Some states do not allow the exclusion or limitation of liability or consequential or incidental damages; the above limitation may not apply to you.

Microsoft, Win32, Windows, and Windows NT are trademarks or registered trademarks of Microsoft Corporation in the United States and/or other countries. Other product and company names mentioned herein may be the trademarks of their respective owners.

© 2001 Microsoft Corporation. All rights reserved.

Contents

About the Image Mastering API................................................................................................3Using the Image Mastering API................................................................................................4

Extending the IDiscmaster and IDiscRecorder Interfaces....................................................5Creating Multi-session Discs................................................................................................5

Language Notes........................................................................................................................5Image Mastering API Reference...............................................................................................6

Interfaces..............................................................................................................................6IDiscMaster......................................................................................................................6

IDiscMaster::Open................................................................................................................7IDiscMaster::EnumDiscMasterFormats................................................................................7IDiscMaster::GetActiveDiscMasterFormat............................................................................8IDiscMaster::SetActiveDiscMasterFormat............................................................................8IDiscMaster::EnumDiscRecorders........................................................................................9IDiscMaster::GetActiveDiscRecorder..................................................................................10IDiscMaster::SetActiveDiscRecorder..................................................................................11IDiscMaster::ClearFormatContent......................................................................................12IDiscMaster::ProgressAdvise..............................................................................................12IDiscMaster::ProgressUnadvise..........................................................................................13IDiscMaster::RecordDisc....................................................................................................13IDiscMaster::Close..............................................................................................................15

IDiscRecorder................................................................................................................15

Image Mastering API (IMAPI) — 2

IDiscRecorder::GetRecorderGUID......................................................................................17IDiscRecorder::GetRecorderType.......................................................................................17IDiscRecorder::GetDisplayNames......................................................................................18IDiscRecorder::GetBasePnPID...........................................................................................18IDiscRecorder::GetPath......................................................................................................19IDiscRecorder::GetRecorderProperties..............................................................................19IDiscRecorder::SetRecorderProperties...............................................................................20IDiscRecorder::OpenExclusive...........................................................................................21IDiscRecorder::QueryMediaType........................................................................................22IDiscRecorder::QueryMediaInfo..........................................................................................23IDiscRecorder::Eject...........................................................................................................24IDiscRecorder::Erase..........................................................................................................24IDiscRecorder::Close..........................................................................................................25

IRedbookDiscMaster.....................................................................................................26IRedbookDiscMaster::GetTotalAudioTracks.......................................................................26IRedbookDiscMaster::GetTotalAudioBlocks.......................................................................27IRedbookDiscMaster::GetUsedAudioBlocks.......................................................................27IRedbookDiscMaster::GetAvailableAudioTrackBlocks.......................................................27IRedbookDiscMaster::GetAudioBlockSize..........................................................................28IRedbookDiscMaster::CreateAudioTrack............................................................................28IRedbookDiscMaster::AddAudioTrackBlocks.....................................................................29IRedbookDiscMaster::CloseAudioTrack.............................................................................30

IJolietDiscMaster...........................................................................................................30IJolietDiscMaster::GetTotalDataBlocks...............................................................................31IJolietDiscMaster::GetUsedDataBlocks..............................................................................31IJolietDiscMaster::GetDataBlockSize.................................................................................31IJolietDiscMaster::AddData.................................................................................................32IJolietDiscMaster::GetJolietProperties................................................................................33IJolietDiscMaster::SetJolietProperties................................................................................34

IDiscMasterProgressEvents..........................................................................................35IDiscMasterProgressEvents::QueryCancel.........................................................................36IDiscMasterProgressEvents::NotifyPnPActivity..................................................................36IDiscMasterProgressEvents::NotifyAddProgress................................................................36IDiscMasterProgressEvents::NotifyBlockProgress.............................................................37IDiscMasterProgressEvents::NotifyTrackProgress.............................................................37IDiscMasterProgressEvents::NotifyPreparingBurn.............................................................38IDiscMasterProgressEvents::NotifyClosingDisc.................................................................38IDiscMasterProgressEvents::NotifyBurnComplete.............................................................39

IMAPI Result Codes...........................................................................................................39



About the Image Mastering APIThe Image Master API (IMAPI) allows an application to “stage” and “burn” a simple audio or data image to on a CD-R or CD-R/W devices. The specific formats to be supported are Redbook audio and data discs with both Joliet and ISO 9660. The API architecture allows for future expansion of the supported format set.

This document focuses on a description of the Adaptec implementation of IMAPI for Microsoft. As such, descriptions of the four main COM objects and their interfaces are included in this document. The four main objects are as follows: MSDiscMasterObj, MSDiscRecorderObj, MSDiscStashObj, and MSBurnEngineObj. Of these, the MSDiscMasterObj is the only object with multiple interfaces besides IUnknown. In particular:

IUnknown

MSDiscMasterObjIDiscMaster

IJolietDiscMaster

IRedbookDiscMaster

There may be multiple MSDiscMasterObj objects instantiated on a system, but only one application may access a recorder at a time. Applications use the IDiscMaster interface to open IMAPI, enumerate supported formats (Joliet and Redbook), select a format, get a list of recorders, select a recorder, and finally start a burn. The IJolietDiscMaster and IRedbookDiscMaster interfaces are returned to an application through the IDiscMaster interface when a format is selected, and they allow specific control of the content of a data or audio disc respectively. While it is expected that every application will be able to find and talk to IDiscMaster and IDiscRecorder, it is not expected that every application will know about or understand the specific format interfaces. Applications can access generic properties of the IJolietDiscMaster Interface. This includes such properties as volume name or legacy file name.

MSDiscRecorder objects are accessed through IDiscRecorder interfaces. Every CD-R or CD-R/W device that is compatible with IMAPI will have a corresponding MSDiscRecorder object. An application uses the pointers to the IDiscRecorder interfaces 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 the IDiscRecorder interface. This includes such properties as writer speed or other burn parameters.

The remaining two objects: MSDiscStashObj and MSBurnEngineObj are internal interfaces accessed by IMAPI. They are minimally documented to clarify architecture only. The MSDiscStashObj represents (through IDiscStash) a raw file up to 800 MB in size that is used by MSDiscMasterObj to create images of the audio or data discs to be burned. The stash is then passed on to the MSBurnEngineObj (through IMSBurnEngine) when a burn is requested from the lower level engine. The MSBurnEngineObj expects that the contents of the stash will be in a specific known format. In this respect, the MSDiscMasterObj and MSBurnEngineObj have an unwritten contract as to the content of the stash.



Using the Image Mastering APIAn application using IMAPI communicates with it through IDiscMaster, IDiscRecorder, IJolietDiscMaster, and IRedbookDiscMaster. The following flow describes a normal interaction between an application and these interfaces.

1) Create an instance of the MSDiscMasterObj using normal COM techniques (CoCreateInstance, smart pointers from an import, and so on) and request the IDiscMaster interface.

2) Acquire access to IMAPI through IDiscMaster. The application should call the Open method on IDiscMaster. If this succeeds, the application has full access to all the interfaces and methods implemented in MSDiscMasterObj.

3) Retrieve the disc master format enumerator to examine the set of formats that the disc master object supports, and then choose the active format. The “formats” returned from the enumerator are, in this case, the IIDs of the interfaces for IJolietDiscMaster and IRedbookDiscMaster.

4) Enumerate the list of supported disc recorders (specific to the active format), and then choose one of these to be the active recorder. IDiscRecorder represents a physical device.

5) Use ProgressAdvise on IDiscMaster to register for progress callbacks.

6) Use the interface for the selected format to build up content. Content builds incrementally, so tracks or folder contents may be added to a disc piece by piece. Building up this content is called “staging an image”. The contents of the staged image cannot be incrementally deleted (you can’t remove a track that has been added), but it is possible to clear all the contents of a staged image so that staging can start again. Use the ClearFormatContent method on the IDiscMaster interface to restart staging.

For Audio:

7) Use CreateAudioTrack to indicate a new audio track is being started on the disc.

8) Use AddAudioTrackBlocks to add raw audio data to a track. At any point, the application can use the GetxxxAudioBlocks methods to get statistical information like total blocks remaining, or total blocks used.

9) Use CloseAudioTrack to close out an audio track.

10) Repeat steps 7-9 until out of space or all audio tracks have been written.

11) Use the RecordDisc method of IDiscMaster to record the disc.

12) Close the IMAPI session using IDiscMaster. Closing out the session will wipe out whatever may have been stored in the disc stash.

For Data:

13) Use AddData to add the contents of folder to the image. The sub-items within a passed in folder become placed in the root of the image file. Use the GetDataBlocks methods to get statistical information like total blocks remaining or total blocks used.

14) Repeat step 13 until out of space or all the data has been added.

For All Discs:



15) Use the RecordDisc method of IDiscMaster to record the disc.

16) Close the IMAPI session using IDiscMaster. Closing out the session will clear the disc stash.

Extending the IDiscmaster and IDiscRecorder InterfacesSuch implementations should pay attention to restrictions on simultaneous access.

Exclusive access is not provided directly the by upper level IMAPI components. There may be multiple instances of the MSDiscMasterObj active on a system at the same time. However, in the case of the Microsoft implementation of IMAPI, there is only a single disc stash allowed open on the system at a time (it is definitely exclusive access).

A third-party implementation that extends IMAPI might not utilize the stash at all, and might therefore allow simultaneous access to all of its format masters.

As with IDiscMaster, an implementer of IDiscRecorder should pay attention to concurrency issues with the physical recorders. IMAPI burn engines must access physical devices through IMAPIW2K.SYS, which provides device enumeration, locking, and raw access to CD-ROM, CD-R, and CD-R/W style devices. It is IMAPIW2K.SYS that exports the GUIDs used to Init instances of MSDiscRecorderObj.

Creating Multi-session DiscsIMAPI is capable of creating multi-session data discs. There are a few additional points that should be kept in mind when doing so.

SetActiveDiscRecorder determines whether there is an IMAPI multi-session disc in the active drive upon setting. If so, IMAPI goes into multi-session mode automatically. Using ClearFormatContent after multi-session mode has been established will cause IMAPI to return to single-session mode. That means that a blank disc will be required for a RecordDisc burn. If in multi-session mode and a call is made to RecordDisc, the same disc must be in the active recorder or an error code of IMAPI_E_WRONGDISC will be returned.

Selecting a recorder while in an active Joliet format will cause IMAPI to read information off of the currently installed disc of the recorder. If this disc is a previous IMAPI Joliet disc and has space for another session, IMAPI will automatically set itself to multi-session mode. This disc will have to be present in the active recorder when RecordDisc is called.

There are 21 MB used to close the first session on a disc. Each additional session requires 11 MB to close.

Language NotesThe IMAPI interface can be utilized through its type library within Visual Basic or Visual C++. Use the following steps to import the type library in Visual C++:

1. Start the OLE/COM Object Viewer delivered with the SDK and Visual C++.

2. Expand the “All Objects” node and scroll down to the Microsoft IMAPI Disc Master object. Click on the object’s name, but do not expand the node to avoid a COM reference.



3. In the right hand pane select the “Implementation” tab and the “Local Server” sub-tab. Note the IMAPI.EXE’s full “Path to Implementation.”

4. Use a ‘#import “<Path to Implementation>”’ line in the header of those modules which will reference the IMAPI objects and their interfaces.

5. Utilize the classes or smart pointers defined in the header files generated by the import to instantiate and manipulate IMAPI objects.

A full discourse on the proper use of COM through the #import statement is beyond the scope of this document. The reader should be very familiar with the contents of #import Visual C++ documentation in the MSDN library. It covers, in detail, the establishment of a namespace, the creation of the .TLH and .TLI files, and the creation of specialized smart pointers for the classes in those headers. Make sure to actually open and review the .TLH and .TLI files created by the import statement. It really will clear up any confusion surrounding parameters, return values, or exception generation.

Image Mastering API ReferenceInterfaces

IDiscMaster

The IDiscMaster interface allows an application to reserve an image mastering API, enumerate disc mastering formats and disc recorders supported by an image mastering object, and start a simulated or actual burn of a disc. Although an image mastering object may support several formats through different interfaces, not all formats may be accessible through a specific recorder. For this reason a recorder must be chosen with SetActiveDiscRecorder after a specific format is chosen with SetActiveDiscRecorderFormat. The MSDiscMasterObj supports IJolietDiscMaster and IRedbookDiscMaster formats.

Methods in Vtable Order

Iunknown Methods Description

QueryInterface Returns pointers to supported interfaces.

AddRef Increments the reference count.

Release Decrements the reference count.

IDiscMaster Methods Description

Open Open an Image Mastering API object.

EnumDiscMasterFormats Retrieve a format enumerator.

GetActiveDiscMasterFormat Get the currently selected recorder format.

SetActiveDiscMasterFormat Set a new active recorder format.

EnumDiscRecorders Retrieve a recorder enumerator.

GetActiveDiscRecorder Get the currently active disc recorder.

SetActiveDiscRecorder Select a new active disc recorder.

ClearFormatContent Reset the “contents” of an unburned image.

ProgressAdvise Request progress notifications from IMAPI.



ProgressUnadvise Cancel progress notifications from IMAPI.

RecordDisc Burn the staged image to active recorder.

Close Discontinue use of IMAPI.

IDiscMaster::Open

Opens an upper level IMAPI object for access by a client application. IdiscMaster::Open may be called even if it is already opened by another app.

Note that all of the other methods of this interface, as well as the IJolietDiscMaster and IRedbookDiscMaster interfaces, should return nothing but IMAPI_E_NOTOPENED until the open call succeeds.

HRESULT Open();

Return Values

S_OKAccess to the interface has been granted and all methods on this and the format interfaces are enabled.

IMAPI_E_ALREADYOPENThe object is already opened.

IDiscMaster::EnumDiscMasterFormats

The EnumDiscMasterFormats function provides an enumerator for all disc mastering formats supported by this disc master object. A disc master format specifies the structure of the content in a staged image file (data/audio) and the COM interface that must be used to manipulate the staged image.

The function returns a standard COM enumerator as documented in the MSDN library on IEnumXXXX, including the Next, Skip, Reset, and Clone calls. In this particular case the type returned in Next’s array is “IID”. In other words, each call to Next will return an array of IIDs, one IID per supported disc master format. A call to SetActiveDiscMasterFormat must be made to select the active format and retrieve a pointer to a format specific interface (do not use QueryInterface in this case because the interface won’t be associated with the active format).

HRESULT EnumDiscMasterFormats( IEnumDiscMasterFormats **ppEnum );

Parameter

ppEnum[out] Address of a pointer to the enumerator.

Return Values

S_OKAn enumerator of the formats was successfully returned.

IMAPI_E_NOTOPENEDThe call failed because IMAPI has not been opened with a call to Open.



Remarks

The MSDiscMasterObj always returns an enumerator that identifies the IJolietDiscMaster and IRedbookDiscMaster formats by their interface IDs.

It is assumed by IMAPI that an application that is capable of using the IRedbookDiscMaster interface will know the IID and semantics of that interface, and it will be aware of it while enumerating the supported formats through the returned interface. Currently, there are only two possible choices, IID_RedbookDiscMaster and IID_IjolietDiscMaster, as defined in the Imapi.h.

IDiscMaster::GetActiveDiscMasterFormat

Retrieves the currently active disc recorder format. The active format specifies both the structure of the staged image file content (audio/data) and the COM interface that must be used to manipulate that staged image.

HRESULT GetActiveDiscMasterFormat( LPIID lpiid );

Parameter

lpiid[out] The IID of the currently active format.

Return Values

S_OKThe IID of the currently active mastering format has been returned successfully.

IMAPI_E_NOACTIVEFORMATAn active format has not been selected using SetActiveDiscMasterFormat.


Remarks

The MSDiscMasterObj only supports the IIDs for IJolietDiscMaster and IRedbookDiscMaster. Use the SetActiveDiscMaster format to choose a disc format and retrieve an interface pointer for that format master.

IDiscMaster::SetActiveDiscMasterFormat

The SetActiveDiscMasterFormat function sets the currently active disc recorder format. The active format specifies both the structure of the staged image file content (audio/data) and the COM interface that must be used to manipulate that staged image.

NOTE: A successful call to this function will clear the contents of the currently staged image. In addition, it may change the list of supported disc recorders. This is because not all recorders have to support all formats. Changes to the recorder list will be announced with a call to IDiscMasterProgressEvents::NotifyPnPActivity. If the currently selected recorder is not a member of the new set of supported devices, then there will no longer be an active recorder (similar to the state after the first call to



IDiscMaster::Open. In this case, the application must select a new active recorder before initiating a burn.

HRESULT SetActiveDiscRecorderFormat( REFIID riid, IUnknown **ppUnk );

Parameter

riid[in] The IID of the currently active format.

ppUnk[out] Pointer to the COM interface for the new disc format.

Return Values

S_OKThe active image format has been changed, and the content of the image file has been cleared (the whole image must be re-staged).


Remarks

The MSDiscMasterObj only supports the IIDs and interface pointers for IJolietDiscMaster and IRedbookDiscMaster. If there is no format set, IDiscMaster always defaults to Joliet format. It is the responsibility of every application to select a format master through the use of EnumDiscMasterFormats and this function.

Note that a call to this function may change the list of available recorders. See the Remarks section of EnumDiscRecorders below for more information on this condition. If there is no format set, IDiscMaster always defaults to Joliet format.

IDiscMaster::EnumDiscRecorders

Provides an enumerator for all of the disc recorders supported by the active disc master format.

The function returns a standard COM enumerator (see documentation on IEnumXXXX in MSDN). The enumerator includes the Next, Skip, and Reset calls. In this particular case, each call to Next will return an array of pointers to an IDiscRecorder. Each of the recorder interfaces represents a single available recorder already associated with an underlying physical disc recorder (i.e. Init has already been called).

HRESULT EnumDiscRecorders( IEnumDiscRecorders **ppEnum );

Parameter

ppEnum[out] Address of a pointer to the enumerator.

Return Values

S_OKThe enumerator was successfully returned.




IMAPI_E_NOACTIVEFORMATThe data format has not been selected.

Remarks

The list of available recorders may change because of Plug and Play arrivals or departures, or because of a call to SetActiveDiscMasterFormat. An application is notified of these changes when it receives a call to IDiscMasterProgressEvents::NotifyPnPActivity. When a change occurs the application should make another call to this function to retrieve a new enumerator, because each enumerator contains a snapshot of the devices supported at the time of the enumeration.

Note that when a device is removed, its pointer and IDiscRecorder interface must remain valid even though the underlying physical device is missing. In this case, operations on an IDiscRecorder or a request to record a disc may return IMAPI_E_DEVICE_NOTPRESENT.

The Maximum write speed data is updated when this is called. The default setting is the highest returned write speed.

IDiscMaster::GetActiveDiscRecorder

The GetActiveDiscRecorder method returns an interface pointer to the active disc recorder. The active disc recorder is the recorder where a burn will occur when RecordDisc is called.

HRESULT GetActiveDiscRecorder( IDiscRecorder **ppRecorder );

Parameter

ppRecorder[out] A pointer to the IDiscRecorder interface of the currently selected disc recorder.

Return Values

S_OKThe active disc recorder is present and has been returned successfully.



IMAPI_E_NOACTIVERECORDERA disc recorder has not been selected, and there is no default. Use SetActiveDiscRecorder to choose an active recorder.

IMAPI_E_DEVICE_NOTPRESENTThe currently active disc recorder has been invalidated because the device was removed from the system. Choose a new active recorder using SetActiveDiscRecorder.



Remarks

After the initial Open call there is no active disc recorder. In other words, there is no default active disc recorder. An application using this API must specifically select both an active mastering format and an active disc recorder before initiating a burn.

Note that the active disc recorder can be invalidated by a removal of the device or a change to the active disc mastering format. For example, a USB CD-R device may be disconnected from the machine while the application is still running (the application is alerted to this condition by a call to IDiscMasterProgressEvents::NotifyPnPActivity). In either case, a new active disc recorder must be chosen before this call will work again.

IDiscMaster::SetActiveDiscRecorder

Selects an active disc recorder. The active disc recorder is the recorder where a burn will occur when RecordDisc is called.

HRESULT SetActiveDiscRecorder( IDiscRecorder *pRecorder );

Parameter

pRecorder[in] Pointer to the interface of a disc recorder object. This pointer should have been returned by a previous call to EnumDiscRecorders.

Return Values

S_OKThe active disc recorder has been successfully changed.



IMAPI_E_DEVICE_NOT_PRESENT

The currently active device is no longer valid because it was removed from the system.

Remarks

SetActiveDiscRecorder must be called after the media to be used has been inserted, and before calling the AddData interface.

The SetActiveDiscRecorder does rely on exclusive access to the MSDiscStashObj, which means that it becomes an exclusive access interface once opened. Subsequent calls to Open through other instances of SetActiveDiscRecorder will fail with IMAPI_E_STASHINUSE.

Selecting a recorder while in an active Joliet format will cause IMAPI to read information off the currently installed disc of the recorder. If this disc is a previous IMAPI Joliet disc and has space for another session, IMAPI will automatically set itself to multi-session mode. This disc will have to be present in the active recorder when RecordDisc is called.



The Maximum write speed data is updated when this is called. The default write speed is set to the highest write speed returned.

IDiscMaster::ClearFormatContent

This function will clear the contents of the current stash file. The stash file is an internal structure that is used to “stage” a disc before recording it to media.

Multi-session Note: SetActiveDiscRecorder determines if there is an IMAPI multi-session disc in the active drive upon setting. If so, IMAPI goes into multi-session mode automatically. Using ClearFormatContent after multi-session mode had been established will cause IMAPI to return to single-session mode. That means that a blank disc will be required for a RecordDisc burn.

HRESULT ClearFormatContent();

Return Values

S_OKThe image file has been cleared and staging can begin again.


Remarks

Be very careful with this function. There is no confirmation and no recovery. If an application fills the image file with a lot of data, and then calls this function that data is gone.

IDiscMaster::ProgressAdvise

The ProgressAdvise function registers an application for progress callbacks. See the IDiscMasterProgressEvents interface description below for more information on the callbacks that are issued.

HRESULT ProgressAdvise( IDiscMasterProgressEvents *pEvents, UINT_ptr *pnCookie);

Parameter

pEvents[in] Pointer to an IDiscMasterProgressEvents interface. Callbacks will occur to this interface.

pnCookie[out,retval] A “cookie” which uniquely identifies this callback registration. Keep the cookie because it will be needed for ProgressUnadvise.

Return Values

S_OKThe progress interface for callbacks has been successfully registered.




IDiscMaster::ProgressUnadvise

Cancel callbacks against a previously registered interface.

HRESULT ProgressUnadvise( UINT_ptr nCookie );

Parameter

nCookie[in] The cookie returned by a previous call to ProgressAdvise.

Return Values

S_OKCallbacks to the previously registered interface have been cancelled.


IDiscMaster::RecordDisc

The RecordDisc function starts the actual recording process on the active disc recorder. It transfers information staged in the disc image (in the active format) to a piece of media in the recorder. The call to this function will not return until the burn is complete, although progress callbacks will be made if registered with ProgressAdvise. Any errors will cause this function to return with little or no corrective action on the part of this method.

Multi-session Note: SetActiveDiscRecorder determines if there is an IMAPI multi-session disc in the active drive upon setting. If so, IMAPI goes into multi-session mode automatically. If in multi-session mode and a call is made to RecordDisc, the same disc that established multi-session mode must be in the active recorder or an error code of IMAPI_E_WRONGDISC will be returned.

HRESULT RecordDisc( boolean bSimulate, boolean bEjectTray );

Parameter

bSimulate[in] If true, media in the active disc recorder is not actually burned. Instead, a simulated burn is performed. The simulation is a good test of a disc recorder at various speeds, and so on, because most of the same commands and operations are performed as in a real burn. If this parameter is false, then the media in the recorder is actually fully burned.

bEjectTray[in] Eject the CD after the burn or not.

Return Values

S_OKThe simulation or actual burn succeeded.




IMAPI_E_WRONGDISCThe call failed because when the active recorder was selected, a previous IMAPI disc was detected and a multi-session session was established. RecordDisc has now detected that this disc is no longer in the active recorder.

IMAPI_E_NOACTIVEFORMATA disc mastering format has not been chosen using SetActiveDiscMasterFormat.

IMAPI_E_NOACTIVERECORDERAn active recorder has not been chosen using SetActiveDiscRecorder.

IMAPI_E_USERABORTThe recording was cancelled during a progress callback by a TRUE return from a call to the QueryCancel method of IDiscMasterProgressEvents.

IMAPI_E_GENERICAn unexpected and unexplained failure ended the recording.

IMAPI_E_MEDIUM_NOTPRESENTThere is no media in the active disc recorder. The application should prompt for media from the user, and then it should retry the call to RecordDisc. There is no preferred mechanism for performing this task. It is suggested that the media be ejected and a dialog box presented to the user. The media status could be checked again once the dialog is dismissed, or an application could proactively poll (for example, once per second) to check if good media has been inserted.

IMAPI_E_DEVICE_NOTACCESSIBLEAnother application or IMAPI engine has reserved the active disc recorder. Try again later.

IMAPI_E_DEVICE_NOTPRESENTThe currently active disc recorder has been invalidated because the device was removed from the system. Choose a new active recorder using SetActiveDiscRecorder.

IMAPI_E_INITIALIZE_WRITEAn error occurred while setting the active disc recorder up for a write.

IMAPI_E_INITIALIZE_ENDWRITEAn error occurred while setting the active disc recorder up to close the disc.

IMAPI_E_FILESYSTEMAccess to the active disc recorder through the operating system has prevented IMAPI from reserving the disc recorder for exclusive use. Try again later.

IMAPI_E_DISCINFOAn error occurred while attempting to access the media inserted into the active disc recorder.

IMAPI_E_TRACKOPENA audio track is currently open. Close the currently open track before recording the disc.

IMAPI_E_INVALIDIMAGEThe image file is empty or corrupted. In either case, there is no usable content and the record operation has been cancelled.



IMAPI_E_LOSS_OF_STREAMINGContent streaming was lost, a buffer under-run may have occurred.

IMAPI_E_COMPRESSEDSTASHThe stash is located on a compressed volume and cannot be read.

IMAPI_E_ENCRYPTEDSTASHThe stash is located on an encrypted volume and cannot be read.

IMAPI_E_NOTENOUGHDISCKFORSTASHThere is not enough free space to create the stash file on the specified volume.

IMAPI_E_REMOVABLESTASHThe specified stash location is a removable media.

Remarks

This function does not return before completion of the operation. It provides no provision for asynchronous or overlapped operation.

The staged image data is not valid after a call to RecordDisc. This allows the application to do both a simulated and an actual burn of the media. For security, the contents of the stash file are cleared automatically after successful completion of the first call to this function. A disc must be re-staged in order to burn it again.

The IDiscMaster::RecordDisc method expects to work with blank media for Audio (MEDIA_BLANK above). If this function returns anything but MEDIA_BLANK, then the media may need to be erased (for example, CD-RW media in a CD-RW drive). See the Erase function below.

IDiscMaster::Close

Closes the IMAPI interface so that other applications can use it.

HRESULT Close();

Return Values

S_OKThe IMAPI interface was successfully closed.

Remarks

Content not committed to media through a call to RecordDisc will be lost.

Closing an already closed DiscMaster will return S-OK.

IDiscRecorder

The IDiscRecorder interface enables access to a single disc recorder device, labeled the active disc recorder. An IMAPI object such as MSDiscMasterObj maintains an active disc recorder.

An IDiscRecorder object represents a single hardware device, but there may be multiple instances of IDiscRecorder all pointing at the same hardware device. OpenExclusive is then used to access that device.



When to Use

Use an instance of this object to select the recorder for a burn through IDiscMaster and to perform basic control tasks on a specific physical disc recorder.

Note that an application does not call CoCreateInstance for one of these objects, but instead uses the IDiscMaster::EnumDiscRecorders function to retrieve an enumerator that returns pointers to all the recorders valid for a specific format.


IUnknown Methods Description




IDiscRecorder Methods Description

Init Initializes the object for an underlying device.Used internally only.

GetRecorderGUID Retrieves the underlying device GUID.

GetRecorderType Identifies device as CD-R or CD-RW.

GetDisplayNames Retrieves a name suitable for GUI display.

GetBasePnPID Returns identifier unique to device class.

GetPath Returns an OS path to the device.

GetRecorderProperties Retrieve IPropertyStorage* for recorder.

SetRecorderProperties Set properties for the recorder.

OpenExclusive Opens a device for exclusive use.

QueryRecorderStatus Checks if recorder is ready to do a burn.

QueryMediaType Identifies the type of media in the recorder.

QueryMediaInfo Retrieves media properties.

Eject Ejects a recorder’s tray, if possible.

Erase Erases CD-R/W media, if possible.

Close Close a recorder after exclusive access.

Remarks

Note that all of the IDiscRecorder interfaces may be used on an IDiscRecorder object even if the disc recorder is not the active disc recorder. The IMAPI client does NOT have to call IdiscMaster::SetActiveDiscRecorder first.



IDiscRecorder::GetRecorderGUID

The GetRecorderGUID function returns the GUID of the physical disc recorder currently associated with this recorder object.

HRESULT GetRecorderGUID ( byte * pbyUniqueID, ULONG ulBufferSize, ULONG *pulReturnSizeRequired);

Parameter

pbyUniqueID[in, out] Pointer to a GUID buffer to be filled in with this recorder’s current GUID information. Pass in NULL for querying the required buffer size.

ulBufferSize[in] Size of the GUID buffer, or 0 when querying the required buffer size.

pbyUniqueID[out] Size of the GUID information.

Return Values

S_OKThis recorder object has been initialized, and the GUID for the physical recorder associated with it has been returned.

IMAPI_E_NOTINITIALIZEDThis recorder object has not been initialized.

IMAPI_S_BUFFER_TO_SMALLThis recorder object is small, but as much of the GUID is returned as possible in the given buffer. Although the hresult is not zero, it is not an exception.

Remarks

Note that if a null is ever passed for the first parameter, the user must also pass a 0 for the second parameter.

IDiscRecorder::GetRecorderType

The GetRecorderType method indicates whether the disc recorder is a CD-R or CD-R/W type device. This does not indicate the type of media that is currently inserted in the device.

HRESULT GetRecorderType( long *fTypeCode );

Parameter

fTypeCode[out] One of RECORDER_CDR or RECORDER_CDRW.

Return Values

S_OKThe device type was successfully returned.




IDiscRecorder::GetDisplayNames

The GetDisplayNames function returns a BSTR with a formatted name for the recorder that can be displayed. The name consists of the manufacturer and product identifier of the device.

HRESULT GetDisplayNames( BSTR *pbstrVendorID, BSTR *pbstrProductID, BSTR *pbstrRevision);

Parameter

pbstrVendorID[out] A displayable name identifying the vendor of the disc recorder. The pointer passed may be NULL if the calling application does not need this value.

pbstrProductID[out] A displayable name identifying the disc recorder’s product name. The pointer passed may be NULL if the calling application does not need this value.

pbstrRevision[out]A displayable name that identifies the revision of the disc recorder. This is typically the revision of the recorder firmware, but it isn’t a requirement (it may be a revision for the entire device). The pointer passed may be NULL if the calling application does not need this value.

Return Values

S_OKThe display name was successfully returned.


Remarks

The display names are typically combined into a string that is displayed in recorder selection list boxes or other GUI components.

Note that the combination of these three strings does not produce a unique identifier for this specific recorder. Combine these strings with the string returned from GetPath (below) to create a unique value.

IDiscRecorder::GetBasePnPID

The GetBasePnPID function returns a string designed for internal use only. The string is basically a concatenation of a recorders manufacturer, product ID, and revision information (if available). It can be used to consistently identify a specific class of device, not by CD-R or CD-R/W, but by make and model. The string can be used by applications that wish to customize behavior according to the specific recorder type.

HRESULT GetBasePnPID( BSTR *pbstrBasePnPID );



Parameter

pbstrBasePnPID[out] The base PnP ID string as described above.

Return Values

S_OKThe basic PnP ID string has been returned successfully.


IDiscRecorder::GetPath

The GetPath function returns a path to the device within the operating system. This may be a drive letter such as ‘E:\’, or a full path such as ‘\Device\CdRom0’. This path should be used by applications in conjunction with the display name to completely identify an available disc recorder.

HRESULT GetPath( BSTR *pbstrPath );

Parameter

pbstrPath[out] The path to the disc recorder.

Return Values

S_OKThe path to the disc recorder has been successfully returned.


IDiscRecorder::GetRecorderProperties

The GetRecorderProperties function returns a pointer to an IPropertyStorage interface. The interface is for a persistent property, although the properties are not retained after IMAPI is closed. A property set format is convenient for IMAPI because it stores an ID/TYPE/VALUE combination, as well as ID/NAME associations. Each combination is a single property, and IMAPI uses these properties for various values that are unique to specific recorders. For example, most recorders would support a WriteSpeed property. Getting the properties returns an interface to a property set that has all of the available properties and their current values. The caller can then modify these properties and change them by calling SetRecorderProperties.

HRESULT GetRecorderProperties( IPropertyStorage **ppPropStg );

Parameter

ppPropStg[out] Address of IPropertyStorage* pointer variable that receives the interface pointer to the property set with all current properties defined.



Return Values

S_OKThis disc recorder supports properties, and they have been successfully returned.

IMAPI_E_DEVICE_NOPROPERTIESThis disc recorder does not support any properties.


Remarks

Current properties include:

Current Write speed. The write speed that the current active recorder is set to. Enumerates through a recorder’s IPropertyStorage as “WriteSpeed.” If the write speed is set to FFFFFFFFh, then the drive will write at the highest speed it is capable of for the given media, regardless of what the reported maximums are.

Maximum Write speed. The maximum write speed that the recorder can be set to. Enumerates through a recorder’s IPropertyStorage as “MaxWriteSpeed.” The maximum write speed is only updated when IDiscmaster::EnumDiscRecorders or IDiscMaster::SetActiveDiscRecorder is called.

Audio Gap Size. The amount of “quiet time“ between audio tracks when using the Redbook interface to create audio discs. Enumerates through a recorder’s IPropertyStorage as “AudioGapSize.” This is the amount of blank audio blocks to place between tracks. The maximum valid value for this is 225. Note that 75 blocks is one second of “quiet time.”

Note: Two additional blocks are always written at the end of each track, before the audio gap blocks of the next track. The number of block between the audio tracks is actually two more than is specified in this property. The default value for this property is 150 blocks (2 seconds) and that most drives do not behave well if this is set to any other value.

IDiscRecorder::SetRecorderProperties

The SetRecorderProperties function accepts an IPropertyStorage pointer for an object with all the properties that the application wishes to change. Sparse settings are supported. It is recommended, however, to query for a property set using GetRecorderProperties, modify only those settings of interest, and then call SetRecorderProperties to change all values at once.

HRESULT SetRecorderProperties( IPropertyStorage *pPropStg );

Parameter

pPropStg[in] Pointer to the IPropertyStorage interface that the disc recorder can use to retrieve new settings on various properties.

Return Values

S_OKThe properties for disc recorder have been successfully changed.



IMAPI_ S_PROPERTIESIGNOREDThe call succeeded, but one or more properties were read-only or unrecognized. Those properties were ignored and their settings were not changed. GetRecorderProperties may be used to determine the list of properties that are specific to a recorder.

IMAPI_E_DEVICE_NOPROPERTIESThis disc recorder does not support any properties.


RPC_X_NULL_REF_POINTERThis calls fails because a NULL pointer was passed.

Remarks

Some properties may be read-only (like “MaxWriteSpeed”). Both read-only properties and properties that don’t match supported properties will be ignored without generating an error (see IMAPI_ S_PROPERTIESIGNORED). For example, someone could submit a property set to this interface and attempt to change “MaxWriteSpeed” and the ClearlyNeverHeardOfBefore property. Since one is read-only and the other is an unknown value, both are ignored and the function succeeds. An application should verify property settings with a call to GetRecorderProperties after a call to SetRecorderProperties.

IDiscRecorder::OpenExclusive

The Open Exclusive function opens a disc recorder for exclusive access. This will block file system access to a recorder through apps like Explorer. The recorder must be opened with this function before it is possible to use the following methods: QueryMediaType, Eject, Erase, Close.

HRESULT OpenExclusive();

Return Values

S_OKThe recorder has been opened for exclusive access successfully.


IMAPI_E_DEVICE_NOTACCESSIBLEAnother application or IMAPI engine has reserved the active disc recorder. Try again later.

IMAPI_E_DEVICE_NOTPRESENTThe currently active disc recorder has been invalidated because the device was removed from the system. Choose a new active recorder using IDiscMaster::SetActiveDiscRecorder.

Remarks

It is important that the recorder be closed before you attempt a call to IDiscMaster::RecordDisc or it will fail with IMAPI_E_DEVICE_NOTACCESSIBLE. The device is exclusively committed to access through either IDiscRecorder or



IDiscMaster, but not both at the same time. This is to ensure that there is no confusion regarding allowed operations and ownership of a recorder during application control or a burn.

An exclusive lock should be held for as short a time as possible. Requests that come from other operating system components are not queued for later execution. Instead, they are simply failed. This could cause confusion with users who don’t think a burn is in progress.

Any time that an OpenExclusive is called, it will appear to the file system that the disc has been removed. When the corresponding IDiscMaster::Close is called, the media will re-appear to the file system. This may cause auto-run issues.

IDiscRecorder::QueryMediaType

The QueryMediaType function will query the device directly to detect the type of media currently inserted in the recorder, if any.

HRESULT QueryMediaType( long *fMediaType, long *fMediaFlags );

Parameter

fMediaType[out] If there is no media present in the drive, both fMediaType and fMediaFlags will be 0. If there is media in the recorder, then fMediaType will return one or more of the following flags:

MEDIA_CDDA_CDROM

MEDIA_CD_ROM_XA

MEDIA_CD_I

MEDIA_CD_EXTRA

MEDIA_CD_OTHER

MEDIA_SPECIAL

fMediaFlags[out] When media is present in the drive, this parameter contains flags that qualify the above fMediaType. This parameter is a bit mask made up of one or more of the following values:

MEDIA_BLANK

MEDIA_RW

MEDIA_WRITABLE

Return Values

S_OKThe media type code has been successfully returned.


IMAPI_E_NOTOPENEDThe call failed because IMAPI has not been opened through a call to IDiscRecorder::OpenExclusive.



IMAPI_E_DEVICE_NOTPRESENTThe currently active disc recorder has been invalidated because the device was removed from the system. Choose a new active recorder using IDiscMaster’s SetActiveDiscRecorder.

IDiscRecorder::QueryMediaInfo

The QueryMediaInfo function returns information about the currently mounted media, such as the total number of blocks used on the media.

HRESULT QueryMediaInfo(

byte *pbsessions, byte *pblasttrack, unsigned long *ulstartaddress, unsigned long *ulnextwritable,unsigned long *ulfreeblocks

);

Parameter

pbsessions[out] The number of sessions on the disc.

pblasttrack[out] The track number of the last track of the previous session.

ulstartaddress[out] The start address of the last track of the previous session.

ulnextwritable[out] The address where writing will begin.

ulfreeblocks[out] How many blocks are available for writing.

Return Values

S_OKThe information being returned is valid.

IMAPI_E_NOMEDIAINDRIVEThere is no media in the drive to query.

IMAPI_E_NOTOPENEDThe device object is not opened.

IMAPI_E_DEVICENOTPRESENTThe device is not present.


Remarks

Using this function allows the calculation of parameters such as the amount of free space left on the disc without using a setting on the active disc recorder, which causes



an exclusive open. The total size of the disc can be calculated by summing the next writable address and free blocks.

IDiscRecorder::Eject

The Eject function will unlock and eject the tray of the disc recorder, if possible.

HRESULT Eject();

Return Values

S_OKThe call to eject the tray succeeded. It is unknown whether the tray actually ejected.



IMAPI_E_DEVICE_NOTPRESENTThe currently active disc recorder has been invalidated because the device was removed from the system. Choose a new active recorder using IDiscMaster’s SetActiveDiscRecorder.

Remarks

Not all recorders support calls to eject their media. Regardless, this function will attempt to eject media.

IDiscRecorder::Erase

The Erase function attempts an erase of CD-R/W media if this is a CD-R/W disc recorder. Both full and quick erases are supported.

Note that erasing a disc can be a very lengthy operation (sometimes in excess of an hour), and there is no progress report for this operation, and no erase completion notification.

HRESULT Erase( boolean bFullErase );

Parameter

bFullErase[in] Indicates if quick (false) or full (true) erase should be performed on the CD-R/W media.

Return Values

S_OKThe CD-RW media in the recorder has been erased successfully.





IMAPI_E_GENERICThe erase operation on a CD-RW drive with CD-RW media failed for some reason.

IMAPI_E_MEDIUM_NOTPRESENTThere is no media in the disc recorder.

IMAPI_E_MEDIUM_INVALIDTYPEThe media type is not CD-RW and it cannot be erased.


IMAPI_E_DEVICE_INVALIDTYPEThe disc recorder is not a CD-RW.

Remarks

This function does not return before completion of the operation. In other words, it provides no provision for asynchronous or overlapped operation.

The quick option erases only the PMA, first session TOC, and the pre-gap of the first track. This will blank a disc quickly (between 1 and 2 minutes depending on recorder speed), but the program area will still contain user data. A full erase, on the other hand, erases the entire disc. This may provide for fewer compatibility problems, but it takes as much as 40 minutes to complete an erase operation.

IDiscRecorder::Close

The Close function releases exclusive access to a disc recorder. This restores file system access to the drive.

HRESULT Close();

Return Values

S_OKExclusive mode was closed out.






IRedbookDiscMaster

The IRedbookDiscMaster interface enables the staging of an audio CD image. It represents one of the formats supported by MSDiscMasterObj, and it allows the creation of multi-track audio discs in Track-at-Once mode (fixed size audio gaps).

Tracks are created in the stash file, data is added to them, and then they are closed. Only one track is staged at a time. This is called the open track. The remaining tracks are closed and committed to the image, while the open track has available to it all the blocks that are not in use by closed tracks.

When to Use

Use this interface to stage a Redbook audio image.






IRedbookDiscMaster Methods Description

GetTotalAudioTracks Returns total tracks staged in the image.

GetTotalAudioBlocks Returns total audio blocks available on disc.

GetUsedAudioBlocks Returns total audio blocks staged in image.

GetAvailableAudioTrackBlocks Returns blocks available for current track.

GetAudioBlockSize Returns the audio block size in bytes (2352).

CreateAudioTrack Indicates a new audio track to be staged.

AddAudioTrackBlocks Adds blocks of audio to track being staged.

CloseAudioTrack Closes out staging of an audio track.

IRedbookDiscMaster::GetTotalAudioTracks

The GetTotalAudioTracks method returns the total number of tracks that have either been staged or are being staged now.

HRESULT GetTotalAudioTracks( long *pnTracks );

Parameter

pnTracks[out,retval] The total number of closed and open tracks.

Return Values

S_OKThe total number of closed and open tracks has been returned successfully.



IMAPI_E_NOTOPENEDThe call failed because IMAPI has not been opened through a call to IDiscMaster::Open method.

IRedbookDiscMaster::GetTotalAudioBlocks

The GetTotalAudioBlocks function returns the total number of blocks available for staging audio tracks. The total includes all block types, including blocks that may need to be allocated for track gaps.

HRESULT GetTotalAudioBlocks( long *pnBlocks );

Parameter

pnBlocks[out,retval] The total number of audio blocks available on a disc.

Return Values

S_OKThe total number of audio blocks has been returned successfully.


IRedbookDiscMaster::GetUsedAudioBlocks

This function returns the total number of audio blocks that are in use.

HRESULT GetUsedAudioBlocks( long *pnBlocks );

Parameter

pnBlocks[out,retval] The total number of blocks in-use in closed and open tracks.

Return Values

S_OKThe total number of used audio blocks has been returned successfully.


IRedbookDiscMaster::GetAvailableAudioTrackBlocks

The GetAvailableAudioTrackBlocks function retrieves the current number of blocks that can actually be added to the track before an additional add will cause a failure for lack of space. This function accounts for gaps associated with open tracks. Additionally, if this function is called when there is no open track, it will return the maximum number



of audio blocks that could be added if a new track is created (accounting for gaps, and so on).

HRESULT GetAvailableAudioTrackBlocks( long *pnBlocks );

Parameter

pnBlocks[out,retval] The number of audio blocks that can be added to the open track before it must be closed.

Return Values

S_OKThe total number of blocks available to the open track has been returned successfully.


IRedbookDiscMaster::GetAudioBlockSize

The GetAudioBlockSize function returns the size of an audio block in bytes.

HRESULT GetAudioBlockSize( long *pnBlockBytes );

Parameter

pnBlockBytes[out,retval] The total size, in bytes, for a single audio block.

Return Values

S_OKThe size, in bytes, for a single audio block has been returned successfully.


Remarks

This function returns the hard-coded value 2352 at the present time.

IRedbookDiscMaster::CreateAudioTrack

The CreateAudioTrack function is called to begin staging a new audio track. It can only be called when there are no open audio tracks in the image. Up to 99 tracks can be created, and the open track may consume all remaining available audio blocks. Once opened, use the AddAudioTrackBlocks function to add data to the track.

HRESULT CreateAudioTrack( long nBlocks);

Parameter

nBlocks



[in] The number of audio blocks to be added to this track.

Return Values

S_OKA new audio track has been successfully opened for staging.


IMAPI_E_TRACKOPENAn audio track is already open. Close the currently open track before opening another.

Remarks

The Nblocks parameter is advisory only. This does not force the track length to that or any other value.

IRedbookDiscMaster::AddAudioTrackBlocks

The AddAudioTrackBlocks function actually adds blocks of audio data to the currently open track. This function can be called repeatedly until there is no more space available or the track is fully written. Once all blocks are added, CloseAudioTrack should be called to finish the track.

HRESULT AddAudioTrackBlocks( byte *pby, long cb );

Parameter

pby[in,size_is(cb)] Pointer to an array of bytes with the track blocks.

cb[in] Count of bytes in the buffer. This count must be a multiple of the audio block size.

Return Values

S_OKThe track data has been added to the open track successfully.

E_INVALIDARGThe byte count is wrong.

IMAPI_E_NOTOPENEDThe call failed because IMAPI has not been opened through a call to IDiscMaster::Open.

IMAPI_E_TRACKNOTOPENA track has not been opened with CreateAudioTrack.

IMAPI_E_DISCFULLCompleting this function fills the disc. As much of the data as possible was kept, and no more calls to add data can be made. The track must now be closed.



Remarks

If a call to this function would overrun the number of available audio blocks, then the function will return IMAPI_E_DISCFULL and it will keep as much of the audio data as it can. The corollary AddData function in IJolietDiscMaster will not keep any of the data so there are no bad files.

IRedbookDiscMaster::CloseAudioTrack

The CloseAudioTrack closes a currently open audio track. All audio tracks must be closed before the IDiscMaster::RecordDisc method can be called.

HRESULT CloseAudioTrack();

Return Values

S_OKThe open audio track has been closed successfully.


IMAPI_E_TRACKNOTOPENA track has not been opened with CreateAudioTrack.

IJolietDiscMaster

The IJolietDiscMaster interface enables the staging of a CD data disc. It represents one of the formats supported by MSDiscMasterObj, and it allows the creation of a single Track-at-Once data disc. The data is written to the disc with the Joliet and ISO-9660 file systems .

A temporary folder is built up and then added to the image. This can be repeated multiple times with the directory and file structures overlapping. The overlapping file structures will appear seamlessly when read back. With the overwrite option used, overlapping paths will cause the last file added to show up in the directory, while the earlier files with conflicting names are still present on the disc but now not readable by normal means.






IJolietDiscMaster Methods Description

GetTotalDataBlocks Returns total data blocks available on disc.

GetUsedDataBlocks Returns total data blocks staged in image.

GetDataBlockSize Returns the data block size in bytes (2048).

AddData Adds directories and files to the image file.



GetJolietProperties Gets the properties of the Joliet interface.

SetJolietProperties Sets the properties of the Joliet interface.

IJolietDiscMaster::GetTotalDataBlocks

The GetTotalDataBlocks function returns the total number of blocks available for staging a Joliet data disc. The data returned from this function is valid only after a SetActiveDiscRecorder call, especially in a multi-session burn.

HRESULT GetTotalDataBlocks( long *pnBlocks );

Parameter

pnBlocks[out,retval] The total number of data blocks available on a disc.

Return Values

S_OKThe total number of data blocks has been returned successfully.


IJolietDiscMaster::GetUsedDataBlocks

The GetUsedDataBlocks function returns the total number of data blocks that are in use. The data returned from this function is valid only after a SetActiveDiscRecorder call, especially in a multi-session burn.

HRESULT GetUsedDataBlocks( long *pnBlocks );

Parameter

pnBlocks[out,retval] The total number of data blocks in use in the staged image.

Return Values

S_OKThe total number of used data blocks has been returned successfully.


IJolietDiscMaster::GetDataBlockSize

The GetDataBlockSize function returns the size of a data block in bytes.



HRESULT GetDataBlockSize( long *pnBlockBytes );

Parameter

pnBlockBytes[out,retval] The total size, in bytes, for a single data block.

Return Values

S_OKThe size, in bytes, for a single data block has been returned successfully.


Remarks

This function returns the hard-coded value 2048 at the present time.

IJolietDiscMaster::AddData

The AddData function adds all of the contents of a “root” storage to the staged image file. This storage will be enumerated to place all sub-storages and streams in the root file system of the stage image file. Sub-storage become folders and streams become files. Multiple calls to this function can be repeated to slowly stage an image file without wasting undue amounts of hard drive space building up a storage file.

Note that when you repeat an AddData, folders with duplicate files will cause a test of the lFileOverwrite flag and if non-zero, the file will be overwritten. The earlier files with conflicting names are still written to disc from the image file. If lFileOverwrite is zero and a file with the same name exists, AddData will fail with IMAPI_E_FILEEXISTS.

Note: While AddData can be called multiple times after calling SetActiveDiscRecorder and calling Burn, SetActiveDiscRecorder must be called any time a new image is started, and immediately before the first AddData call, regardless of whether the burner is the same one used in the previous image creation.

HRESULT AddData( IStorage *pStorage, long lFileOverwrite);

Parameter

pStorage[in] Path to the Storage whose sub-items are to be added to the root of the staged image file.

lFileOverwrite[in] Will overwrite existing files with the same name if non-zero.

Return Values

S_OKAll of the contents of the passed in storage object have been added to the disc successfully.




IMAPI_E_FILEEXISTSThe call failed because AddData encountered an existing file with the same name as a new file to add and the lFileOverwrite flag was zero. This will cause a failure and the image file will return to the state at which it was before the call to AddData.

IMAPI_E_DISCFULLCompleting this function would overflow the disc. None of the sub-items in the passed in storage object have been added to the staged image.

IMAPI_E_BADJOLIETNAMEThe storage object passed to AddData contains one or more sub-item names that do not conform to the Joliet file naming conventions. None of the contents of the storage have been added to the image.

Remarks

If a call to this function would overrun the number of available data blocks, then the function will return IMAPI_E_DISCFULL and it will ignore all of the data that was to be added. This ensures that the final Joliet file system will not be corrupted.

IJolietDiscMaster::GetJolietProperties

The GetJolietProperties function returns a pointer to an IPropertyStorage interface. The interface is for a persistent property, although the properties are not retained after IMAPI is closed. A property set is convenient for IMAPI because it stores an ID/TYPE/VALUE combination, as well as ID/NAME associations. Each combination is a single property, and IMAPI uses these properties for various values that are unique to the Joliet interface. For example, the Joliet interface would support a “VolumeName” property. Getting the properties returns an interface to a property set that has all of the available properties and their current values. The caller can then modify these properties and change them by calling SetJolietProperties.

HRESULT GetJolietProperties( IPropertyStorage **ppPropStg );

Parameter

ppPropStg[out] Address of IPropertyStorage* pointer variable that receives the interface pointer to the Joliet property set with all current properties defined.

Return Values

S_OKThis interface supports properties, and they have been successfully returned.

IMAPI_E_DEVICE_NOPROPERTIESThis interface does not support any properties.




IMAPI_E_NOACTIVEFORMATThe Joliet format is not active.

IMAPI_E_ WRONGFORMATThe Joliet format is not the active format

Remarks

Current properties include:

Volume Name. The volume name of the disc after recording. Enumerates through Joliet’s IPropertyStorage as “VolumeName.” Default is the current date.

Boot Image Placement. “PlaceBootImageOnDisc” is a Boolean that reports if a boot image is to be placed on the disc.

Boot Image ID. Returns a BString in “BootImageManufacturerIDString” (maximum of 24 bytes) that contains Identification information of the creator of the boot image.

Boot Image Platform. Indicates the OS the boot image is for. Returned as a byte value in “BootImagePlatform”: 0 = x86, 1 = PowerPC, 2 = Mac, others are undefined.

Emulation type. The “BootImageEmulationType” is a byte value that indicates the emulation type of the boot image: 0 = no emulation (raw CD blocks); 1 = 1.2-MB diskette image; 2 = 1.44-inch diskette image; 3 = 2.88-MB diskette image; 4 = hard disk emulation. For more information on each of these, the user should refer to the “El Torito Bootable CD-ROM Format Specification” by Phoenix Technologies.

Boot Image Location. The “BootImage” parameter returns an IStream object where the IMAPI client stores the boot image they want burned on the CD.

Note: By setting these four boot image parameters, IMAPI will create a bootable disc. No further work, beyond providing the boot image is necessary.

IJolietDiscMaster::SetJolietProperties

The SetJolietProperties function accepts an IPropertyStorage pointer for an object with all the Joliet properties that the application wishes to change. One should query for a property set using GetJolietProperties, modify only those settings of interest, and then call SetJolietProperties to change all values at once.

HRESULT SetJolietProperties( IPropertyStorage *pPropStg );

Parameter

pPropStg[in] Pointer to the IPropertyStorage interface that the Joliet interface can use to retrieve new settings on various properties.

Return Values

S_OKThe properties for the Joliet interface have been successfully changed.

IMAPI_S_PROPERTIESIGNOREDThe call succeeded, but one or more properties were read-only or unrecognized. Those properties were ignored and their settings were not changed. GetJolietProperties may be used to determine the list of properties that are specific to a Joliet interface.



IMAPI_E_DEVICE_NOPROPERTIESThis Joliet interface does not support any properties.


IMAPI_E_NOACTIVEFORMATThe Joliet format is not active.

IMAPI_E_ WRONGFORMATThe Joliet format is not the active format.

Remarks

Some properties may be read-only. Both read-only properties and properties that don’t match supported properties will be ignored without generating an error (see IMAPI__S_PROPERTIESIGNORED). For example, a property change request could be submitted to attempt to change a read only property and the ClearlyNeverHeardOfBefore property. Since one is read-only and the other is an unknown value, both are ignored and the function succeeds. An application should verify property settings with a call to GetJolietProperties after a call to SetJolietProperties.

IDiscMasterProgressEvents

The IDiscMasterProgressEvents interface provides a single interface for all the callbacks that can be made from IMAPI back to an application. An application implements this interface on one of its objects and then registers that interface using IDiscMaster::ProgressAdvise. All but one of the methods in this interface are related to progress during staging or burns. If an application is not interested in a particular callback, it must still implement the callback function and then return E_NOTIMPL on the call.






IdiscMasterProgressEvents Description

QueryCancel Checks whether a burn is to be cancelled.

NotifyPnPActivity Reports possible changes to recorder list.

NotifyAddProgress Reports progress of audio/data staging.

NotifyBlockProgress Reports progress of audio/data burn.

NotifyTrackProgress Reports progress of an audio burn.

NotifyPreparingBurn Reports progress during burn setup.

NotifyClosingDisc Reports progress while closing a disc.

NotifyBurnComplete Reports that the burn is fully complete.

NotifyEraseComplete Reports that an erase is fully complete.



IDiscMasterProgressEvents::QueryCancel

The QueryCancel function is called by IMAPI to check whether an AddData, AddAudioTrackBlocks, or RecordDisc should be cancelled.

HRESULT QueryCancel( boolean *pbCancel );

Parameter

pbCancel[out,retval] Set to true to cancel a burn, false to allow it to continue.

Return Values

S_OKThe cancel indication (pbCancel) has been set successfully.

E_NOTIMPLThis function has not been implemented.

IDiscMasterProgressEvents::NotifyPnPActivity

The NotifyPnPActivity function is called by IMAPI whenever it detects a change to the list of valid disc recorders. For example, if a USB CD-R driver is removed from the system this function will be called. An application should respond by getting a new list of valid recorders. If the current active recorder has been invalidated, then a new recorder should be chosen.

HRESULT NotifyPnPActivity();

Return Values

S_OKThe notification has been acknowledged.


IDiscMasterProgressEvents::NotifyAddProgress

The NotifyAddProgress function is called by IMAPI to notify an application of its progress in response to calls to IRedbookDiscMaster::AddAudioTrackBlocks or IJolietDiscMaster::AddData.

An application can rely on a block progress calls for “0 out of nTotalSteps” and “nTotalSteps out of nTotalSteps”.

HRESULT NotifyAddProgress( long nCompletedSteps, long nTotalSteps );

Parameter

nCompletedSteps[in] The number of arbitrary “steps” which have been completed in adding audio or data to a staged image.



nTotalSteps[in] The total number of arbitrary “steps” which must be taken to add a full set of audio or data to the staged image.

Return Values



IDiscMasterProgressEvents::NotifyBlockProgress

The NotifyBlockProgress function is called by IMAPI to notify an application of its progress in burning a disc on the active recorder. If an audio disc is being burned then the block counts reflect the progress in burning a single track. If a data disc is being burned then the block counts reflect the progress on the entire disc.

An application can rely on a block progress calls for “0 out of nTotal” and “nTotal out of nTotal”.

HRESULT NotifyBlockProgress( long nCompleted, long nTotal );

Parameter

nCompleted[in] The number of blocks that have been burned onto a disc/track so far.

nTotal[in] The total number of blocks that need to be burned to finish a disc/track.

Return Values



IDiscMasterProgressEvents::NotifyTrackProgress

The NotifyTrackProgress function is called by IMAPI during the burn of an audio disc. The call notifies an application whenever a new track is started or finished. The notification for 0 out of nTotalTracks indicates the start of track 1. The notification for track N out of nTotalTracks indicates that track N is complete and track N+1 is beginning. Finally, the notification for nTotalTracks out of nTotalTracks indicates the last track has been written.

HRESULT NotifyTrackProgress( long nCurrentTrack, long nTotalTracks );



Parameter

nCurrentTrack[in] The number of tracks that have been completely burned.

nTotalTracks[in] The total number of tracks that must be burned.

Return Values



IDiscMasterProgressEvents::NotifyPreparingBurn

The NotifyPreparingBurn function is called by IMAPI to notify the application that it is preparing to burn a disc. The estimated amount of time before the start of burn is passed. No further notifications will occur until the burn starts.

HRESULT NotifyPreparingBurn( long nEstimatedSeconds );

Parameter

nEstimatedSeconds[in] The number of seconds from notification that IMAPI estimates burn preparation will take.

Return Values



IDiscMasterProgressEvents::NotifyClosingDisc

The NotifyClosingDisc function is called by IMAPI to notify the application that it is has begun closing the disc (finishing the burn). The estimated amount of time before the end of burn is passed. No further notifications will occur until the burn ends.

HRESULT NotifyClosingDisc( long nEstimatedSeconds );

Parameter

nEstimatedSeconds[in] The number of seconds from notification that IMAPI estimates disc closing will take.

Return Values





IDiscMasterProgressEvents::NotifyBurnComplete

The NotifyBurnComplete function is called by IMAPI to notify an application that a call to IDiscMaster::RecordDisc is finished.

HRESULT NotifyBurnComplete( HRESULT status );

Parameter

status[in] The HRESULT code which will be returned from IDiscMaster::RecordDisc.

Return Values



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

Result Code Description

S_OK No error – Success

S_BUFFER_TO_SMALL

IMAPI_S_PROPERTIESIGNORED An unknown property was passed in a property set and it was ignored.

IMAPI_E_NOTOPENED An Open call hasn’t been made on IDiscMaster.

IMAPI_E_NOTINITIALIZED A recorder object has not been initialized.

IMAPI_E_USERABORT The user cancelled the operation

IMAPI_E_GENERIC Generic error

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 Device can’t be used / 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 Unable to initialize drive interface for writing

IMAPI_E_INITIALIZE_ENDWRITE Unable to initialize drive interface for closing

IMAPI_E_FILESYSTEM Error enabling/disabling file system access or auto-insertion detection

IMAPI_E_FILEACCESS Error writing image file



IMAPI_E_DISCINFO Error while trying to read disc data from 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 can’t hold any more data.

IMAPI_E_BADJOLIETNAME App 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 A active format master has not been selected using the IDiscMaster::SetActiveDiscMasterFormat.

IMAPI_E_NOACTIVERECORDER An active disc recorder has not been selected with IDiscMaster::SetActiveDiscRecorder.

IMAPI_E_WRONGFORMAT A call to IJolietDiscMaster has been made when IRedbookDiscMaster is the active format, or vice versa. Change the format and clear the image file contents if you wan to use a different format.

IMAPI_E_ALREADYOPEN A call IDiscMaster::Open call has already been made by your application against this object.

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, 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 Selected stash location is on a removable media.

IMAPI_E_NOMEDIAINDRIVE There is no media in the drive to query.


imapispec-v09

Documents

item developed based

block counts reflect

image mastering api

return values s ok

mb diskette image

active format specifies

active mastering format

image mastering object