# Examples

## Overview

We have prepared some examples to help you implement your first Sandboxed API
library.

You can find them in
[//sandboxed_api/examples](https://github.com/google/sandboxed-api/blob/master/sandboxed_api/examples),
see below for detailed explanations.

> [!NOTE]
> **Note:** In the summer of 2020, Google interns created a number of SAPI sandboxed versions of open-source libraries which are available for download on [GitHub](https://github.com/google/sandboxed-api/tree/main/oss-internship-2020).

## hello_sapi

This is a very basic example which illustrates how SAPI works. The
[hello_lib.cc](https://github.com/google/sandboxed-api/blob/main/sandboxed_api/examples/hello_sapi/hello_lib.cc)
implements one function, `AddTwoIntegers()`, which will be sandboxed and called
in the [Host
Code](https://github.com/google/sandboxed-api/blob/main/sandboxed_api/examples/hello_sapi/hello_main.cc).

The second Host Code file,
[hello_transacted.cc](https://github.com/google/sandboxed-api/blob/main/sandboxed_api/examples/hello_sapi/hello_transacted.cc),
demonstrates an example use of [SAPI
Transactions](https://developers.google.com/code-sandboxing/sandboxed-api/transactions).

## Sum

A demo library implementing a few [C
functions](https://github.com/google/sandboxed-api/blob/master/sandboxed_api/examples/sum/lib/sum.c)
and a single [C++
function](https://github.com/google/sandboxed-api/blob/master/sandboxed_api/examples/sum/lib/sum_cpp.cc).
It uses protobufs to exchange data between Host Code and the SAPI Library.

- The sandbox definition can be found in the [sandbox.h](https://github.com/google/sandboxed-api/blob/master/sandboxed_api/examples/sum/lib/sandbox.h) file.
- The (automatically generated) function annotation file (a file providing prototypes of sandboxed functions) can be found in `bazel-out/genfiles/sandboxed_api/examples/sum/lib/sum-sapi.sapi.h` after a Bazel build.
- The actual execution logic (a.k.a. Host Code) which makes use of the exported sandboxed procedures can be found in [main_sum.cc](https://github.com/google/sandboxed-api/blob/master/sandboxed_api/examples/sum/main_sum.cc).

## zlib

This is a demo implementation (functional, but currently not used in production)
for the zlib library, exporting some of its functions and making them available
to the [Host
Code](https://github.com/google/sandboxed-api/blob/master/sandboxed_api/examples/zlib/main_zlib.cc).

The demonstrated functionality of the Host Code is decoding of zlib streams from
stdin to stdout.

This SAPI library doesn't use the `sandbox.h` file, as it uses the default
Sandbox2 policy, and an embedded SAPI library, so there is no need to provide
the `sapi::Sandbox::GetLibPath()` or the `sapi::Sandbox::GetPolicy()` method.

The zlib SAPI can be found in
[//sapi_sandbox/examples/zlib](https://github.com/google/sandboxed-api/blob/master/sandboxed_api/examples/zlib),
along with its [Host
Code](https://github.com/google/sandboxed-api/blob/master/sandboxed_api/examples/zlib/main_zlib.cc).

## stringop

This example demonstrates the use of protobufs to provide a string `reverse` and
`duplication` function. The
[library](https://github.com/google/sandboxed-api/tree/main/sandboxed_api/examples/stringop/lib)
also contains a dedicated
[sandbox.h](https://github.com/google/sandboxed-api/blob/main/sandboxed_api/examples/stringop/lib/sandbox.h)
to provide a stricter Sandbox Policy.

The [Host
Code](https://github.com/google/sandboxed-api/blob/main/sandboxed_api/examples/stringop/main_stringop.cc)
doesn't represent a "normal"program, instead it demonstrates the functionality
of the SAPI library using unit tests.

In this example, the non-protobuf based functions are also included to provide a
comparison between the two approaches.