Funzione IsCrossIsolatedEnvironmentClipboardContent (isolatedwindowsenvironmentutils.h)

Articolo
03/05/2024

IsCrossIsolatedEnvironmentClipboardContent può essere chiamato dopo che un'app rileva un errore di incolla per determinare se il contenuto incollato proviene dall'altro lato di Microsoft Defender Application Guard un limite MDAG (). In questo scenario, le applicazioni possono visualizzare un messaggio di errore personalizzato per aiutare gli utenti a comprendere che l'operazione degli Appunti è stata intenzionalmente bloccata da MDAG.

Sintassi

HRESULT IsCrossIsolatedEnvironmentClipboardContent(
  BOOL *isCrossIsolatedEnvironmentClipboardContent
);

Parametri

isCrossIsolatedEnvironmentClipboardContent

[out]

Puntatore a un valore booleano che riceve il risultato dell'API. Questo parametro sarà se il contenuto degli Appunti proviene true dall'altro lato di un limite MDAG, false in caso contrario.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è S_OK. Se ha esito negativo, viene restituito un codice di errore HRESULT.

Commenti

Questa API può essere chiamata sia dall'host che dall'istanza dell'app Ambiente Windows isolato e può rilevare entrambi gli scenari pertinenti:

Scenario 1 - Chiamato da un documento host (ad esempio: incollamento del contenuto all'host)
- Restituisce true se il contenuto degli Appunti proviene da qualsiasi ambiente Windows isolato.
Scenario 2 - Chiamato da un documento dell'ambiente Windows isolato (ad esempio, incollando il contenuto all'ambiente isolato)
- Restituisce true se il contenuto degli Appunti proviene dall'host o da un ambiente Windows isolato diverso.

Questa API consente anche alle app di continuare a visualizzare il gestore di errori incollare predefinito, se appropriato. Ad esempio, il contenuto copia/incollamento all'interno dello stesso ambiente isolato non è soggetto ai criteri degli Appunti MDAG. Qualsiasi errore potrebbe essere dovuto a un errore incollare non correlato, ad esempio i dati danneggiati. In questo caso, IsCrossIsolatedEnvironmentClipboardContent restituirebbe false, quindi l'app sa seguire il flusso predefinito del gestore degli errori di incolla.

Esempio

Questo esempio illustra come un'app può personalizzare il messaggio di errore incolla visualizzato all'utente. Il primo frammento mostra come usare IsCrossIsolatedEnvironmentClipboardContent per visualizzare un messaggio di errore appropriato se il gestore incolla di un'app ha esito negativo. In questo esempio il gestore OnPaste incolla dell'app (definito nel secondo frammento di codice) viene richiamato dal WM_PASTE messaggio ricevuto nel relativo 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;
}

Il secondo frammento di codice mostra il gestore incolla di un'app per illustrare il modo in cui le azioni degli Appunti potrebbero non riuscire se bloccate da 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;
}