IsCrossIsolatedEnvironmentClipboardContent, fonction (isolatedwindowsenvironmentutils.h)

Article
03/01/2024

IsCrossIsolatedEnvironmentClipboardContent peut être appelé après qu’une application a détecté un échec de collage pour déterminer si le contenu collé provient de l’autre côté d’une limite de Protection d'application Microsoft Defender (MDAG). Dans ce scénario, les applications peuvent afficher un message d’erreur personnalisé pour aider les utilisateurs à comprendre que l’opération du Presse-papiers a été bloquée intentionnellement par MDAG.

Syntaxe

HRESULT IsCrossIsolatedEnvironmentClipboardContent(
  BOOL *isCrossIsolatedEnvironmentClipboardContent
);

Paramètres

isCrossIsolatedEnvironmentClipboardContent

[out]

Pointeur vers une valeur booléenne qui reçoit le résultat de l’API. Ce paramètre est true si le contenu du Presse-papiers provient de l’autre côté d’une limite MDAG, false sinon.

Valeur retournée

Si la fonction réussit, la valeur de retour est S_OK. En cas d'échec, retourne un code d'erreur HRESULT.

Remarques

Cette API peut être appelée à partir de l’hôte et de l’application Environnement Windows isolé instance et peut détecter les deux scénarios pertinents :

Scénario 1 - Appelé à partir d’un document hôte (par exemple , collage de contenu sur l’hôte)
- Retourne true si le contenu du Presse-papiers provient d’un environnement Windows isolé.
Scénario 2 - Appelé à partir d’un document d’environnement Windows isolé (par exemple, collage de contenu dans un environnement isolé)
- Retourne true si le contenu du Presse-papiers provient de l’hôte ou d’un autre environnement Windows isolé.

Cette API permet également aux applications de continuer à afficher leur gestionnaire d’erreurs de collage par défaut, le cas échéant. Par exemple, le copier/coller du contenu dans le même environnement isolé n’est pas soumis à la stratégie du Presse-papiers MDAG. Toute défaillance serait due à une erreur de collage non liée, telle que des données endommagées. Dans ce cas, IsCrossIsolatedEnvironmentClipboardContent retournerait false, de sorte que l’application sait suivre son flux de gestionnaire d’erreurs de collage par défaut.

Exemples

Cet exemple montre comment une application peut personnaliser le message d’erreur de collage affiché à l’utilisateur. Le premier extrait de code montre comment utiliser IsCrossIsolatedEnvironmentClipboardContent pour afficher un message d’erreur approprié en cas d’échec du gestionnaire de collage d’une application. Dans cet exemple, le gestionnaire OnPaste de collage de l’application (défini dans le deuxième extrait de code) est appelé par le WM_PASTE message reçu dans son 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;
}

Le deuxième extrait de code montre le gestionnaire de collage d’une application pour montrer comment les actions du Presse-papiers peuvent échouer si elles sont bloquées par 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;
}

Configuration requise

Condition requise	Valeur
En-tête	isolatedwindowsenvironmentutils.h
DLL	isolatedwindowsenvironmentutils.dll

Voir aussi

Vue d’ensemble de Microsoft Defender Application Guard

IsolatedWindowsEnvironment

IsolatedWindowsEnvironmentHost

Partager via