Метод IWiaDataCallback::BandedDataCallback (wia_xp.h)

Статья
03/08/2023

Предоставляет уведомления о состоянии передачи данных. Методы передачи данных 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 будет содержать причину вызова . Не все параметры будут содержать данные обо всех вызовах. Например, при вызове 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 .

Пример кода приложения определяет объект CDataCallback , производный от интерфейса IWiaDataCallback . Приложение должно создать экземпляр объекта 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
Header	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

Возвращаемое значение

Комментарии

Примеры

Требования

Обратная связь

Дополнительные ресурсы