Introduction
Comme expliqué sur la page Présentation, le code hôte effectue des appels RPC à la bibliothèque en bac à sable. Le bac à sable entraîne une séparation de la mémoire entre les processus. Par conséquent, le code hôte ne peut pas accéder directement à la mémoire de la bibliothèque en bac à sable.
Pour s'assurer que le code hôte peut accéder aux variables et aux blocs de mémoire dans un processus distant, et pour simplifier l'implémentation du code de logique principal, SAPI fournit un ensemble complet de classes C++. Toutefois, dans de nombreux cas, vous pourrez également utiliser des types C natifs.
Les types spéciaux (types SAPI) sont nécessaires lorsque vous transmettez des pointeurs à des types simples et à des blocs de mémoire (structures, tableaux).
Par exemple, lors de l'appel d'une fonction prenant un pointeur, le pointeur doit être converti en pointeur correspondant dans la mémoire de la bibliothèque sandboxée.
L'extrait de code ci-dessous illustre ce scénario. Au lieu d'un tableau de trois entiers, un objet ::sapi::v::Array<int> est créé, qui peut ensuite être transmis dans l'appel d'API de la bibliothèque bac à sable :
int arr[3] = {1, 2, 3};
sapi::v::Array<int> sarr(arr, ABSL_ARRAYSIZE(arr));
Pour obtenir une présentation complète de tous les types SAPI disponibles, consultez les fichiers d'en-tête var_*.h dans le code source du projet SAPI. Ces fichiers d'en-tête fournissent des classes et des modèles représentant différents types de données, par exemple :
::sapi::v::UCharreprésente des caractères non signés connus.::sapi::v::Array<int>représente un tableau d'entiers.
Types de SAPI
Cette section présente trois types de SAPI couramment utilisés dans le code hôte.
Pointeurs SAPI
Si une fonction à mettre en bac à sable nécessite de transmettre un pointeur, ce pointeur doit être obtenu à partir de l'une des méthodes PtrXXX() ci-dessous. Ces méthodes sont implémentées par les classes de variables SAPI.
| Types de pointeurs | |
|---|---|
::PtrNone() |
Ne synchronise pas la mémoire sous-jacente entre le processus de code hôte et le processus de bibliothèque sandbox lorsqu'il est transmis à une fonction d'API sandbox. |
::PtrBefore() |
Synchronise la mémoire de l'objet vers lequel il pointe avant l'appel de la fonction API dans le bac à sable. Cela signifie que la mémoire locale de la variable pointée sera transférée au processus de la bibliothèque bac à sable avant le lancement de l'appel. |
::PtrAfter() |
Synchronise la mémoire de l'objet vers lequel il pointe après l'appel de la fonction d'API dans le bac à sable. Cela signifie que la mémoire distante de la variable pointée sera transférée à la mémoire du processus du code hôte après l'exécution de l'appel. |
::PtrBoth() |
Combine les fonctionnalités de ::PtrBefore() et ::PtrAfter(). |
Pour accéder à la documentation sur les pointeurs SAPI, cliquez ici.
Structure SAPI
Le modèle ::sapi::v::Struct est documenté dans var_struct.h. Il fournit un constructeur qui peut être utilisé pour encapsuler des structures existantes. SAPI_Struct fournit toutes les méthodes décrites dans Pointeurs SAPI pour obtenir un objet ::sapi::v::Ptr pouvant être utilisé pour les appels de bibliothèque en bac à sable.
L'extrait de code ci-dessous montre une structure en cours d'initialisation, puis transmise à un appel de fonction en bac à sable dans l'exemple 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));
…
Si votre struct existant contient des pointeurs, ceux-ci pointeront vers des adresses dans le Sandboxee. Par conséquent, vous devrez transférer les données Sandboxee avant qu'elles ne deviennent accessibles au code hôte.
Tableaux SAPI
Le modèle ::sapi::v::Array est documenté dans var_array.h. Il fournit deux constructeurs : l'un peut être utilisé pour encapsuler des tableaux d'éléments existants et l'autre pour créer un tableau de manière dynamique.
Cet extrait de code (tiré de l'exemple de somme) montre l'utilisation du constructeur qui encapsule un tableau qui n'appartient pas à cet objet :
int arr[10];
sapi::v::Array<int> iarr(arr, ABSL_ARRAYSIZE(arr));
Cet extrait de code montre un exemple de constructeur utilisé pour créer un tableau de manière dynamique :
sapi::v::Array<uint8_t> buffer(PNG_IMAGE_SIZE(*image.mutable_data()));
SAPI Array fournit toutes les méthodes décrites dans Pointeurs SAPI pour obtenir un objet ::sapi::v::Ptr pouvant être utilisé pour les appels de bibliothèque en bac à sable.