Image Masterin api (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_OK

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

IMAPI_E_ALREADYOPEN

The 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_OK

An enumerator of the formats was successfully returned.

IMAPI_E_NOTOPENED

The 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_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.

IMAPI_E_NOTOPENED

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

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_OK

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

IMAPI_E_NOTOPENED

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

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_OK

The enumerator was successfully returned.

IMAPI_E_NOTOPENED

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

IMAPI_E_NOACTIVEFORMAT

The 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.