Introduction
Comme expliqué sur la page Présentation, le code hôte effectue des appels RPC vers 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 à distance et pour simplifier l'implémentation du code logique principal, SAPI fournit un ensemble complet de classes C++. Toutefois, dans de nombreux cas, vous pourrez également utiliser des C-types natifs.
Les types spéciaux (types SAPI) sont nécessaires lors de la transmission de pointeurs à des types simples et des blocs de mémoire (structures, tableaux).
Par exemple, lorsque vous appelez une fonction qui utilise un pointeur, celui-ci doit être converti en un pointeur correspondant dans la mémoire de la bibliothèque en bac à sable. 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éé. Il peut ensuite être transmis dans l'appel d'API de la bibliothèque Sandboxed:
int arr[3] = {1, 2, 3};
sapi::v::Array<int> sarr(arr, ABSL_ARRAYSIZE(arr));
Pour une présentation complète de tous les types de 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 à bac à sable nécessite la transmission d'un pointeur, celui-ci 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 en bac à sable lorsqu'elle est transmise à une fonction d'API en bac à sable. |
::PtrBefore() |
Synchronise la mémoire de l'objet qu'il pointe avant l'appel de la fonction de l'API en bac à sable. Cela signifie que la mémoire locale de la variable pointée sera transférée vers le processus de la bibliothèque Sandboxed avant le lancement de l'appel. |
::PtrAfter() |
Synchronise la mémoire de l'objet qu'il pointe après l'appel de la fonction de l'API en bac à sable. Cela signifie que la mémoire distante de la variable pointée sera transférée vers la mémoire de traitement du code hôte une fois l'appel terminé. |
::PtrBoth() |
Combine les fonctionnalités de ::PtrBefore() et ::PtrAfter(). |
La documentation sur les pointeurs SAPI est disponible ici.
Struct 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 la section 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 lancée, 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 structure existante contient des pointeurs, ceux-ci pointeront vers des adresses dans Sandboxee. Vous devez donc transférer les données du bac à sable avant qu'elles ne soient accessibles au code de l'hôte.
Tableaux SAPI
Le modèle ::sapi::v::Array est documenté dans var_array.h. Il fournit deux constructeurs, l'un permettant d'encapsuler des tableaux d'éléments existants et l'autre de créer un tableau de façon dynamique.
Cet extrait de code (extrait de l'exemple de somme) montre comment utiliser le constructeur qui encapsule un tableau n'appartenant 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 la section Pointeurs SAPI pour obtenir un objet ::sapi::v::Ptr pouvant être utilisé pour les appels de bibliothèque en bac à sable.