Stream Interface Driver Implementation
Various issues can affect your design decisions as you implement a stream interface driver dynamic-link library (DLL). To implement the stream interface driver, you can create a DLL containing the required entry points for the drivers, and then regulate either single access or multiple access to a driver.
Required Entry Points for Stream Interface Drivers
For every driver that exposes the stream interface, the required entry points implement standard file I/O functions and power management functions that are used by the kernel.
You can implement a driver with only Init and Deinit entry points and no device prefix. You cannot access this driver using CreateFile. PCIBUS and RegEnum are two examples of this type of driver. These drivers are in the %_WINCEROOT%\Public\Common\OAK\Drivers\PCIbus and %_WINCEROOT%\Public\Common\OAK\Drivers\RegEnum.
If CreateFile can access the driver, it must have a prefix, such as FWR. Entry points for this driver are typically decorated with the prefix; for example, FWR_Open, FWR_Close, and so on.
However, if DEVFLAGS_NAKEDENTRIES is specified in the driver's Flags registry subkey, the entry point names can be undecorated; for example, Open, Close, and so on. The sample battery driver, which is in %_WINCEROOT%\Public\Common\OAK\Drivers\Battdrvr, is an example of a driver that uses undecorated entry points. The battery driver's registry settings must still include a prefix.
If you can access a battery driver using CreateFile, its XXX_Open and XXX_Close entry points are required. Also, at least one of the handle-based entry points must be defined. The handle-based entry points are XXX_Read, XXX_Write, XXX_Seek, and XXX_IOControl. The driver is not required for you to export unused handle-based APIs.
The XXX_PowerUp and XXX_PowerDown entry points are optional.
Your implementations of these entry points must be declared for export from your DLL by placing __declspec(dllexport) in front of your function declaration. If you are developing in C++, your entry points must also be declared extern "C" as well. The following table shows the required entry points for the stream interface.
| Function | Description |
|---|---|
| XXX_Close | Closes the device context identified by hOpenContext. |
| XXX_Deinit | Called by the Device Manager to de-initialize a device. |
| XXX_Init | Called by the Device Manager to initialize a device. |
| XXX_IOControl | Sends a command to a device. |
| XXX_Open | Opens a device for reading, writing, or both. An application indirectly invokes this function when it calls CreateFile to open special device file names. |
| XXX_PowerDown | Ends power to the device. It is useful only with devices that can be shut off under software control. |
| XXX_PowerUp | Restores power to a device. |
| XXX_Read | Reads data from the device identified by the open context. |
| XXX_Seek | Moves the data pointer in the device. |
| XXX_Write | Writes data to the device. |
Single Access and Multiple Access
Because peripheral devices are exposed to applications as special files when you create a stream interface, you provide the implementation of such a file. Therefore, consider whether it is practical, based on the capabilities of the device that your driver serves, to enable multiple applications to have simultaneous access to the special file. That is, consider whether your driver can have multiple open file handles on its device. A stream interface driver can implement either single access or multiple access by using the hOpenContext parameter passed to all file I/O functions.
To enable multiple access, each call to the XXX_Open function should return a different value for hOpenContext. The device driver must track which return values from XXX_Open are in use. Subsequent calls to XXX_Close, XXX_Read, XXX_Write, XXX_Seek, and XXX_IOControl pass these values back to the device driver, enabling the driver to identify which internal data structures to manipulate.
To enforce single access, only the first call to XXX_Open should return a valid hOpenContext value. As long as this value remains valid, which is until XXX_Close is called for the value, subsequent calls to XXX_Open should return NULL to the calling application to indicate failure.
To implement the Telephony API (TAPI) you must have serial port devices that support multiple access. OEMs who are using any of the serial port upper layer implementations from Microsoft gain this functionality automatically. OEMs who write their own serial port upper layers must implement multiple access for themselves in order to support TAPI.
See Also
Stream Interface Drivers | Stream Interface Driver Architecture | I/O Control Codes
Last updated on Tuesday, May 18, 2004
© 1992-2003 Microsoft Corporation. All rights reserved.