DrvEscape Function Code Example (Compact 7)
3/12/2014
The RDC client calls the ExtEscape function that is defined in Compact 7 and passes in an escape sequence and the RemoteFX-encoded display data. The ExtEscape function then passes the escape sequence and display data to the DrvEscape function in the display driver.
The DrvEscape function is a display driver function that allows applications to access the capabilities of a particular device, such as hardware-accelerated decoding. These device capabilities are not necessarily available within the application or the Compact 7 operating system. The DrvEscape function must be implemented by an OEM in order to access the hardware-accelerated decoding capabilities of the device.
The iEsc parameter of the DrvEscape function queries whether the driver supports a particular escape function. QUERYESCSUPPORT is the only predefined value.
DrvEscape should return a nonzero value for any supported escape sequences when iEsc is set to QUERYESCSUPPORT. In this case, pvIn points to an escape function number. During initialization and before offloading of the RemoteFX-encoded data stream through the ExtEscape function, the RDP client makes multiple QUERYESCSUPPORT calls to verify whether an escape sequence is supported by the display driver. The following code example shows how to implement the DrvEscape function in the display driver.
Important
For readability, the following code example does not contain security or error handling. Do not use the following code in a production environment.
ULONG DrvEscape(
SURFOBJ * pso,
ULONG iEsc,
ULONG cjIn,
void * pvIn,
ULONG cjOut,
void * pvOut
)
{
if (iEsc == QUERYESCSUPPORT)
{
if ( *(DWORD*)pvIn == ESCAPE_GET_CAPABILITIES
|| *(DWORD*)pvIn == ESCAPE_DEC3
|| *(DWORD*)pvIn == ESCAPE_COPY_2BMP )
{
// The escape functions are supported.
return 1;
}
}
else if (iEsc == ESCAPE_GET_CAPABILITIES)
{
int RetVal = 0;
RetVal = esc_get_capabilities(pso,iEsc,cjIn,pvIn,cjOut,pvOut);
return RetVal;
}
else if (iEsc == ESCAPE_DEC3)
{
int RetVal = 0;
RetVal = esc_dec3(pso,iEsc,cjIn,pvIn,cjOut,pvOut);
return RetVal;
}
else if (iEsc == ESCAPE_COPY_2BMP)
{
int RetVal = 0;
RetVal = esc_copy_2bmp(pso,iEsc,cjIn,pvIn);
return RetVal;
}
return 0;
}
The GDI passes data directly from the RDC client to the display 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.
Driver-specific escape sequences may conflict with those that are used in other display drivers; so the display driver needs to validate the escape parameters before processing the escape data. One way to do that is for the driver to validate the input block size, output block size, and the input block parameters.
For added security, drivers should include a specific value that OEMs must set in every input block to ensure that the input block is from a trusted source. In RemoteFX, this security mechanism is achieved by using an escape header data structure. The escape headers in RemoteFX always contain a magic value that corresponds to 0xBEEFABCE.
In addition to providing a driver that has the usual display capabilities, as an OEM, you need to implement the following escape sequences and functions in your display driver to access the capabilities of the hardware:
- Window-frame mode display drivers must support the QUERYESCSUPPORT, ESCAPE_GET_CAPABILITIES, ESCAPE_DEC3, and ESCAPE_COPY_2BMP escape sequences in the DrvEscape function.
- Full-screen mode display drivers must implement the QUERYESCSUPPORT, ESCAPE_GET_CAPABILITIES, ESCAPE_DEC3, and ESCAPE_EXIT_CA escape sequences in the DrvEscape function as well as implement functionality for Extract Rectangle Information from RemoteFX Display Data.
The following sections introduce these escape sequences and provide code examples for how to use them:
- ESCAPE_COPY_2BMP Code Example
- ESCAPE_DEC3 Code Example
- ESCAPE_EXIT_CA Code Example
- ESCAPE_GET_CAPABILITIES Code Example