IsCrossIsolatedEnvironmentClipboardContent 함수(isolatedwindowsenvironmentutils.h)

아티클
02/28/2024

IsCrossIsolatedEnvironmentClipboardContent는 앱에서 붙여넣는 콘텐츠가 MDAG(Microsoft Defender Application Guard) 경계의 반대편에서 제공되었는지 확인하는 붙여넣기 실패를 감지한 후 호출할 수 있습니다. 이 시나리오에서 애플리케이션은 사용자가 클립보드 작업이 MDAG에 의해 의도적으로 차단되었음을 이해하는 데 도움이 되는 사용자 지정 오류 메시지를 표시할 수 있습니다.

구문

HRESULT IsCrossIsolatedEnvironmentClipboardContent(
  BOOL *isCrossIsolatedEnvironmentClipboardContent
);

매개 변수

isCrossIsolatedEnvironmentClipboardContent

[out]

API의 결과를 수신하는 부울 값에 대한 포인터입니다. 이 매개 변수는 true 클립보드 콘텐츠가 MDAG 경계의 다른 쪽에서 온 경우 이고, false 그렇지 않으면 입니다.

반환 값

함수가 성공하면 반환 값은 입니다 S_OK. 그렇지 않으면 HRESULT 오류 코드가 반환됩니다.

설명

이 API는 호스트 및 격리된 Windows 환경 앱 instance 모두 호출할 수 있으며 두 관련 시나리오를 모두 검색할 수 있습니다.

시나리오 1 - 호스트 문서에서 호출됨(예: 호스트에 콘텐츠 붙여넣기)
- 클립보드 콘텐츠가 격리된 Windows 환경에서 제공된 경우 true를 반환합니다.
시나리오 2 - 격리된 Windows 환경 문서에서 호출됨(예: 격리된 환경에 콘텐츠 붙여넣기)
- 클립보드 콘텐츠가 호스트 또는 다른 격리된 Windows 환경에서 온 경우 true를 반환합니다.

또한 이 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;
}