Carga y descarga de un minidriver WIA
Una vez instalado el controlador del dispositivo WIA, el servicio WIA intenta cargarlo por primera vez. Se llama al método IStiUSD::Initialize del minidriver de WIA y debe realizar las siguientes tareas:
Compruebe el modo de transferencia para determinar la intención del autor de la llamada para inicializar este controlador de dispositivo. Esto se hace llamando al método IStiDeviceControl::GetMyDeviceOpenMode .
Obtenga el nombre del puerto del dispositivo instalado para que este controlador pueda llamar a CreateFile (documentado en el Microsoft Windows SDK) en el puerto adecuado para acceder al dispositivo. Esto se hace llamando al método IStiDeviceControl::GetMyDevicePortName .
Lea la configuración del Registro específica del dispositivo escrita durante la instalación del dispositivo. Esto se puede hacer mediante el parámetro hParametersKey pasado a IStiUSD::Initialize.
El servicio WIA llama al método IStiUSD::Initialize cuando se carga por primera vez el controlador. También se llama al método IStiUSD::Initialize cuando un cliente usa los DDIS de STI heredados y llama al método IStillImage::CreateDevice .
El método IStiUSD::Initialize debe inicializar el controlador WIA y el dispositivo para su uso. Los controladores WIA pueden almacenar el puntero de interfaz IStiDeviceControl si lo necesitan más adelante. Se debe llamar al método IStiDeviceControl::AddRef antes de almacenar esta interfaz. Si no necesita almacenar la interfaz, omitala. Nolibere la interfaz IStiDeviceControl si no ha llamado primero a IStiDeviceControl::AddRef. Esto puede provocar resultados imprevisibles. La interfaz COM IStiDeviceControl es necesaria para obtener información sobre los puertos del dispositivo. El nombre del puerto usado en una llamada a la función CreateFile se puede obtener llamando al método IStiDeviceControl::GetMyDevicePortName . En el caso de los dispositivos en puertos compartidos, como los dispositivos de puerto serie, no se recomienda abrir el puerto en IStiUSD::Initialize . El puerto solo debe abrirse en llamadas a IStiUSD::LockDevice. El cierre de los puertos debe controlarse internamente para proporcionar acceso rápido. (Abrir y cerrar en IStiUSD::LockDevice e IStiUSD::UnLockDevice es muy ineficaz. CreateFile puede provocar un retraso que hace que el dispositivo aparezca lento y no responda al usuario).
Si un controlador WIA no puede admitir varias llamadas CreateFile en el mismo puerto de dispositivo, se debe llamar al método IStiDeviceControl::GetMyDeviceOpenMode .
El controlador WIA debe comprobar el valor del modo devuelto para la marca STI_DEVICE_CREATE_DATA y abrir el puerto en consecuencia.
Si se debe abrir el puerto del dispositivo, se debe usar una llamada a CreateFile . Al abrir un puerto, se debe usar la marca FILE_FLAG_OVERLAPPED. Esto permite usar la estructura SUPERPUESTA (descrita en la documentación de Windows SDK) al acceder al dispositivo. El uso de E/S superpuesta ayudará a controlar el acceso dinámico al hardware. Cuando se detecta un problema, el controlador WIA puede llamar a CancelIo (descrito en la documentación de Windows SDK) para detener todo el acceso de hardware actual.
En el ejemplo siguiente se muestra una implementación del método IStiUSD::Initialize .
STDMETHODIMP CWIADevice::Initialize(
PSTIDEVICECONTROL pIStiDeviceControl,
DWORD dwStiVersion,
HKEY hParametersKey)
{
if (!pIStiDeviceControl) {
return STIERR_INVALID_PARAM;
}
HRESULT hr = S_OK;
//
// Get the mode of the device to check why we were created. status, data, or both...
//
DWORD dwMode = 0;
hr = pIStiDeviceControl->GetMyDeviceOpenMode(&dwMode);
if(FAILED(hr)){
return hr;
}
if(dwMode & STI_DEVICE_CREATE_DATA)
{
//
// device is being opened for data
//
}
if(dwMode & STI_DEVICE_CREATE_STATUS)
{
//
// device is being opened for status
//
}
if(dwMode & STI_DEVICE_CREATE_BOTH)
{
//
// device is being opened for both data and status
//
}
//
// Get the name of the device port to be used in a call to CreateFile().
//
WCHAR szDevicePortNameW[MAX_PATH];
memset(szDevicePortNameW,0,sizeof(szDevicePortNameW));
hr = pIStiDeviceControl->GetMyDevicePortName(szDevicePortNameW,
sizeof(szDevicePortNameW)/sizeof(WCHAR));
if(FAILED(hr)) {
return hr;
}
//
// Open kernel-mode device driver. Use the FILE_FLAG_OVERLAPPED flag
// for proper cancellation
// of kernel-mode operations and asynchronous file IO.
// The CancelIo() call will function properly if this flag is used.
// It is recommended to use this flag.
//
m_hDeviceDataHandle = CreateFileW(szDevicePortNameW,
GENERIC_READ | GENERIC_WRITE, // Access mask
0, // Share mode
NULL, // SA
OPEN_EXISTING, // Create disposition
FILE_ATTRIBUTE_SYSTEM|FILE_FLAG_OVERLAPPED,
NULL );
m_dwLastOperationError = ::GetLastError();
hr = (m_hDeviceDataHandle != INVALID_HANDLE_VALUE) ?
S_OK : MAKE_HRESULT(SEVERITY_ERROR,FACILITY_WIN32,m_dwLastOperationError);
if (FAILED(hr)) {
return hr;
}
//
// Open DeviceData section to read driver specific information
//
HKEY hKey = hParametersKey;
HKEY hOpenKey = NULL;
if (RegOpenKeyEx(hKey, // handle to open key
TEXT("DeviceData"), // address of name of subkey to open
0, // options (must be NULL)
KEY_QUERY_VALUE|KEY_READ, // just want to QUERY a value
&hOpenKey // address of handle to open key
) == ERROR_SUCCESS) {
//
// This is where you read registry entries for your device.
// The DeviceData section is the proper place to put this
// information. Information about your device should
// have been written using the WIA device's .INF installation
// file.
// You can access this information from this location in the
// Registry. The WIA service owns the hParameters HKEY.
// DO NOT CLOSE THIS KEY. Always close any HKEYS opened by
// this WIA driver after you are finished.
//
//
// close registry key when finished, reading DeviceData information.
//
RegCloseKey(hOpenKey);
} else {
return E_FAIL;
}
return hr;
}
El servicio WIA llama a IStiUSD::GetCapabilities después de una llamada correcta al método IStiUSD::Initialize . A continuación, IStiUSD::GetCapabilities proporciona la estructura de STI_USD_CAPS con información de versión de STI, marcas de compatibilidad de WIA (marcas de bits que indican las funcionalidades del controlador) y cualquier requisito de evento.
En el ejemplo siguiente se muestra una implementación de IStiUSD::GetCapabilities.
/********************************************************************\
* CWIADevice::GetCapabilities
* Remarks:
* This WIA driver sets the following capability flags:
* 1. STI_GENCAP_WIA - This driver supports WIA
* 2. STI_USD_GENCAP_NATIVE_PUSHSUPPORT - This driver supports push
* buttons
* 3. STI_GENCAP_NOTIFICATIONS - This driver requires the use of
* interrupt events.
*
\********************************************************************/
STDMETHODIMP CWIADevice::GetCapabilities(PSTI_USD_CAPS pUsdCaps)
{
//
// If the caller did not pass in the correct parameters,
// then fail the call with E_INVALIDARG.
//
if (!pUsdCaps) {
return E_INVALIDARG;
}
memset(pUsdCaps, 0, sizeof(STI_USD_CAPS));
pUsdCaps->dwVersion = STI_VERSION; // STI version
pUsdCaps->dwGenericCaps = STI_GENCAP_WIA| // WIA support
STI_USD_GENCAP_NATIVE_PUSHSUPPORT| // button support
STI_GENCAP_NOTIFICATIONS; // interrupt event support
return S_OK;
}