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

Fournit des notifications de transfert de données status. Les méthodes de transfert de données WIA (Windows Image Acquisition) de l’interface IWiaDataTransfer appellent régulièrement cette méthode.

Syntaxe

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

Paramètres

[in] lMessage

Type : LONG

Spécifie une constante qui indique la raison du rappel. Peut avoir l’une des valeurs suivantes :

IT_MSG_DATA

Le système WIA transfère des données à l’application.

IT_MSG_DATA_HEADER

L’application reçoit un en-tête avant de recevoir les données réelles.

IT_MSG_DEVICE_STATUS

Windows Vista ou version ultérieure. L’état de l’appareil a changé.

IT_MSG_FILE_PREVIEW_DATA

Le système WIA transfère les données d’aperçu à l’application.

IT_MSG_FILE_PREVIEW_DATA_HEADER

L’application reçoit un en-tête avant de recevoir les données d’aperçu réelles.

IT_MSG_NEW_PAGE

Le transfert de données commence une nouvelle page.

IT_MSG_STATUS

Cet appel du rappel envoie uniquement des informations status.

IT_MSG_TERMINATION

Le transfert de données est terminé.

[in] lStatus

Type : LONG

Spécifie une constante qui indique la status de l’appareil WIA. Peut être défini sur une combinaison des éléments suivants :

IT_STATUS_TRANSFER_FROM_DEVICE

Les données sont en cours de transfert à partir de l’appareil WIA.

IT_STATUS_PROCESSING_DATA

Les données sont en cours de traitement.

IT_STATUS_TRANSFER_TO_CLIENT

Les données sont en cours de transfert vers la mémoire tampon de données du client.

[in] lPercentComplete

Type : LONG

Spécifie le pourcentage de données totales qui ont été transférées jusqu’à présent.

[in] lOffset

Type : LONG

Spécifie un décalage, en octets, à partir du début de la mémoire tampon où commence la bande de données actuelle.

[in] lLength

Type : LONG

Spécifie la longueur, en octets, de la bande de données actuelle.

[in] lReserved

Type : LONG

Réservé à une utilisation interne par le système d’exécution WIA.

[in] lResLength

Type : LONG

Réservé à une utilisation interne par le système d’exécution WIA.

[in] pbBuffer

Type : BYTE*

Pointeur vers le tampon de données.

Valeur retournée

Type : HRESULT

Si la méthode réussit, la méthode retourne S_OK. Pour annuler le transfert de données, il retourne S_FALSE. Si la méthode échoue, elle retourne un code d’erreur COM standard.

Remarques

Votre application doit fournir la méthode IWiaDataCallback ::BandedDataCallback . Cette méthode est régulièrement appelée par les méthodes de transfert de données de l’interface IWiaDataTransfer . Il fournit status messages à l’application pendant le transfert de données. En retournant S_FALSE, votre programme peut également utiliser cette méthode pour arrêter prématurément le transfert de données.

Lorsque cette méthode est appelée, le paramètre lMessage contient la raison de l’appel. Tous les paramètres ne contiennent pas de données sur tous les appels. Par exemple, lorsque IWiaDataCallback ::BandedDataCallback est appelé avec un message de IT_MSG_TERMINATION, il ne doit pas tenter d’utiliser les valeurs dans les paramètres pbBuffer, lOffset et lLength .

Si la valeur de lMessage est IT_MSG_DATA, la mémoire tampon pointée par pbBuffer contient une bande de données d’image. Le paramètre lOffset contient un décalage en octets par rapport au début de la mémoire tampon où commence la bande de données actuelle. Le paramètre lLength a spécifié la longueur en octets de la bande de données actuelle.

Pendant les appels où lMessage est défini sur IT_MSG_DATA ou IT_MSG_STATUS, le paramètre lStatus contient une valeur valide. Son contenu ne doit pas être utilisé lorsque lMessage contient d’autres valeurs.

Si lMessage est IT_MSG_DATA_HEADER, le paramètre pbBuffer pointe vers une structure WIA_DATA_CALLBACK_HEADER .

Lorsqu’une erreur s’est produite lors d’un transfert de données d’image, le pilote définit lMessage sur IT_MSG_DEVICE_STATUS. L’objet de rappel proxy appelle ReportStatus, qui gère l’erreur et affiche les messages à l’utilisateur.

Exemples

L’exemple suivant montre une façon possible d’implémenter la méthode IWiaDataCallback ::BandedDataCallback .

L’exemple de code d’application définit l’objet CDataCallback qu’il dérive de l’interface IWiaDataCallback . L’application doit instancier un objet CDataCallback . Il appelle ensuite CDataCallback ::QueryInterface pour obtenir un pointeur d’interface IWiaDataCallback . Lorsque l’application est prête à recevoir des données, elle appelle la méthode idtGetBandedData et transmet à la méthode un pointeur vers l’interface IWiaDataCallback .

Régulièrement, la méthode idtGetBandedData utilise le pointeur d’interface IWiaDataCallback pour appeler la méthode CDataCallback ::BandedDataCallback de l’application. Les premiers appels envoient des messages status. Ils sont suivis d’un appel qui transfère un en-tête de données à la méthode de rappel. Une fois que l’application a reçu l’en-tête de données, idtGetBandedData appelle CDataCallback ::BandedDataCallback pour transférer des données vers l’application. Une fois le transfert de données terminé, il appelle la méthode de rappel une dernière fois pour transmettre un message d’arrêt.

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

Configuration requise