Guia de variáveis

Introdução

Como explicado na página Visão geral, o código do host faz chamadas de RPC para a biblioteca em sandbox. O sandbox resulta em uma separação de memória entre os processos. Assim, o código do host não pode acessar diretamente a memória na biblioteca em sandbox.

Para garantir que o código do host possa acessar variáveis e blocos de memória em um processo remoto e simplificar a implementação do código de lógica principal, a SAPI oferece um conjunto abrangente de classes C++. No entanto, em muitos casos, também é possível usar tipos C nativos.

A necessidade dos tipos especiais (tipos SAPI) surge ao transmitir ponteiros para tipos simples e blocos de memória (estruturas, matrizes).

Por exemplo, ao chamar uma função que usa um ponteiro, ele precisa ser convertido em um ponteiro correspondente na memória da biblioteca em sandbox. O snippet de código abaixo mostra esse cenário. Em vez de uma matriz de três números inteiros, um objeto ::sapi::v::Array<int> é criado e pode ser transmitido na chamada de API da biblioteca em sandbox:

int arr[3] = {1, 2, 3};
sapi::v::Array<int> sarr(arr, ABSL_ARRAYSIZE(arr));

Para uma visão geral abrangente de todos os tipos de SAPI disponíveis, consulte os arquivos de cabeçalho var_*.h no código-fonte do projeto SAPI. Esses arquivos de cabeçalho fornecem classes e modelos que representam vários tipos de dados, por exemplo:

  • ::sapi::v::UChar representa caracteres não assinados conhecidos
  • ::sapi::v::Array<int> representa uma matriz de números inteiros

Tipos de SAPI

Esta seção apresenta três tipos de SAPI comuns no código do host.

Ponteiros da SAPI

Se uma função a ser isolada precisar transmitir um ponteiro, ele deverá ser obtido de um dos métodos PtrXXX() abaixo. Esses métodos são implementados pelas classes de variáveis da SAPI.

Tipos de ponteiro
::PtrNone() Não sincroniza a memória subjacente entre o processo de código do host e o processo da biblioteca em sandbox quando transmitido para uma função de API em sandbox.
::PtrBefore() Sincroniza a memória do objeto apontado antes da chamada de função da API no modo sandbox. Isso significa que a memória local da variável apontada será transferida para o processo da biblioteca em sandbox antes do início da chamada.
::PtrAfter() Sincroniza a memória do objeto a que ele aponta depois que a chamada de função da API no modo sandbox é feita. Isso significa que a memória remota da variável apontada será transferida para a memória do processo de código do host depois que a chamada for concluída.
::PtrBoth() Combina a funcionalidade de ::PtrBefore() e ::PtrAfter().

A documentação para ponteiros da SAPI está disponível aqui.

Estrutura da SAPI

O modelo ::sapi::v::Struct está documentado em var_struct.h. Ele fornece um construtor que pode ser usado para encapsular estruturas atuais. A struct SAPI fornece todos os métodos descritos em Ponteiros SAPI para receber um objeto ::sapi::v::Ptr que pode ser usado para chamadas de biblioteca em sandbox.

O snippet de código abaixo mostra uma estrutura sendo iniciada e transmitida para uma chamada de função em sandbox no exemplo zlib:

sapi::v::Struct<sapi::zlib::z_stream> strm;
…
if (ret = api.deflateInit_(strm.PtrBoth(), Z_DEFAULT_COMPRESSION,
                             version.PtrBefore(), sizeof(sapi::zlib::z_stream));
…

Se o struct atual tiver ponteiros, eles vão apontar para endereços no Sandboxee. Como consequência, você terá que transferir os dados do Sandboxee antes que eles fiquem acessíveis ao código do host.

Matrizes da SAPI

O modelo ::sapi::v::Array está documentado em var_array.h. Ele oferece dois construtores: um que pode ser usado para agrupar matrizes de elementos e outro para criar uma matriz dinamicamente.

Este snippet de código (extraído do exemplo de soma) mostra o uso do construtor que envolve uma matriz que não pertence a este objeto:

int arr[10];
sapi::v::Array<int> iarr(arr, ABSL_ARRAYSIZE(arr));

Este snippet de código mostra um exemplo do construtor usado para criar dinamicamente uma matriz:

sapi::v::Array<uint8_t> buffer(PNG_IMAGE_SIZE(*image.mutable_data()));

O SAPI Array fornece todos os métodos descritos em Ponteiros SAPI para receber um objeto ::sapi::v::Ptr que pode ser usado para chamadas de biblioteca em sandbox.