IDiscMasterProgressEvents Interface

IID_IDiscMasterProgressEvents

{EC9E51C1-4E5D-11D3-9144-00104BA11C5E}

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

Methods in VTable order

IUnknown Methods

Description

QueryInterface

Returns pointers to supported interfaces.

AddRef

Increments reference count.

Release

Decrements reference count.

IDiscMasterProgressEvents Members

Description

QueryCancel

Checks whether a burn is to be canceled.

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 interface implementation

' ****************************************************************************************
' Interface name = IDiscMasterProgressEvents
' IID = {EC9E51C1-4E5D-11D3-9144-00104BA11C5E}
' The IDiscMasterProgressEvents interface provides a single interface for all callbacks
' that can be made from IMAPI to an application. An application implements this interface
' on one of its objects and then registers it using IDiscMaster::ProgressAdvise. All but
' one of the methods in this interface are related to progress during staging or burns.
' Even if an application is not interested in a particular callback, it must implement the
' callback function and return E_NOTIMPL on the call.
' ****************************************************************************************

' ****************************************************************************************
' This is an event class for the IDiscMaster interface.
' To advise it you have to build an instance of this class and call the
' IDiscMaster_ProgressAdvise wrapper function. To unadvise, you have to call the
' IDiscMaster_ProgressUnadvise wrapper function passing to it the cookie returned in the
' call to IDiscMaster_ProgressAdvise.
' Note: Not sure if ProgressAdvise will call IDiscMasterProgressEvents_QueryInterface or
' not. If it calls it, then you will need to destroy this class after calling
' IDiscMaster_ProgressAdvise with a call to IDiscMasterProgressEvents_Release.
' ****************************************************************************************

' ****************************************************************************************
' IDiscMasterProgressEvents virtual table
' ****************************************************************************************
TYPE IDiscMasterProgressEventsVtbl
   ' IUnknown interface
   QueryInterface AS DWORD           ' Returns pointers to supported interfaces
   AddRef AS DWORD                   ' Increments reference count
   Release AS DWORD                  ' Decrements reference count
   ' IDiscMasterProgressEvents interface
   QueryCancel AS DWORD              ' QueryCancel method
   NotifyPnPActivity AS DWORD        ' NotifyPnPActivity method
   NotifyAddProgress AS DWORD        ' NotifyAddProgress method
   NotifyBlockProgress AS DWORD      ' NotifyBlockProgress method
   NotifyTrackProgress AS DWORD      ' NotifyTrackProgress method
   NotifyPreparingBurn AS DWORD      ' NotifyPreparingBurn method
   NotifyClosingDisc AS DWORD        ' NotifyClosingDisc method
   NotifyBurnComplete AS DWORD       ' NotifyBurnComplete method
   NotifyEraseComplete AS DWORD      ' NotifyEraseComplete method
   ' Custom data
   pVtblAddr AS DWORD                ' Address of the virtual table
   cRef AS DWORD                     ' Reference counter
   pthis AS DWORD                    ' IUnknown of the control that fires the events
END TYPE
' ****************************************************************************************

' ****************************************************************************************
' UI4 AddRef()
' ****************************************************************************************
FUNCTION IDiscMasterProgressEvents_AddRef ( _
    BYVAL pCookie AS IDiscMasterProgressEventsVtbl PTR _
    ) AS DWORD

    INCR @@pCookie.cRef
    FUNCTION = @@pCookie.cRef

END FUNCTION
' ****************************************************************************************

' ****************************************************************************************
' HRESULT QueryInterface([in] *GUID riid, [out] **VOID ppvObj)
' ****************************************************************************************
FUNCTION IDiscMasterProgressEvents_QueryInterface ( _
    BYVAL pCookie AS IDiscMasterProgressEventsVtbl PTR _
  , BYREF riid AS GUID _
  , BYREF ppvObj AS DWORD _
    ) AS LONG

    IF riid = GUID$("{00000000-0000-0000-C000-000000000046}") OR _   ' // IUnknown interface
       riid = GUID$("{00020400-0000-0000-C000-000000000046}") OR _   ' // IDispatch interface
       riid = GUID$("{EC9E51C1-4E5D-11D3-9144-00104BA11C5E}") THEN   ' // IDiscMasterProgressEvents interface
       ppvObj = pCookie
       IDiscMasterProgressEvents_AddRef pCookie
       FUNCTION = %S_OK
    ELSE
       ppvObj = %NULL
       FUNCTION = %E_NOINTERFACE
    END IF

END FUNCTION
' ****************************************************************************************

' ****************************************************************************************
' UI4 Release()
' ****************************************************************************************
FUNCTION IDiscMasterProgressEvents_Release ( _
    BYVAL pCookie AS IDiscMasterProgressEventsVtbl PTR _
    ) AS DWORD

    LOCAL pVtblAddr AS DWORD
    IF @@pCookie.cRef = 1 THEN
       pVtblAddr = @@pCookie.pVtblAddr
       IF ISTRUE HeapFree(GetProcessHeap(), 0, BYVAL pVtblAddr) THEN
          FUNCTION = %S_OK
          EXIT FUNCTION
       ELSE
          FUNCTION = @@pCookie.cRef
          EXIT FUNCTION
       END IF
    END IF
    DECR @@pCookie.cRef
    FUNCTION = @@pCookie.cRef

END FUNCTION
' ****************************************************************************************

' ****************************************************************************************
' Builds the IDiscMasterProgressEvents Virtual Table
' ****************************************************************************************
FUNCTION IDiscMasterProgressEvents_BuildVtbl (BYVAL pthis AS DWORD) AS DWORD

   LOCAL pVtbl AS IDiscMasterProgressEventsVtbl PTR
   LOCAL pUnk AS IDiscMasterProgressEventsVtbl PTR

   pVtbl = HeapAlloc(GetProcessHeap(), %HEAP_ZERO_MEMORY, SIZEOF(@pVtbl))
   IF pVtbl = 0 THEN EXIT FUNCTION

   @pVtbl.QueryInterface        = CODEPTR(IDiscMasterProgressEvents_QueryInterface)
   @pVtbl.AddRef                = CODEPTR(IDiscMasterProgressEvents_AddRef)
   @pVtbl.Release               = CODEPTR(IDiscMasterProgressEvents_Release)

   @pVtbl.QueryCancel           = CODEPTR(IDiscMasterProgressEvents_QueryCancel)
   @pVtbl.NotifyPnPActivity     = CODEPTR(IDiscMasterProgressEvents_NotifyPnPActivity)
   @pVtbl.NotifyAddProgress     = CODEPTR(IDiscMasterProgressEvents_NotifyAddProgress)
   @pVtbl.NotifyBlockProgress   = CODEPTR(IDiscMasterProgressEvents_NotifyBlockProgress)
   @pVtbl.NotifyTrackProgress   = CODEPTR(IDiscMasterProgressEvents_NotifyTrackProgress)
   @pVtbl.NotifyPreparingBurn   = CODEPTR(IDiscMasterProgressEvents_NotifyPreparingBurn)
   @pVtbl.NotifyClosingDisc     = CODEPTR(IDiscMasterProgressEvents_NotifyClosingDisc)
   @pVtbl.NotifyBurnComplete    = CODEPTR(IDiscMasterProgressEvents_NotifyBurnComplete)
   @pVtbl.NotifyEraseComplete   = CODEPTR(IDiscMasterProgressEvents_NotifyEraseComplete)

   @pVtbl.pVtblAddr             = pVtbl
   @pVtbl.pthis                 = pthis
   @pVtbl.cRef                  = 1

   pUnk = VARPTR(@pVtbl.pVtblAddr)
   FUNCTION = pUnk

END FUNCTION
' ****************************************************************************************


' ****************************************************************************************
' QueryCancel method
' Checks whether a burn is to be canceled.
' /* [helpstring] */ HRESULT ( STDMETHODCALLTYPE *QueryCancel )(
'    IDiscMasterProgressEvents * This,
'    /* [retval][out] */ boolean *pbCancel);
' The QueryCancel method is called by IMAPI to check whether an AddData,
' AddAudioTrackBlocks, or RecordDisc operation should be canceled.
' Parameters
' pbCancel
'    [out] If this parameter is TRUE, cancel the burn. If this parameter is FALSE, continue the burn.
' Return Values
' This method returns one of the following values.
' S_OK
'    The cancel indication (pbCancel) has been set successfully.
' E_NOTIMPL
'    This method has not been implemented.
' ****************************************************************************************
FUNCTION IDiscMasterProgressEvents_QueryCancel ALIAS "IDiscMasterProgressEvents_QueryCancel" ( _
    BYVAL pCookie AS IDiscMasterProgressEventsVtbl PTR _  ' IUNKNOWN <interface>
  , BYREF pbCancel AS LONG _                              ' *BOOL [out]
    ) EXPORT AS LONG                                      ' HRESULT <LONG>

   LOCAL pthis AS DWORD
   pthis = @@pCookie.pthis

   ' Put your code here
   ' FUNCTION = %S_OK or %E_NOTIMPL

END FUNCTION
' ****************************************************************************************

' ****************************************************************************************
' NotifyPnPActivity method
' Reports possible changes to recorder list.
' /* [helpstring] */ HRESULT ( STDMETHODCALLTYPE *NotifyPnPActivity )(
'    IDiscMasterProgressEvents * This);
' The NotifyPnPActivity method is called by IMAPI to notify the application that there is
' a change to the list of valid disc recorders. (For example, a USB CD-R driver is removed
' from the system.)
' Parameters
' This method has no parameters.
' Return Values
' This method returns one of the following values.
' S_OK
'    The notification has been acknowledged.
' E_NOTIMPL
'    This method has not been implemented.
' Remarks
' An application should respond by calling IDiscMaster::EnumDiscRecorders to update its
' list of valid recorders. If the current active recorder has been invalidated, then a new
' recorder should be chosen.
' ****************************************************************************************
FUNCTION IDiscMasterProgressEvents_NotifyPnPActivity ALIAS "IDiscMasterProgressEvents_NotifyPnPActivity" ( _
    BYVAL pCookie AS IDiscMasterProgressEventsVtbl PTR _  ' IUNKNOWN <interface>
    ) EXPORT AS LONG                                      ' HRESULT <LONG>

   LOCAL pthis AS DWORD
   pthis = @@pCookie.pthis

   ' Put your code here
   ' FUNCTION = %S_OK or %E_NOTIMPL

END FUNCTION
' ****************************************************************************************

' ****************************************************************************************
' NotifyAddProgress method
' Reports progress of audio/data staging.
' /* [helpstring] */ HRESULT ( STDMETHODCALLTYPE *NotifyAddProgress )(
'    IDiscMasterProgressEvents * This,
'    /* [in] */ long nCompletedSteps,
'    /* [in] */ long nTotalSteps);
' The NotifyAddProgress method is called by IMAPI to notify an application of its progress
' in response to calls to IRedbookDiscMaster::AddAudioTrackBlocks or
' IJolietDiscMaster::AddData. Notifications are sent for the first and last steps, and at
' points in between.
' Parameters
' nCompletedSteps
'    [in] Number of arbitrary steps that have been completed in adding audio or data to a staged image.
' nTotalSteps
'    [in] Total number of arbitrary steps that must be taken to add a full set of audio or data to the staged image.
' Return Values
' This method returns one of the following values.
' S_OK
'    The notification has been acknowledged.
' E_NOTIMPL
'    This method has not been implemented.
' ****************************************************************************************
FUNCTION IDiscMasterProgressEvents_NotifyAddProgress ALIAS "IDiscMasterProgressEvents_NotifyAddProgress" ( _
    BYVAL pCookie AS IDiscMasterProgressEventsVtbl PTR _  ' IUNKNOWN <interface>
  , BYVAL nCompletedSteps AS LONG _                       ' LONG [in]
  , BYVAL nTotalSteps AS LONG _                           ' LONG [in]
    ) EXPORT AS LONG                                      ' HRESULT <LONG>

   LOCAL pthis AS DWORD
   pthis = @@pCookie.pthis

   ' Put your code here
   ' FUNCTION = %S_OK or %E_NOTIMPL

END FUNCTION
' ****************************************************************************************

' ****************************************************************************************
' NotifyBlockProgress method
' Reports progress of audio/data burn.
' /* [helpstring] */ HRESULT ( STDMETHODCALLTYPE *NotifyBlockProgress )(
'    IDiscMasterProgressEvents * This,
'    /* [in] */ long nCompleted,
'    /* [in] */ long nTotal);
' The NotifyBlockProgress method is called by IMAPI to notify an application of its
' progress in burning a disc on the active recorder. Notifications are sent for the first
' and last blocks, and at points in between.
' Parameters
' nCompleted
'    [in] Number of blocks that have been burned onto a disc or track so far.
' nTotal
'    [in] Total number of blocks to be burned to finish a disc or track.
' Return Values
' This method returns one of the following values.
' S_OK
'    The notification has been acknowledged.
' E_NOTIMPL
'    This method has not been implemented.
' ****************************************************************************************
FUNCTION IDiscMasterProgressEvents_NotifyBlockProgress ALIAS "IDiscMasterProgressEvents_NotifyBlockProgress" ( _
    BYVAL pCookie AS IDiscMasterProgressEventsVtbl PTR _  ' IUNKNOWN <interface>
  , BYVAL nCompleted AS LONG _                            ' LONG [in]
  , BYVAL nTotal AS LONG _                                ' LONG [in]
    ) EXPORT AS LONG                                      ' HRESULT <LONG>

   LOCAL pthis AS DWORD
   pthis = @@pCookie.pthis

   ' Put your code here
   ' FUNCTION = %S_OK or %E_NOTIMPL

END FUNCTION
' ****************************************************************************************

' ****************************************************************************************
' NotifyTrackProgress method
' Reports progress of an audio burn.
' /* [helpstring] */ HRESULT ( STDMETHODCALLTYPE *NotifyTrackProgress )(
'    IDiscMasterProgressEvents * This,
'    /* [in] */ long nCurrentTrack,
'    /* [in] */ long nTotalTracks);
' The NotifyTrackProgress method is called by IMAPI during the burn of an audio disc to
' notify an application that a track has started or finished.
' Parameters
' nCurrentTrack
'    [in] Number of tracks that have been completely burned.
' nTotalTracks
'    [in] Total number of tracks that must be burned.
' Return Values
' This method returns one of the following values.
' S_OK
'    The notification has been acknowledged.
' E_NOTIMPL
'    This method has not been implemented.
' Remarks
' The notification for zero 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.
' ****************************************************************************************
FUNCTION IDiscMasterProgressEvents_NotifyTrackProgress ALIAS "IDiscMasterProgressEvents_NotifyTrackProgress" ( _
    BYVAL pCookie AS IDiscMasterProgressEventsVtbl PTR _  ' IUNKNOWN <interface>
  , BYVAL nCurrentTrack AS LONG _                         ' LONG [in]
  , BYVAL nTotalTracks AS LONG _                          ' LONG [in]
    ) EXPORT AS LONG                                      ' HRESULT <LONG>

   LOCAL pthis AS DWORD
   pthis = @@pCookie.pthis

   ' Put your code here
   ' FUNCTION = %S_OK or %E_NOTIMPL

END FUNCTION
' ****************************************************************************************

' ****************************************************************************************
' NotifyPreparingBurn method
' Reports progress during burn setup.
' /* [helpstring] */ HRESULT ( STDMETHODCALLTYPE *NotifyPreparingBurn )(
'    IDiscMasterProgressEvents * This,
'    /* [in] */ long nEstimatedSeconds);
' The NotifyPreparingBurn method is called by IMAPI to notify the application that it is
' preparing to burn a disc. No further notifications are sent until the burn starts.
' Parameters
' nEstimatedSeconds
'    [in] Number of seconds from notification that IMAPI estimates it will take to prepare to burn the disc.
' Return Values
' This method returns one of the following values.
' S_OK
'    The notification has been acknowledged.
' E_NOTIMPL
'    This method has not been implemented.
' ****************************************************************************************
FUNCTION IDiscMasterProgressEvents_NotifyPreparingBurn ALIAS "IDiscMasterProgressEvents_NotifyPreparingBurn" ( _
    BYVAL pCookie AS IDiscMasterProgressEventsVtbl PTR _  ' IUNKNOWN <interface>
  , BYVAL nEstimatedSeconds AS LONG _                     ' LONG [in]
    ) EXPORT AS LONG                                      ' HRESULT <LONG>

   LOCAL pthis AS DWORD
   pthis = @@pCookie.pthis

   ' Put your code here
   ' FUNCTION = %S_OK or %E_NOTIMPL

END FUNCTION
' ****************************************************************************************

' ****************************************************************************************
' NotifyClosingDisc method
' Reports progress while closing a disc.
' /* [helpstring] */ HRESULT ( STDMETHODCALLTYPE *NotifyClosingDisc )(
'    IDiscMasterProgressEvents * This,
'    /* [in] */ long nEstimatedSeconds);
' The NotifyClosingDisc method is called by IMAPI to notify the application that it is has
' started closing the disc. No further notifications are sent until the burn is finished.
' Parameters
' nEstimatedSeconds
'    [in] Number of seconds from notification that IMAPI estimates it will take to close the disc.
' Return Values
' This method returns one of the following values.
' S_OK
'    The notification has been acknowledged.
' E_NOTIMPL
'    This method has not been implemented.
' ****************************************************************************************
FUNCTION IDiscMasterProgressEvents_NotifyClosingDisc ALIAS "IDiscMasterProgressEvents_NotifyClosingDisc" ( _
    BYVAL pCookie AS IDiscMasterProgressEventsVtbl PTR _  ' IUNKNOWN <interface>
  , BYVAL nEstimatedSeconds AS LONG _                     ' LONG [in]
    ) EXPORT AS LONG                                      ' HRESULT <LONG>

   LOCAL pthis AS DWORD
   pthis = @@pCookie.pthis

   ' Put your code here
   ' FUNCTION = %S_OK or %E_NOTIMPL

END FUNCTION
' ****************************************************************************************

' ****************************************************************************************
' NotifyBurnComplete method
' Reports that the burn is fully complete.
' /* [helpstring] */ HRESULT ( STDMETHODCALLTYPE *NotifyBurnComplete )(
'    IDiscMasterProgressEvents * This,
'    /* [in] */ HRESULT status);
' The NotifyBurnComplete method is called by IMAPI to notify an application that a call to
' IDiscMaster::RecordDisc has finished.
' Parameters
' status
'    [in] Status code to be returned from IDiscMaster::RecordDisc.
' Return Values
' This method returns one of the following values.
' S_OK
'    The notification has been acknowledged.
' E_NOTIMPL
'    This method has not been implemented.
' ****************************************************************************************
FUNCTION IDiscMasterProgressEvents_NotifyBurnComplete ALIAS "IDiscMasterProgressEvents_NotifyBurnComplete" ( _
    BYVAL pCookie AS IDiscMasterProgressEventsVtbl PTR _  ' IUNKNOWN <interface>
  , BYVAL nstatus AS LONG _                               ' HRESULT <LONG> [in]
    ) EXPORT AS LONG                                      ' HRESULT <LONG>

   LOCAL pthis AS DWORD
   pthis = @@pCookie.pthis

   ' Put your code here
   ' FUNCTION = %S_OK or %E_NOTIMPL

END FUNCTION
' ****************************************************************************************

' ****************************************************************************************
' NotifyEraseComplete method
' Reports that an erase is fully complete.
' /* [helpstring] */ HRESULT ( STDMETHODCALLTYPE *NotifyEraseComplete )(
'    IDiscMasterProgressEvents * This,
'    /* [in] */ HRESULT status);
' The NotifyEraseComplete method is called by IMAPI to notify an application that a call
' to IDiscRecorder::Erase has finished.
' Parameters
' status
'    [in] Status code to be returned from IDiscRecorder::Erase.
' Return Values
' This method returns one of the following values.
' S_OK
'    The notification has been acknowledged.
' E_NOTIMPL
'    This method has not been implemented.
' ****************************************************************************************
FUNCTION IDiscMasterProgressEvents_NotifyEraseComplete ALIAS "IDiscMasterProgressEvents_NotifyEraseComplete" ( _
    BYVAL pCookie AS IDiscMasterProgressEventsVtbl PTR _  ' IUNKNOWN <interface>
  , BYVAL nstatus AS LONG _                               ' HRESULT <LONG> [in]
    ) EXPORT AS LONG                                      ' HRESULT <LONG>

   LOCAL pthis AS DWORD
   pthis = @@pCookie.pthis

   ' Put your code here
   ' FUNCTION = %S_OK or %E_NOTIMPL

END FUNCTION
' ****************************************************************************************