IWiaDataCallback：：BandedDataCallback 方法 (wia_xp.h)
提供数据传输状态通知。 Windows 映像获取 (WIA) IWiaDataTransfer 接口的数据传输方法定期调用此方法。
语法
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
);
参数
[in] lMessage
类型： LONG
指定一个常量，该常量指示回调的原因。 可以是以下其中一个值：
IT_MSG_DATA
WIA 系统正在将数据传输到应用程序。
IT_MSG_DATA_HEADER
应用程序在接收实际数据之前接收标头。
IT_MSG_DEVICE_STATUS
Windows Vista 或更高版本。 设备的状态已更改。
IT_MSG_FILE_PREVIEW_DATA
WIA 系统正在向应用程序传输预览数据。
IT_MSG_FILE_PREVIEW_DATA_HEADER
应用程序在接收实际预览数据之前接收标头。
IT_MSG_NEW_PAGE
数据传输将开始一个新页面。
IT_MSG_STATUS
回调的此调用仅发送状态信息。
IT_MSG_TERMINATION
数据传输已完成。
[in] lStatus
类型： LONG
指定指示 WIA 设备状态的常量。 可以设置为以下组合：
IT_STATUS_TRANSFER_FROM_DEVICE
数据当前正在从 WIA 设备传输。
IT_STATUS_PROCESSING_DATA
数据当前正在处理中。
IT_STATUS_TRANSFER_TO_CLIENT
数据当前正在传输到客户端的数据缓冲区。
[in] lPercentComplete
类型： LONG
指定到目前为止已传输的总数据的百分比。
[in] lOffset
类型： LONG
指定从当前数据带开始的缓冲区开头的偏移量（以字节为单位）。
[in] lLength
类型： LONG
指定当前数据带的长度（以字节为单位）。
[in] lReserved
类型： LONG
保留供 WIA 运行时系统内部使用。
[in] lResLength
类型： LONG
保留供 WIA 运行时系统内部使用。
[in] pbBuffer
类型： BYTE*
指向数据缓冲区的指针。
返回值
类型： HRESULT
如果方法成功，该方法将返回S_OK。 若要取消数据传输，它将返回S_FALSE。 如果方法失败，则返回标准 COM 错误代码。
注解
应用程序必须提供 IWiaDataCallback：：BandedDataCallback 方法。 此方法由 IWiaDataTransfer 接口的数据传输方法定期调用。 它在数据传输期间向应用程序提供状态消息。 通过返回S_FALSE，程序还可以使用此方法提前终止数据传输。
调用此方法时， lMessage 参数将包含调用的原因。 并非所有参数都将包含所有调用的数据。 例如，当使用 IT_MSG_TERMINATION 消息调用 IWiaDataCallback：：BandedDataCallback 时，不应尝试使用 pbBuffer、 lOffset 和 lLength 参数中的值。
如果 lMessage 的值IT_MSG_DATA，则 pbBuffer 指向的缓冲区包含一个图像数据带。 lOffset 参数包含与当前数据带开始的缓冲区开头的偏移量（以字节为单位）。 lLength 参数指定当前数据带的长度（以字节为单位）。
在 lMessage 设置为 IT_MSG_DATA 或 IT_MSG_STATUS 的调用期间， lStatus 参数包含有效值。 当 lMessage 包含其他值时，不应使用其内容。
如果 IT_MSG_DATA_HEADER lMessage ，则 pbBuffer 参数指向 WIA_DATA_CALLBACK_HEADER 结构。
在映像数据传输过程中发生错误时，驱动程序会将 lMessage 设置为 IT_MSG_DEVICE_STATUS。 代理回调对象调用 ReportStatus，它处理错误并向用户显示消息。
示例
以下示例演示实现 IWiaDataCallback：：BandedDataCallback 方法的一种可能方法。
示例应用程序代码定义从 IWiaDataCallback 接口派生的 CDataCallback 对象。 应用程序必须实例化 CDataCallback 对象。 然后，它调用 CDataCallback：：QueryInterface 以获取 IWiaDataCallback 接口指针。 当应用程序准备好接收数据时，它会调用 idtGetBandedData 方法，并将方法传递指向 IWiaDataCallback 接口的指针。
idtGetBandedData 方法定期使用 IWiaDataCallback 接口指针调用应用程序的 CDataCallback：：BandedDataCallback 方法。 第一个调用发送状态消息。 之后是一个调用，用于将数据标头传输到回调方法。 应用程序收到数据标头后， idtGetBandedData 调用 CDataCallback：：BandedDataCallback 将数据传输到应用程序。 数据传输完成后，它会调用回调方法作为传输终止消息的最后时间。
//
// 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;
}
};
要求
| 要求 | 值 |
|---|---|
| 最低受支持的客户端 | Windows 2000 专业版、Windows XP [仅限桌面应用] |
| 最低受支持的服务器 | Windows Server 2003 [仅限桌面应用] |
| 目标平台 | Windows |
| 标头 | wia_xp.h (包括 Wia.h) |
| Library | Wiaguid.lib |