Функция IsCrossIsolatedEnvironmentClipboardContent (isolatedwindowsenvironmentutils.h)

Статья
03/16/2023

IsCrossIsolatedEnvironmentClipboardContent можно вызвать после того, как приложение обнаружит сбой вставки, чтобы определить, поступило ли вставляемое содержимое с другой стороны границы Application Guard в Microsoft Defender (MDAG). В этом сценарии приложения могут отображать пользовательское сообщение об ошибке, чтобы помочь пользователям понять, что операция буфера обмена была намеренно заблокирована MDAG.

Синтаксис

HRESULT IsCrossIsolatedEnvironmentClipboardContent(
  BOOL *isCrossIsolatedEnvironmentClipboardContent
);

Параметры

isCrossIsolatedEnvironmentClipboardContent

[out]

Указатель на логическое значение, которое получает результат API. Этот параметр будет иметь значение true , если содержимое буфера обмена поступило с другой стороны границы MDAG, false в противном случае .

Возвращаемое значение

Если функция выполняется успешно, возвращается S_OKзначение . При возникновении ошибки возвращает код ошибки типа HRESULT.

Сценарий 1. Вызов из ведущего документа (например, вставка содержимого на узел)
- Возвращает значение true, если содержимое буфера обмена поступило из любой изолированной среды Windows.
Сценарий 2. Вызывается из документа изолированной среды Windows (например, вставка содержимого в изолированную среду)
- Возвращает значение true, если содержимое буфера обмена поступило с узла или из другой изолированной среды Windows.

Этот API также позволяет приложениям по-прежнему отображать обработчик ошибок вставки по умолчанию, если это необходимо. Например, копирование и вставка содержимого в одной изолированной среде не регулируется политикой буфера обмена MDAG. Любой сбой будет вызван несвязанной ошибкой вставки, например поврежденными данными. В этом случае IsCrossIsolatedEnvironmentClipboardContent вернет значение false, поэтому приложение будет следовать потоку обработчика ошибок вставки по умолчанию.

Примеры

В этом примере показано, как приложение может настроить сообщение об ошибке вставки, отображаемое для пользователя. В первом фрагменте кода показано, как использовать IsCrossIsolatedEnvironmentClipboardContent для отображения соответствующего сообщения об ошибке в случае сбоя обработчика вставки приложения. В этом примере обработчик OnPaste вставки приложения (определенный во втором фрагменте кода) вызывается сообщениемWM_PASTE, полученным в .WndProc

// Assume this is the WndProc method that handles WM messages for an app.
// Assume SampleAppHelperClass::DisplayMsgBox shows a simple UI error dialog with given string.

LRESULT CALLBACK SampleAppWndProc(HWND hWnd, UINT message, WPARAM wParam, LPARAM lParam)
{
  LRESULT retVal = 0;
  switch (message)
  {
  case WM_PASTE:
  {
    RETURN_LAST_ERROR_IF(!OpenClipboard(hWnd));

    // See definition of OnPaste in code snippet #2, below.
    retVal = OnPaste(hWnd, message, wParam, lParam);

    // To avoid a race condition with the clipboard changing underneath us, call
    // IsCrossIsolatedEnvironmentClipboardContent with the clipboard still open.
    HRESULT hr = S_OK;
    BOOL isCrossEnvContent = FALSE;

    hr = IsCrossIsolatedEnvironmentClipboardContent(&isCrossEnvContent);

    CloseClipboard();

    if (retVal != ERROR_SUCCESS)
    {
      // Show a MDAG specific error message if the clipboard content crossed the host/isolated
      // environment boundary. Otherwise, show the app’s default paste error message.
      if (SUCCEEDED(hr) && isCrossEnvContent)
      {
        // This runs on both the host and Isolated Environment app instance, so customize error
        // message per scenario.
        BOOL isIsolatedWindowsEnvironment = FALSE;
        IsProcessInIsolatedWindowsEnvironment(&isIsolatedWindowsEnvironment);
        std::wstring direction = isIsolatedWindowsEnvironment ? L"into" : L"from";

        SampleAppHelperClass::DisplayMsgBox(hWnd, L"Pasting content %s a MDAG document failed, verify this operation is permitted by your administrator.\n", direction.c_str());
      }
      else
      {
        SampleAppHelperClass::DisplayMsgBox(hWnd, L"Paste operation failed.\nError code 0x%x", retVal);
      }
    }
  }
  break;
  default:
    return DefWindowProc(hWnd, message, wParam, lParam);
  }
  return retVal;
}

Во втором фрагменте кода показан обработчик вставки приложения, демонстрирующий, как действия буфера обмена могут завершиться ошибкой при блокировке MDAG.

// Invoked by user Paste action, such as Ctr+V or clicking the Paste button.
HRESULT OnPaste(HWND hWnd)
{
  RETURN_LAST_ERROR_IF(!IsClipboardFormatAvailable(CF_TEXT));
  HGLOBAL clipboardData = GetClipboardData(CF_TEXT);
  RETURN_LAST_ERROR_IF(clipboardData == NULL);

  // Now that we've verified clipboard access suceeds, assume InsertTextFromClipboard is an
  // application defined method to insert text into desired location.
  RETURN_IF_FAILED(InsertTextFromClipboard(clipboardData, hWnd));

  CloseClipboard();

  return S_OK;
}