DXGKDDI_OPM_GET_INFORMATION callback function (dispmprt.h)

The DXGKDDI_OPM_GET_INFORMATION function retrieves information from the given protected output object.

Syntax

DXGKDDI_OPM_GET_INFORMATION DxgkddiOpmGetInformation;

NTSTATUS DxgkddiOpmGetInformation(
  [in]  PVOID MiniportDeviceContext,
  [in]  HANDLE ProtectedOutputHandle,
  [in]  const DXGKMDT_OPM_GET_INFO_PARAMETERS *Parameters,
  [out] PDXGKMDT_OPM_REQUESTED_INFORMATION RequestedInformation
)
{...}

Parameters

[in] MiniportDeviceContext

A handle to a context block associated with a display adapter. Previously, the display miniport driver's DxgkDdiAddDevice function provided this handle to the DirectX graphics kernel subsystem.

[in] ProtectedOutputHandle

The handle to a protected output object. The DxgkDdiOPMCreateProtectedOutput function creates the protected output object and returns the handle to the object. The protected output object that corresponds to this handle should have OPM semantics.

[in] Parameters

A pointer to a DXGKMDT_OPM_COPP_COMPATIBLE_GET_INFO_PARAMETERS structure that contains parameters that are used to retrieve information from a protected output object whose handle is specified in the ProtectedOutputHandle parameter. DXGKDDI_OPM_GET_INFORMATION determines if the parameters contain a valid request from the application that indirectly created the protected output object. For more information, see the Remarks section.

[out] RequestedInformation

A pointer to a DXGKMDT_OPM_REQUESTED_INFORMATION structure that receives the protected output object's information if DXGKDDI_OPM_GET_INFORMATION returns successfully.

If DXGKDDI_OPM_GET_INFORMATION fails, the value that RequestedInformation points to is unchanged.

Return value

DxgkDdiOPMGetCOPPCompatibleInformation returns STATUS_SUCCESS or an Ntstatus.h error code.

Remarks

The DirectX graphics kernel subsystem should call DXGKDDI_OPM_GET_INFORMATION only if the output has OPM semantics.

Before the DirectX graphics kernel subsystem passes the protected output handle to the ProtectedOutputHandle parameter in a call to DXGKDDI_OPM_GET_INFORMATION, the DirectX graphics kernel subsystem always passes the protected output handle to the DxgkDdiOPMSetSigningKeyAndSequenceNumbers and DxgkDdiOPMGetRandomNumber functions.

DXGKDDI_OPM_GET_INFORMATION retrieves one of the following types of information:

• The protected output's connector type.
• The content protection types that the protected output supports. Protected outputs can currently support ACP, CGMS-A, and HDCP.
• The protected output's current virtual protection level for a particular protection type.
• The physical output's actual protection level for a particular protection type.
• The version of the HDCP SRM that the protected output currently uses.
• The type of expansion bus that the graphics adapter uses and how the graphics adapter is connected to the computer's north bridge.
• The format of the images that the graphics adapter sends from the physical output to the monitor.

The guidInformation member of the DXGKMDT_OPM_GET_INFO_PARAMETERS structure that the Parameters parameter points to should never contain the DXGKMDT_OPM_GET_CONNECTED_HDCP_DEVICE_INFORMATION and DXGKMDT_OPM_GET_ACP_AND_CGMSA_SIGNALING GUIDs because only COPP applications should specify these GUIDs.

The first 4 bytes of the abParameters member of DXGKMDT_OPM_GET_INFO_PARAMETERS should never contain the DXGKMDT_OPM_PROTECTION_TYPE_COPP_COMPATIBLE_HDCP protection type when the DXGKMDT_OPM_GET_VIRTUAL_PROTECTION_LEVEL or DXGKMDT_OPM_GET_ACTUAL_PROTECTION_LEVEL GUID is specified in the guidInformation member of DXGKMDT_OPM_GET_INFO_PARAMETERS because only COPP applications use this protection type.

The driver must perform the following sequence when its DXGKDDI_OPM_GET_INFORMATION function is called.

1. Verify that the protected output handle that was passed to the ProtectedOutputHandle parameter of DXGKDDI_OPM_GET_INFORMATION has OPM semantics.

2. Verify that the information in the Parameters parameter was signed with the protected output object's signing key. The protected output object's signing key was previously set when the DxgkDdiOPMSetSigningKeyAndSequenceNumbers function was called. The Advanced Encryption Standard (AES) block cipher and the OMAC-1 signing algorithm should be used to verify the signature. For information about AES, see the RSA Laboratories website. For information about OMAC-1, see the DXGKMDT_OPM_OMAC reference page.

3. Retrieve the requested information.

4. Copy the random number that the rnRandomNumber member of DXGKMDT_OPM_GET_INFO_PARAMETERS specifies to the rnRandomNumber member in the DXGKMDT_OPM_STANDARD_INFORMATION or DXGKMDT_OPM_ACTUAL_OUTPUT_FORMAT structure. The structure that is used depends on the type of information that the caller requested and is set in the abRequestedInformation member of the DXGKMDT_OPM_REQUESTED_INFORMATION structure that the RequestedInformation parameter points to.

5. Sign the DXGKMDT_OPM_REQUESTED_INFORMATION structure and place the signature in the omac member of DXGKMDT_OPM_REQUESTED_INFORMATION. The AES block cipher and the OMAC-1 signing algorithm should be used to sign the structure.

Initially, the DirectX graphics kernel subsystem calls DXGKDDI_OPM_GET_INFORMATION to retrieve information about the output and then calls DxgkDdiOPMConfigureProtectedOutput one or more times to configure the output. Subsequently, the DirectX graphics kernel subsystem calls DXGKDDI_OPM_GET_INFORMATION without also calling DxgkDdiOPMConfigureProtectedOutput.

DXGKDDI_OPM_GET_INFORMATION should be made pageable.

Requirements

See also

DxgkDdiAddDevice

DxgkDdiOPMConfigureProtectedOutput

DxgkDdiOPMCreateProtectedOutput

DXGKDDI_OPM_GET_INFORMATION

DxgkDdiOPMGetRandomNumber

DxgkDdiOPMSetSigningKeyAndSequenceNumbers

DXGKMDT_OPM_COPP_COMPATIBLE_GET_INFO_PARAMETERS

DXGKMDT_OPM_OMAC

DXGKMDT_OPM_REQUESTED_INFORMATION