IsCrossIsolatedEnvironmentClipboardContent 函式 (isolatedwindowsenvironmentutils.h)

發行項
02/28/2024

IsCrossIsolatedEnvironmentClipboardContent 可以在應用程式偵測到貼上失敗之後呼叫，以判斷貼上的內容是否來自 Microsoft Defender 應用程式防護 (MDAG) 界限的另一端。在此案例中，應用程式可以顯示自定義錯誤訊息，協助用戶瞭解 MDAG 刻意封鎖剪貼簿作業。

語法

HRESULT IsCrossIsolatedEnvironmentClipboardContent(
  BOOL *isCrossIsolatedEnvironmentClipboardContent
);

參數

isCrossIsolatedEnvironmentClipboardContent

[out]

接收 API 結果之布爾值的指標。如果剪貼簿內容來自 MDAG 界限的另一端，則此參數會 true 是， false 否則為。

傳回值

如果函式成功，則傳回值為 S_OK。如果方法失敗，則會傳回 HRESULT 錯誤碼。

備註

您可以從主機和隔離的 Windows 環境應用程式實例呼叫此 API，而且可以偵測這兩個相關案例：

案例 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;
}