IWiaDataCallback::BandedDataCallback メソッド (wia_xp.h)

[アーティクル]
03/08/2023

データ転送の状態通知を提供します。 IWiaDataTransfer インターフェイスの Windows Image Acquisition (WIA) データ転送メソッドは、このメソッドを定期的に呼び出します。

構文

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 パラメーターに呼び出しの理由が含まれます。すべてのパラメーターに、すべての呼び出しのデータが含まれているわけではありません。たとえば、 IWiaDataCallback::BandedDataCallback が IT_MSG_TERMINATION のメッセージで呼び出された場合、 pbBuffer、 lOffset、および lLength パラメーターの値の使用を試行しないでください。

lMessage の値がIT_MSG_DATA場合、pbBuffer によって指されるバッファーには、画像データのバンドが含まれます。 lOffset パラメーターには、データの現在のバンドが開始されるバッファーの先頭からのオフセット (バイト単位) が含まれます。 lLength パラメーターは、現在のデータバンドの長さをバイト単位で指定しました。

lMessage が IT_MSG_DATA または IT_MSG_STATUS に設定されている呼び出し中に、lStatus パラメーターに有効な値が含まれます。 lMessage に他の値が含まれている場合は、その内容を使用しないでください。

lMessage がIT_MSG_DATA_HEADERの場合、pbBuffer パラメーターはWIA_DATA_CALLBACK_HEADER構造体を指します。

イメージデータ転送中にエラーが発生すると、ドライバーは lMessage をIT_MSG_DEVICE_STATUSに設定します。プロキシコールバックオブジェクトは ReportStatus を呼び出し、エラーを処理し、ユーザーにメッセージを表示します。

例

次の例は、 IWiaDataCallback::BandedDataCallback メソッドを実装する方法の 1 つを示しています。

アプリケーションコード例では、 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 Professional、Windows XP [デスクトップアプリのみ]
サポートされている最小のサーバー	Windows Server 2003 (デスクトップアプリのみ)
対象プラットフォーム	Windows
ヘッダー	wia_xp.h (Wia.h を含む)
Library	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

戻り値

注釈

例

要件

フィードバック

その他のリソース