mirror of
https://github.com/google/sandboxed-api.git
synced 2024-03-22 13:11:30 +08:00
70 lines
2.9 KiB
Markdown
70 lines
2.9 KiB
Markdown
|
# Variables
|
||
|
|
|
||
|
|
Typically, you'll be able to use native C-types to deal with the SAPI Library,
|
||
|
|
but sometimes some special types will be required. This mainly happens when
|
||
|
|
passing pointers to simple types, and pointers to memory blocks (structures,
|
||
|
|
arrays). Because you operate on local process memory (of the host code), when
|
||
|
|
calling a function taking a pointer, it must be converted into a corresponding
|
||
|
|
pointer inside the sandboxed process (SAPI Library) memory.
|
||
|
|
|
||
|
|
Take a look at the [SAPI directory](..). The `var_*.h` files provide classes
|
||
|
|
and templates representing various types of data, e.g. `::sapi::v::UChar`
|
||
|
|
represents well-known `unsigned char` while `::sapi::v::Array<int>` represents
|
||
|
|
an array of integers (`int[]`).
|
||
|
|
|
||
|
|
|
||
|
|
## Pointers
|
||
|
|
|
||
|
|
When creating your host code, you'll be generally using functions exported by
|
||
|
|
an auto-generated SAPI interface header file from your SAPI Library. Most of
|
||
|
|
them will take simple types (or typedef'd types), but when a pointer is needed,
|
||
|
|
you need to wrap it with the `::sapi::v::Ptr` template class.
|
||
|
|
|
||
|
|
Most types that you will use, provide the following methods:
|
||
|
|
|
||
|
|
* `::PtrNone()`: this pointer, when passed to the SAPI Library function,
|
||
|
|
doesn't synchronize the underlying memory between the host code process and
|
||
|
|
the SAPI Library process.
|
||
|
|
* `::PtrBefore()`: when passed to the SAPI Library function, will synchronize
|
||
|
|
memory of the object it points to, before the call takes place. This means,
|
||
|
|
that the local memory of the pointed variable will be transferred to the
|
||
|
|
SAPI Library process before the call is initiated.
|
||
|
|
* `::PtrAfter()`: this pointer will synchronize memory of the object it points
|
||
|
|
to, after the call has taken place. This means, that the remote memory of a
|
||
|
|
pointed variable will be transferred to the host code process' memory, after
|
||
|
|
the call has been completed.
|
||
|
|
* `::PtrBoth()`: combines the functionality of both `::PtrBefore()` and
|
||
|
|
`::PtrAfter()`
|
||
|
|
|
||
|
|
|
||
|
|
## Structures
|
||
|
|
|
||
|
|
When a pointer to a structure is used inside a call to a SAPI Library, that
|
||
|
|
structure needs to created with the `::sapi::v::Struct` template. You can use
|
||
|
|
the `PtrNone()`/`Before()`/`After()`/`Both()` methods of this template to obtain
|
||
|
|
a relevant `::sapi::v::Ptr` object that can be used in SAPI Library function
|
||
|
|
calls.
|
||
|
|
|
||
|
|
|
||
|
|
## Arrays
|
||
|
|
|
||
|
|
The `::sapi::v::Array` template allow to wrap both existing arrays of elements,
|
||
|
|
as well as dynamically create one for you (please take a look at its
|
||
|
|
constructor to decide which one you would like to use).
|
||
|
|
|
||
|
|
The use of pointers is analogous to [Structures](#structures).
|
||
|
|
|
||
|
|
|
||
|
|
## Examples
|
||
|
|
|
||
|
|
Our canonical [sum library](../examples/sum/main_sum.cc) demonstrates use of
|
||
|
|
pointers to call sandboxed functions in its corresponding SAPI Library.
|
||
|
|
|
||
|
|
You might also want to take a look at the [Examples](examples.md) page to
|
||
|
|
familiarize yourself with other working examples of libraries sandboxed
|
||
|
|
with SAPI.
|
||
|
|
|
||
|
|
* [sum library](../examples/sum/main_sum.cc)
|
||
|
|
* [stringop](../examples/stringop/main_stringop.cc)
|
||
|
|
* [zlib](../examples/zlib/main_zlib.cc)
|