Guida alle variabili

Introduzione

Come spiegato nella pagina Panoramica, Host Code effettua chiamate RPC alla libreria con sandbox. Il sandboxing determina una separazione della memoria tra i processi, pertanto il codice host non può accedere direttamente alla memoria nella libreria con sandbox.

Per assicurare che l'host Code possa accedere a variabili e blocchi di memoria in un processo remoto e per semplificare l'implementazione del codice logico principale, SAPI fornisce un set completo di classi C++. Tuttavia, in molti casi sarai anche in grado di utilizzare tipi C nativi.

La necessità di tipi speciali (tipi SAPI) sorge quando si passano i puntatori a tipi semplici e blocchi di memoria (strutture, array).

Ad esempio, quando si chiama una funzione che utilizza un puntatore, quest'ultimo deve essere convertito in un puntatore corrispondente all'interno della memoria della libreria con sandbox. Lo snippet di codice riportato di seguito mostra questo scenario. Anziché un array di tre numeri interi, viene creato un oggetto ::sapi::v::Array<int> che può essere passato nella chiamata API della libreria con sandbox:

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

Per una panoramica completa di tutti i tipi di SAPI disponibili, esamina i file di intestazione var_*.h nel codice sorgente del progetto SAPI. Questi file di intestazione forniscono classi e modelli che rappresentano vari tipi di dati, ad esempio:

• ::sapi::v::UChar rappresenta caratteri non firmati noti
• ::sapi::v::Array<int> rappresenta un array di numeri interi

Tipi SAPI

Questa sezione introduce tre tipi di SAPI comunemente utilizzati in Host Code.

Puntatori SAPI

Se una funzione per l'inserimento nella sandbox richiede il passaggio di un puntatore, questo deve essere ottenuto da uno dei metodi PtrXXX() riportati di seguito. Questi metodi sono implementati dalle classi di variabili SAPI.

Tipi di puntatore
::PtrNone()	Non sincronizza la memoria sottostante tra il processo Host Code e il processo Sandboxed Library quando viene passato a una funzione API con sandbox.
::PtrBefore()	Sincronizza la memoria dell'oggetto a cui rimanda prima che venga effettuata la chiamata funzione dell'API con sandbox. Ciò significa che la memoria locale della variabile puntata verrà trasferita al processo della Libreria con sandbox prima dell'inizio della chiamata.
::PtrAfter()	Sincronizza la memoria dell'oggetto a cui rimanda dopo che ha luogo la chiamata funzione dell'API con sandbox. Ciò significa che la memoria remota della variabile puntata verrà trasferita alla memoria di processo del codice host dopo il completamento della chiamata.
::PtrBoth()	Combina le funzionalità di ::PtrBefore() e ::PtrAfter().

La documentazione relativa ai puntatori SAPI è disponibile qui.

Struct SAPI

Il modello ::sapi::v::Struct è documentato in var_struct.h e fornisce un costruttore che può essere utilizzato per eseguire il wrapping di strutture esistenti. Lo struct SAPI fornisce tutti i metodi descritti nei puntatori SAPI per ottenere un oggetto ::sapi::v::Ptr che può essere utilizzato per le chiamate alle librerie con sandbox.

Lo snippet di codice riportato di seguito mostra una struttura che viene avviata e poi passata a una chiamata funzione con sandbox nell'esempio di 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 lo struct esistente contiene puntatori, questi punteranno agli indirizzi all'interno della sandbox. Di conseguenza, dovrai trasferire i dati di Sandboxee prima che siano accessibili a Host Code.

Array SAPI

Il modello ::sapi::v::Array è documentato in var_array.h e fornisce due costruttori, uno che può essere utilizzato per eseguire il wrapping di array di elementi esistenti e un altro per creare dinamicamente un array.

Questo snippet di codice (tratto dall'esempio di somma) mostra l'utilizzo del costruttore che esegue il wrapping di un array non di proprietà di questo oggetto:

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

Questo snippet di codice mostra un esempio del costruttore utilizzato per creare dinamicamente un array:

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

L'array SAPI fornisce tutti i metodi descritti in Puntatori SAPI per ottenere un oggetto ::sapi::v::Ptr che può essere utilizzato per le chiamate alla libreria con sandbox.