FillLogicalDeviceBlock

OS2_PM_DRV_ENABLE: FillLogicalDeviceBlock is called on the first occasion that a specific application or process opens a device context that uses the called presentation driver.

Syntax

FillLogicalDeviceBlock(ulSubfunction, pParam1, pParam2, pDispatchTable);

Parameters

ulSubfunction (ULONG) - input

01h.

pParam1 (PULONG) - input

A pointer to the following structure:

ulVersion

Version number in binary coded decimal (BCD) of the graphic engine.

cTableSize

The number of entries in the dispatch table. The presentation driver should not replace pointers past the end of the table.

pParam2 (PLONG) - input

A pointer to the following structure:

pfsFlags

Pointer to a WORD of logical device flags. Flag bits 0 and 2 apply to the presentation driver and are set ON or OFF, as appropriate, by the presentation driver. All other flags are reserved for system use and must not be modified.

Bit 0

Set ON if each device context for this presentation driver requires its own physical device block. Even if the presentation driver sets this bit off, the FillPhysicalDeviceBlock subfunction can still be called more than once (although no work may need to be done after FillPhysicalDeviceBlock is called the first time).

Bit 2

Set ON if the szDeviceName and pszDriverName fields of a DevOpenDC call for this device are ignored. Setting Bit 2 ON indicates that the presentation driver supports only one physical device in one configuration, for example, the display driver. Hardcopy drivers do not set this bit unless the hardcopy driver supports only one physical device in one configuration.

Bit 7

This is a new bit in OS/2 2.1, Graphics Engine Version 0x202 or later. Setting Bit 7 ON indicates that the presentation driver may update the dispatch table in FillPhysicalDeviceBlock. Do this if your driver supports more than one type of device and you want to hook different functions based on the device type.

pDispatchTable (PLONG) - input

A pointer to the presentation driver's copy of the dispatch table. This table is an array of 32-bit pointers to system-default function- handling routines. The low-order byte of a function number identifies the offset to the relevant pointer.

Return Code

rc (LONG) - returns

Return codes.

The handling routine should return a LONG integer. Valid values are:

• 0 Successful
• -1 Error

Remarks

This subfunction is not called when the same application or process opens additional device contexts with the same presentation driver. However, the graphics engine can call this subfunction at other times and the call should always be honored. If the value of pDispatchTable is nonzero, the handling routine must initialize the dispatch table.

The major tasks that the handling routine must implement are:

1. Add an entry to the DosExitList to ensure that any allocated resources are freed when the owning application or process terminates.
2. Save those pointers in the dispatch table that are needed to pass hooked functions back to the graphics engine. A typical example is GreCharString, which must be hooked by the presentation driver, but can be passed back to the default handling routine.
3. Initialize the dispatch table. That is, modify the table so that the entries for functions hooked by the presentation driver contain pointers to the driver's handling routines.
4. Set flags to indicate how future DevOpenDC calls to this device should be handled.

In some typical presentation drivers, the handling routine for FillLogicalDeviceBlock allocates global heap space for use by the device contexts. The memory for this heap space is obtained by calling the SSAllocMem function. This global heap space is available to all instances of a device context that are opened by the application or process for which the presentation driver was enabled.