Metodo IWiaDataCallback::BandedDataCallback (wia_xp.h)

Fornisce notifiche sullo stato del trasferimento dei dati. I metodi di trasferimento dei dati di Acquisizione immagini Windows (WIA) dell'interfaccia IWiaDataTransfer chiamano periodicamente questo metodo.

Sintassi

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

Parametri

[in] lMessage

Tipo: LONG

Specifica una costante che indica il motivo del callback. I possibili valori sono i seguenti:

IT_MSG_DATA

Il sistema WIA trasferisce i dati all'applicazione.

IT_MSG_DATA_HEADER

L'applicazione riceve un'intestazione prima di ricevere i dati effettivi.

IT_MSG_DEVICE_STATUS

Windows Vista o versione successiva. Lo stato del dispositivo è stato modificato.

IT_MSG_FILE_PREVIEW_DATA

Il sistema WIA sta trasferendo i dati di anteprima all'applicazione.

IT_MSG_FILE_PREVIEW_DATA_HEADER

L'applicazione riceve un'intestazione prima di ricevere i dati di anteprima effettivi.

IT_MSG_NEW_PAGE

Il trasferimento dei dati inizia una nuova pagina.

IT_MSG_STATUS

Questa chiamata al callback invia solo informazioni sullo stato.

IT_MSG_TERMINATION

Il trasferimento dei dati è completo.

[in] lStatus

Tipo: LONG

Specifica una costante che indica lo stato del dispositivo WIA. Può essere impostato su una combinazione dei seguenti elementi:

IT_STATUS_TRANSFER_FROM_DEVICE

I dati vengono attualmente trasferiti dal dispositivo WIA.

IT_STATUS_PROCESSING_DATA

I dati vengono attualmente elaborati.

IT_STATUS_TRANSFER_TO_CLIENT

I dati vengono attualmente trasferiti nel buffer dei dati del client.

[in] lPercentComplete

Tipo: LONG

Specifica la percentuale dei dati totali trasferiti finora.

[in] lOffset

Tipo: LONG

Specifica un offset, in byte, dall'inizio del buffer in cui inizia la banda corrente di dati.

[in] lLength

Tipo: LONG

Specifica la lunghezza, in byte, della banda di dati corrente.

[in] lReserved

Tipo: LONG

Riservato per l'uso interno da parte del sistema di runtime WIA.

[in] lResLength

Tipo: LONG

Riservato per l'uso interno da parte del sistema di runtime WIA.

[in] pbBuffer

Tipo: BYTE*

Puntatore al buffer di dati.

Valore restituito

Tipo: HRESULT

Se il metodo ha esito positivo, il metodo restituisce S_OK. Per annullare il trasferimento dei dati, restituisce S_FALSE. Se il metodo ha esito negativo, restituisce un codice di errore COM standard.

Commenti

L'applicazione deve fornire il metodo IWiaDataCallback::BandedDataCallback . Questo metodo viene richiamato periodicamente dai metodi di trasferimento dei dati dell'interfaccia IWiaDataTransfer . Fornisce messaggi di stato all'applicazione durante il trasferimento dei dati. Restituendo S_FALSE, il programma può anche usare questo metodo per terminare prematuramente il trasferimento dei dati.

Quando questo metodo viene richiamato, il parametro lMessage conterrà il motivo della chiamata. Non tutti i parametri conterranno dati su tutte le chiamate. Ad esempio, quando IWiaDataCallback::BandedDataCallback viene richiamato con un messaggio di IT_MSG_TERMINATION, non deve tentare di usare i valori nei parametri pbBuffer, lOffset e lLength .

Se il valore di lMessage è IT_MSG_DATA, il buffer a cui punta pbBuffer contiene una banda di dati di immagine. Il parametro lOffset contiene un offset in byte dall'inizio del buffer in cui inizia la banda corrente di dati. Il parametro lLength ha specificato la lunghezza in byte della banda di dati corrente.

Durante le chiamate in cui lMessage è impostato su IT_MSG_DATA o IT_MSG_STATUS, il parametro lStatus contiene un valore valido. Il contenuto non deve essere usato quando lMessage contiene altri valori.

Se lMessage è IT_MSG_DATA_HEADER, il parametro pbBuffer punta a una struttura WIA_DATA_CALLBACK_HEADER .

Quando si è verificato un errore durante il trasferimento dei dati di un'immagine, il driver imposta lMessage su IT_MSG_DEVICE_STATUS. L'oggetto di callback proxy chiama ReportStatus, che gestisce l'errore e visualizza i messaggi all'utente.

Esempio

L'esempio seguente illustra un modo possibile per implementare il metodo IWiaDataCallback::BandedDataCallback .

Il codice dell'applicazione di esempio definisce l'oggetto CDataCallback che deriva dall'interfaccia IWiaDataCallback . L'applicazione deve creare un'istanza di un oggetto CDataCallback . Chiama quindi CDataCallback::QueryInterface per ottenere un puntatore all'interfaccia IWiaDataCallback . Quando l'applicazione è pronta per ricevere i dati, richiama il metodo idtGetBandedData e passa il metodo un puntatore all'interfaccia IWiaDataCallback .

Periodicamente, il metodo idtGetBandedData usa il puntatore all'interfaccia IWiaDataCallback per richiamare il metodo CDataCallback::BandedDataCallback dell'applicazione. Le prime chiamate inviano messaggi di stato. Vengono seguiti da una chiamata che trasferisce un'intestazione dati al metodo di callback. Dopo che l'applicazione riceve l'intestazione dati, idtGetBandedData richiama CDataCallback::BandedDataCallback per trasferire i dati all'applicazione. Al termine del trasferimento dei dati, chiama il metodo di callback un'ora finale per trasmettere un messaggio di terminazione.

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

Requisiti