IWiaDataCallback::BandedDataCallback-Methode (wia_xp.h)

Stellt Datenübertragung status Benachrichtigungen bereit. Windows Image Acquisition (WIA)-Datenübertragungsmethoden der IWiaDataTransfer-Schnittstelle rufen diese Methode regelmäßig auf.

Syntax

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

Parameter

[in] lMessage

Typ: LONG

Gibt eine Konstante an, die den Grund für den Rückruf angibt. Folgenden Werte sind möglich:

IT_MSG_DATA

Das WIA-System überträgt Daten an die Anwendung.

IT_MSG_DATA_HEADER

Die Anwendung empfängt vor dem Empfang der tatsächlichen Daten einen Header.

IT_MSG_DEVICE_STATUS

Windows Vista oder höher. Der Status auf dem Gerät wurde geändert.

IT_MSG_FILE_PREVIEW_DATA

Das WIA-System überträgt Vorschaudaten an die Anwendung.

IT_MSG_FILE_PREVIEW_DATA_HEADER

Die Anwendung empfängt einen Header, bevor die tatsächlichen Vorschaudaten empfangen werden.

IT_MSG_NEW_PAGE

Die Datenübertragung beginnt eine neue Seite.

IT_MSG_STATUS

Dieser Aufruf des Rückrufs sendet nur status Informationen.

IT_MSG_TERMINATION

Die Datenübertragung ist abgeschlossen.

[in] lStatus

Typ: LONG

Gibt eine Konstante an, die die status des WIA-Geräts angibt. Kann auf eine Kombination aus folgendem festgelegt werden:

IT_STATUS_TRANSFER_FROM_DEVICE

Derzeit werden Daten vom WIA-Gerät übertragen.

IT_STATUS_PROCESSING_DATA

Die Daten werden derzeit verarbeitet.

IT_STATUS_TRANSFER_TO_CLIENT

Daten werden derzeit in den Datenpuffer des Clients übertragen.

[in] lPercentComplete

Typ: LONG

Gibt den Prozentsatz der bisher übertragenen Gesamtdaten an.

[in] lOffset

Typ: LONG

Gibt einen Offset in Bytes vom Anfang des Puffers an, an dem das aktuelle Datenband beginnt.

[in] lLength

Typ: LONG

Gibt die Länge des aktuellen Datenbands in Bytes an.

[in] lReserved

Typ: LONG

Reserviert für die interne Verwendung durch das WIA-Laufzeitsystem.

[in] lResLength

Typ: LONG

Reserviert für die interne Verwendung durch das WIA-Laufzeitsystem.

[in] pbBuffer

Typ: BYTE*

Zeiger auf den Datenpuffer.

Rückgabewert

Typ: HRESULT

Wenn die Methode erfolgreich ist, gibt die Methode S_OK zurück. Um die Datenübertragung abzubrechen, wird S_FALSE zurückgegeben. Wenn die Methode fehlschlägt, wird ein COM-Standardfehlercode zurückgegeben.

Hinweise

Ihre Anwendung muss die IWiaDataCallback::BandedDataCallback-Methode bereitstellen. Diese Methode wird regelmäßig von den Datenübertragungsmethoden der IWiaDataTransfer-Schnittstelle aufgerufen. Es stellt status Nachrichten an die Anwendung während der Datenübertragung bereit. Wenn Sie S_FALSE zurückgeben, kann Ihr Programm diese Methode auch verwenden, um die Datenübertragung vorzeitig zu beenden.

Wenn diese Methode aufgerufen wird, enthält der lMessage-Parameter den Grund für den Aufruf. Nicht alle Parameter enthalten Daten zu allen Aufrufen. Wenn beispielsweise IWiaDataCallback::BandedDataCallback mit einer Meldung von IT_MSG_TERMINATION aufgerufen wird, sollte nicht versucht werden, die Werte in den Parametern pbBuffer, lOffset und lLength zu verwenden.

Wenn der Wert von lMessage IT_MSG_DATA ist, enthält der Puffer, auf den pbBuffer verweist, ein Band von Bilddaten. Der lOffset-Parameter enthält einen Offset in Bytes vom Anfang des Puffers, an dem das aktuelle Datenband beginnt. Der lLength-Parameter hat die Länge des aktuellen Datenbands in Bytes angegeben.

Bei Aufrufen, bei denen lMessage auf IT_MSG_DATA oder IT_MSG_STATUS festgelegt ist, enthält der lStatus-Parameter einen gültigen Wert. Der Inhalt sollte nicht verwendet werden, wenn lMessage andere Werte enthält.

Wenn lMessage IT_MSG_DATA_HEADER ist, zeigt der pbBuffer-Parameter auf eine WIA_DATA_CALLBACK_HEADER-Struktur .

Wenn während einer Bilddatenübertragung ein Fehler aufgetreten ist, legt der Treiber lMessage auf IT_MSG_DEVICE_STATUS fest. Das Proxyrückrufobjekt ruft ReportStatus auf, das den Fehler behandelt und dem Benutzer Meldungen anzeigt.

Beispiele

Das folgende Beispiel zeigt eine mögliche Möglichkeit zum Implementieren der IWiaDataCallback::BandedDataCallback-Methode .

Der Beispielanwendungscode definiert das CDataCallback-Objekt , das von der IWiaDataCallback-Schnittstelle abgeleitet wird. Die Anwendung muss ein CDataCallback-Objekt instanziieren. Anschließend wird CDataCallback::QueryInterface aufgerufen, um einen IWiaDataCallback-Schnittstellenzeiger abzurufen. Wenn die Anwendung zum Empfangen von Daten bereit ist, ruft sie die idtGetBandedData-Methode auf und übergibt der Methode einen Zeiger an die IWiaDataCallback-Schnittstelle .

In regelmäßigen Abständen verwendet die idtGetBandedData-Methode den IWiaDataCallback-Schnittstellenzeiger , um die CDataCallback::BandedDataCallback-Methode der Anwendung aufzurufen. Die ersten Aufrufe senden status Nachrichten. Darauf folgt ein Aufruf, der einen Datenheader an die Rückrufmethode überträgt. Nachdem die Anwendung den Datenheader empfangen hat, ruft idtGetBandedDataCDataCallback::BandedDataCallback auf, um Daten an die Anwendung zu übertragen. Wenn die Datenübertragung abgeschlossen ist, ruft sie die Rückrufmethode ein letztes Mal auf, um eine Beendigungsnachricht zu übertragen.

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

Anforderungen