Compartilhar via


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

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