Compartir a través de

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

  • Artículo

Proporciona notificaciones de estado de transferencia de datos. Los métodos de transferencia de datos de adquisición de imágenes de Windows (WIA) de la interfaz IWiaDataTransfer llaman periódicamente a este método.

Sintaxis

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 una constante que indica el motivo de la devolución de llamada. Puede ser uno de los siguientes valores:

IT_MSG_DATA

El sistema WIA transfiere datos a la aplicación.

IT_MSG_DATA_HEADER

La aplicación recibe un encabezado antes de recibir los datos reales.

IT_MSG_DEVICE_STATUS

Windows Vista o posterior. El estado en el dispositivo ha cambiado.

IT_MSG_FILE_PREVIEW_DATA

El sistema WIA transfiere los datos de vista previa a la aplicación.

IT_MSG_FILE_PREVIEW_DATA_HEADER

La aplicación recibe un encabezado antes de recibir los datos reales de vista previa.

IT_MSG_NEW_PAGE

La transferencia de datos comienza una nueva página.

IT_MSG_STATUS

Esta invocación de la devolución de llamada solo envía información de estado.

IT_MSG_TERMINATION

La transferencia de datos se ha completado.

[in] lStatus

Tipo: LONG

Especifica una constante que indica el estado del dispositivo WIA. Se puede establecer en una combinación de lo siguiente:

IT_STATUS_TRANSFER_FROM_DEVICE

Actualmente, los datos se transfieren desde el dispositivo WIA.

IT_STATUS_PROCESSING_DATA

Los datos se están procesando actualmente.

IT_STATUS_TRANSFER_TO_CLIENT

Los datos se están transfiriendo actualmente al búfer de datos del cliente.

[in] lPercentComplete

Tipo: LONG

Especifica el porcentaje de los datos totales transferidos hasta ahora.

[in] lOffset

Tipo: LONG

Especifica un desplazamiento, en bytes, desde el principio del búfer donde comienza la banda actual de datos.

[in] lLength

Tipo: LONG

Especifica la longitud, en bytes, de la banda de datos actual.

[in] lReserved

Tipo: LONG

Reservado para uso interno del sistema en tiempo de ejecución de WIA.

[in] lResLength

Tipo: LONG

Reservado para uso interno del sistema en tiempo de ejecución de WIA.

[in] pbBuffer

Tipo: BYTE*

Puntero al búfer de datos.

Valor devuelto

Tipo: HRESULT

Si el método se realiza correctamente, el método devuelve S_OK. Para cancelar la transferencia de datos, devuelve S_FALSE. Si se produce un error en el método, devuelve un código de error COM estándar.

Comentarios

La aplicación debe proporcionar el método IWiaDataCallback::BandedDataCallback . Los métodos de transferencia de datos de la interfaz IWiaDataTransfer invocan periódicamente este método. Proporciona mensajes de estado a la aplicación durante la transferencia de datos. Al devolver S_FALSE, el programa también puede usar este método para finalizar prematuramente la transferencia de datos.

Cuando se invoca este método, el parámetro lMessage contendrá el motivo de la llamada. No todos los parámetros contendrán datos en todas las llamadas. Por ejemplo, cuando se invoca IWiaDataCallback::BandedDataCallback con un mensaje de IT_MSG_TERMINATION, no debe intentar usar los valores en los parámetros pbBuffer, lOffset y lLength .

Si el valor de lMessage es IT_MSG_DATA, el búfer al que apunta pbBuffer contiene una banda de datos de imagen. El parámetro lOffset contiene un desplazamiento en bytes desde el principio del búfer donde comienza la banda actual de datos. El parámetro lLength especificó la longitud en bytes de la banda actual de datos.

Durante las llamadas en las que lMessage se establece en IT_MSG_DATA o IT_MSG_STATUS, el parámetro lStatus contiene un valor válido. Su contenido no se debe usar cuando lMessage contiene otros valores.

Si lMessage es IT_MSG_DATA_HEADER, el parámetro pbBuffer apunta a una estructura de WIA_DATA_CALLBACK_HEADER .

Cuando se ha producido un error durante una transferencia de datos de imagen, el controlador establece lMessage en IT_MSG_DEVICE_STATUS. El objeto de devolución de llamada de proxy llama a ReportStatus, que controla el error y muestra los mensajes al usuario.

Ejemplos

En el ejemplo siguiente se muestra una manera posible de implementar el método IWiaDataCallback::BandedDataCallback .

El código de aplicación de ejemplo define el objeto CDataCallback que deriva de la interfaz IWiaDataCallback . La aplicación debe crear una instancia de un objeto CDataCallback . A continuación, llama a CDataCallback::QueryInterface para obtener un puntero de interfaz IWiaDataCallback . Cuando la aplicación está lista para recibir datos, invoca el método idtGetBandedData y pasa el método un puntero a la interfaz IWiaDataCallback .

Periódicamente, el método idtGetBandedData usa el puntero de interfaz IWiaDataCallback para invocar el método CDataCallback::BandedDataCallback de la aplicación. Las primeras invocaciones envían mensajes de estado. Estos van seguidos de una llamada que transfiere un encabezado de datos al método de devolución de llamada. Una vez que la aplicación recibe el encabezado de datos, idtGetBandedData invoca CDataCallback::BandedDataCallback para transferir datos a la aplicación. Una vez completada la transferencia de datos, llama al método de devolución de llamada una hora final para transmitir un mensaje de finalización.


//
// 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 Value
Cliente mínimo compatible Windows 2000 Professional, Windows XP [solo aplicaciones de escritorio]
Servidor mínimo compatible Windows Server 2003 [solo aplicaciones de escritorio]
Plataforma de destino Windows
Encabezado wia_xp.h (incluye Wia.h)
Library Wiaguid.lib