Stream Interface Driver Implementation (Windows Embedded CE 6.0)

1/6/2010

Various issues can affect your design decisions as you implement a stream interface driver dynamic-link library (DLL). To implement the stream interface driver, create a DLL containing the required entry points for the drivers, and then decide whether you want to enforce either single or multiple access to the driver.

Services in Services.exe behave similarly to drivers that the Device Manager manages.

Stream Interface Driver Entry Points

Here and elsewhere, XXX refers to a three character prefix you choose for your device driver. When implementing a stream interface driver replace XXX with a prefix appropriate for your specific implementation.

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 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 still must include a prefix.

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.

For more information about the stream interface, see Stream Interface Driver Functions.

Single Access and Multiple Access

Because peripheral devices are exposed to applications as 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 exposes, to enable multiple applications to have simultaneous access to the file that represents the device. 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 (Device Manager) 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 (Device Manager), XXX_Read (Device Manager), XXX_Write (Device Manager), XXX_Seek (Device Manager), and XXX_IOControl (Device Manager) 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

Concepts

Stream Interface Driver Development Concepts
I/O Control Codes