sandboxed-api/sandboxed_api/docs/variables.md

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.

Examples

Our canonical sum library demonstrates use of pointers to call sandboxed functions in its corresponding SAPI Library.

You might also want to take a look at the Examples page to familiarize yourself with other working examples of libraries sandboxed with SAPI.

• sum library
• stringop
• zlib