IPrintOemUni::EnableDriver method (prcomoem.h)

The IPrintOemUni::EnableDriver method allows a rendering plug-in for Unidrv 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.

Remarks

A rendering plug-in for Unidrv must implement the IPrintOemUni::EnableDriver method.

The IPrintOemUni::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 IPrintOemUni::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 IPrintOemUni::EnableDriver is optional.

If you implement IPrintOemUni::EnableDriver, you must also implement IPrintOemUni::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 IPrintOemUni::EnableDriver, but not deallocated in IPrintOemUni::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 Unidrv can hook out a graphics DDI function only if the Unidrv driver defines the function. The following graphics DDI functions are defined in Unidrv and/or Pscript5 and can therefore be hooked out:

• DrvAlphaBlend

• DrvBitBlt

• DrvCopyBits

• DrvDitherColor

• DrvEndDoc

• DrvEscape

• DrvFillPath

• DrvFontManagement

• DrvGetGlyphMode

• DrvGradientFill

• DrvIcmCreateColorTransform

• DrvIcmDeleteColorTransform

• DrvLineTo

• DrvNextBand

• DrvPlgBlt

• DrvQueryAdvanceWidths

• DrvQueryDeviceSupport

• 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 graphics DDI functions to receive PDEV pointers:

• 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.

• 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.

Note that while a printer graphics DLL includes the addresses of its DrvEnablePDEV, DrvDisablePDEV, and DrvResetPDEV functions in the DRVENABLEDATA structure, a rendering plug-in explicitly exports EnablePDEV, DisablePDEV, and ResetPDEV as methods of the IPrintOemUni interface and does not place their addresses in the DRVENABLEDATA structure.

If IPrintOemUni::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 only 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