IsCrossIsolatedEnvironmentClipboardContent-Funktion (isolatedwindowsenvironmentutils.h)

Artikel
02/28/2024

IsCrossIsolatedEnvironmentClipboardContent kann aufgerufen werden, nachdem eine App einen Einfügefehler erkannt hat, um zu bestimmen, ob der eingefügte Inhalt von der anderen Seite einer Microsoft Defender Application Guard -Grenze (MDAG) stammt. In diesem Szenario können Anwendungen eine benutzerdefinierte Fehlermeldung anzeigen, damit Benutzer nachvollziehen können, dass der Zwischenablagevorgang absichtlich von MDAG blockiert wurde.

Syntax

HRESULT IsCrossIsolatedEnvironmentClipboardContent(
  BOOL *isCrossIsolatedEnvironmentClipboardContent
);

Parameter

isCrossIsolatedEnvironmentClipboardContent

[out]

Ein Zeiger auf einen booleschen Wert, der das Ergebnis der API empfängt. Dieser Parameter ist true , wenn der Zwischenablageinhalt von der anderen Seite einer MDAG-Grenze stammt, false andernfalls.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist S_OKder Rückgabewert . Bei einem Fehler wird ein HRESULT-Fehlercode zurückgegeben.

Hinweise

Diese API kann sowohl von der Host- als auch von der Isolierten Windows-Umgebung-App instance aufgerufen werden und kann beide relevanten Szenarien erkennen:

Szenario 1: Aufruf aus einem Hostdokument (z. B. Einfügen von Inhalten auf den Host)
- Gibt true zurück, wenn der Zwischenablageinhalt aus einer isolierten Windows-Umgebung stammt.
Szenario 2: Aufruf aus einem Dokument für eine isolierte Windows-Umgebung (z. B. Einfügen von Inhalten in isolierte Umgebung)
- Gibt true zurück, wenn der Zwischenablageinhalt vom Host oder aus einer anderen isolierten Windows-Umgebung stammt.

Mit dieser API können Apps auch weiterhin ihren standardmäßigen Einfügefehlerhandler anzeigen, wenn dies angebracht ist. Beispielsweise unterliegt das Kopieren/Einfügen von Inhalten in derselben isolierten Umgebung nicht der MDAG-Zwischenablagerichtlinie. Jeder Fehler ist auf einen nicht zusammenhängenden Einfügefehler zurückzuführen, z. B. beschädigte Daten. In diesem Fall gibt IsCrossIsolatedEnvironmentClipboardContent false zurück, sodass die App weiß, dass sie ihren standardmäßigen Fehlerhandlerflow für Einfügevorgänge befolgt.

Beispiele

Dieses Beispiel zeigt, wie eine App die dem Benutzer angezeigte Einfügefehlermeldung anpassen kann. Der erste Codeausschnitt zeigt, wie Sie IsCrossIsolatedEnvironmentClipboardContent verwenden, um eine entsprechende Fehlermeldung anzuzeigen, wenn der Einfügehandler einer App fehlschlägt. In diesem Beispiel wird der Einfügehandler OnPaste der App (definiert im zweiten Codeausschnitt) von der Nachricht aufgerufen, die in ihrem WM_PASTEWndProcempfangen wird.

// 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;
}

Der zweite Codeausschnitt zeigt den Einfügehandler einer App, um zu veranschaulichen, wie Zwischenablageaktionen fehlschlagen können, wenn sie von MDAG blockiert werden.

// 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;
}