Partager via

USB Serial Host Driver Application Programming Interface (Windows Embedded CE 6.0)

  • Article

1/6/2010

While programming applications that use the USB serial host driver, you may need to consult Help in an application development environment or driver development kit for a Windows-based desktop platform.

The following list shows details of the programming interface for the USB serial host driver:

  • It exposes a re-entrant file I/O interface to desktop applications. In a desktop application, when opening a handle to a USB function client device through the USB serial host driver, wceusbsh00x represents the xth instance of a USB function client device. For example, to open a handle to the first instance of a USB function client device, use "\\.\wceusbsh001" as the first parameter to CreateFile. For more information about using CreateFile in a desktop application, see Help in an application development environment for a Windows-based desktop platform.
  • It supports multiple USB function client devices. For example, use "\\.\wceusbsh002" as the first parameter to CreateFile to open a handle to the second instance of a USB function client device, use "\\.\wceusbsh003" to open a handle to the third instance of a USB function client device, and so on. For more information about using CreateFile in a desktop application, see Help in an application development environment for a Windows-based desktop platform.
  • It exposes a serial interface to desktop applications. The serial interface consists of IOCTLs that you can call with DeviceIoControl. The following list shows the IOCTLs that the USB serial host driver implements:
    • IOCTL_SERIAL_CLR_DTR
    • IOCTL_SERIAL_CLR_RTS
    • IOCTL_SERIAL_CONFIG_SIZE
    • IOCTL_SERIAL_GET_BAUD_RATE
    • IOCTL_SERIAL_GET_CHARS
    • IOCTL_SERIAL_GET_COMMSTATUS
    • IOCTL_SERIAL_GET_DTRRTS
    • IOCTL_SERIAL_GET_HANDFLOW
    • IOCTL_SERIAL_GET_LINE_CONTROL
    • IOCTL_SERIAL_GET_MODEMSTATUS
    • IOCTL_SERIAL_GET_PROPERTIES
    • IOCTL_SERIAL_GET_TIMEOUTS
    • IOCTL_SERIAL_GET_WAIT_MASK
    • IOCTL_SERIAL_IMMEDIATE_CHAR
    • IOCTL_SERIAL_PURGE
    • IOCTL_SERIAL_RESET_DEVICE
    • IOCTL_SERIAL_SET_BAUD_RATE
    • IOCTL_SERIAL_SET_CHARS
    • IOCTL_SERIAL_SET_DTR
    • IOCTL_SERIAL_SET_HANDFLOW
    • IOCTL_SERIAL_SET_LINE_CONTROL
    • IOCTL_SERIAL_SET_QUEUE_SIZE
    • IOCTL_SERIAL_SET_RTS
    • IOCTL_SERIAL_SET_TIMEOUTS
    • IOCTL_SERIAL_SET_WAIT_MASK
    • IOCTL_SERIAL_WAIT_ON_MASK
      In a driver development kit for a Windows-based desktop platform, Ntddser.h defines these IOCTLs. For more information about DeviceIoControl with these IOCTLs, see Help in an application development environment for a Windows-based desktop platform.
  • It uses a Windows-based desktop platform USB client driver interface to communicate with the USB function client device. For information about the Windows-based desktop platform USB client driver interface, see Help in a driver development kit for a Windows-based desktop platform.
  • It registers a Plug and Play identifier with the Windows-based desktop operating system so that user mode and kernel mode modules can receive Plug and Play notifications when the USB serial host driver becomes available or unavailable. The Plug and Play identifier for the USB serial host driver is {25dbce51-6c8f-4a72-8a6d-b54c2b4fc835}. For information about using Plug and Play identifiers, see Help in an application development environment or a driver development kit for a Windows-based desktop platform.

Application Programming Interface Considerations

The following list shows details to consider while using the USB serial host driver:

  • It does not automatically free open USB function client driver handles that remain open after removing a USB function client device. If an application does not free the handle when the user removes a USB function client device, the application retains an open handle to the USB function client device. Then, if the user attaches the USB function client device, the USB serial host driver creates another instance of the USB function client device. To prevent the USB serial host driver from creating an unneeded handle, monitor Plug and Play events in the application, and when a removal event for a USB function client device occurs, free the handle.
  • It does not support device power states such as remote wake. To support device power states, the USB function client device must support them. The USB function client driver receives power-up and power-down notifications each time the target device powers on or powers off, but to the desktop software, these notifications simulate unplugging or plugging in the target device.
  • It does not support write requests of blocks larger than 128 KB. The USB serial host driver rejects write requests of blocks larger than 128 KB. Before the application requests that the driver write a block that is larger than 128 KB, the application should break up the block.
  • It does not send a zero-length packet to indicate the end of a transaction for write requests that are multiples of wMaxPacketSize in the endpoint. This affects USB host to USB host data flow, not USB host to USB function client data flow. The desktop application should account for this by sending an additional zero-length packet write with WriteFile. For information about using WriteFile in a desktop application, see Help in an application development environment for a Windows-based desktop platform.

See Also

Concepts

USB Serial Host Driver Development Concepts

Other Resources

Serial Port Drivers
USB Function Drivers