Returning Error Codes from COPP Functions

This section applies only to Windows Server 2003 SP1 and later, and Windows XP SP2 and later.

The COPP DDI can return the following types of error codes:

• Error codes that are defined in the winerror.h header file and are common to all Windows applications. These Windows error codes start with the E_ prefix.

• Error codes that are defined in the ddraw.h header file and are unique to DirectDraw. These DirectDraw error codes start with the DDERR_ prefix.

No error codes are unique to the COPP DDI.

When implementing the COPP DDI, you should restrict your usage of Windows error codes to the following:

• E_UNEXPECTED

  The display driver is in an invalid state. For example, the COPPSequenceStart function was called before the COPPKeyExchange function.

• E_INVALIDARG

  Input parameters passed to the driver are invalid.

• E_POINTER

  An output parameter, which should point to a valid address, is NULL.

The COPP DDI can return the E_FAIL and DDERR_GENERIC error codes; however, because they do not indicate what caused the error, their use is discouraged.

The Remarks section for each COPP function specifies the DDERR_ error codes that the COPP function can report. The COPP DDI should not be required to return any other DDERR_ error codes.

When propagating error information from the COPP DDI in the video miniport driver to the display driver, you should not use the return value from the EngDeviceIoControl function, because the Windows kernel manipulates the error value that is returned from the IOCTL to EngDeviceIoControl. Instead, error information should be passed through the lpInBuffer parameter of EngDeviceIoControl. For more information, see Calling the COPP DDI from the Display Driver and the example code in COPP Video Miniport Driver Template and Performing COPP Operations.