Método IWiaDataCallback::BandedDataCallback (wia_xp.h)

Artigo
03/08/2023

Fornece notificações de status de transferência de dados. Os métodos de transferência de dados wia (aquisição de imagens do Windows) da interface IWiaDataTransfer chamam periodicamente esse método.

Sintaxe

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
);

Parâmetros

[in] lMessage

Tipo: LONG

Especifica uma constante que indica o motivo do retorno de chamada. Pode ser um dos seguintes valores:

IT_MSG_DATA

O sistema WIA está transferindo dados para o aplicativo.

IT_MSG_DATA_HEADER

O aplicativo está recebendo um cabeçalho antes de receber os dados reais.

IT_MSG_DEVICE_STATUS

Windows Vista ou posterior. O status no dispositivo foi alterado.

IT_MSG_FILE_PREVIEW_DATA

O sistema WIA está transferindo dados de visualização para o aplicativo.

IT_MSG_FILE_PREVIEW_DATA_HEADER

O aplicativo está recebendo um cabeçalho antes de receber os dados de visualização reais.

IT_MSG_NEW_PAGE

A transferência de dados está iniciando uma nova página.

IT_MSG_STATUS

Essa invocação do retorno de chamada está enviando apenas status informações.

IT_MSG_TERMINATION

A transferência de dados foi concluída.

[in] lStatus

Tipo: LONG

Especifica uma constante que indica o status do dispositivo WIA. Pode ser definido como uma combinação do seguinte:

IT_STATUS_TRANSFER_FROM_DEVICE

No momento, os dados estão sendo transferidos do dispositivo WIA.

IT_STATUS_PROCESSING_DATA

No momento, os dados estão sendo processados.

IT_STATUS_TRANSFER_TO_CLIENT

Atualmente, os dados estão sendo transferidos para o buffer de dados do cliente.

[in] lPercentComplete

Tipo: LONG

Especifica o percentual do total de dados que foram transferidos até agora.

[in] lOffset

Tipo: LONG

Especifica um deslocamento, em bytes, desde o início do buffer em que a faixa atual de dados começa.

[in] lLength

Tipo: LONG

Especifica o comprimento, em bytes, da faixa de dados atual.

[in] lReserved

Tipo: LONG

Reservado para uso interno pelo sistema de tempo de execução wia.

[in] lResLength

Tipo: LONG

Reservado para uso interno pelo sistema de tempo de execução wia.

[in] pbBuffer

Tipo: BYTE*

Ponteiro para o buffer de dados.

Retornar valor

Tipo: HRESULT

Se o método for bem-sucedido, o método retornará S_OK. Para cancelar a transferência de dados, ele retorna S_FALSE. Se o método falhar, ele retornará um código de erro COM padrão.

Comentários

Seu aplicativo deve fornecer o método IWiaDataCallback::BandedDataCallback . Esse método é invocado periodicamente pelos métodos de transferência de dados da interface IWiaDataTransfer . Ele fornece status mensagens para o aplicativo durante a transferência de dados. Retornando S_FALSE, seu programa também pode usar esse método para encerrar prematuramente a transferência de dados.

Quando esse método for invocado, o parâmetro lMessage conterá o motivo da chamada. Nem todos os parâmetros conterão dados em todas as chamadas. Por exemplo, quando IWiaDataCallback::BandedDataCallback é invocado com uma mensagem de IT_MSG_TERMINATION, ele não deve tentar usar os valores nos parâmetros pbBuffer, lOffset e lLength .

Se o valor de lMessage for IT_MSG_DATA, o buffer apontado por pbBuffer conterá uma faixa de dados de imagem. O parâmetro lOffset contém um deslocamento em bytes desde o início do buffer em que a faixa atual de dados começa. O parâmetro lLength especificou o comprimento em bytes da faixa de dados atual.

Durante chamadas em que lMessage é definido como IT_MSG_DATA ou IT_MSG_STATUS, o parâmetro lStatus contém um valor válido. Seu conteúdo não deve ser usado quando lMessage contém outros valores.

Se lMessage for IT_MSG_DATA_HEADER, o parâmetro pbBuffer apontará para uma estrutura de WIA_DATA_CALLBACK_HEADER .

Quando ocorre um erro durante uma transferência de dados de imagem, o driver define lMessage como IT_MSG_DEVICE_STATUS. O objeto de retorno de chamada proxy chama ReportStatus, que manipula o erro e exibe mensagens para o usuário.

Exemplos

O exemplo a seguir mostra uma maneira possível de implementar o método IWiaDataCallback::BandedDataCallback .

O código de aplicativo de exemplo define o objeto CDataCallback que ele deriva da interface IWiaDataCallback . O aplicativo deve instanciar um objeto CDataCallback . Em seguida, ele chama CDataCallback::QueryInterface para obter um ponteiro de interface IWiaDataCallback . Quando o aplicativo está pronto para receber dados, ele invoca o método idtGetBandedData e passa o método um ponteiro para a interface IWiaDataCallback .

Periodicamente, o método idtGetBandedData usa o ponteiro da interface IWiaDataCallback para invocar o método CDataCallback::BandedDataCallback do aplicativo. As primeiras invocações enviam mensagens status. Eles são seguidos por uma chamada que transfere um cabeçalho de dados para o método de retorno de chamada. Depois que o aplicativo recebe o cabeçalho de dados, idtGetBandedData invoca CDataCallback::BandedDataCallback para transferir dados para o aplicativo. Quando a transferência de dados for concluída, ela chamará o método de retorno de chamada de uma hora final para transmitir uma mensagem de encerramento.


//
// 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;
    }
};

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 2000 Professional, Windows XP [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2003 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	wia_xp.h (inclua Wia.h)
Biblioteca	Wiaguid.lib

Compartilhar via

Método IWiaDataCallback::BandedDataCallback (wia_xp.h)

Sintaxe

Parâmetros

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

Retornar valor

Comentários

Exemplos

Requisitos

Comentários

Recursos adicionais