InstallPMEngineDisplayHooks

OS2_PM_DRV_ENABLE: InstallPMEngineDisplayHooks provides the addresses of the graphics engine and display driver dispatch tables so that the dynamic link libraries for display hooks can intercept the dispatching of these functions for monitoring or other purposes.

Syntax

InstallPMEngineDisplayHooks(ulSubfunction, pParam1, pParam2);

Parameters

ulSubfunction (ULONG) - input

0Ch.

pParam1 (PLONG) - input

A pointer to the following data structure:

ulVersion

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

comptype

A structure consisting of two short flag variables:

fEngine32Bit

This flag will always be true.

fDriver32Bit

This flag is set if the current display driver is a 32-bit driver.

pParam2 (PLONG) - input

A pointer to the dispatch tables of the display driver and graphics engine:

pEngHooks

Pointer to the 32-bit entry points of the graphics engine.

pDrvHooks

Pointer to the entry points of the current display driver, which can consist of a table of 16-bit or 32-bit entry points:

typedef struct _CompType {
    USHORT fEngine32Bit;
    USHORT fDriver32Bit;
} COMPTYPE;

typedef struct _P1 {
    ULONG    version;
    COMPTYPE comptype;
} P1;

typedef struct _P2 {
    PLONG pEngTable;
    PLONG pDrvTable;
} P2;

Return Code

rc (LONG) - returns

Return codes.

The return value is 0 if the function is successful; otherwise, it is an error value.

If the error returned = PMERR_DRVR_NOT_SUPPORTED, the graphics engine will unload the hooking DLL and work as though no routine were installed. This would be the case if the hooking DLL only handled 32-bit entry points and received a display dispatch table of 16-bit entry points.

Remarks

For a display hook's DLL to be installed, the name of the DLL must be added to OS2.INI with keyname = MODULENAME and application name = PM_ED_HOOKS.

The graphics engine will load the DLLs so identified in OS2.INI in turn, from left to right, so that the rightmost name will be the last display hook's DLL offered access to the dispatch tables.

Display hook DLLs need to be Ring-2-conforming. Support for 16-bit drivers runs at Ring 2. OS/2 2.0 32-bit drivers have a choice to run predetermined calls at Ring 2.

Sample Code

#include <os2.h>

ULONG    ulSubfunction;  /*  0Ch. */
PLONG    pParam1;
PLONG    pParam2;
LONG     rc;             /*  Return codes. */

rc = InstallPMEngineDisplayHooks(ulSubfunction,
       pParam1, pParam2);