Função IsCrossIsolatedEnvironmentClipboardContent (isolatedwindowsenvironmentutils.h)

Artigo
10/04/2023

IsCrossIsolatedEnvironmentClipboardContent pode ser chamado depois que um aplicativo detecta uma falha de colagem para determinar se o conteúdo que está sendo colado veio do outro lado de um limite de Microsoft Defender Application Guard (MDAG). Nesse cenário, os aplicativos podem exibir uma mensagem de erro personalizada para ajudar os usuários a entender que a operação da área de transferência foi bloqueada intencionalmente pelo MDAG.

Sintaxe

HRESULT IsCrossIsolatedEnvironmentClipboardContent(
  BOOL *isCrossIsolatedEnvironmentClipboardContent
);

Parâmetros

isCrossIsolatedEnvironmentClipboardContent

[out]

Um ponteiro para um valor booliano que recebe o resultado da API. Esse parâmetro será true se o conteúdo da área de transferência veio do outro lado de um limite do MDAG, false caso contrário.

Retornar valor

Se a função for bem-sucedida, o valor retornado será S_OK. Se falhar, retornará um código de erro HRESULT.

Comentários

Essa API pode ser chamada do host e da instância do aplicativo ambiente isolado do Windows e pode detectar ambos os cenários relevantes:

Cenário 1 – Chamado de um documento de host (por exemplo: colar conteúdo no host)
- Retorna true se o conteúdo da área de transferência veio de qualquer Ambiente Isolado do Windows.
Cenário 2 – Chamado de um documento de ambiente isolado do Windows (por exemplo: colar conteúdo em ambiente isolado)
- Retorna true se o conteúdo da área de transferência veio do host ou de um ambiente isolado do Windows diferente.

Essa API também permite que os aplicativos continuem a mostrar seu manipulador de erros de colagem padrão quando apropriado. Por exemplo, copiar/colar conteúdo no mesmo ambiente isolado não está sujeito à política de área de transferência do MDAG. Qualquer falha seria devido a um erro de colagem não relacionado, como dados corrompidos. Nesse caso, IsCrossIsolatedEnvironmentClipboardContent retornaria false, portanto, o aplicativo sabe seguir o fluxo padrão do manipulador de erros de colagem.

Exemplos

Este exemplo mostra como um aplicativo pode personalizar a mensagem de erro de colagem mostrada ao usuário. O primeiro snippet mostra como usar IsCrossIsolatedEnvironmentClipboardContent para mostrar uma mensagem de erro apropriada se o manipulador de colagem de um aplicativo falhar. Neste exemplo, o manipulador OnPaste de colagem do aplicativo (definido no segundo snippet de código) é invocado pela WM_PASTE mensagem recebida em seu 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;
}

O segundo snippet de código mostra o manipulador de colagem de um aplicativo para demonstrar como as ações da área de transferência podem falhar se bloqueadas pelo 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;
}