IsCrossIsolatedEnvironmentClipboardContent, fonction (isolatedwindowsenvironmentutils.h)

IsCrossIsolatedEnvironmentClipboardContent peut être appelé après qu’une application détecte un échec de collage pour déterminer si le contenu collé provient de l’autre côté d’une limite Microsoft Defender Application Guard (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é intentionnellement bloquée 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 sera 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, il retourne un code d’erreur HRESULT .

Remarques

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

• Scénario 1 : appelé à partir d’un document hôte (par exemple, collage de contenu à 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 à 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, la copie/collage de contenu dans le même environnement isolé n’est pas soumise à la stratégie de Presse-papiers MDAG. Toute défaillance est due à une erreur de collage non liée, telle que les données endommagées. Dans ce cas, IsCrossIsolatedEnvironmentClipboardContent retourne false. L’application sait donc suivre son flux de gestionnaire d’erreurs de collage par défaut.

Examples

Cet exemple montre comment une application peut personnaliser le message d’erreur coller affiché à l’utilisateur. Le premier extrait de code montre comment utiliser IsCrossIsolatedEnvironmentClipboardContent pour afficher un message d’erreur approprié si le gestionnaire de collage d’une application échoue. 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;
}

Spécifications

Voir aussi

Microsoft Defender Application Guard vue d’ensemble

IsolatedWindowsEnvironment

IsolatedWindowsEnvironmentHost