## Physical Device Driver Reference

[prev][next][parent][TOC]

### Character Device Monitor Process

A character device monitor can monitor only one data stream belonging to a character device driver. An application, however, can include one or more character device monitors that monitor one or more data streams belonging to one or more character device drivers. For example, an application can monitor keystrokes and mouse clicks for each OS/2 session. This application will include a character device monitor for each OS/2 session for each of the physical keyboard and mouse device drivers.

To monitor a data stream belonging to a character device driver, an application must first gain access to that data stream. An application gains access to a data stream by calling:

DosMonOpen to establish a connection to the physical device driver. DosMonOpen returns a device handle for monitors to the application. The application will use this handle to direct subsequent DosMonReg and DosMonClose calls to the physical device driver.

DosMonReg to register a monitor with a particular data stream belonging to the physical device driver. Once the monitor is installed in the monitor chain, the monitor dispatcher automatically moves data between monitors (if there is more than one in the chain) and returns filtered data to the physical device driver.

After an application has gained access to a data stream, it can remove, insert, modify, or view all characters passing through the data stream. An application intercepts data flowing through a data stream by calling:

DosMonRead to take data from the data stream and place it into a private data area where the application can freely access it for filtering.

DosMonWrite to take filtered data from the application's private data area and return it to the data stream.

When an application no longer needs to monitor data streams belonging to a single character device driver, it must relinquish access to all data streams belonging to that physical device driver, in addition to terminating its monitor threads. An application terminates a monitor by calling:

DosMonClose to close the device handle (that is, terminate the connection to the physical device driver for the monitors).

DosExit to terminate its monitor threads that are directly accessing the data streams.

Refer to the OS/2 Control Program Programming Reference for more information on the 16-bit Dosxxx functions. The following figure illustrates pseudocode for a simple character device monitor.

    --------------------------------------------------------------

          A Simple, Single-Threaded Character Device Monitor

    Get access to the device's data stream:

      CALL DosMonOpen to open the device and get a monitor handle
        for the device
      CALL DosSetPrty to set priority of the monitor thread high
      CALL DosMonReg to register a monitor for the data stream of
        the device

    WHILE monitoring the data stream:

      CALL DosMonRead to take a data record from the data stream
      Filter the data record
      CALL DosMonWrite to return the filtered data record to the
        data stream

    END WHILE

    After monitoring the data stream:

      CALL DosMonClose to terminate the monitor and close the
        monitor handle to the device
      CALL DosExit to terminate this application

    --------------------------------------------------------------