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................................................................................................4 Using the Image Mastering API................................................................................................5 Extending the IDiscmaster and IDiscRecorder Interfaces....................................................6 Creating Multi-session Discs................................................................................................6 Language Notes........................................................................................................................6 Image Mastering API Reference...............................................................................................7 Interfaces..............................................................................................................................7 IDiscMaster..............................................................................................................................7 IDiscMaster::Open................................................................................................................8 IDiscMaster::Open...................................................................................................................8 IDiscMaster::EnumDiscMasterFormats.................................................................................8 IDiscMaster::EnumDiscMasterFormats...................................................................................8 IDiscMaster::GetActiveDiscMasterFormat............................................................................9 IDiscMaster::GetActiveDiscMasterFormat...............................................................................9 IDiscMaster::SetActiveDiscMasterFormat.............................................................................9 IDiscMaster::SetActiveDiscMasterFormat...............................................................................9 IDiscMaster::EnumDiscRecorders......................................................................................10 IDiscMaster::EnumDiscRecorders.........................................................................................10 Image Mastering API (IMAPI) — 2 IDiscMaster::GetActiveDiscRecorder..................................................................................11 IDiscMaster::GetActiveDiscRecorder....................................................................................11 IDiscMaster::SetActiveDiscRecorder..................................................................................12 IDiscMaster::SetActiveDiscRecorder.....................................................................................12 IDiscMaster::ClearFormatContent.......................................................................................13 IDiscMaster::ClearFormatContent.........................................................................................13 IDiscMaster::ProgressAdvise..............................................................................................13 IDiscMaster::ProgressAdvise................................................................................................13 IDiscMaster::ProgressUnadvise..........................................................................................14 IDiscMaster::ProgressUnadvise............................................................................................14 IDiscMaster::RecordDisc.....................................................................................................14 IDiscMaster::RecordDisc.......................................................................................................14 IDiscMaster::Close..............................................................................................................16 IDiscMaster::Close................................................................................................................16 IDiscRecorder........................................................................................................................16 IDiscRecorder::GetRecorderGUID......................................................................................17 IDiscRecorder::GetRecorderGUID........................................................................................17 IDiscRecorder::GetRecorderType.......................................................................................18 IDiscRecorder::GetRecorderType.........................................................................................18 IDiscRecorder::GetDisplayNames......................................................................................18 IDiscRecorder::GetDisplayNames.........................................................................................18 IDiscRecorder::GetBasePnPID...........................................................................................19 IDiscRecorder::GetBasePnPID.............................................................................................19 IDiscRecorder::GetPath......................................................................................................20 IDiscRecorder::GetPath.........................................................................................................20 IDiscRecorder::GetRecorderProperties..............................................................................20 IDiscRecorder::GetRecorderProperties.................................................................................20 IDiscRecorder::SetRecorderProperties...............................................................................21 IDiscRecorder::SetRecorderProperties.................................................................................21 IDiscRecorder::OpenExclusive...........................................................................................22 IDiscRecorder::OpenExclusive..............................................................................................22 IDiscRecorder::QueryMediaType........................................................................................23 IDiscRecorder::QueryMediaType..........................................................................................23 IDiscRecorder::QueryMediaInfo..........................................................................................23 IDiscRecorder::QueryMediaInfo............................................................................................23 IDiscRecorder::Eject...........................................................................................................24 IDiscRecorder::Eject..............................................................................................................24 IDiscRecorder::Erase..........................................................................................................25 IDiscRecorder::Erase............................................................................................................25 IDiscRecorder::Close..........................................................................................................26 IDiscRecorder::Close.............................................................................................................26 IRedbookDiscMaster.............................................................................................................26 IRedbookDiscMaster::GetTotalAudioTracks.......................................................................27 IRedbookDiscMaster::GetTotalAudioTracks.........................................................................27 IRedbookDiscMaster::GetTotalAudioBlocks.......................................................................27 IRedbookDiscMaster::GetTotalAudioBlocks..........................................................................27 IRedbookDiscMaster::GetUsedAudioBlocks.......................................................................28 IRedbookDiscMaster::GetUsedAudioBlocks.........................................................................28 IRedbookDiscMaster::GetAvailableAudioTrackBlocks........................................................28 IRedbookDiscMaster::GetAvailableAudioTrackBlocks..........................................................28 IRedbookDiscMaster::GetAudioBlockSize..........................................................................29 IRedbookDiscMaster::GetAudioBlockSize............................................................................29 IRedbookDiscMaster::CreateAudioTrack............................................................................29 IRedbookDiscMaster::CreateAudioTrack..............................................................................29 IRedbookDiscMaster::AddAudioTrackBlocks......................................................................30 IRedbookDiscMaster::AddAudioTrackBlocks........................................................................30 IRedbookDiscMaster::CloseAudioTrack.............................................................................30 © 2001 Microsoft Corporation. All rights reserved. Image Mastering API (IMAPI) — 3 IRedbookDiscMaster::CloseAudioTrack................................................................................30 IJolietDiscMaster...................................................................................................................31 IJolietDiscMaster::GetTotalDataBlocks...............................................................................31 IJolietDiscMaster::GetTotalDataBlocks.................................................................................31 IJolietDiscMaster::GetUsedDataBlocks..............................................................................32 IJolietDiscMaster::GetUsedDataBlocks.................................................................................32 IJolietDiscMaster::GetDataBlockSize..................................................................................32 IJolietDiscMaster::GetDataBlockSize....................................................................................32 IJolietDiscMaster::AddData.................................................................................................33 IJolietDiscMaster::AddData...................................................................................................33 IJolietDiscMaster::GetJolietProperties................................................................................34 IJolietDiscMaster::GetJolietProperties...................................................................................34 IJolietDiscMaster::SetJolietProperties.................................................................................35 IJolietDiscMaster::SetJolietProperties...................................................................................35 IDiscMasterProgressEvents..................................................................................................36 IDiscMasterProgressEvents::QueryCancel.........................................................................36 IDiscMasterProgressEvents::QueryCancel...........................................................................36 IDiscMasterProgressEvents::NotifyPnPActivity..................................................................37 IDiscMasterProgressEvents::NotifyPnPActivity.....................................................................37 IDiscMasterProgressEvents::NotifyAddProgress................................................................37 IDiscMasterProgressEvents::NotifyAddProgress..................................................................37 IDiscMasterProgressEvents::NotifyBlockProgress.............................................................37 IDiscMasterProgressEvents::NotifyBlockProgress................................................................37 IDiscMasterProgressEvents::NotifyTrackProgress.............................................................38 IDiscMasterProgressEvents::NotifyTrackProgress................................................................38 IDiscMasterProgressEvents::NotifyPreparingBurn.............................................................38 IDiscMasterProgressEvents::NotifyPreparingBurn................................................................38 IDiscMasterProgressEvents::NotifyClosingDisc..................................................................39 IDiscMasterProgressEvents::NotifyClosingDisc....................................................................39 IDiscMasterProgressEvents::NotifyBurnComplete..............................................................39 IDiscMasterProgressEvents::NotifyBurnComplete................................................................39 IMAPI Result Codes...........................................................................................................40 © 2001 Microsoft Corporation. All rights reserved. Image Mastering API (IMAPI) — 4 About the Image Mastering API The 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 MSDiscMasterObj IDiscMaster 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. © 2001 Microsoft Corporation. All rights reserved. 6) Use the interface for the selected format to build up content. 14) Repeat step 13 until out of space or all the data has been added.Image Mastering API (IMAPI) — 5 Using the Image Mastering API An application using IMAPI communicates with it through IDiscMaster. IDiscRecorder represents a physical device. the application can use the GetxxxAudioBlocks methods to get statistical information like total blocks remaining. 5) Use ProgressAdvise on IDiscMaster to register for progress callbacks. IJolietDiscMaster. 10) Repeat steps 7-9 until out of space or all audio tracks have been written. the IIDs of the interfaces for IJolietDiscMaster and IRedbookDiscMaster. For Data: 13) Use AddData to add the contents of folder to the image. 4) Enumerate the list of supported disc recorders (specific to the active format). smart pointers from an import. The contents of the staged image cannot be incrementally deleted (you can’t remove a track that has been added). so tracks or folder contents may be added to a disc piece by piece. All rights reserved. . 1) Create an instance of the MSDiscMasterObj using normal COM techniques (CoCreateInstance. and IRedbookDiscMaster. At any point. or total blocks used. Content builds incrementally. The sub-items within a passed in folder become placed in the root of the image file. The application should call the Open method on IDiscMaster. in this case. and then choose one of these to be the active recorder. Closing out the session will wipe out whatever may have been stored in the disc stash. 8) Use AddAudioTrackBlocks to add raw audio data to a track. If this succeeds. © 2001 Microsoft Corporation. 3) Retrieve the disc master format enumerator to examine the set of formats that the disc master object supports. Use the GetDataBlocks methods to get statistical information like total blocks remaining or total blocks used. Use the ClearFormatContent method on the IDiscMaster interface to restart staging. The “formats” returned from the enumerator are. For Audio: 7) Use CreateAudioTrack to indicate a new audio track is being started on the disc. 2) Acquire access to IMAPI through IDiscMaster. and so on) and request the IDiscMaster interface. 12) Close the IMAPI session using IDiscMaster. the application has full access to all the interfaces and methods implemented in MSDiscMasterObj. The following flow describes a normal interaction between an application and these interfaces. but it is possible to clear all the contents of a staged image so that staging can start again. Building up this content is called “staging an image”. 9) Use CloseAudioTrack to close out an audio track. and then choose the active format. IDiscRecorder. 11) Use the RecordDisc method of IDiscMaster to record the disc. This disc will have to be present in the active recorder when RecordDisc is called. © 2001 Microsoft Corporation. and raw access to CD-ROM. There may be multiple instances of the MSDiscMasterObj active on a system at the same time. 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). It is IMAPIW2K. A third-party implementation that extends IMAPI might not utilize the stash at all. If this disc is a previous IMAPI Joliet disc and has space for another session. 16) Close the IMAPI session using IDiscMaster. There are a few additional points that should be kept in mind when doing so. an implementer of IDiscRecorder should pay attention to concurrency issues with the physical recorders. Use the following steps to import the type library in Visual C++: 1. If so. Using ClearFormatContent after multi-session mode has been established will cause IMAPI to return to single-session mode. IMAPI goes into multi-session mode automatically. Expand the “All Objects” node and scroll down to the Microsoft IMAPI Disc Master object.SYS that exports the GUIDs used to Init instances of MSDiscRecorderObj. Selecting a recorder while in an active Joliet format will cause IMAPI to read information off of the currently installed disc of the recorder. Language Notes The IMAPI interface can be utilized through its type library within Visual Basic or Visual C++. the same disc must be in the active recorder or an error code of IMAPI_E_WRONGDISC will be returned. which provides device enumeration. but do not expand the node to avoid a COM reference.SYS. Exclusive access is not provided directly the by upper level IMAPI components.Image Mastering API (IMAPI) — 6 For All Discs: 15) Use the RecordDisc method of IDiscMaster to record the disc. and might therefore allow simultaneous access to all of its format masters. SetActiveDiscRecorder determines whether there is an IMAPI multi-session disc in the active drive upon setting. 2. Click on the object’s name. locking. However. Extending the IDiscmaster and IDiscRecorder Interfaces Such implementations should pay attention to restrictions on simultaneous access. Closing out the session will clear the disc stash. CD-R. . There are 21 MB used to close the first session on a disc. If in multi-session mode and a call is made to RecordDisc. IMAPI burn engines must access physical devices through IMAPIW2K. That means that a blank disc will be required for a RecordDisc burn. and CD-R/W style devices. Each additional session requires 11 MB to close. All rights reserved. IMAPI will automatically set itself to multisession mode. Creating Multi-session Discs IMAPI is capable of creating multi-session data discs. As with IDiscMaster. Start the OLE/COM Object Viewer delivered with the SDK and Visual C++. In the right hand pane select the “Implementation” tab and the “Local Server” subtab. A full discourse on the proper use of COM through the #import statement is beyond the scope of this document. Select a new active disc recorder. enumerate disc mastering formats and disc recorders supported by an image mastering object. Although an image mastering object may support several formats through different interfaces. Decrements the reference count. The reader should be very familiar with the contents of #import Visual C++ documentation in the MSDN library. Get the currently active disc recorder. 5. © 2001 Microsoft Corporation. It really will clear up any confusion surrounding parameters. the creation of the .TLH and . Image Mastering API Reference Interfaces IDiscMaster The IDiscMaster interface allows an application to reserve an image mastering API. Set a new active recorder format. Make sure to actually open and review the . Cancel progress notifications from IMAPI.” 4. return values. or exception generation. Utilize the classes or smart pointers defined in the header files generated by the import to instantiate and manipulate IMAPI objects.Image Mastering API (IMAPI) — 7 3. in detail. For this reason a recorder must be chosen with SetActiveDiscRecorder after a specific format is chosen with SetActiveDiscRecorderFormat. Increments the reference count.TLH and . and start a simulated or actual burn of a disc. Reset the “contents” of an unburned image.EXE’s full “Path to Implementation. Retrieve a recorder enumerator. and the creation of specialized smart pointers for the classes in those headers. Description Open an Image Mastering API object. the establishment of a namespace. Retrieve a format enumerator. .TLI files created by the import statement. Get the currently selected recorder format. The MSDiscMasterObj supports IJolietDiscMaster and IRedbookDiscMaster formats.TLI files. All rights reserved. Note the IMAPI. not all formats may be accessible through a specific recorder. Use a ‘#import “<Path to Implementation>”’ line in the header of those modules which will reference the IMAPI objects and their interfaces. It covers. Request progress notifications from IMAPI. Methods in Vtable Order Iunknown Methods QueryInterface AddRef Release IDiscMaster Methods Open EnumDiscMasterFormats GetActiveDiscMasterFormat SetActiveDiscMasterFormat EnumDiscRecorders GetActiveDiscRecorder SetActiveDiscRecorder ClearFormatContent ProgressAdvise ProgressUnadvise Description Returns pointers to supported interfaces. In this particular case the type returned in Next’s array is “IID”. Discontinue use of IMAPI. Return Values S_OK An enumerator of the formats was successfully returned. In other words. as well as the IJolietDiscMaster and IRedbookDiscMaster interfaces. and Clone calls. The function returns a standard COM enumerator as documented in the MSDN library on IEnumXXXX. Parameter ppEnum [out] Address of a pointer to the enumerator. IDiscMaster::Open Opens an upper level IMAPI object for access by a client application. Return Values S_OK Access to the interface has been granted and all methods on this and the format interfaces are enabled. Skip. IdiscMaster::Open may be called even if it is already opened by another app. including the Next. should return nothing but IMAPI_E_NOTOPENED until the open call succeeds. each call to Next will return an array of IIDs. All rights reserved.Image Mastering API (IMAPI) — 8 RecordDisc Close Burn the staged image to active recorder. Note that all of the other methods of this interface. IMAPI_E_ALREADYOPEN The object is already opened. IMAPI_E_NOTOPENED The call failed because IMAPI has not been opened with a call to Open. 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. 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). . Reset. HRESULT EnumDiscMasterFormats( IEnumDiscMasterFormats **ppEnum ). HRESULT Open(). one IID per supported disc master format. © 2001 Microsoft Corporation. Currently. 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. there are only two possible choices. IDiscMaster::GetActiveDiscMasterFormat Retrieves the currently active disc recorder format. as defined in the Imapi. 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. then there will no longer be an active recorder (similar to the state after the first call to IDiscMaster::Open. Changes to the recorder list will be announced with a call to IDiscMasterProgressEvents::NotifyPnPActivity.Image Mastering API (IMAPI) — 9 Remarks The MSDiscMasterObj always returns an enumerator that identifies the IJolietDiscMaster and IRedbookDiscMaster formats by their interface IDs. In addition.h. All rights reserved. NOTE: A successful call to this function will clear the contents of the currently staged image. In this case. 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. This is because not all recorders have to support all formats. HRESULT GetActiveDiscMasterFormat( LPIID lpiid ). it may change the list of supported disc recorders. 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. © 2001 Microsoft Corporation. IID_RedbookDiscMaster and IID_IjolietDiscMaster. Return Values S_OK The IID of the currently active mastering format has been returned successfully. IMAPI_E_NOACTIVEFORMAT An active format has not been selected using SetActiveDiscMasterFormat. Parameter lpiid [out] The IID of the currently active format. the application must select a new active recorder before initiating a burn. IMAPI_E_NOTOPENED The call failed because IMAPI has not been opened with a call to Open. and it will be aware of it while enumerating the supported formats through the returned interface. If the currently selected recorder is not a member of the new set of supported devices. Remarks The MSDiscMasterObj only supports the IIDs for IJolietDiscMaster and IRedbookDiscMaster. . Parameter ppEnum [out] Address of a pointer to the enumerator. Parameter riid [in] The IID of the currently active format. Return Values S_OK The active image format has been changed. Skip. IUnknown **ppUnk ). It is the responsibility of every application to select a format master through the use of EnumDiscMasterFormats and this function. The enumerator includes the Next. HRESULT EnumDiscRecorders( IEnumDiscRecorders **ppEnum ). and the content of the image file has been cleared (the whole image must be re-staged). . © 2001 Microsoft Corporation. IMAPI_E_NOTOPENED The call failed because IMAPI has not been opened with a call to Open. each call to Next will return an array of pointers to an IDiscRecorder. Remarks The MSDiscMasterObj only supports the IIDs and interface pointers for IJolietDiscMaster and IRedbookDiscMaster. In this particular case. Return Values S_OK The enumerator was successfully returned. and Reset calls. Init has already been called). If there is no format set. Each of the recorder interfaces represents a single available recorder already associated with an underlying physical disc recorder (i. If there is no format set. All rights reserved. IDiscMaster always defaults to Joliet format. IDiscMaster always defaults to Joliet format. IMAPI_E_NOACTIVEFORMAT The data format has not been selected. ppUnk [out] Pointer to the COM interface for the new disc format.Image Mastering API (IMAPI) — 10 HRESULT SetActiveDiscRecorderFormat( REFIID riid. IMAPI_E_NOTOPENED The call failed because IMAPI has not been opened with a call to Open. 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. The function returns a standard COM enumerator (see documentation on IEnumXXXX in MSDN). IDiscMaster::EnumDiscRecorders Provides an enumerator for all of the disc recorders supported by the active disc master format.e. Remarks After the initial Open call there is no active disc recorder. IMAPI_E_NOACTIVEFORMAT The data format has not been selected. because each enumerator contains a snapshot of the devices supported at the time of the enumeration. Use SetActiveDiscRecorder to choose an active recorder. Parameter ppRecorder [out] A pointer to the IDiscRecorder interface of the currently selected disc recorder. IMAPI_E_NOACTIVERECORDER A disc recorder has not been selected. IMAPI_E_DEVICE_NOTPRESENT The currently active disc recorder has been invalidated because the device was removed from the system. When a change occurs the application should make another call to this function to retrieve a new enumerator. Note that when a device is removed. Note that the active disc recorder can be invalidated by a removal of the device or a change to the active disc mastering format. and there is no default. An application using this API must specifically select both an active mastering format and an active disc recorder before initiating a burn. In other words. . The active disc recorder is the recorder where a burn will occur when RecordDisc is called. Choose a new active recorder using SetActiveDiscRecorder. IDiscMaster::GetActiveDiscRecorder The GetActiveDiscRecorder method returns an interface pointer to the active disc recorder. The Maximum write speed data is updated when this is called. operations on an IDiscRecorder or a request to record a disc may return IMAPI_E_DEVICE_NOTPRESENT.Image Mastering API (IMAPI) — 11 Remarks The list of available recorders may change because of Plug and Play arrivals or departures. The default setting is the highest returned write speed. HRESULT GetActiveDiscRecorder( IDiscRecorder **ppRecorder ). In this case. or because of a call to SetActiveDiscMasterFormat. IMAPI_E_NOTOPENED The call failed because IMAPI has not been opened with a call to Open. Return Values S_OK The active disc recorder is present and has been returned successfully. a USB CD-R device may be © 2001 Microsoft Corporation. An application is notified of these changes when it receives a call to IDiscMasterProgressEvents::NotifyPnPActivity. there is no default active disc recorder. its pointer and IDiscRecorder interface must remain valid even though the underlying physical device is missing. All rights reserved. For example. If this disc is a previous IMAPI Joliet disc and has space for another session. and before calling the AddData interface. IMAPI_E_NOTOPENED The call failed because IMAPI has not been opened with a call to Open. The Maximum write speed data is updated when this is called. IMAPI_E_NOACTIVEFORMAT The data format has not been selected. In either case.Image Mastering API (IMAPI) — 12 disconnected from the machine while the application is still running (the application is alerted to this condition by a call to IDiscMasterProgressEvents::NotifyPnPActivity). . Remarks SetActiveDiscRecorder must be called after the media to be used has been inserted. The default write speed is set to the highest write speed returned. Return Values S_OK The 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. which means that it becomes an exclusive access interface once opened. IMAPI will automatically set itself to multi-session mode. IDiscMaster::SetActiveDiscRecorder Selects an active disc recorder. Selecting a recorder while in an active Joliet format will cause IMAPI to read information off the currently installed disc of the recorder. The active disc recorder is the recorder where a burn will occur when RecordDisc is called. All rights reserved. a new active disc recorder must be chosen before this call will work again. The SetActiveDiscRecorder does rely on exclusive access to the MSDiscStashObj. This pointer should have been returned by a previous call to EnumDiscRecorders. © 2001 Microsoft Corporation. HRESULT SetActiveDiscRecorder( IDiscRecorder *pRecorder ). Parameter pRecorder [in] Pointer to the interface of a disc recorder object. Subsequent calls to Open through other instances of SetActiveDiscRecorder will fail with IMAPI_E_STASHINUSE. This disc will have to be present in the active recorder when RecordDisc is called. All rights reserved. Remarks Be very careful with this function. The stash file is an internal structure that is used to “stage” a disc before recording it to media.Image Mastering API (IMAPI) — 13 IDiscMaster::ClearFormatContent This function will clear the contents of the current stash file. See the IDiscMasterProgressEvents interface description below for more information on the callbacks that are issued. © 2001 Microsoft Corporation. HRESULT ProgressAdvise( IDiscMasterProgressEvents *pEvents. There is no confirmation and no recovery. Callbacks will occur to this interface. pnCookie [out.retval] A “cookie” which uniquely identifies this callback registration. . UINT_ptr *pnCookie ). Keep the cookie because it will be needed for ProgressUnadvise. That means that a blank disc will be required for a RecordDisc burn. IMAPI_E_NOTOPENED The call failed because IMAPI has not been opened with a call to Open. Return Values S_OK The image file has been cleared and staging can begin again. IMAPI_E_NOTOPENED The call failed because IMAPI has not been opened with a call to Open. If so. Parameter pEvents [in] Pointer to an IDiscMasterProgressEvents interface. Return Values S_OK The progress interface for callbacks has been successfully registered. If an application fills the image file with a lot of data. IDiscMaster::ProgressAdvise The ProgressAdvise function registers an application for progress callbacks. Using ClearFormatContent after multi-session mode had been established will cause IMAPI to return to single-session mode. Multi-session Note: SetActiveDiscRecorder determines if there is an IMAPI multisession disc in the active drive upon setting. and then calls this function that data is gone. IMAPI goes into multi-session mode automatically. HRESULT ClearFormatContent(). Any errors will cause this function to return with little or no corrective action on the part of this method. If this parameter is false. HRESULT ProgressUnadvise( UINT_ptr nCookie ).Image Mastering API (IMAPI) — 14 IDiscMaster::ProgressUnadvise Cancel callbacks against a previously registered interface. then the media in the recorder is actually fully burned. although progress callbacks will be made if registered with ProgressAdvise. HRESULT RecordDisc( boolean bSimulate. The simulation is a good test of a disc recorder at various speeds. media in the active disc recorder is not actually burned. © 2001 Microsoft Corporation. Instead. If so. 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. boolean bEjectTray ). IMAPI_E_NOTOPENED The call failed because IMAPI has not been opened with a call to Open. bEjectTray [in] Eject the CD after the burn or not. Multi-session Note: SetActiveDiscRecorder determines if there is an IMAPI multisession disc in the active drive upon setting. If in multi-session mode and a call is made to RecordDisc. a simulated burn is performed. The call to this function will not return until the burn is complete. . Return Values S_OK Callbacks 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. IMAPI goes into multi-session mode automatically. All rights reserved. Parameter bSimulate [in] If true. IMAPI_E_NOTOPENED The call failed because IMAPI has not been opened with a call to Open. Parameter nCookie [in] The cookie returned by a previous call to ProgressAdvise. because most of the same commands and operations are performed as in a real burn. and so on. Return Values S_OK The simulation or actual burn succeeded. IMAPI_E_FILESYSTEM Access to the active disc recorder through the operating system has prevented IMAPI from reserving the disc recorder for exclusive use. a previous IMAPI disc was detected and a multi-session session was established. there is no usable content and the record operation has been cancelled. IMAPI_E_GENERIC An unexpected and unexplained failure ended the recording. IMAPI_E_DISCINFO An error occurred while attempting to access the media inserted into the active disc recorder. IMAPI_E_NOACTIVERECORDER An active recorder has not been chosen using SetActiveDiscRecorder. IMAPI_E_INITIALIZE_WRITE An error occurred while setting the active disc recorder up for a write. IMAPI_E_INITIALIZE_ENDWRITE An error occurred while setting the active disc recorder up to close the disc. The media status could be checked again once the dialog is dismissed. IMAPI_E_TRACKOPEN A audio track is currently open. All rights reserved. . Try again later. and then it should retry the call to RecordDisc. IMAPI_E_DEVICE_NOTPRESENT The currently active disc recorder has been invalidated because the device was removed from the system. IMAPI_E_INVALIDIMAGE The image file is empty or corrupted. Choose a new active recorder using SetActiveDiscRecorder. RecordDisc has now detected that this disc is no longer in the active recorder. © 2001 Microsoft Corporation. Try again later. or an application could proactively poll (for example. There is no preferred mechanism for performing this task. IMAPI_E_USERABORT The recording was cancelled during a progress callback by a TRUE return from a call to the QueryCancel method of IDiscMasterProgressEvents. IMAPI_E_MEDIUM_NOTPRESENT There is no media in the active disc recorder. Close the currently open track before recording the disc. It is suggested that the media be ejected and a dialog box presented to the user. IMAPI_E_LOSS_OF_STREAMING Content streaming was lost. IMAPI_E_NOACTIVEFORMAT A disc mastering format has not been chosen using SetActiveDiscMasterFormat. In either case. The application should prompt for media from the user. IMAPI_E_DEVICE_NOTACCESSIBLE Another application or IMAPI engine has reserved the active disc recorder. a buffer under-run may have occurred.Image Mastering API (IMAPI) — 15 IMAPI_E_WRONGDISC The call failed because when the active recorder was selected. once per second) to check if good media has been inserted. A disc must be re-staged in order to burn it again. An IMAPI object such as MSDiscMasterObj maintains an active disc recorder. The staged image data is not valid after a call to RecordDisc. HRESULT Close().Image Mastering API (IMAPI) — 16 IMAPI_E_COMPRESSEDSTASH The stash is located on a compressed volume and cannot be read. Remarks Content not committed to media through a call to RecordDisc will be lost. the contents of the stash file are cleared automatically after successful completion of the first call to this function. labeled the active disc recorder. IDiscMaster::Close Closes the IMAPI interface so that other applications can use it. For security. IMAPI_E_ENCRYPTEDSTASH The stash is located on an encrypted volume and cannot be read. but there may be multiple instances of IDiscRecorder all pointing at the same hardware device. If this function returns anything but MEDIA_BLANK. 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. This allows the application to do both a simulated and an actual burn of the media. then the media may need to be erased (for example. CD-RW media in a CD-RW drive). IDiscRecorder The IDiscRecorder interface enables access to a single disc recorder device. See the Erase function below. All rights reserved. © 2001 Microsoft Corporation. IMAPI_E_REMOVABLESTASH The specified stash location is a removable media. It provides no provision for asynchronous or overlapped operation. OpenExclusive is then used to access that device. The IDiscMaster::RecordDisc method expects to work with blank media for Audio (MEDIA_BLANK above). Closing an already closed DiscMaster will return S-OK. . Return Values S_OK The IMAPI interface was successfully closed. Remarks This function does not return before completion of the operation. IMAPI_E_NOTENOUGHDISCKFORSTASH There is not enough free space to create the stash file on the specified volume. An IDiscRecorder object represents a single hardware device. Set properties for the recorder. Returns an OS path to the device. Close a recorder after exclusive access.Image Mastering API (IMAPI) — 17 Note that an application does not call CoCreateInstance for one of these objects. Retrieves the underlying device GUID. Increments the reference count. 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. but instead uses the IDiscMaster::EnumDiscRecorders function to retrieve an enumerator that returns pointers to all the recorders valid for a specific format. Description Initializes the object for an underlying device. The IMAPI client does NOT have to call IdiscMaster::SetActiveDiscRecorder first. Opens a device for exclusive use. Retrieves a name suitable for GUI display. Erases CD-R/W media. Retrieves media properties. IDiscRecorder::GetRecorderGUID The GetRecorderGUID function returns the GUID of the physical disc recorder currently associated with this recorder object. Retrieve IPropertyStorage* for recorder. HRESULT GetRecorderGUID ( byte * pbyUniqueID. Identifies the type of media in the recorder. if possible. ULONG *pulReturnSizeRequired ). Decrements the reference count. Methods in Vtable Order IUnknown Methods QueryInterface AddRef Release IDiscRecorder Methods Init GetRecorderGUID GetRecorderType GetDisplayNames GetBasePnPID GetPath GetRecorderProperties SetRecorderProperties OpenExclusive QueryRecorderStatus QueryMediaType QueryMediaInfo Eject Erase Close Description Returns pointers to supported interfaces. Ejects a recorder’s tray. All rights reserved. Used internally only. Checks if recorder is ready to do a burn. ULONG ulBufferSize. Identifies device as CD-R or CD-RW. . Returns identifier unique to device class. © 2001 Microsoft Corporation. if possible. . and the GUID for the physical recorder associated with it has been returned. IMAPI_E_NOTINITIALIZED This recorder object has not been initialized. ulBufferSize [in] Size of the GUID buffer. but as much of the GUID is returned as possible in the given buffer. or 0 when querying the required buffer size. the user must also pass a 0 for the second parameter. IMAPI_E_NOTINITIALIZED This recorder object has not been initialized. Although the hresult is not zero. IDiscRecorder::GetRecorderType The GetRecorderType method indicates whether the disc recorder is a CD-R or CDR/W type device. it is not an exception. Return Values S_OK The device type was successfully returned. Remarks Note that if a null is ever passed for the first parameter. All rights reserved. Pass in NULL for querying the required buffer size. Return Values S_OK This recorder object has been initialized. HRESULT GetRecorderType( long *fTypeCode ). The name consists of the manufacturer and product identifier of the device. © 2001 Microsoft Corporation. Parameter fTypeCode [out] One of RECORDER_CDR or RECORDER_CDRW. pbyUniqueID [out] Size of the GUID information.Image Mastering API (IMAPI) — 18 Parameter pbyUniqueID [in. IDiscRecorder::GetDisplayNames The GetDisplayNames function returns a BSTR with a formatted name for the recorder that can be displayed. IMAPI_S_BUFFER_TO_SMALL This recorder object is small. This does not indicate the type of media that is currently inserted in the device. out] Pointer to a GUID buffer to be filled in with this recorder’s current GUID information. All rights reserved. Return Values S_OK The display name was successfully returned. BSTR *pbstrRevision ). HRESULT GetBasePnPID( BSTR *pbstrBasePnPID ). The pointer passed may be NULL if the calling application does not need this value. The pointer passed may be NULL if the calling application does not need this value.Image Mastering API (IMAPI) — 19 HRESULT GetDisplayNames( BSTR *pbstrVendorID. not by CD-R or CD-R/W. Return Values S_OK The basic PnP ID string has been returned successfully. IMAPI_E_NOTINITIALIZED This recorder object has not been initialized. This is typically the revision of the recorder firmware. Remarks The display names are typically combined into a string that is displayed in recorder selection list boxes or other GUI components. Parameter pbstrVendorID [out] A displayable name identifying the vendor of the disc recorder. but it isn’t a requirement (it may be a revision for the entire device). The string is basically a concatenation of a recorders manufacturer. pbstrProductID [out] A displayable name identifying the disc recorder’s product name. and revision information (if available). The string can be used by applications that wish to customize behavior according to the specific recorder type. Note that the combination of these three strings does not produce a unique identifier for this specific recorder. It can be used to consistently identify a specific class of device. Combine these strings with the string returned from GetPath (below) to create a unique value. but by make and model. Parameter pbstrBasePnPID [out] The base PnP ID string as described above. product ID. IDiscRecorder::GetBasePnPID The GetBasePnPID function returns a string designed for internal use only. BSTR *pbstrProductID. . © 2001 Microsoft Corporation. pbstrRevision [out]A displayable name that identifies the revision of the disc recorder. The pointer passed may be NULL if the calling application does not need this value. © 2001 Microsoft Corporation. This path should be used by applications in conjunction with the display name to completely identify an available disc recorder. 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. HRESULT GetPath( BSTR *pbstrPath ). IDiscRecorder::GetPath The GetPath function returns a path to the device within the operating system. IMAPI_E_NOTINITIALIZED This recorder object has not been initialized. Return Values S_OK The path to the disc recorder has been successfully returned. Parameter ppPropStg [out] Address of IPropertyStorage* pointer variable that receives the interface pointer to the property set with all current properties defined. .Image Mastering API (IMAPI) — 20 IMAPI_E_NOTINITIALIZED This recorder object has not been initialized. For example. and they have been successfully returned. HRESULT GetRecorderProperties( IPropertyStorage **ppPropStg ). All rights reserved. IDiscRecorder::GetRecorderProperties The GetRecorderProperties function returns a pointer to an IPropertyStorage interface. Return Values S_OK This disc recorder supports properties. as well as ID/NAME associations. or a full path such as ‘\Device\CdRom0’. Parameter pbstrPath [out] The path to the disc recorder. IMAPI_E_DEVICE_NOPROPERTIES This disc recorder does not support any properties. Each combination is a single property. The interface is for a persistent property. and IMAPI uses these properties for various values that are unique to specific recorders. A property set format is convenient for IMAPI because it stores an ID/TYPE/VALUE combination. although the properties are not retained after IMAPI is closed. The caller can then modify these properties and change them by calling SetRecorderProperties. This may be a drive letter such as ‘E:\’. IMAPI_E_NOTINITIALIZED This recorder object has not been initialized. however.” If the write speed is set to FFFFFFFFh. Those properties were ignored and their settings were not changed. Audio Gap Size. © 2001 Microsoft Corporation. Parameter pPropStg [in] Pointer to the IPropertyStorage interface that the disc recorder can use to retrieve new settings on various properties. Sparse settings are supported.Image Mastering API (IMAPI) — 21 Remarks Current properties include: Current Write speed. IMAPI_E_DEVICE_NOPROPERTIES This disc recorder does not support any properties. IDiscRecorder::SetRecorderProperties The SetRecorderProperties function accepts an IPropertyStorage pointer for an object with all the properties that the application wishes to change. The maximum valid value for this is 225. Return Values S_OK The properties for disc recorder have been successfully changed.” Note: Two additional blocks are always written at the end of each track. Maximum Write speed. Enumerates through a recorder’s IPropertyStorage as “AudioGapSize. modify only those settings of interest. Enumerates through a recorder’s IPropertyStorage as “WriteSpeed. 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. The write speed that the current active recorder is set to. GetRecorderProperties may be used to determine the list of properties that are specific to a recorder. to query for a property set using GetRecorderProperties. IMAPI_E_NOTINITIALIZED This recorder object has not been initialized. The number of block between the audio tracks is actually two more than is specified in this property.” The maximum write speed is only updated when IDiscmaster::EnumDiscRecorders or IDiscMaster::SetActiveDiscRecorder is called. HRESULT SetRecorderProperties( IPropertyStorage *pPropStg ). regardless of what the reported maximums are. Note that 75 blocks is one second of “quiet time. but one or more properties were read-only or unrecognized. before the audio gap blocks of the next track. Enumerates through a recorder’s IPropertyStorage as “MaxWriteSpeed. The maximum write speed that the recorder can be set to. . The amount of “quiet time“ between audio tracks when using the Redbook interface to create audio discs. It is recommended. All rights reserved. and then call SetRecorderProperties to change all values at once. then the drive will write at the highest speed it is capable of for the given media. IMAPI_ S_PROPERTIESIGNORED The call succeeded.” This is the amount of blank audio blocks to place between tracks. Since one is read-only and the other is an unknown value. An exclusive lock should be held for as short a time as possible. Choose a new active recorder using IDiscMaster::SetActiveDiscRecorder. This is to ensure that there is no confusion regarding allowed operations and ownership of a recorder during application control or a burn. Requests that come from other operating system components are not queued for later execution. . the media will re-appear to the file system. For example. Any time that an OpenExclusive is called. Both read-only properties and properties that don’t match supported properties will be ignored without generating an error (see IMAPI_ S_PROPERTIESIGNORED). Return Values S_OK The recorder has been opened for exclusive access successfully. IMAPI_E_NOTINITIALIZED This recorder object has not been initialized. HRESULT OpenExclusive().Image Mastering API (IMAPI) — 22 RPC_X_NULL_REF_POINTER This calls fails because a NULL pointer was passed. Instead. The device is exclusively committed to access through either IDiscRecorder or IDiscMaster. This could cause confusion with users who don’t think a burn is in progress. they are simply failed. but not both at the same time. Erase. someone could submit a property set to this interface and attempt to change “MaxWriteSpeed” and the ClearlyNeverHeardOfBefore property. it will appear to the file system that the disc has been removed. Eject. This may cause auto-run issues. both are ignored and the function succeeds. 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. An application should verify property settings with a call to GetRecorderProperties after a call to SetRecorderProperties. Remarks Some properties may be read-only (like “MaxWriteSpeed”). IMAPI_E_DEVICE_NOTPRESENT The currently active disc recorder has been invalidated because the device was removed from the system. When the corresponding IDiscMaster::Close is called. The recorder must be opened with this function before it is possible to use the following methods: QueryMediaType. All rights reserved. This will block file system access to a recorder through apps like Explorer. Close. Try again later. IMAPI_E_DEVICE_NOTACCESSIBLE Another application or IMAPI engine has reserved the active disc recorder. IDiscRecorder::OpenExclusive The Open Exclusive function opens a disc recorder for exclusive access. © 2001 Microsoft Corporation. IMAPI_E_NOTOPENED The call failed because IMAPI has not been opened through a call to IDiscRecorder::OpenExclusive. IMAPI_E_NOTINITIALIZED This recorder object has not been initialized. All rights reserved.Image Mastering API (IMAPI) — 23 IDiscRecorder::QueryMediaType The QueryMediaType function will query the device directly to detect the type of media currently inserted in the recorder. long *fMediaFlags ). © 2001 Microsoft Corporation. IMAPI_E_DEVICE_NOTPRESENT The 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. if any. this parameter contains flags that qualify the above fMediaType. If there is media in the recorder. HRESULT QueryMediaType( long *fMediaType. HRESULT QueryMediaInfo( byte *pbsessions. both fMediaType and fMediaFlags will be 0. 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_OK The media type code has been successfully returned. 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. such as the total number of blocks used on the media. Parameter fMediaType [out] If there is no media present in the drive. . ulfreeblocks [out] How many blocks are available for writing. IMAPI_E_NOTINITIALIZED This recorder object has not been initialized. IDiscRecorder::Eject The Eject function will unlock and eject the tray of the disc recorder. Return Values S_OK The call to eject the tray succeeded. It is unknown whether the tray actually ejected.Image Mastering API (IMAPI) — 24 byte *pblasttrack. if possible. Return Values S_OK The information being returned is valid. Parameter pbsessions [out] The number of sessions on the disc. IMAPI_E_DEVICENOTPRESENT The 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. All rights reserved. which causes an exclusive open. IMAPI_E_NOMEDIAINDRIVE There is no media in the drive to query. ulstartaddress [out] The start address of the last track of the previous session. © 2001 Microsoft Corporation. The total size of the disc can be calculated by summing the next writable address and free blocks. unsigned long *ulfreeblocks ). ulnextwritable [out] The address where writing will begin. pblasttrack [out] The track number of the last track of the previous session. unsigned long *ulnextwritable. unsigned long *ulstartaddress. HRESULT Eject(). IMAPI_E_NOTOPENED The device object is not opened. . Parameter bFullErase [in] Indicates if quick (false) or full (true) erase should be performed on the CD-R/W media. and there is no progress report for this operation. Choose a new active recorder using IDiscMaster::SetActiveDiscRecorder. HRESULT Erase( boolean bFullErase ). . Choose a new active recorder using IDiscMaster’s SetActiveDiscRecorder. Both full and quick erases are supported. All rights reserved. Regardless. and no erase completion notification. IMAPI_E_MEDIUM_NOTPRESENT There is no media in the disc recorder. IMAPI_E_DEVICE_NOTPRESENT The currently active disc recorder has been invalidated because the device was removed from the system.Image Mastering API (IMAPI) — 25 IMAPI_E_NOTINITIALIZED This recorder object has not been initialized. IMAPI_E_MEDIUM_INVALIDTYPE The media type is not CD-RW and it cannot be erased. IMAPI_E_NOTOPENED The call failed because IMAPI has not been opened through a call to IDiscRecorder::OpenExclusive. Note that erasing a disc can be a very lengthy operation (sometimes in excess of an hour). this function will attempt to eject media. IMAPI_E_NOTINITIALIZED This recorder object has not been initialized. Return Values S_OK The CD-RW media in the recorder has been erased successfully. © 2001 Microsoft Corporation. IMAPI_E_DEVICE_NOTPRESENT The currently active disc recorder has been invalidated because the device was removed from the system. IMAPI_E_GENERIC The erase operation on a CD-RW drive with CD-RW media failed for some reason. Remarks Not all recorders support calls to eject their media. IMAPI_E_NOTOPENED The call failed because IMAPI has not been opened through a call to IDiscRecorder::OpenExclusive. IDiscRecorder::Erase The Erase function attempts an erase of CD-R/W media if this is a CD-R/W disc recorder. first session TOC. This restores file system access to the drive. and the pre-gap of the first track. A full erase. Remarks This function does not return before completion of the operation. but the program area will still contain user data. . IRedbookDiscMaster The IRedbookDiscMaster interface enables the staging of an audio CD image. © 2001 Microsoft Corporation. HRESULT Close(). but it takes as much as 40 minutes to complete an erase operation. IMAPI_E_NOTINITIALIZED This recorder object has not been initialized. it provides no provision for asynchronous or overlapped operation. Choose a new active recorder using IDiscMaster::SetActiveDiscRecorder. and it allows the creation of multi-track audio discs in Track-at-Once mode (fixed size audio gaps). IMAPI_E_NOTOPENED The call failed because IMAPI has not been opened through a call to IDiscRecorder::OpenExclusive. Return Values S_OK Exclusive mode was closed out. In other words. It represents one of the formats supported by MSDiscMasterObj. Only one track is staged at a time. Tracks are created in the stash file. erases the entire disc. IMAPI_E_DEVICE_NOTPRESENT The currently active disc recorder has been invalidated because the device was removed from the system. IDiscRecorder::Close The Close function releases exclusive access to a disc recorder. 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. Methods in Vtable Order IUnknown Methods QueryInterface Description Returns pointers to supported interfaces. This is called the open track. This may provide for fewer compatibility problems. on the other hand. All rights reserved. and then they are closed. This will blank a disc quickly (between 1 and 2 minutes depending on recorder speed).Image Mastering API (IMAPI) — 26 IMAPI_E_DEVICE_INVALIDTYPE The disc recorder is not a CD-RW. data is added to them. When to Use Use this interface to stage a Redbook audio image. The quick option erases only the PMA. Indicates a new audio track to be staged. Closes out staging of an audio track. Return Values S_OK The total number of closed and open tracks has been returned successfully. Returns total audio blocks staged in image. Returns total audio blocks available on disc. Returns blocks available for current track. Decrements the reference count. Returns the audio block size in bytes (2352). Adds blocks of audio to track being staged. . IMAPI_E_NOTOPENED The call failed because IMAPI has not been opened through a call to IDiscMaster::Open method. including blocks that may need to be allocated for track gaps. Parameter pnBlocks [out. © 2001 Microsoft Corporation. All rights reserved. The total includes all block types. HRESULT GetTotalAudioBlocks( long *pnBlocks ). IRedbookDiscMaster::GetTotalAudioTracks The GetTotalAudioTracks method returns the total number of tracks that have either been staged or are being staged now. Description Returns total tracks staged in the image. Return Values S_OK The total number of audio blocks has been returned successfully. HRESULT GetTotalAudioTracks( long *pnTracks ).retval] The total number of audio blocks available on a disc. Parameter pnTracks [out. IRedbookDiscMaster::GetTotalAudioBlocks The GetTotalAudioBlocks function returns the total number of blocks available for staging audio tracks.retval] The total number of closed and open tracks.Image Mastering API (IMAPI) — 27 AddRef Release IRedbookDiscMaster Methods GetTotalAudioTracks GetTotalAudioBlocks GetUsedAudioBlocks GetAvailableAudioTrackBlocks GetAudioBlockSize CreateAudioTrack AddAudioTrackBlocks CloseAudioTrack Increments the reference count. © 2001 Microsoft Corporation. Return Values S_OK The total number of used audio blocks has been returned successfully. IMAPI_E_NOTOPENED The call failed because IMAPI has not been opened through a call to IDiscMaster::Open method. IRedbookDiscMaster::GetUsedAudioBlocks This function returns the total number of audio blocks that are in use. HRESULT GetUsedAudioBlocks( long *pnBlocks ). IMAPI_E_NOTOPENED The call failed because IMAPI has not been opened through a call to IDiscMaster::Open method. All rights reserved. . Parameter pnBlocks [out. Return Values S_OK The total number of blocks available to the open track has been returned successfully. Parameter pnBlocks [out. 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 ). Additionally.retval] The number of audio blocks that can be added to the open track before it must be closed.retval] The total number of blocks in-use in closed and open tracks.Image Mastering API (IMAPI) — 28 IMAPI_E_NOTOPENED The call failed because IMAPI has not been opened through a call to IDiscMaster::Open method. 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. if this function is called when there is no open track. This function accounts for gaps associated with open tracks. retval] The total size. Return Values S_OK A new audio track has been successfully opened for staging. IMAPI_E_TRACKOPEN An audio track is already open. Return Values S_OK The size. This does not force the track length to that or any other value. Once opened. Parameter nBlocks [in] The number of audio blocks to be added to this track. in bytes. IRedbookDiscMaster::CreateAudioTrack The CreateAudioTrack function is called to begin staging a new audio track. All rights reserved. and the open track may consume all remaining available audio blocks. IMAPI_E_NOTOPENED The call failed because IMAPI has not been opened through a call to IDiscMaster::Open method. Remarks The Nblocks parameter is advisory only. HRESULT GetAudioBlockSize( long *pnBlockBytes ). for a single audio block. in bytes. use the AddAudioTrackBlocks function to add data to the track.Image Mastering API (IMAPI) — 29 IRedbookDiscMaster::GetAudioBlockSize The GetAudioBlockSize function returns the size of an audio block in bytes. © 2001 Microsoft Corporation. Parameter pnBlockBytes [out. It can only be called when there are no open audio tracks in the image. . Close the currently open track before opening another. Up to 99 tracks can be created. HRESULT CreateAudioTrack( long nBlocks). for a single audio block has been returned successfully. Remarks This function returns the hard-coded value 2352 at the present time. IMAPI_E_NOTOPENED The call failed because IMAPI has not been opened through a call to IDiscMaster::Open method. then the function will return IMAPI_E_DISCFULL and it will keep as much of the audio data as it can. As much of the data as possible was kept. CloseAudioTrack should be called to finish the track. Remarks If a call to this function would overrun the number of available audio blocks. HRESULT AddAudioTrackBlocks( byte *pby. E_INVALIDARG The byte count is wrong. The corollary AddData function in IJolietDiscMaster will not keep any of the data so there are no bad files.size_is(cb)] Pointer to an array of bytes with the track blocks.Image Mastering API (IMAPI) — 30 IRedbookDiscMaster::AddAudioTrackBlocks The AddAudioTrackBlocks function actually adds blocks of audio data to the currently open track. IMAPI_E_DISCFULL Completing this function fills the disc. Return Values S_OK The track data has been added to the open track successfully. IMAPI_E_NOTOPENED The call failed because IMAPI has not been opened through a call to IDiscMaster::Open. . Return Values S_OK The open audio track has been closed successfully. long cb ). IMAPI_E_TRACKNOTOPEN A track has not been opened with CreateAudioTrack. All rights reserved. The track must now be closed. Once all blocks are added. cb [in] Count of bytes in the buffer. © 2001 Microsoft Corporation. This function can be called repeatedly until there is no more space available or the track is fully written. HRESULT CloseAudioTrack(). IRedbookDiscMaster::CloseAudioTrack The CloseAudioTrack closes a currently open audio track. All audio tracks must be closed before the IDiscMaster::RecordDisc method can be called. This count must be a multiple of the audio block size. Parameter pby [in. and no more calls to add data can be made. IMAPI_E_NOTOPENED The call failed because IMAPI has not been opened through a call to IDiscMaster::Open. The data is written to the disc with the Joliet and ISO9660 file systems . Decrements the reference count. IJolietDiscMaster::GetTotalDataBlocks The GetTotalDataBlocks function returns the total number of blocks available for staging a Joliet data disc. It represents one of the formats supported by MSDiscMasterObj. This can be repeated multiple times with the directory and file structures overlapping. Returns total data blocks staged in image. overlapping paths will cause the last file added to show up in the directory.Image Mastering API (IMAPI) — 31 IMAPI_E_TRACKNOTOPEN A track has not been opened with CreateAudioTrack. Increments the reference count. Return Values S_OK The total number of data blocks has been returned successfully. Gets the properties of the Joliet interface. © 2001 Microsoft Corporation. All rights reserved. A temporary folder is built up and then added to the image. The data returned from this function is valid only after a SetActiveDiscRecorder call. . Sets the properties of the Joliet interface. With the overwrite option used. Description Returns total data blocks available on disc.retval] The total number of data blocks available on a disc. while the earlier files with conflicting names are still present on the disc but now not readable by normal means. especially in a multi-session burn. Parameter pnBlocks [out. HRESULT GetTotalDataBlocks( long *pnBlocks ). and it allows the creation of a single Track-at-Once data disc. Adds directories and files to the image file. Returns the data block size in bytes (2048). IJolietDiscMaster The IJolietDiscMaster interface enables the staging of a CD data disc. Methods in Vtable Order IUnknown Methods QueryInterface AddRef Release IJolietDiscMaster Methods GetTotalDataBlocks GetUsedDataBlocks GetDataBlockSize AddData GetJolietProperties SetJolietProperties Description Returns pointers to supported interfaces. The overlapping file structures will appear seamlessly when read back. HRESULT GetUsedDataBlocks( long *pnBlocks ). especially in a multi-session burn. Parameter pnBlocks [out. HRESULT GetDataBlockSize( long *pnBlockBytes ). in bytes. in bytes.retval] The total number of data blocks in use in the staged image. IJolietDiscMaster::GetUsedDataBlocks The GetUsedDataBlocks function returns the total number of data blocks that are in use. IMAPI_E_NOTOPENED The call failed because IMAPI has not been opened through a call to IDiscMaster::Open. IMAPI_E_NOTOPENED The call failed because IMAPI has not been opened through a call to IDiscMaster::Open.retval] The total size. © 2001 Microsoft Corporation. Parameter pnBlockBytes [out.Image Mastering API (IMAPI) — 32 IMAPI_E_NOTOPENED The call failed because IMAPI has not been opened through a call to IDiscMaster::Open. for a single data block has been returned successfully. Return Values S_OK The size. . IJolietDiscMaster::GetDataBlockSize The GetDataBlockSize function returns the size of a data block in bytes. Remarks This function returns the hard-coded value 2048 at the present time. The data returned from this function is valid only after a SetActiveDiscRecorder call. All rights reserved. for a single data block. Return Values S_OK The total number of used data blocks has been returned successfully. Note that when you repeat an AddData. This storage will be enumerated to place all sub-storages and streams in the root file system of the stage image file. long lFileOverwrite ). 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. IMAPI_E_BADJOLIETNAME The storage object passed to AddData contains one or more sub-item names that do not conform to the Joliet file naming conventions. Parameter pStorage [in] Path to the Storage whose sub-items are to be added to the root of the staged image file. All rights reserved. If lFileOverwrite is zero and a file with the same name exists. IMAPI_E_DISCFULL Completing this function would overflow the disc. regardless of whether the burner is the same one used in the previous image creation. IMAPI_E_NOTOPENED The call failed because IMAPI has not been opened through a call to IDiscMaster::Open. AddData will fail with IMAPI_E_FILEEXISTS. Note: While AddData can be called multiple times after calling SetActiveDiscRecorder and calling Burn. None of the contents of the storage have been added to the image. SetActiveDiscRecorder must be called any time a new image is started. the file will be overwritten. Sub-storage become folders and streams become files. The earlier files with conflicting names are still written to disc from the image file. None of the sub-items in the passed in storage object have been added to the staged image. This will cause a failure and the image file will return to the state at which it was before the call to AddData. folders with duplicate files will cause a test of the lFileOverwrite flag and if non-zero. HRESULT AddData( IStorage *pStorage. and immediately before the first AddData call. Return Values S_OK All of the contents of the passed in storage object have been added to the disc successfully. © 2001 Microsoft Corporation. IMAPI_E_FILEEXISTS The call failed because AddData encountered an existing file with the same name as a new file to add and the lFileOverwrite flag was zero.Image Mastering API (IMAPI) — 33 IJolietDiscMaster::AddData The AddData function adds all of the contents of a “root” storage to the staged image file. lFileOverwrite [in] Will overwrite existing files with the same name if non-zero. . Each combination is a single property. The volume name of the disc after recording. All rights reserved. then the function will return IMAPI_E_DISCFULL and it will ignore all of the data that was to be added. others are undefined. Return Values S_OK This interface supports properties. © 2001 Microsoft Corporation. “PlaceBootImageOnDisc” is a Boolean that reports if a boot image is to be placed on the disc. Indicates the OS the boot image is for. Returned as a byte value in “BootImagePlatform”: 0 = x86. Returns a BString in “BootImageManufacturerIDString” (maximum of 24 bytes) that contains Identification information of the creator of the boot image. Getting the properties returns an interface to a property set that has all of the available properties and their current values. the Joliet interface would support a “VolumeName” property. For example. 2 = Mac. IMAPI_E_NOTOPENED The call failed because IMAPI has not been opened through a call to IDiscMaster::Open.Image Mastering API (IMAPI) — 34 Remarks If a call to this function would overrun the number of available data blocks. although the properties are not retained after IMAPI is closed. as well as ID/NAME associations. IMAPI_E_NOACTIVEFORMAT The Joliet format is not active. The caller can then modify these properties and change them by calling SetJolietProperties. The interface is for a persistent property. Boot Image ID. Boot Image Placement. Boot Image Platform. HRESULT GetJolietProperties( IPropertyStorage **ppPropStg ). IMAPI_E_ WRONGFORMAT The Joliet format is not the active format Remarks Current properties include: Volume Name. Parameter ppPropStg [out] Address of IPropertyStorage* pointer variable that receives the interface pointer to the Joliet property set with all current properties defined. IMAPI_E_DEVICE_NOPROPERTIES This interface does not support any properties. 1 = PowerPC. Enumerates through Joliet’s IPropertyStorage as “VolumeName. This ensures that the final Joliet file system will not be corrupted. . IJolietDiscMaster::GetJolietProperties The GetJolietProperties function returns a pointer to an IPropertyStorage interface.” Default is the current date. and IMAPI uses these properties for various values that are unique to the Joliet interface. and they have been successfully returned. A property set is convenient for IMAPI because it stores an ID/TYPE/VALUE combination. IMAPI will create a bootable disc. Since one is read-only and the other is an © 2001 Microsoft Corporation. Both read-only properties and properties that don’t match supported properties will be ignored without generating an error (see IMAPI__S_PROPERTIESIGNORED). The “BootImage” parameter returns an IStream object where the IMAPI client stores the boot image they want burned on the CD. 2 = 1. 1 = 1.88-MB diskette image. 4 = hard disk emulation. Note: By setting these four boot image parameters. IMAPI_E_NOTOPENED The call failed because IMAPI has not been opened through a call to IDiscMaster::Open. but one or more properties were read-only or unrecognized. IJolietDiscMaster::SetJolietProperties The SetJolietProperties function accepts an IPropertyStorage pointer for an object with all the Joliet properties that the application wishes to change. the user should refer to the “El Torito Bootable CD-ROM Format Specification” by Phoenix Technologies. beyond providing the boot image is necessary. GetJolietProperties may be used to determine the list of properties that are specific to a Joliet interface. Remarks Some properties may be read-only. No further work.Image Mastering API (IMAPI) — 35 Emulation type. a property change request could be submitted to attempt to change a read only property and the ClearlyNeverHeardOfBefore property. IMAPI_E_NOACTIVEFORMAT The Joliet format is not active. IMAPI_S_PROPERTIESIGNORED The call succeeded. The “BootImageEmulationType” is a byte value that indicates the emulation type of the boot image: 0 = no emulation (raw CD blocks). IMAPI_E_DEVICE_NOPROPERTIES This Joliet interface does not support any properties. . modify only those settings of interest. For more information on each of these. Boot Image Location. One should query for a property set using GetJolietProperties. For example. and then call SetJolietProperties to change all values at once.44-inch diskette image.2-MB diskette image. 3 = 2. Parameter pPropStg [in] Pointer to the IPropertyStorage interface that the Joliet interface can use to retrieve new settings on various properties. Return Values S_OK The properties for the Joliet interface have been successfully changed. HRESULT SetJolietProperties( IPropertyStorage *pPropStg ). All rights reserved. Those properties were ignored and their settings were not changed. IMAPI_E_ WRONGFORMAT The Joliet format is not the active format. Increments the reference count. IDiscMasterProgressEvents::QueryCancel The QueryCancel function is called by IMAPI to check whether an AddData. Reports progress while closing a disc. E_NOTIMPL This function has not been implemented. false to allow it to continue. both are ignored and the function succeeds. Methods in Vtable Order IUnknown Methods QueryInterface AddRef Release IdiscMasterProgressEvents QueryCancel NotifyPnPActivity NotifyAddProgress NotifyBlockProgress NotifyTrackProgress NotifyPreparingBurn NotifyClosingDisc NotifyBurnComplete NotifyEraseComplete Description Returns pointers to supported interfaces. Reports progress of audio/data burn. Decrements the reference count. Return Values S_OK The cancel indication (pbCancel) has been set successfully. All but one of the methods in this interface are related to progress during staging or burns. © 2001 Microsoft Corporation. Reports that the burn is fully complete. Reports progress during burn setup. it must still implement the callback function and then return E_NOTIMPL on the call. Parameter pbCancel [out. HRESULT QueryCancel( boolean *pbCancel ). AddAudioTrackBlocks. Reports progress of an audio burn. IDiscMasterProgressEvents The IDiscMasterProgressEvents interface provides a single interface for all the callbacks that can be made from IMAPI back to an application.Image Mastering API (IMAPI) — 36 unknown value. An application implements this interface on one of its objects and then registers that interface using IDiscMaster::ProgressAdvise. Reports possible changes to recorder list. Description Checks whether a burn is to be cancelled. or RecordDisc should be cancelled. If an application is not interested in a particular callback. An application should verify property settings with a call to GetJolietProperties after a call to SetJolietProperties.retval] Set to true to cancel a burn. . Reports progress of audio/data staging. Reports that an erase is fully complete. All rights reserved. IDiscMasterProgressEvents::NotifyBlockProgress The NotifyBlockProgress function is called by IMAPI to notify an application of its progress in burning a disc on the active recorder. © 2001 Microsoft Corporation. Parameter nCompletedSteps [in] The number of arbitrary “steps” which have been completed in adding audio or data to a staged image.Image Mastering API (IMAPI) — 37 IDiscMasterProgressEvents::NotifyPnPActivity The NotifyPnPActivity function is called by IMAPI whenever it detects a change to the list of valid disc recorders. An application should respond by getting a new list of valid recorders. 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. If a data disc is being burned then the block counts reflect the progress on the entire disc. E_NOTIMPL This function has not been implemented. HRESULT NotifyPnPActivity(). An application can rely on a block progress calls for “0 out of nTotalSteps” and “nTotalSteps out of nTotalSteps”. All rights reserved. HRESULT NotifyAddProgress( long nCompletedSteps. Return Values S_OK The notification has been acknowledged. For example. 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. long nTotalSteps ). Return Values S_OK The notification has been acknowledged. E_NOTIMPL This function has not been implemented. If an audio disc is being burned then the block counts reflect the progress in burning a single track. . then a new recorder should be chosen. if a USB CD-R driver is removed from the system this function will be called. If the current active recorder has been invalidated. nTotalTracks [in] The total number of tracks that must be burned. Parameter nCurrentTrack [in] The number of tracks that have been completely burned. IDiscMasterProgressEvents::NotifyPreparingBurn The NotifyPreparingBurn function is called by IMAPI to notify the application that it is preparing to burn a disc. The notification for 0 out of nTotalTracks indicates the start of track 1. Parameter nCompleted [in] The number of blocks that have been burned onto a disc/track so far. HRESULT NotifyBlockProgress( long nCompleted. long nTotal ). E_NOTIMPL This function has not been implemented. nTotal [in] The total number of blocks that need to be burned to finish a disc/track. The notification for track N out of nTotalTracks indicates that track N is complete and track N+1 is beginning. HRESULT NotifyPreparingBurn( long nEstimatedSeconds ). HRESULT NotifyTrackProgress( long nCurrentTrack. The call notifies an application whenever a new track is started or finished. Return Values S_OK The notification has been acknowledged. long nTotalTracks ). Return Values S_OK The notification has been acknowledged. No further notifications will occur until the burn starts.Image Mastering API (IMAPI) — 38 An application can rely on a block progress calls for “0 out of nTotal” and “nTotal out of nTotal”. Finally. The estimated amount of time before the start of burn is passed. All rights reserved. © 2001 Microsoft Corporation. . IDiscMasterProgressEvents::NotifyTrackProgress The NotifyTrackProgress function is called by IMAPI during the burn of an audio disc. the notification for nTotalTracks out of nTotalTracks indicates the last track has been written. E_NOTIMPL This function has not been implemented. E_NOTIMPL This function has not been implemented. IDiscMasterProgressEvents::NotifyBurnComplete The NotifyBurnComplete function is called by IMAPI to notify an application that a call to IDiscMaster::RecordDisc is finished. Return Values S_OK The notification has been acknowledged. E_NOTIMPL This function has not been implemented. E_NOTIMPL This function has not been implemented. Parameter nEstimatedSeconds [in] The number of seconds from notification that IMAPI estimates disc closing will take. Return Values S_OK The notification has been acknowledged. All rights reserved. Parameter status [in] The HRESULT code which will be returned from IDiscMaster::RecordDisc. No further notifications will occur until the burn ends. HRESULT NotifyBurnComplete( HRESULT status ).Image Mastering API (IMAPI) — 39 Parameter nEstimatedSeconds [in] The number of seconds from notification that IMAPI estimates burn preparation will take. HRESULT NotifyClosingDisc( long nEstimatedSeconds ). . IDiscMasterProgressEvents::NotifyClosingDisc The NotifyClosingDisc function is called by IMAPI to notify the application that it is has begun closing the disc (finishing the burn). © 2001 Microsoft Corporation. Return Values S_OK The notification has been acknowledged. The estimated amount of time before the end of burn is passed. Change the format and clear the image file contents if you wan to use a different format. All rights reserved. Device can’t be used / already in use. The device is not present or has been removed. An active disc recorder has not been selected with IDiscMaster::SetActiveDiscRecorder. The recorder does not support an operation. IMAPI_E_NOTOPENED IMAPI_E_NOTINITIALIZED IMAPI_E_USERABORT IMAPI_E_GENERIC IMAPI_E_MEDIUM_NOTPRESENT IMAPI_E_MEDIUM_INVALIDTYPE IMAPI_E_DEVICE_NOPROPERTIES IMAPI_E_DEVICE_NOTACCESSIBLE IMAPI_E_DEVICE_NOTPRESENT IMAPI_E_DEVICE_INVALIDTYPE IMAPI_E_INITIALIZE_WRITE IMAPI_E_INITIALIZE_ENDWRITE IMAPI_E_FILESYSTEM IMAPI_E_FILEACCESS IMAPI_E_DISCINFO IMAPI_E_TRACKNOTOPEN IMAPI_E_TRACKOPEN IMAPI_E_DISCFULL IMAPI_E_BADJOLIETNAME IMAPI_E_INVALIDIMAGE The disc can’t hold any more data. An Open call hasn’t been made on IDiscMaster. Unable to initialize drive interface for writing Unable to initialize drive interface for closing Error enabling/disabling file system access or autoinsertion detection Error writing image file Error while trying to read disc data from device An audio track is not open for writing. . A active format master has not been selected using the IDiscMaster::SetActiveDiscMasterFormat. An open audio track is already being staged. It has been corrupted or cleared and has no usable content. A recorder object has not been initialized. App tried to add a badly named element to a disc. The staged image is not suitable for a burn. The Imapi multi-session disc has been removed from the active recorder. Result Code S_OK S_BUFFER_TO_SMALL IMAPI_S_PROPERTIESIGNORED Description No error – Success An unknown property was passed in a property set and it was ignored. The file to add is already in the image file and the IMAPI_E_NOACTIVEFORMAT IMAPI_E_NOACTIVERECORDER IMAPI_E_WRONGFORMAT IMAPI_E_ALREADYOPEN IMAPI_E_WRONGDISC IMAPI_E_FILEEXISTS © 2001 Microsoft Corporation.Image Mastering API (IMAPI) — 40 IMAPI Result Codes The following result codes are returned from methods of the IMAPI interfaces. A call IDiscMaster::Open call has already been made by your application against this object. A call to IJolietDiscMaster has been made when IRedbookDiscMaster is the active format. or vice versa. The user cancelled the operation Generic error There is no disc in the device The media is not a type that can be used. The recorder does not support any properties. There is no media in the drive to query. All rights reserved. . IMAPI cannot access the device. Try again later. There is not enough free space to create the stash file on the specified volume. Another application is already using this device. The stash is located on an encrypted volume and cannot be read. Another application is already using the IMAPI stash file required to stage a disc image. IMAPI_E_NOMEDIAINDRIVE © 2001 Microsoft Corporation.Image Mastering API (IMAPI) — 41 IMAPI_E_STASHINUSE IMAPI_E_DEVICE_STILL_IN_USE IMAPI_E_LOSS_OF_STREAMING IMAPI_E_COMPRESSEDSTASH IMAPI_E_ENCRYPTEDSTASH IMAPI_E_NOTENOUGHDISKFORSTASH IMAPI_E_REMOVABLESTASH overwrite flag was not set. The stash is located on a compressed volume and cannot be read. Content streaming was lost. a buffer under-run may have occurred. Selected stash location is on a removable media.