WDM Still Image Architecture
This paper describes the architecture and components that provide for acquisition of images from devices primarily used for capturing still pictures using scanners and digital still cameras under the Microsoft Windows 98 and Windows 2000 operating systems.
Important: Complete implementation for these operating systems is documented in the related Windows DDK. For Windows XP and Windows Me, implement WIA support as described in the current Windows DDK.
On This Page
Overview
Although current devices are scanners and digital still cameras, these devices are referred to as still image devices to distinguish them from video devices. Examples of devices that use this architecture are:
| • | Flatbed scanners including those with an automatic document feeder, transparency adapter, or other options (such as a start button). |
| • | Sheet fed scanners with paper-inserted detection mechanism. |
| • | Hand held scanners. |
| • | Digital still cameras, including those with stored images and associated data (thumbnails, audio, and so on). |
Until Microsoft incorporated a still image architecture in Windows 98, Windows operating system support for still image devices had been near non-existent. The IHV has had to provide individual, proprietary solutions for their imaging devices to accomplish integration under Windows. This paper describes the first phase of the common solution Microsoft is providing for support of still image devices. This support includes:
| • | Still image device driver interface |
| • | Class installer for Imaging devices, including installation wizard for non-Plug and Play solutions |
| • | Still image device control panel |
| • | Push-model event monitor and control center |
The scope of this paper is limited to those items intended for release in both Windows 98 and Windows 2000.
Architecture
A major design goal of this architecture is to reduce the software investment made by an IHV. It reduces the amount of work that a vendor has to do and focuses the work they do on device features, not system-related tasks. In addition, this architecture, seen below, puts as much vendor-supplied code as is possible in user mode (ring 3) to allow vendors to avoid kernel code development.
Figure 1 Still image architecture.
The following describes the components of Figure 1.
Application. Two primary types of applications use still images. One is for editing of image data, with typical applications of this type being Adobe Photoshop or Microsoft PictureIt!. The other is for authoring documents that include image data but that do not focus on editing that image data. Typical applications of this type are word processing or page layout applications, such as Microsoft Word, or a presentation application, such as Microsoft PowerPoint. These applications might be more interested in the text data resulting from an OCR interpretation of the image data rather than image data itself.
Still Image APIs. The APIs of TWAIN, ISIS, and Adobe Acquire interfaces are the common image APIs in use today. Currently, an IHV has to supply a device-specific component that implements a "driver" for each of these APIs that they support. Note: These IHV components will require a slight revision to conform to the Still Image architecture's components. The STI architecture is 32 bit.
Color Management API. This interface and implementation maintains device color profiles and provides for color space conversion. All color output from scanners must be defined. To accomplish this, a scanner will be required to either create sRGB output or embed the ICC profile for the image that was just scanned into the image file to identify the color space information for that image. For more information on the specific functionality and interfaces see the ICM 2.0 color matching specification.
Still Image Control Panel. Still image devices are managed in a manner similar to other devices -- tracked using Device Manager and accessed using control panels in Windows. The Microsoft-provided control panel (Scanning and Cameras) includes the following functionality for installed still image devices:
| • | Listing the installed still image devices. |
| • | Adding and removing non-Plug and Play still image devices. |
| • | Test validation of a selected device. |
| • | Vendor-specific configuration/control (by vendor-attached property sheets). |
| • | Control of the association between specific device events and applications to be notified of these events. This is used for "push model" support (see the following item). |
Still Image Event Monitor. This Microsoft-provided application supports push model behavior by providing the following functionality:
| • | Detects events coming from installed still image devices. |
| • | Dispatches a set of those events to the STI control center. |
Still Image Control Center. This Microsoft-provided module supports push model behavior by implementing a specific policy on how still image device events are distributed to applications. From the control panel, the user may configure which applications are invoked when device events occur.
Still Image DDI. This Microsoft-provided device driver interface is a conduit for communication with a particular device. The Still Image APIs, the Control Panel, the Event Monitor, and the Control Center all use the Still Image DDI. This DDI uses the color management system as a repository for the color profile supplied for a specific device. The DDI provides interfaces for the following functionality:
| • | Enumeration |
| • | Device information (primitive capabilities and status) |
| • | Test activation |
| • | Data and command I/O |
| • | Notification for device events, including polling for device activity |
| • | Retrieval of an ICM color profile and other ancillary information associated with a device |
User-mode Minidrivers. These vendor-written modulesare small components used to implement device-specific DDI functionality (test, status, and data I/O). They inform the DDI of the device's capabilities (requires polling for events, for example) and use the standard interfaces of CreateFile, ReadFile, WriteFile, and DeviceIoControl to communicate with a specific kernel device driver.
Still Image Kernel-mode Drivers. These Microsoft-provided modules function as a way of packaging a command or data for delivery on a specific bus type. There are not expected to be many of these, and perhaps none produced outside of Microsoft. Although the kernel drivers need not be WDM-based, any new kernel-mode drivers that Microsoft delivers will be.
Note: If a device does not conform to the standard Microsoft kernel drivers for a specific bus, the vendor will need to supply its own kernel-mode driver.
Bus Drivers. These Microsoft-provided modules are used for communication with the still image device. Examples are the USB or SCSI driver stacks, as well as the serial, IR, and parallel port drivers.
Still Image Device Driver Interface
The still image DDI is not an abstraction for imaging. It is an abstraction for dealing with devices on a variety of buses and/or devices that generate events, causing applications to be instantiated. It is very applicable to still image devices because of their use of multiple buses.
The current DDI implementation provides support for SCSI, Parallel, Serial, IR, and USB devices and the architecture is extensible so that IEEE 1394, or MFP devices can be easily incorporated.
A device vendor supplies a small, device-specific user-mode minidriver (USD) in addition to the imaging API component they are already providing (an ISIS driver or TWAIN data source, for example).
The functionality of the DDI includes:
| • | Device enumeration. |
| • | Device information (capabilities and status). |
| • | Test activation. |
| • | Data and command I/O. |
| • | Notification for device events, including polling for device activity. |
Kernel-Mode Bus Drivers
Still image kernel-mode drivers will be provided for SCSI, USB, and parallel devices under Windows 2000. Serial devices will use the existing Win32 user-mode APIs. The kernel-mode drivers are written in a way that most devices of that bus type will be able to reuse the Microsoft driver.
SCSI. SCSI devices are of either processor or scanner type. Devices that work using read/write SCSI commands are of processor type. All HP SCSI SCL scanners fall into this category. These devices can use ReadFile and WriteFile to send information to the device, and a SCSI command block will be created by the kernel-mode driver. Devices that work using SCSI commands specific to scanners are of scanner type. Many existing scanners are of this type (the Canoscan Color 600 for example). These devices use DeviceIoControl to send information to the kernel driver. This use is much like WinASPI in that the vendor code (typically the TWAIN data source) forms SCSI command information and sends it through the user-mode minidriver to the SCSI bus. The SCSI ID and logical unit number, however, are controlled by the Still Image SCSI kernel-mode driver.
USB. The USB kernel driver is rather constrained from a device communication point of view, but is very flexible from a protocol point of view. Microsoft implemented a driver for a USB device with:
| • | A single interface |
| • | A control end point |
| • | An interrupt end point |
| • | A bulk input end point |
| • | An optional bulk output end point |
Data is exchanged in a "pass through" mode; that is, no packet or message protocol is used. This driver just sends/receives sets of bytes. It is up to vendor-supplied user-mode components to implement a command set or message protocol.
Parallel. These devices include those using the ECP and EPP modes. In addition there is the ability to stack a filter driver on top of the Microsoft supplied components. This driver would be used to implement proprietary modes and messaging protocols. Example code for such a filter driver can be found in the DDK as the ParScan module. Because Microsoft is not shipping an implementation of such a driver, it must be implemented and delivered by a vendor.
Serial. These devices use the current serial port drivers included in the Microsoft operating systems.
IR. These devices use the current IR interfaces (IrComm or IrSock) included in the Microsoft operating systems.
In the future, this architecture will be able to support the following devices:
| • | IEEE 1394 still image devices |
| • | Network still image devices |
| • | Multi-function device -- that is, those devices that are both scanners and printers |
IHV-Provided User-mode Minidrivers
An IHV has the responsibility to supply the following components:
| • | User mode minidriver, which provides an implementation of the various interfaces in the DDI. |
| • | Installation information using an INF file. |
| • | Color profile for the device, in the case where the output is other than sRGB. |
In addition, the vendor can supply the following optional components:
| • | Upper-level software (TWAIN data source or ISIS driver) that uses the DDI. |
| • | Property sheets for the control panel. |
| • | A DLL used to extend the installation process for vendor-specific installation needs. |
Installation/Setup Wizard
To provide for easy and consistent installation, Microsoft provides a class installer featuring:
| • | Installation wizard for legacy devices on parallel and serial ports. |
| • | WDM Plug and Play detection when installing or using hot attach/detach operations on Plug and Play-aware buses, as well as detection on other enumerable buses (SCSI or Parallel). |
| • | Vendor extensibility (calibration or other installation specifics). |
Still Image Control Panel
The still image control panel provides the user with a common interface for still image devices. These include:
| • | Enumerate devices. Lists the installed still image devices. |
| • | Add/remove devices. Non-Plug and Play still image devices can be added or removed. |
| • | Test devices. Allows verification of still image device installation and operation. |
| • | Configure/control devices. Microsoft supplies standard property pages, which inform the user of the device status, provide the ability to test the devices, and control the push model event mechanism. Vendors can add additional property sheets for their specific needs. |
| • | Associate device events with applications. Using the control panel, the user selects a device and one of the push model events for this device. Given this device/event pair, the user selects the subset of push model aware-applications that can be used. In this way, the control panel is used to associate device events with applications. |
CenterPush Model Event Monitor and Control
The still image architecture provides a consistent model in which a still image device can initiate data transfer to an application (push model), in contrast to an application having to request data from the device (pull model). Two functional components (in a single binary -- \windows\system\stimon.exe) make this behavior possible:
| • | An event monitor to detect events coming from a device. |
| • | A control center to decide how to react to those events. |
The still image architecture components provide the following services for use by the still image control panel, control center, and applications:
| • | Maintain the event types associated with devices. These events are identified by the IHV as push events for their device. |
| • | Dispatch push events to the control center. |
| • | Maintain a list of all push model-aware applications. |
| • | Launch or notify an application on behalf of a control center and provide information to the application as to which device and event initiated the notification. |
Event Monitor
The event monitor maintains a list of active push model devices. Devices indicate in their INF file that they support push model events. The event monitor responds to the installation of new devices by responding to Plug and Play messages for attaching and detaching devices as well as those devices added or removed by using the Still Image control panel.
The event monitor opens all devices that support the push model. The open is done in status mode to allow another application to open the device in data mode (for example, a pull model use of a device). The event monitor waits for events on these devices. Currently, few devices are capable of actually generating an event directly from the device when data transfer has been initiated. In most cases, a separate thread within the Still Image DDI implementation simulates this behavior by polling the device and causing an event when the device becomes active.
When an event comes in from a device, the event monitor passes the event along to the control center.
The Control Center
The control center implementation allows the user to control the association between device events and applications that need to be notified when these events are detected. Using the control panel, the user selects a device and one of the device's push model events. Given this device/event pair, the user selects the subset of push model-aware applications that can be used.
Using this method, the user can easily associate a specific push event on a specific device for use with an OCR application and another event on the same device for use with a photo editing application. The control center uses the following simple policy:
| • | Upon receiving a device event from the event monitor, the control center obtains the subset of all registered applications selected by the user to respond to this device event (PREFERREDAPPS). The control center maintains this information. |
| • | If there are PREFERREDAPPS selected for this device/event and PREFERREDAPPS has only one item, it is launched. Otherwise, a dialog containing PREFERREDAPPS is displayed and the user selects the application to be launched. If the user does not select an application within a timeout period, the dialog is dismissed and no application is launched. |
Push Model-Aware Applications
Existing applications must be revised to make use of the STI push model behavior. Applications that are push model-aware call the RegisterLaunchInformation interface. This will add the application to the list of push model-aware applications. It is also possible to register an application at the time of the installation, but the application should register itself each time it is run in case the user relocated the application. The syntax of the entry in the application's INF file is:
;Register Application "Imaging" as a push model aware application for use with the Still Image Event Monitor HKLM"SOFTWARE\Microsoft\Windows\CurrentVersion\StillImage \Registered Applications", Imaging,, "%25%\KodakImg.Exe\StiDevice:%%1\StiEvent:%%2"
An application can detect if it was launched by way of the control center. If the GetSTILaunchInformation interface fails, then the application was not launched by way of the control center. An application, TWAIN data source, or other software can decide to reject using the device that caused the push model event. However, it must notify the user in some manner as to why the device is not acceptable. This allows the user to utilize the still image control panel to deselect this particular application for use with this device.
If an application was notified by way of the control center, the application might need additional information to locate the device using its image API. TWAIN and ISIS are the two APIs that Microsoft defines information for, but any API can use the STI mechanism for obtaining additional information. On installation, the INF file will place information into the registry that provides this supplementary information. A key/value string is used to specify this information, such as:
TwainDS="HP PictureScan 3.0" ISIS="epson.pxw"
The application then uses the GetDeviceValue interface to obtain the associated data.
After a TWAIN data source has been loaded, it can obtain the device and event by using the same GetSTILaunchInformation() API, because it is in the original address space. With this information, it can open the device and start communication providing a seamless transition from push event, application launch, and to image acquisition.
Once an application (or a TWAIN data source) has a device open, all events will be sent to this application.
When an application is uninstalled it need to call UnRegisterLaunchApplication to remove the application from the permanent list of push model-aware applications. Only an application can register and unregister itself; the user cannot add or remove an application from the control panel. The user can only select or unselect those applications to be associated with particular devices.
Example code:
// call STI to find out whether this was launched by STI
HRESULT hres;
hres = StiCreateInstance(GetModuleHandle(NULL), STI_VERSION, &pSti,NULL);
hres = pSti->RegisterLaunchApplication(L"MyApp",szModulePathW) ;
// was this a STI launch???
// call STI-API and get the device name, event and event code
WCHAR szDeviceName[65];
WCHAR szEventName[65];
char ActualDeviceName [256];
DWORD dwEventCode;
hres = pSti->GetSTILaunchInformation(szDeviceName,&dwEventCode,szEventName);
if (SUCCEEDED(hres)) {
DWORD val = 256, type;
pSti->GetDeviceValue(szDeviceName, STI_DEVICE_VALUE_TWAIN_NAME, &type,
(unsigned char*)&ActualDeviceName[0], &val);}
When a device is open in data mode (by using Sti->CreateDevice()), no push model events are interpreted by the STI event monitor. These events are also not passed along to the application that has the device open. If a button used to launch an application is also used to stop an application, these are two separate events. It is up to the USD to provide for this virtual event mechanism. Notice that the interface to implement the virtual events is not available in this release. In general, when applications or TWAIN data sources are done obtaining an image from a device it should release the device so the STI monitor can return to responding to launch events.
If an application has already been launched via STI and there is no current open data mode for the device, upon a subsequent event the application may again be launched. It is up to the application to decide if multiple instances of the application are to be allowed. If not (the preferred operation), the application must detect that it is a second instance and revector the GetSTILaunchInformation to the original instance.
When a device arrival or device removal notice is detected by the STI monitor, it is rebroadcast with specific information as to which device was added or removed from the still image collection of devices. Notice that specific formats for these messages will be documented in a future version of this document.
On installation, the IHV can associate an application to be associated with each event from a device. By default all events are marked with a wildcard indicating that all registered applications are to be associated with this event.
API Overview
The Still Image APIs use COM style interfaces. There are four COM interfaces involved when dealing with still image devices. In addition, access to the kernel components is accomplished using the standard file APIs. The following picture illustrates the relationship between interfaces and functional components.
Figure 2 Interfaces for Scanners and Cameras.A detailed reference will be provided in the latest version of the Windows 2000 Device Driver Kit.
In order to use these interfaces, the still image subsystem's primary interface (IStillImage) has to be located. This is done by using a call to StiCreateInstance. This obtains a pointer to the IStillImage interface.
IStillImage
This interface is used to deal with the global subsystem for still image and is used by both IHVs and ISVs. These APIs do not require the user to have any device open. The APIs for this interface are:
| • | Initialize. Initializes STI. |
| • | GetDeviceList. Obtain an array of structures that describe all of the installed scanners and cameras. |
| • | GetDeviceInfo. Obtain an information structure about a particular device by the name of the device. |
| • | CreateDevice. Obtain an interface pointer to a device by supplying a device name. |
| • | GetDeviceValue. Obtain data that has been associated with a device by supplying a device name and a value name. |
| • | SetDeviceData. Associate data with a device by supplying a device name, a value name and the value type and data. |
| • | GetSTILaunchInformation. Obtain information regarding which device and what event from that device caused an application to be notified during push model operation. |
| • | RegisterLaunchApplication. Used by an application to tell the still image subsystem that it knows how to interpret push model information. |
| • | UnRegisterLaunchApplication. Used by an application to tell the still image subsystem that it no longer wishes to be used in push mode. |
| • | EnableHwNotifications. Used to turn event processing (and thus polling) on and off. |
IStiDevice
This interface is used by the IHV when using an imaging API such as TWAIN or ISIS to use the device. In this context, the IHV is a client of the device. For example, a TWAIN data source complies with the TWAIN API on its top edge and uses this interface on its bottom edge. This interface uses the upper edge of the still image DDI. In addition, this interface is used by the Still Image control panel and the event monitor. The APIs for this interface are:
| • | GetStatus. Obtains the current status of the device. This includes bit indicators that the device is operational, in an error state, and has events pending. |
| • | DeviceReset. Puts the device into a known state. |
| • | Diagnostic. Runs a set of diagnostics that the IHV has determined appropriate for the device. |
| • | GetLastErrorInfo. Obtains the last known error on the device. |
| • | GetLastNotificationData. Returns data related to last known event. |
| • | LockDevice. Prepares device for access. Any access (or group of access calls) to a device should be preceeded with a call to LockDevice. Several devices are sensitive to access by multiple clients. This call effectively reserves the device for single use. Serial devices actually obtain the port during LockStatus. Access to the device without a lock in place is not guaranteed to produce reliable results. |
| • | Subscribe/Unsubscribe. Mechanism for redirecting particular events to an application or TWAIN data source. |
| • | UnlockDevice. Releases the device for access by other clients. |
The following APIs are dependent on the vendor's implementation. They all involve getting commands and data to the device. Not all devices require all interfaces to be functional, but they all must be supplied with an implementation. Those that are not functional must return an error.
| • | Escape. A multi-parameter API to request a service of the device. The implementation of this call will vary between vendors. It can be used for data, command, or not at all. |
| • | RawReadData. Obtains data from the device. |
| • | RawWriteData. Sends data to the device. |
| • | RawReadCcommand. Obtains command information from the device. |
| • | RawWriteCommand. Sends command information to the device. |
IStiUSD
This interface is used by the still image DDI to communicate with a particular device. In this case, the device is a client of the still image DDI. Most of the APIs here in the interface have the same name as those in IStiDevice. This is because the IHV has the responsibility to implement that functionality for their specific device. This is how the IHV integrates their user-mode minidriver device into the Still Image architecture. There four additional routines (Subscribe/Unsubscribe are not implemented in IStiUSD):
| • | GetCapabiliies. Returns capablities of device, such as "event capable." |
| • | GetNotificationData. Returns data related to last event. |
| • | Initialize. Puts USD (user mode minidriver) into a known state. |
| • | SetNotificationHandle. Sets handle for asynchronous event. |
IStiDeviceControl
This interface is used by the IHV to obtain low-level services from the still image DDI. It sits on the bottom edge of the still image DDI.
| • | GetMyDevicePortName. Obtains the name of the device entry used by CreateFile to open the device. |
| • | GetMyDeviceOpenMode. Obtains the mode (DATA, STATUS) that was requested when the device was opened. |
In addition to these interfaces, there are semantics attached to the use of the standard file calls (ReadFile, WriteFile, DeviceIoControl) for each of the Microsoft-supplied kernel components. These are described in the DDK documentation.