DXGKCB_MIRACAST_SEND_MESSAGE callback function (dispmprt.h)

Article
10/21/2021

Sends an asynchronous message to the user-mode display driver.

Syntax

DXGKCB_MIRACAST_SEND_MESSAGE DxgkcbMiracastSendMessage;

NTSTATUS DxgkcbMiracastSendMessage(
  [in]           HANDLE MiracastHandle,
  [in]           ULONG InputBufferSize,
  [in]           VOID *pInputBuffer,
  [in]           ULONG OutputBufferSize,
  [out]          VOID *pOutputBuffer,
  [in, optional] DXGKCB_MIRACAST_SEND_MESSAGE_CALLBACK pCallback,
  [in, optional] PVOID pCallbackContext
)
{...}

Parameters

[in] MiracastHandle

A driver-supplied handle to the Miracast display device. This handle was originally passed in the MiracastHandle member of the DXGK_MIRACAST_DISPLAY_CALLBACKS structure in a call to the DxgkDdiMiracastCreateContext function.

[in] InputBufferSize

The size, in bytes, of the input buffer pointed to by pInputBuffer.

[in] pInputBuffer

A pointer to the input buffer. InputBufferSize specifies the size of the buffer.

See Remarks for more info about the input buffer.

[in] OutputBufferSize

The size, in bytes, of the output buffer pointed to by pOutputBuffer.

[out] pOutputBuffer

A pointer to the output buffer. OutBufferSize specifies the size of the buffer.

See Remarks for more info about the output buffer.

[in, optional] pCallback

An optional pointer, supplied by the display miniport driver, to the DxgkCbMiracastSendMessageCallback callback function.

If the display miniport driver supplies the pointer to DxgkCbMiracastSendMessageCallback, then after the user-mode driver handles the message, the operating system sends a message to the user-mode driver asynchronously by calling DxgkCbMiracastSendMessageCallback.

See Return value and Remarks sections for more about calls to DxgkCbMiracastSendMessageCallback.

[in, optional] pCallbackContext

An optional driver-supplied pointer to the driver-supplied callback context. The operating system passes this context to the driver-supplied callback routine after the operation has completed.

Return value

Returns STATUS_PENDING if it successfully delivers the message. Otherwise, it returns one of the error codes that are defined in Ntstatus.h.

If the display miniport driver needs to know the status of message handling in user mode, it should supply the DxgkCbMiracastSendMessageCallback function in the pCallback parameter and check the return status in that function's pIoStatusBlock parameter.

Remarks

If the display miniport driver supplies the pInputBuffer and pOutputBuffer buffers, it is the driver’s responsibility to hold these two buffers until the DxgkCbMiracastSendMessageCallback function is called. Otherwise, a random memory corruption issue can be created.

If the driver supplies the DxgkCbMiracastSendMessageCallback in the pCallback parameter, it's possible that DxgkCbMiracastSendMessageCallback will return before DxgkCbMiracastSendMessage returns.

Example calling sequence

Here's example code that shows how to use this function:

typedef struct _CALLBACK_CONTEXT
{
    UCHAR InputBuffer[INPUT_BUFFER_SIZE];
    UCHAR OutputBuffer[OUTPUT_BUFFER_SIZE];
} CALLBACK_CONTEXT, *PCALLBACK_CONTEXT;

...

_IRQL_requires_(PASSIVE_LEVEL)
VOID
DriverCallbackFunction(
    _In_ PVOID Context,
    _In_ PIO_STATUS_BLOCK pIoStatusBlock
    )
{
    PCALLBACK_CONTEXT CallbackContex = (PCALLBACK_CONTEXT)Context;

    ExFreePool(CallbackContex);
}

...

    CallbackContex = (PCALLBACK_CONTEXT)ExAllocatePoolWithTag(
                            PagedPool,
                            sizeof(CALLBACK_CONTEXT),
                            DRIVER_TAG);

    if (CallbackContex == NULL)
    {
        return STATUS_NO_MEMORY;
    }

    RtlZeroMemory(CallbackContex, sizeof(CALLBACK_CONTEXT));

    CallbackContex->InputBuffer[0] = 0xaa;
    CallbackContex->InputBuffer[1] = 0x55;

    Status = 
      pDeviceContext->MiracastCallbacks.DxgkCbMiracastSendMessage(
          pDeviceContext->MiracastCallbacks.MiracastHandle,
          sizeof(CallbackContex->InputBuffer),
          CallbackContex->InputBuffer,
          sizeof(CallbackContex->OutputBuffer),
          CallbackContext->OutputBuffer,
          &DriverCallbackFunction,
          CallbackContex);

Requirements

Requirement	Value
Minimum supported client	Windows 8.1
Minimum supported server	Windows Server 2012 R2
Target Platform	Desktop
Header	dispmprt.h (include Dispmprt.h)
IRQL	PASSIVE_LEVEL