Image Masterin api (imapi)

IDiscMaster::GetActiveDiscRecorder

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

HRESULT GetActiveDiscRecorder( IDiscRecorder **ppRecorder );

Parameter

ppRecorder

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

Return Values

S_OK

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

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.

IMAPI_E_NOACTIVERECORDER

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

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

Remarks

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

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

IDiscMaster::SetActiveDiscRecorder

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

HRESULT SetActiveDiscRecorder( IDiscRecorder *pRecorder );

Parameter

pRecorder

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

Return Values

S_OK

The active disc recorder has been successfully changed.

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.

IMAPI_E_DEVICE_NOT_PRESENT

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

Remarks

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

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

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

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

IDiscMaster::ClearFormatContent

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

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

HRESULT ClearFormatContent();

Return Values

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

Remarks

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

IDiscMaster::ProgressAdvise

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

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

Parameter

pEvents

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

pnCookie

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

Return Values

S_OK

The progress interface for callbacks has been successfully registered.

IMAPI_E_NOTOPENED

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

IDiscMaster::ProgressUnadvise

Cancel callbacks against a previously registered interface.

HRESULT ProgressUnadvise( UINT_ptr nCookie );

Parameter

nCookie

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

Return Values

S_OK

Callbacks to the previously registered interface have been cancelled.

IMAPI_E_NOTOPENED

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

IDiscMaster::RecordDisc

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

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

HRESULT RecordDisc( boolean bSimulate, boolean bEjectTray );

Parameter

bSimulate

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

bEjectTray

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

Return Values

S_OK

The simulation or actual burn succeeded.

IMAPI_E_NOTOPENED

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

IMAPI_E_WRONGDISC

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

IMAPI_E_NOACTIVEFORMAT

A disc mastering format has not been chosen using SetActiveDiscMasterFormat.

IMAPI_E_NOACTIVERECORDER

An active recorder has not been chosen using SetActiveDiscRecorder.

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_GENERIC

An unexpected and unexplained failure ended the recording.

IMAPI_E_MEDIUM_NOTPRESENT

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

IMAPI_E_DEVICE_NOTACCESSIBLE

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

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

IMAPI_E_FILESYSTEM

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

IMAPI_E_DISCINFO

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

IMAPI_E_TRACKOPEN

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

IMAPI_E_INVALIDIMAGE

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

IMAPI_E_LOSS_OF_STREAMING

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

IMAPI_E_COMPRESSEDSTASH

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

IMAPI_E_ENCRYPTEDSTASH

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

IMAPI_E_NOTENOUGHDISCKFORSTASH

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

IMAPI_E_REMOVABLESTASH

The specified stash location is a removable media.

Remarks

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

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

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

IDiscMaster::Close

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

HRESULT Close();

Return Values

S_OK

The IMAPI interface was successfully closed.

Remarks

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

Closing an already closed DiscMaster will return S-OK.

IDiscRecorder

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

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

When to Use

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

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

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IDiscRecorder Methods	Description
Init	Initializes the object for an underlying device. Used internally only.
GetRecorderGUID	Retrieves the underlying device GUID.
GetRecorderType	Identifies device as CD-R or CD-RW.
GetDisplayNames	Retrieves a name suitable for GUI display.
GetBasePnPID	Returns identifier unique to device class.
GetPath	Returns an OS path to the device.
GetRecorderProperties	Retrieve IPropertyStorage* for recorder.
SetRecorderProperties	Set properties for the recorder.
OpenExclusive	Opens a device for exclusive use.
QueryRecorderStatus	Checks if recorder is ready to do a burn.
QueryMediaType	Identifies the type of media in the recorder.
QueryMediaInfo	Retrieves media properties.
Eject	Ejects a recorder’s tray, if possible.
Erase	Erases CD-R/W media, if possible.
Close	Close a recorder after exclusive access.

Remarks

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

IDiscRecorder::GetRecorderGUID

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

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

Parameter

pbyUniqueID

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

ulBufferSize

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

pbyUniqueID

[out] Size of the GUID information.

Return Values

S_OK

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

IMAPI_E_NOTINITIALIZED

This recorder object has not been initialized.

IMAPI_S_BUFFER_TO_SMALL

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

Remarks

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

IDiscRecorder::GetRecorderType

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

HRESULT GetRecorderType( long *fTypeCode );

Parameter

fTypeCode

[out] One of RECORDER_CDR or RECORDER_CDRW.

Return Values

S_OK

The device type was successfully returned.

IMAPI_E_NOTINITIALIZED

This recorder object has not been initialized.

IDiscRecorder::GetDisplayNames

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

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

Parameter

pbstrVendorID

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

pbstrProductID

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

pbstrRevision

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

Return Values

S_OK

The display name was successfully returned.

IMAPI_E_NOTINITIALIZED

This recorder object has not been initialized.

Remarks

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

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

IDiscRecorder::GetBasePnPID

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

HRESULT GetBasePnPID( BSTR *pbstrBasePnPID );

Parameter

pbstrBasePnPID

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

Return Values

S_OK

The basic PnP ID string has been returned successfully.

IMAPI_E_NOTINITIALIZED

This recorder object has not been initialized.

IDiscRecorder::GetPath

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

HRESULT GetPath( BSTR *pbstrPath );

Parameter

pbstrPath

[out] The path to the disc recorder.

Return Values

S_OK

The path to the disc recorder has been successfully returned.

IMAPI_E_NOTINITIALIZED

This recorder object has not been initialized.

IDiscRecorder::GetRecorderProperties

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

HRESULT GetRecorderProperties( IPropertyStorage **ppPropStg );

Parameter

ppPropStg

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

Return Values

S_OK

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

IMAPI_E_DEVICE_NOPROPERTIES

This disc recorder does not support any properties.

IMAPI_E_NOTINITIALIZED

This recorder object has not been initialized.

Remarks

Current properties include:

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

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

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

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

IDiscRecorder::SetRecorderProperties

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

HRESULT SetRecorderProperties( IPropertyStorage *pPropStg );

Parameter

pPropStg

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

Return Values

S_OK

The properties for disc recorder have been successfully changed.

IMAPI_ S_PROPERTIESIGNORED

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

IMAPI_E_DEVICE_NOPROPERTIES

This disc recorder does not support any properties.

IMAPI_E_NOTINITIALIZED

This recorder object has not been initialized.

RPC_X_NULL_REF_POINTER

This calls fails because a NULL pointer was passed.

Remarks

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

IDiscRecorder::OpenExclusive

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

HRESULT OpenExclusive();

Return Values

S_OK

The recorder has been opened for exclusive access successfully.

IMAPI_E_NOTINITIALIZED

This recorder object has not been initialized.

IMAPI_E_DEVICE_NOTACCESSIBLE

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

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::SetActiveDiscRecorder.

Remarks

It is important that the recorder be closed before you attempt a call to IDiscMaster::RecordDisc or it will fail with IMAPI_E_DEVICE_NOTACCESSIBLE. The device is exclusively committed to access through either IDiscRecorder or IDiscMaster, but not both at the same time. This is to ensure that there is no confusion regarding allowed operations and ownership of a recorder during application control or a burn.

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

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

IDiscRecorder::QueryMediaType

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

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

Parameter

fMediaType

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

MEDIA_CDDA_CDROM

MEDIA_CD_ROM_XA

MEDIA_CD_I

MEDIA_CD_EXTRA

MEDIA_CD_OTHER

MEDIA_SPECIAL

fMediaFlags

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

MEDIA_BLANK

MEDIA_RW

MEDIA_WRITABLE

Return Values

S_OK

The media type code has been successfully returned.

IMAPI_E_NOTINITIALIZED

This recorder object has not been initialized.

IMAPI_E_NOTOPENED

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

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, such as the total number of blocks used on the media.

HRESULT QueryMediaInfo(
byte *pbsessions,
byte *pblasttrack,
unsigned long *ulstartaddress,
unsigned long *ulnextwritable,
unsigned long *ulfreeblocks
);

Parameter

pbsessions

[out] The number of sessions on the disc.

pblasttrack

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

ulstartaddress

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

ulnextwritable

[out] The address where writing will begin.

ulfreeblocks

[out] How many blocks are available for writing.

Return Values

S_OK

The information being returned is valid.

IMAPI_E_NOMEDIAINDRIVE

There is no media in the drive to query.

IMAPI_E_NOTOPENED

The device object is not opened.

IMAPI_E_DEVICENOTPRESENT

The device is not present.

IMAPI_E_NOTINITIALIZED

This recorder object has not been initialized.

Remarks

Using this function allows the calculation of parameters such as the amount of free space left on the disc without using a setting on the active disc recorder, which causes an exclusive open. The total size of the disc can be calculated by summing the next writable address and free blocks.

IDiscRecorder::Eject

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

HRESULT Eject();

Return Values

S_OK

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

IMAPI_E_NOTINITIALIZED

This recorder object has not been initialized.

IMAPI_E_NOTOPENED

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

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.

Remarks

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

IDiscRecorder::Erase

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

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

HRESULT Erase( boolean bFullErase );

Parameter

bFullErase

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

Return Values

S_OK

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

IMAPI_E_NOTINITIALIZED

This recorder object has not been initialized.

IMAPI_E_NOTOPENED

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

IMAPI_E_GENERIC

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

IMAPI_E_MEDIUM_NOTPRESENT

There is no media in the disc recorder.

IMAPI_E_MEDIUM_INVALIDTYPE

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

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::SetActiveDiscRecorder.

IMAPI_E_DEVICE_INVALIDTYPE

The disc recorder is not a CD-RW.

Remarks

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

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

IDiscRecorder::Close

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

HRESULT Close();

Return Values

S_OK

Exclusive mode was closed out.

IMAPI_E_NOTINITIALIZED

This recorder object has not been initialized.

IMAPI_E_NOTOPENED

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

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::SetActiveDiscRecorder.

IRedbookDiscMaster

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

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

When to Use

Use this interface to stage a Redbook audio image.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IRedbookDiscMaster Methods	Description
GetTotalAudioTracks	Returns total tracks staged in the image.
GetTotalAudioBlocks	Returns total audio blocks available on disc.
GetUsedAudioBlocks	Returns total audio blocks staged in image.
GetAvailableAudioTrackBlocks	Returns blocks available for current track.
GetAudioBlockSize	Returns the audio block size in bytes (2352).
CreateAudioTrack	Indicates a new audio track to be staged.
AddAudioTrackBlocks	Adds blocks of audio to track being staged.
CloseAudioTrack	Closes out staging of an audio track.

IRedbookDiscMaster::GetTotalAudioTracks

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

HRESULT GetTotalAudioTracks( long *pnTracks );

Parameter

pnTracks

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

Return Values

S_OK

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

IMAPI_E_NOTOPENED

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

IRedbookDiscMaster::GetTotalAudioBlocks

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

HRESULT GetTotalAudioBlocks( long *pnBlocks );

Parameter

pnBlocks

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

Return Values

S_OK

The total number of 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 );

Parameter

pnBlocks

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

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::GetAvailableAudioTrackBlocks

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

HRESULT GetAvailableAudioTrackBlocks( long *pnBlocks );

Parameter

pnBlocks

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

Return Values

S_OK

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

IMAPI_E_NOTOPENED

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

IRedbookDiscMaster::GetAudioBlockSize

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

HRESULT GetAudioBlockSize( long *pnBlockBytes );

Parameter

pnBlockBytes

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

Return Values

S_OK

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

IMAPI_E_NOTOPENED

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

Remarks

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

IRedbookDiscMaster::CreateAudioTrack

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

HRESULT CreateAudioTrack( long nBlocks);

Parameter

nBlocks

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

Return Values

S_OK

A new audio track has been successfully opened for staging.

IMAPI_E_NOTOPENED

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

IMAPI_E_TRACKOPEN

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

Remarks

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

IRedbookDiscMaster::AddAudioTrackBlocks

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

HRESULT AddAudioTrackBlocks( byte *pby, long cb );

Parameter

pby

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

cb

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

Return Values

S_OK

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

E_INVALIDARG

The byte count is wrong.

IMAPI_E_NOTOPENED

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

IMAPI_E_TRACKNOTOPEN

A track has not been opened with CreateAudioTrack.

IMAPI_E_DISCFULL

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

Remarks

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

IRedbookDiscMaster::CloseAudioTrack

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

HRESULT CloseAudioTrack();

Return Values

S_OK

The open audio track has been closed successfully.

IMAPI_E_NOTOPENED

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

IMAPI_E_TRACKNOTOPEN

A track has not been opened with CreateAudioTrack.

IJolietDiscMaster

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

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

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IJolietDiscMaster Methods	Description
GetTotalDataBlocks	Returns total data blocks available on disc.
GetUsedDataBlocks	Returns total data blocks staged in image.
GetDataBlockSize	Returns the data block size in bytes (2048).
AddData	Adds directories and files to the image file.
GetJolietProperties	Gets the properties of the Joliet interface.
SetJolietProperties	Sets the properties of the Joliet interface.

IJolietDiscMaster::GetTotalDataBlocks

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

HRESULT GetTotalDataBlocks( long *pnBlocks );

Parameter

pnBlocks

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

Return Values

S_OK

The total number of data blocks has been returned successfully.

IMAPI_E_NOTOPENED

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

IJolietDiscMaster::GetUsedDataBlocks

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

HRESULT GetUsedDataBlocks( long *pnBlocks );

Parameter

pnBlocks

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

Return Values

S_OK

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

IMAPI_E_NOTOPENED

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

IJolietDiscMaster::GetDataBlockSize

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

HRESULT GetDataBlockSize( long *pnBlockBytes );

Parameter

pnBlockBytes

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

Return Values

S_OK

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

IMAPI_E_NOTOPENED

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

Remarks

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

IJolietDiscMaster::AddData

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

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

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

HRESULT AddData(
IStorage *pStorage,
long lFileOverwrite
);

Parameter

pStorage

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

lFileOverwrite

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

Return Values

S_OK

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

IMAPI_E_NOTOPENED

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

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. This will cause a failure and the image file will return to the state at which it was before the call to AddData.

IMAPI_E_DISCFULL

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

IMAPI_E_BADJOLIETNAME

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

Remarks

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

IJolietDiscMaster::GetJolietProperties

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

HRESULT GetJolietProperties( IPropertyStorage **ppPropStg );

Parameter

ppPropStg

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

Return Values

S_OK

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

IMAPI_E_DEVICE_NOPROPERTIES

This interface does not support any properties.

IMAPI_E_NOTOPENED

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

IMAPI_E_NOACTIVEFORMAT

The Joliet format is not active.

IMAPI_E_ WRONGFORMAT

The Joliet format is not the active format

Remarks

Current properties include:

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

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

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

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

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

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

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

IJolietDiscMaster::SetJolietProperties

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

HRESULT SetJolietProperties( IPropertyStorage *pPropStg );

Parameter

pPropStg

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

Return Values

S_OK

The properties for the Joliet interface have been successfully changed.

IMAPI_S_PROPERTIESIGNORED

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

IMAPI_E_DEVICE_NOPROPERTIES

This Joliet interface does not support any properties.

IMAPI_E_NOTOPENED

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

IMAPI_E_NOACTIVEFORMAT

The Joliet format is not active.

IMAPI_E_ WRONGFORMAT

The Joliet format is not the active format.

Remarks

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

IDiscMasterProgressEvents

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

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IdiscMasterProgressEvents	Description
QueryCancel	Checks whether a burn is to be cancelled.
NotifyPnPActivity	Reports possible changes to recorder list.
NotifyAddProgress	Reports progress of audio/data staging.
NotifyBlockProgress	Reports progress of audio/data burn.
NotifyTrackProgress	Reports progress of an audio burn.
NotifyPreparingBurn	Reports progress during burn setup.
NotifyClosingDisc	Reports progress while closing a disc.
NotifyBurnComplete	Reports that the burn is fully complete.
NotifyEraseComplete	Reports that an erase is fully complete.

IDiscMasterProgressEvents::QueryCancel

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

HRESULT QueryCancel( boolean *pbCancel );

Parameter

pbCancel

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

Return Values

S_OK

The cancel indication (pbCancel) has been set successfully.

E_NOTIMPL

This function has not been implemented.

IDiscMasterProgressEvents::NotifyPnPActivity

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

HRESULT NotifyPnPActivity();

Return Values

S_OK

The notification has been acknowledged.

E_NOTIMPL

This function has not been implemented.

IDiscMasterProgressEvents::NotifyAddProgress

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

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

HRESULT NotifyAddProgress( long nCompletedSteps, long nTotalSteps );

Parameter

nCompletedSteps

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

nTotalSteps

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

Return Values

S_OK

The notification has been acknowledged.

E_NOTIMPL

This function has not been implemented.

IDiscMasterProgressEvents::NotifyBlockProgress

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

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

HRESULT NotifyBlockProgress( long nCompleted, long nTotal );

Parameter

nCompleted

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

nTotal

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

Return Values

S_OK

The notification has been acknowledged.

E_NOTIMPL

This function has not been implemented.

IDiscMasterProgressEvents::NotifyTrackProgress

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

HRESULT NotifyTrackProgress( long nCurrentTrack, long nTotalTracks );

Parameter

nCurrentTrack

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

nTotalTracks

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

Return Values

S_OK

The notification has been acknowledged.

E_NOTIMPL

This function has not been implemented.

IDiscMasterProgressEvents::NotifyPreparingBurn

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

HRESULT NotifyPreparingBurn( long nEstimatedSeconds );

Parameter

nEstimatedSeconds

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

Return Values

S_OK

The notification has been acknowledged.

E_NOTIMPL

This function has not been implemented.

IDiscMasterProgressEvents::NotifyClosingDisc

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

HRESULT NotifyClosingDisc( long nEstimatedSeconds );

Parameter

nEstimatedSeconds

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

Return Values

S_OK

The notification has been acknowledged.

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.

HRESULT NotifyBurnComplete( HRESULT status );

Parameter

status

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

Return Values

S_OK

The notification has been acknowledged.

E_NOTIMPL

This function has not been implemented.