IsCrossIsolatedEnvironmentClipboardContent-Funktion (isolatedwindowsenvironmentutils.h)

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

Syntax

HRESULT IsCrossIsolatedEnvironmentClipboardContent(
  BOOL *isCrossIsolatedEnvironmentClipboardContent
);

Die Parameter

isCrossIsolatedEnvironmentClipboardContent

[out]

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

Rückgabewert

Wenn die Funktion erfolgreich ist, lautet S_OKder Rückgabewert . Wenn ein Fehler auftritt, wird ein HRESULT Fehlercode zurückgegeben.

Bemerkungen

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

• Szenario 1 – Von einem Hostdokument aufgerufen (z. B. Einfügen von Inhalten an den Host)
  • Gibt "true" zurück, wenn der Inhalt der Zwischenablage aus einer isolierten Windows-Umgebung stammt.
• Szenario 2 – Aus einem isolierten Windows-Umgebungsdokument aufgerufen (z. B. Einfügen von Inhalten in isolierte Umgebung)
  • Gibt "true" zurück, wenn der Inhalt der Zwischenablage vom Host oder aus einer anderen isolierten Windows-Umgebung stammt.

Diese API ermöglicht Apps außerdem, ihren Standardmäßigen Einfügefehlerhandler ggf. anzuzeigen. Beispielsweise unterliegt das Kopieren/Einfügen von Inhalten innerhalb derselben isolierten Umgebung nicht der MDAG-Zwischenablagerichtlinie. Jeder Fehler würde auf einen Nicht-Verknüpften Einfügefehler zurückzuführen sein, z. B. beschädigte Daten. In diesem Fall würde IsCrossIsolatedEnvironmentClipboardContent "false" zurückgeben, sodass die App weiß, ihren Standardmäßigen Fehlerhandlerfluss beim Einfügen zu befolgen.

Examples

In diesem Beispiel wird gezeigt, wie eine App die dem Benutzer angezeigte Fehlermeldung zum Einfügen anpassen kann. Der erste Codeausschnitt zeigt, wie IsCrossIsolatedEnvironmentClipboardContent verwendet wird, um eine entsprechende Fehlermeldung anzuzeigen, wenn der Einfügehandler einer App fehlschlägt. In diesem Beispiel wird der Einfügehandler OnPaste der App (im zweiten Codeausschnitt definiert) von der WM_PASTE empfangenen Nachricht aufgerufen 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;
}

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

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

Anforderungen

Siehe auch

Übersicht über Microsoft Defender Application Guard

IsolatedWindowsEnvironment

IsolatedWindowsEnvironmentHost