DrvEscape (Windows Embedded CE 6.0)

1/6/2010

This function retrieves information from a device that is not available in a device-independent DDI. This function operates the same as on Windows-based desktop platforms, but Windows Embedded CE does not support the DrvDrawEscape function. DrvEscape is used for retrieving information from a device that is not available in a device-independent device driver interface; the particular query depends on the value of the iEsc parameter.

Syntax

ULONG DrvEscape(
  DHPDEV dhpdev,
  SURFOBJ* pso,
  ULONG iEsc,
  ULONG cjIn,
  PVOID pvIn,
  ULONG cjOut,
  PVOID pvOut
);

Parameters

• dhpdev
  [in] Handle to the device that is getting the DrvEscape call.

• pso
  [in] Pointer to a SURFOBJ structure that describes the surface to which the call is directed.

• iEsc
  [in] Query. The meaning of the other parameters depends on this value. QUERYESCSUPPORT is the only predefined value; it queries whether the driver supports a particular escape function. In this case, pvIn points to an escape function number; cjOut and pvOut are ignored. If the specified function is supported, the return value is nonzero.

• cjIn
  [in] Size, in bytes, of the buffer pointed to by pvIn.

• pvIn
  [in] Pointer to the input data for the call. The format of the input data depends on the query specified by the iEsc parameter.

• cjOut
  [in] Size, in bytes, of the buffer pointed to by pvOut.

• pvOut
  [out] Pointer to the output buffer. The format of the output data depends on the query specified by the iEsc parameter.

Return Value

The return value is dependent on the query specified by the iEsc parameter. If the function specified in the query is not supported, the return value is zero.

Remarks

Drawing on the device is not allowed in this function.

GDI passes data directly from a possibly malicious client application to the driver, which means that the DrvEscape function must validate all input arguments. The following list shows what this function must verify:

• The iEsc parameter value represents a valid query.
• The cjIn parameter value is valid for the specified query.
• The pvIn parameter contents are valid for the specified query.
• The cjOut parameter contents are valid for the specified query.

Microsoft reserves the range 0 to 0X10000 for its escape codes. Third-party vendors are free to choose escape codes for their own use above this range. Driver-specific escape codes may conflict with those used in other display drivers, so it is important for a display driver to validate escape parameters before processing the escape. One way to do this is to validate the input block size, output block size, and the input block parameters. For added security, drivers should include a specific value that must be set appropriately in every input block to ensure that the input block is from a trusted source.

Requirements

See Also

Reference

Display Driver Functions

Other Resources

Display Drivers