Metode IWiaDataCallback::BandedDataCallback (wia_xp.h)
Menyediakan pemberitahuan status transfer data. Metode transfer data Windows Image Acquisition (WIA) dari antarmuka IWiaDataTransfer secara berkala memanggil metode ini.
Sintaks
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
Jenis: LONG
Menentukan konstanta yang menunjukkan alasan panggilan balik. Dapat berupa salah satu dari nilai berikut:
IT_MSG_DATA
Sistem WIA mentransfer data ke aplikasi.
IT_MSG_DATA_HEADER
Aplikasi menerima header sebelum menerima data aktual.
IT_MSG_DEVICE_STATUS
Windows Vista atau yang lebih baru. Status pada perangkat telah berubah.
IT_MSG_FILE_PREVIEW_DATA
Sistem WIA mentransfer data pratinjau ke aplikasi.
IT_MSG_FILE_PREVIEW_DATA_HEADER
Aplikasi menerima header sebelum menerima data pratinjau aktual.
IT_MSG_NEW_PAGE
Transfer data memulai halaman baru.
IT_MSG_STATUS
Pemanggilan panggilan balik ini hanya mengirim informasi status.
IT_MSG_TERMINATION
Transfer data selesai.
[in] lStatus
Jenis: LONG
Menentukan konstanta yang menunjukkan status perangkat WIA. Dapat diatur ke kombinasi dari berikut ini:
IT_STATUS_TRANSFER_FROM_DEVICE
Data saat ini sedang ditransfer dari perangkat WIA.
IT_STATUS_PROCESSING_DATA
Data saat ini sedang diproses.
IT_STATUS_TRANSFER_TO_CLIENT
Data saat ini sedang ditransfer ke buffer data klien.
[in] lPercentComplete
Jenis: LONG
Menentukan persentase total data yang telah ditransfer sejauh ini.
[in] lOffset
Jenis: LONG
Menentukan offset, dalam byte, dari awal buffer tempat pita data saat ini dimulai.
[in] lLength
Jenis: LONG
Menentukan panjang, dalam byte, dari pita data saat ini.
[in] lReserved
Jenis: LONG
Dicadangkan untuk penggunaan internal oleh sistem run-time WIA.
[in] lResLength
Jenis: LONG
Dicadangkan untuk penggunaan internal oleh sistem run-time WIA.
[in] pbBuffer
Jenis: BYTE*
Arahkan ke buffer data.
Nilai kembali
Jenis: HRESULT
Jika metode berhasil, metode akan mengembalikan S_OK. Untuk membatalkan transfer data, transfer data mengembalikan S_FALSE. Jika metode gagal, metode mengembalikan kode kesalahan COM standar.
Keterangan
Aplikasi Anda harus menyediakan metode IWiaDataCallback::BandedDataCallback . Metode ini secara berkala dipanggil oleh metode transfer data antarmuka IWiaDataTransfer . Ini menyediakan pesan status ke aplikasi selama transfer data. Dengan mengembalikan S_FALSE, program Anda juga dapat menggunakan metode ini untuk menghentikan transfer data secara prematur.
Ketika metode ini dipanggil, parameter lMessage akan berisi alasan panggilan. Tidak semua parameter akan berisi data pada semua panggilan. Misalnya, ketika IWiaDataCallback::BandedDataCallback dipanggil dengan pesan IT_MSG_TERMINATION, IWiaDataCallback tidak boleh mencoba menggunakan nilai dalam parameter pbBuffer, lOffset, dan lLength .
Jika nilai lMessage IT_MSG_DATA, buffer yang diarahkan oleh pbBuffer berisi sekumpulan data gambar. Parameter lOffset berisi offset dalam byte dari awal buffer tempat pita data saat ini dimulai. Parameter lLength menentukan panjang dalam byte pita data saat ini.
Selama panggilan di mana lMessage diatur ke IT_MSG_DATA atau IT_MSG_STATUS, parameter lStatus berisi nilai yang valid. Isinya tidak boleh digunakan ketika lMessage berisi nilai lain.
Jika lMessage IT_MSG_DATA_HEADER, parameter pbBuffer menunjuk ke struktur WIA_DATA_CALLBACK_HEADER .
Ketika terjadi kesalahan selama transfer data gambar, driver mengatur lMessage ke IT_MSG_DEVICE_STATUS. Objek panggilan balik proksi memanggil ReportStatus, yang menangani kesalahan dan menampilkan pesan kepada pengguna.
Contoh
Contoh berikut menunjukkan salah satu cara yang mungkin untuk mengimplementasikan metode IWiaDataCallback::BandedDataCallback .
Contoh kode aplikasi mendefinisikan objek CDataCallback yang berasal dari antarmuka IWiaDataCallback . Aplikasi harus membuat instans objek CDataCallback . Kemudian memanggil CDataCallback::QueryInterface untuk mendapatkan penunjuk antarmuka IWiaDataCallback . Ketika aplikasi siap menerima data, aplikasi memanggil metode idtGetBandedData dan meneruskan metode penunjuk ke antarmuka IWiaDataCallback .
Secara berkala, metode idtGetBandedData menggunakan penunjuk antarmuka IWiaDataCallback untuk memanggil metode CDataCallback::BandedDataCallback aplikasi. Pemanggilan pertama mengirim pesan status. Ini diikuti dengan panggilan yang mentransfer header data ke metode panggilan balik. Setelah aplikasi menerima header data, idtGetBandedData memanggil CDataCallback::BandedDataCallback untuk mentransfer data ke aplikasi. Ketika transfer data selesai, transfer data memanggil metode panggilan balik sebagai waktu terakhir untuk mengirimkan pesan penghentian.
//
// 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;
}
};
Persyaratan
| Persyaratan | Nilai |
|---|---|
| Klien minimum yang didukung | Windows 2000 Professional, Windows XP [hanya aplikasi desktop] |
| Server minimum yang didukung | Windows Server 2003 [hanya aplikasi desktop] |
| Target Platform | Windows |
| Header | wia_xp.h (termasuk Wia.h) |
| Pustaka | Wiaguid.lib |
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk