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 |
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de