IPrintOemPS::EnableDriver method (prcomoem.h)

The IPrintOemPS::EnableDriver method allows a rendering plug-in for Pscript to hook out some graphics DDI functions.

Syntax

HRESULT EnableDriver(
  DWORD          DriverVersion,
  DWORD          cbSize,
  PDRVENABLEDATA pded
);

Parameters

DriverVersion

Caller-supplied interface version number. This value is defined by PRINTER_OEMINTF_VERSION, in printoem.h.

cbSize

Caller-supplied size, in bytes, of the structure pointed to by pded.

pded

Caller-supplied pointer to a DRVENABLEDATA structure.

Return value

The method must return one of the following values:

Return code	Description
S_OK	The operation succeeded.
E_FAIL	The operation failed
E_NOTIMPL	The method is not implemented.

Remarks

The IPrintOemPS::EnableDriver method allows a rendering plug-in to perform the same types of operations as the DrvEnableDriver function that is exported by printer graphics DLLs.

Like the DrvEnableDriver function, the IPrintOemPS::EnableDriver method is responsible for providing addresses of internally supported graphics DDI functions, known as hooking functions. It can also perform other one-time initialization operations. Unlike the DrvEnableDriver function, implementation of the IPrintOemPS::EnableDriver method is optional.

If you implement IPrintOemPS::EnableDriver, you must also implement IPrintOemPS::DisableDriver. Actions begun in the former method might need to be completed in the latter method. For example, if a large buffer is allocated in IPrintOemPS::EnableDriver, but not deallocated in IPrintOemPS::DisableDriver, a memory leak can occur.

The method should fill the supplied DRVENABLEDATA structure and allocate an array of DRVFN structures. It should fill the array with pointers to hooking functions, along with winddi.h-defined index values that identify the hooked out graphics DDI functions.

A rendering plug-in for Pscript5 can hook out a graphics DDI function only if the Pscript5 driver defines the function. The following graphics DDI functions are defined in Pscript5 and or Unidrv and can therefore be hooked out:

• DrvAlphaBlend

• DrvBitBlt

• DrvCopyBits

• DrvDitherColor

• DrvEndDoc

• DrvEscape

• DrvFillPath

• DrvFontManagement

• DrvGetGlyphMode

• DrvGradientFill

• DrvIcmCreateColorTransform

• DrvIcmDeleteColorTransform

• DrvLineTo

• DrvNextBand

• DrvPlgBlt

• DrvQueryDeviceSupport

• DrvQueryAdvanceWidths

• DrvQueryFont

• DrvQueryFontData

• DrvQueryFontTree

• DrvRealizeBrush

• DrvSendPage

• DrvStartBanding

• DrvStartDoc

• DrvStartPage

• DrvStretchBlt

• DrvStretchBltROP

• DrvStrokeAndFillPath

• DrvStrokePath

• DrvTextOut

• DrvTransparentBlt

If you provide a customized hooking function, it preempts the driver's equivalent graphics DDI function. Hooking functions can also call back into the driver's graphics DDI functions. For more information, see Customized Graphics DDI Functions.

Customized hooking functions have the same input and output parameters as the equivalent graphics DDI function, with one exception - where graphics DDI functions receive PDEV pointers, customized hooking functions receive DEVOBJ pointers. There are two ways for these functions to receive PDEV pointers:

1. As the contents of the dhpdev member of a SURFOBJ structure for the destination surface. For the equivalent customized hooking function, the destination SURFOBJ structure's dhpdev member points to a DEVOBJ structure, and must be cast to type PDEVOBJ when referenced. An example graphics DDI function is DrvBitBlt.

2. As an input argument for a dhpdev parameter. The equivalent customized hooking function must cast this input parameter to type PDEVOBJ when referencing it. An example graphics DDI function is DrvDitherColor.

While a printer graphics DLL includes the addresses of its DrvEnablePDEV, DrvDisablePDEV, and DrvResetPDEV functions in the DRVENABLEDATA structure, a rendering plug-in for Pscript5 implements EnablePDEV, DisablePDEV, and ResetPDEV as methods of the IPrintOemPS interface and does not place their addresses in the DRVENABLEDATA structure.

If IPrintOemPS::EnableDriver methods are exported by multiple rendering plug-ins, the methods are called in the order that the plug-ins are specified for installation.

Each graphics DDI function can be hooked out by one rendering plug-in. If multiple plug-ins attempt to hook out the same graphics DDI function, all hook-outs after the first one are ignored.

For more information about creating and installing rendering plug-ins, see Customizing Microsoft's Printer Drivers.

Requirements

Requirement	Value
Target Platform	Desktop
Header	prcomoem.h (include Prcomoem.h)