Panduan Variabel

Pengantar

Seperti yang dijelaskan di halaman Ringkasan, Host Code melakukan panggilan RPC ke Library Sandbox. Sandboxing menghasilkan pemisahan memori di antara proses sehingga Kode Host tidak dapat langsung mengakses memori di Library dengan Sandbox.

Untuk memastikan bahwa Host Code dapat mengakses variabel dan blok memori dalam proses jarak jauh dan untuk membuat implementasi kode logika utama menjadi lebih sederhana, SAPI menyediakan rangkaian class C++ yang komprehensif. Namun, dalam banyak kasus, Anda juga dapat menggunakan jenis C native.

Kebutuhan akan jenis khusus (Tipe SAPI) muncul ketika meneruskan pointer ke jenis sederhana dan blok memori (struktur, array).

Misalnya, saat memanggil fungsi yang menggunakan pointer, pointer harus dikonversi menjadi pointer yang sesuai di dalam memori Library Sandbox. Cuplikan kode di bawah memvisualisasikan skenario ini. Sebagai ganti array tiga bilangan bulat, objek ::sapi::v::Array<int> dibuat yang kemudian dapat diteruskan dalam panggilan API Library dengan Sandbox:

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

Untuk ringkasan komprehensif tentang semua Jenis SAPI yang tersedia, tinjau file header var_*.h di kode sumber project SAPI. File header ini menyediakan class dan template yang mewakili berbagai jenis data, misalnya:

  • ::sapi::v::UChar mewakili karakter tidak bertanda tangan yang dikenal
  • ::sapi::v::Array<int> mewakili array bilangan bulat

Jenis SAPI

Bagian ini memperkenalkan tiga Jenis SAPI yang umum ditemukan di Kode Host.

Pointer SAPI

Jika fungsi yang akan di-sandbox memerlukan penerusan pointer, pointer ini harus diperoleh dari salah satu metode PtrXXX() di bawah. Metode ini diimplementasikan oleh class variabel SAPI.

Jenis Pointer
::PtrNone() Tidak menyinkronkan memori dasar antara proses Kode Host dan proses Library dengan Sandbox saat diteruskan ke fungsi API dengan sandbox.
::PtrBefore() Menyinkronkan memori objek yang ditunjuk sebelum panggilan fungsi API dengan sandbox berlangsung. Ini berarti memori lokal dari variabel yang ditunjuk akan ditransfer ke proses Library dengan Sandbox sebelum panggilan dimulai.
::PtrAfter() Menyinkronkan memori objek yang ditunjuk setelah panggilan fungsi API dengan sandbox berlangsung. Artinya, memori jarak jauh dari variabel yang ditunjuk akan ditransfer ke memori proses Kode Host setelah panggilan selesai.
::PtrBoth() Menggabungkan fungsi ::PtrBefore() dan ::PtrAfter().

Dokumentasi untuk pointer SAPI dapat ditemukan di sini.

Struktur SAPI

Template ::sapi::v::Struct didokumentasikan dalam var_struct.h. Template ini menyediakan konstruktor yang dapat digunakan untuk menggabungkan struktur yang ada. SAPI Struct menyediakan semua metode yang dijelaskan dalam Pointer SAPI untuk mendapatkan objek ::sapi::v::Ptr yang dapat digunakan untuk panggilan library dalam sandbox.

Cuplikan kode di bawah ini menunjukkan struktur yang dimulai, lalu diteruskan ke panggilan fungsi dengan sandbox dalam contoh 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));
…

Jika struct yang ada berisi pointer, pointer tersebut akan mengarah ke alamat di Sandboxee. Akibatnya, Anda harus mentransfer data Sandboxee sebelum data tersebut dapat diakses oleh Kode Host.

Array SAPI

Template ::sapi::v::Array didokumentasikan dalam var_array.h. Template ini menyediakan dua konstruktor, satu konstruktor dapat digunakan untuk menggabungkan array elemen yang ada, dan satu lagi untuk membuat array secara dinamis.

Cuplikan kode ini (diambil dari contoh jumlah) menunjukkan penggunaan konstruktor yang menggabungkan array yang tidak dimiliki oleh objek ini:

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

Cuplikan kode ini menunjukkan contoh konstruktor yang digunakan untuk membuat array secara dinamis:

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

Array SAPI menyediakan semua metode yang dijelaskan dalam Pointer SAPI untuk mendapatkan objek ::sapi::v::Ptr yang dapat digunakan untuk panggilan library dalam sandbox.