## Physical Device Driver Reference

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

### MonitorCreate

As previously stated in the introduction to this chapter, individual physical device drivers determine how their data streams are defined. For example, the physical keyboard and mouse device drivers define data streams for each OS/2 session. The physical parallel port device drivers define data streams for each printer device. Each data stream can be monitored by a chain of one or more monitors. However, before monitor registration can occur, the physical device driver must create a monitor chain for its data stream by calling the DevHlp_MonitorCreate.

MonitorCreate can be called at task time or at INIT time. The physical device driver can call MonitorCreate anytime prior to registering a monitor when:

The physical device driver is installed. The physical device driver developer might prefer to create all monitor chains for each data stream during initialization of the physical device driver. For example, a character device driver can create monitor chains for each OS/2 session during initialization. Because each monitor chain requires additional system resources, creating them at install time can be a resource-expensive choice when monitors might not likely be registered on the monitor chains. In most cases, monitor chains should not be created at install time.

The physical device driver receives a monitor open request.

The physical device driver receives a monitor register request (when no monitor chain has been created, and before the DevHlp_Register is called to register the monitor). The physical device driver developer might prefer to create all monitor chains as they are needed. For example, a data stream can be defined when an OS/2 session is started. The monitor chains associated with that data stream can be created only when an application calls DosMonReg to register a monitor.

On calling MonitorCreate, the physical device driver places the parameters to the call in the registers as illustrated in the table below. The parameters include the selector:offset addresses of the physical device driver's:

Monitor Chain Buffer.

This buffer is the last buffer in a monitor chain and must reside within the physical device driver's first data segment (that is, the device driver 's header segment). The monitor dispatcher places filtered data (that is, data that has passed through all monitors in the monitor chain) into this buffer. The physical device driver processes this data by placing it into its API buffer, or by sending it to the device.

Notice that on calling MonitorCreate, the physical device driver must specify the length of the device driver's monitor chain buffer within the first WORD of the buffer, length WORD inclusive. Data records passing through a monitor chain will not exceed the length of the device driver's monitor chain buffer minus 2 bytes. The monitor dispatcher places filtered data into this buffer, starting at the second WORD of the buffer. The monitor dispatcher places the length of the data (in bytes) in the first WORD of the buffer, overwriting the original length WORD for the buffer.

Notification Routine.

This routine is called by the monitor dispatcher when filtered data is placed into the device driver's monitor chain buffer. This routine must reside in the device driver's first code segment.

In addition, the physical device driver specifies a monitor chain handle parameter. This parameter is used to indicate creation or deletion of a monitor chain. If the handle is zero when MonitorCreate is called, a new monitor chain is created and the monitor chain handle is returned to the physical device driver. If the handle is nonzero when MonitorCreate is called, the monitor chain with that handle is deleted.

    /-------------------------------------------------------------\

    |Registers      |Parameter Description                        |

    |---------------+---------------------------------------------|

    |ES:SI          |Address of Monitor Chain Buffer              |

    |---------------+---------------------------------------------|

    |DS:DI          |Address of Notification Routine              |

    |---------------+---------------------------------------------|

    |AX             |= 0 to create a new monitor chain (returns   |

    |               |handle); <>0 to delete a specific monitor    |

    |               |chain.                                       |

    \-------------------------------------------------------------/

The monitor chain handle is known only to the physical device driver and to the monitor dispatcher. The physical device driver uses this handle to identify the monitor chain to the monitor dispatcher on subsequent calls to the Monitor Dispatcher Device Helper services. For example, when the physical device driver registers a monitor for an application with its monitor chain, it uses the monitor chain handle returned from a previous call to MonitorCreate to indicate on which monitor chain the monitor must be registered.

The physical device driver maintains the list of monitor chain handles for its monitor chains, as well as the number of monitors registered on each monitor chain. When there are no monitors registered with a monitor chain, the monitor chain is empty. Notice that monitor chains are initially created empty. An empty monitor chain can be deleted by the physical device driver by calling MonitorCreate with the handle parameter set to the handle of the empty monitor chain. Physical device drivers that create their monitor chains as they are needed generally delete empty monitor chains when they are no longer needed.