IWiaDataCallback::BandedDataCallback 메서드(wia_xp.h)

데이터 전송 상태 알림을 제공합니다. IWiaDataTransfer 인터페이스의 WIA(Windows Image Acquisition) 데이터 전송 메서드는 주기적으로 이 메서드를 호출합니다.

구문

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 메서드를 구현할 수 있는 한 가지 방법을 보여줍니다.

예제 애플리케이션 코드는 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;
    }
};

요구 사항