IWiaDataCallback：：BandedDataCallback 方法 (wia_xp.h)

發行項
03/03/2024

提供數據傳輸狀態通知。 Windows Image Acquisition (WIA) IWiaDataTransfer 介面的數據傳輸方法會定期呼叫此方法。

語法

HRESULT BandedDataCallback(
  [in] LONG lMessage,
  [in] LONG lStatus,
  [in] LONG lPercentComplete,
  [in] LONG lOffset,
  [in] LONG lLength,
  [in] LONG lReserved,
  [in] LONG lResLength,
  [in] BYTE *pbBuffer
);

參數

[in] lMessage

類型： LONG

指定常數，指出回呼的原因。可以是下列值之一：

IT_MSG_DATA

WIA 系統正在將數據傳送至應用程式。

IT_MSG_DATA_HEADER

應用程式會在接收實際數據之前接收標頭。

IT_MSG_DEVICE_STATUS

Windows Vista 或更新版本。裝置的狀態已變更。

IT_MSG_FILE_PREVIEW_DATA

WIA 系統正在將預覽數據傳送至應用程式。

IT_MSG_FILE_PREVIEW_DATA_HEADER

應用程式會在接收實際預覽數據之前收到標頭。

IT_MSG_NEW_PAGE

數據傳輸會開始新的頁面。

IT_MSG_STATUS

這個回呼調用只會傳送狀態資訊。

IT_MSG_TERMINATION

數據傳輸已完成。

[in] lStatus

類型： LONG

指定常數，指出 WIA 裝置的狀態。可以設定為下列各項的組合：

IT_STATUS_TRANSFER_FROM_DEVICE

數據目前正在從 WIA 裝置傳輸。

IT_STATUS_PROCESSING_DATA

目前正在處理數據。

IT_STATUS_TRANSFER_TO_CLIENT

數據目前正在傳送至客戶端的數據緩衝區。

[in] lPercentComplete

類型： LONG

指定到目前為止已傳輸的總數據百分比。

[in] lOffset

類型： LONG

指定從目前數據帶開始之緩衝區開頭的位移，以位元組為單位。

[in] lLength

類型： LONG

指定目前數據帶的長度，以位元組為單位。

[in] lReserved

類型： LONG

保留供 WIA 執行時間系統內部使用。

[in] lResLength

類型： LONG

保留供 WIA 執行時間系統內部使用。

[in] pbBuffer

類型： BYTE*

資料緩衝區的指標。

傳回值

類型： HRESULT

如果方法成功，方法會傳回S_OK。若要取消數據傳輸，它會傳回S_FALSE。如果方法失敗，它會傳回標準 COM 錯誤碼。

備註

您的應用程式必須提供 IWiaDataCallback：：BandedDataCallback 方法。這個方法會由 IWiaDataTransfer 介面的數據傳輸方法定期叫用。它會在資料傳輸期間將狀態消息提供給應用程式。藉由傳回S_FALSE，您的程式也可以使用這個方法來提前終止數據傳輸。

叫用此方法時， lMessage 參數會包含呼叫的原因。並非所有參數都會包含所有呼叫的數據。例如，使用IT_MSG_TERMINATION訊息叫用 IWiaDataCallback：：BandedDataCallback 時，不應該嘗試使用 pbBuffer、 lOffset 和 lLength 參數中的值。

如果 lMessage 的值 IT_MSG_DATA，pbBuffer 所指向的緩衝區會包含影像數據的訊號範圍。 lOffset 參數包含從緩衝區開頭開始的位元組位移。 lLength 參數指定目前數據帶的長度以位元組為單位。

在 lMessage 設定為IT_MSG_DATA或IT_MSG_STATUS的呼叫期間， lStatus 參數會包含有效的值。 當 lMessage 包含其他值時，不應使用其內容。

如果 lMessageIT_MSG_DATA_HEADER，pbBuffer 參數會指向 WIA_DATA_CALLBACK_HEADER 結構。

在影像數據傳輸期間發生錯誤時，驅動程式會將 lMessage 設定為 IT_MSG_DEVICE_STATUS。 Proxy 回呼物件會呼叫 ReportStatus，以處理錯誤並向使用者顯示訊息。

範例

下列範例示範實作 IWiaDataCallback：：BandedDataCallback 方法的其中一個可能方式。

範例應用程式程式代碼會定義衍生自 IWiaDataCallback 介面的 CDataCallback 物件。應用程式必須具現化 CDataCallback 物件。然後它會呼叫 CDataCallback：：QueryInterface 來取得 IWiaDataCallback 介面指標。當應用程式準備好接收數據時，它會叫用 idtGetBandedData 方法，並將方法傳遞至 IWiaDataCallback 介面的指標。

idtGetBandedData 方法會定期使用 IWiaDataCallback 介面指標來叫用應用程式的 CDataCallback：：BandedDataCallback 方法。第一個調用會傳送狀態消息。後面接著會將數據標頭傳送至回呼方法的呼叫。應用程式收到數據標頭之後， idtGetBandedData 會叫用 CDataCallback：：BandedDataCallback 以將數據傳送至應用程式。數據傳輸完成時，它會在最後一次呼叫回呼方法，以傳輸終止訊息。


//
// The application must instantiate the CDataCallback object using
// the "new" operator, and call QueryInterface to retrieve the 
// IWiaDataCallback interface.
//
// In this example, using in-memory transfer, the application then
// calls the IWiaDataTransfer::idtGetBandedData method and passes
// it the IWiaDataCallback interface pointer.
//
// If the application performs a file transfer using
// IWiaDataTransfer::idtGetData, only status messages are sent,
// and the data is transferred in a file.
//
class CDataCallback : public IWiaDataCallback
{
private:
    LONG  m_cRef;               // Object reference count 
    PBYTE m_pBuffer;            // Data buffer
    LONG  m_nBufferLength;      // Length of buffer
    LONG  m_nBytesTransfered;   // Total number of bytes transferred
    GUID  m_guidFormat;         // Data format

public:
    
    //
    // Constructor and destructor
    //
    CDataCallback()
      : m_cRef(1),
        m_pBuffer(NULL),
        m_nBufferLength(0),
        m_nBytesTransfered(0),
        m_guidFormat(IID_NULL)
    {
    }
    ~CDataCallback()
    {
        //
        // Free the item buffer
        //
        if (m_pBuffer)
        {
            LocalFree( m_pBuffer );
            m_pBuffer = NULL;
        }
        m_nBufferLength = 0;
        m_nBytesTransfered = 0;
    }

    //
    // IUnknown methods
    //
    HRESULT CALLBACK QueryInterface( REFIID riid, void **ppvObject )
    {
        //
        // Validate arguments
        //
        if (NULL == ppvObject)
        {
            return E_INVALIDARG;
        }

        //
        // Return the appropriate interface
        //
        if (IsEqualIID( riid, IID_IUnknown ))
        {
            *ppvObject = static_cast<CDataCallback *>(this);
        }
        else if (IsEqualIID( riid, IID_IWiaDataCallback ))
        {
            *ppvObject = static_cast<CDataCallback *>(this);
        }
        else
        {
            *ppvObject = NULL;
            return(E_NOINTERFACE);
        }

        //
        // Increment the reference count before returning the interface.
        //
        reinterpret_cast<IUnknown*>(*ppvObject)->AddRef();
        return S_OK;
    }
    ULONG CALLBACK AddRef()
    {
        return InterlockedIncrement(&m_cRef);
    }    
    ULONG CALLBACK Release()
    {
        LONG cRef = InterlockedDecrement(&m_cRef);
        if (0 == cRef)
        {
            delete this;
        }
        return cRef;
    }

    //
    // The IWiaDataTransfer::idtGetBandedData method periodically 
    // calls the IWiaDataCallback::BandedDataCallback method with
    // status messages. It sends the callback method a data header
    // message followed by one or more data messages to transfer 
    // data. It concludes by sending a termination message.
    //
    
    HRESULT _stdcall BandedDataCallback(
            LONG lMessage,
            LONG lStatus,
            LONG lPercentComplete,
            LONG lOffset,
            LONG lLength,
            LONG lReserved,
            LONG lResLength,
            BYTE *pbData)
    {
        UNREFERENCED_PARAMETER(lReserved);
        UNREFERENCED_PARAMETER(lResLength);
        switch (lMessage)
        {
        case IT_MSG_DATA_HEADER:
            {
                //
                // The data header contains the image's final size.
                //
                PWIA_DATA_CALLBACK_HEADER pHeader = reinterpret_cast(pbData);
                if (pHeader && pHeader->lBufferSize)
                {
                    //
                    // Allocate a block of memory to hold the image
                    //
                    m_pBuffer = reinterpret_cast(LocalAlloc(LPTR,pHeader->lBufferSize));
                    if (m_pBuffer)
                    {
                        //
                        // Save the buffer size.
                        //
                        m_nBufferLength = pHeader->lBufferSize;

                        //
                        // Initialize the bytes transferred count.
                        //
                        m_nBytesTransfered = 0;

                        //
                        // Save the file format.
                        //
                        m_guidFormat = pHeader->guidFormatID;
                    }
                }
            }
            break;

        case IT_MSG_DATA:
            {
                //
                // Make sure a block of memory has been created.
                //
                if (NULL != m_pBuffer)
                {
                    //
                    // Copy the new band.
                    //
                    CopyMemory( m_pBuffer + lOffset, pbData, lLength );

                    //
                    // Increment the byte count.
                    //
                    m_nBytesTransfered += lLength;
                }
            }
            break;

        case IT_MSG_STATUS:
            {
                //
                // Display transfer phase
                //
                if (lStatus & IT_STATUS_TRANSFER_FROM_DEVICE)
                {
                    _tprintf(TEXT("Transfer from device\n"));
                }
                else if (lStatus & IT_STATUS_PROCESSING_DATA)
                {
                    _tprintf(TEXT("Processing Data\n"));
                }
                else if (lStatus & IT_STATUS_TRANSFER_TO_CLIENT)
                {
                    _tprintf(TEXT("Transfer to Client\n"));
                }

                //
                // Display percent complete
                //
                _tprintf( TEXT("lPercentComplete: %d\n"), lPercentComplete );
            }
            break;
        }

        return S_OK;
    }
};

規格需求

需求	值
最低支援的用戶端	Windows 2000 專業版、Windows XP [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2003 [僅限傳統型應用程式]
目標平台	Windows
標頭	wia_xp.h (包括 Wia.h)
程式庫	Wiaguid.lib

共用方式為

IWiaDataCallback：：BandedDataCallback 方法 (wia_xp.h)

語法

參數

IT_MSG_DATA

IT_MSG_DATA_HEADER

IT_MSG_DEVICE_STATUS

IT_MSG_FILE_PREVIEW_DATA

IT_MSG_FILE_PREVIEW_DATA_HEADER

IT_MSG_NEW_PAGE

IT_MSG_STATUS

IT_MSG_TERMINATION

IT_STATUS_TRANSFER_FROM_DEVICE

IT_STATUS_PROCESSING_DATA

IT_STATUS_TRANSFER_TO_CLIENT

傳回值

備註

範例

規格需求

意見反應

其他資源