변수 가이드
컬렉션을 사용해 정리하기
내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.
소개
개요 페이지에 설명된 대로 호스트 코드에서 샌드박스 라이브러리에 RPC 호출을 실행합니다. 샌드박싱으로 인해 프로세스 간에 메모리가 분리되므로 호스트 코드는 샌드박스 라이브러리의 메모리에 직접 액세스할 수 없습니다.
호스트 코드에서 원격 프로세스의 변수와 메모리 블록에 액세스할 수 있고 기본 로직 코드의 구현을 더 간단하게 할 수 있도록 SAPI는 포괄적인 C++ 클래스 집합을 제공합니다. 하지만 대부분의 경우 네이티브 C 유형도 사용할 수 있습니다.
특수 유형 (SAPI 유형)은 단순 유형과 메모리 블록 (구조체, 배열)에 포인터를 전달할 때 필요합니다.
예를 들어 포인터를 사용하는 함수를 호출할 때 포인터는 샌드박스 라이브러리의 메모리 내에서 해당 포인터로 변환되어야 합니다.
아래 코드 스니펫은 이 시나리오를 시각화합니다. 정수 3개로 된 배열 대신 샌드박스 라이브러리의 API 호출에 전달할 수 있는 ::sapi::v::Array<int> 객체가 생성됩니다.
int arr[3] = {1, 2, 3};
sapi::v::Array<int> sarr(arr, ABSL_ARRAYSIZE(arr));
사용 가능한 모든 SAPI 유형에 대한 포괄적인 개요는 SAPI 프로젝트 소스 코드의 var_*.h 헤더 파일을 검토하세요. 이러한 헤더 파일은 다음과 같은 다양한 유형의 데이터를 나타내는 클래스와 템플릿을 제공합니다.
::sapi::v::UChar는 잘 알려진 서명되지 않은 문자를 나타냅니다.::sapi::v::Array<int>는 정수 배열을 나타냅니다.
SAPI 유형
이 섹션에서는 호스트 코드에서 흔히 볼 수 있는 세 가지 SAPI 유형을 소개합니다.
SAPI 포인터
샌드박스 처리할 함수에 포인터를 전달해야 하는 경우 이 포인터는 아래 PtrXXX() 메서드 중 하나에서 가져와야 합니다. 이러한 메서드는 SAPI 변수 클래스에 의해 구현됩니다.
| 포인터 유형 |
|---|
::PtrNone() |
샌드박스 처리된 API 함수에 전달될 때 호스트 코드 프로세스와 샌드박스 처리된 라이브러리 프로세스 간에 기본 메모리를 동기화하지 않습니다. |
::PtrBefore() |
샌드박스 처리된 API 함수 호출이 발생하기 전에 가리키는 객체의 메모리를 동기화합니다.
즉, 호출이 시작되기 전에 포인팅된 변수의 로컬 메모리가 샌드박스 라이브러리 프로세스로 전송됩니다. |
::PtrAfter() |
샌드박스 처리된 API 함수 호출이 발생한 후에 가리키는 객체의 메모리를 동기화합니다.
즉, 호출이 완료된 후에 포인팅된 변수의 원격 메모리가 호스트 코드 프로세스 메모리로 전송됩니다. |
::PtrBoth() |
::PtrBefore() 및 ::PtrAfter()의 기능을 결합합니다. |
SAPI 포인터에 관한 문서는 여기에서 확인할 수 있습니다.
SAPI 구조체
템플릿 ::sapi::v::Struct는 var_struct.h에 문서화되어 있습니다. 기존 구조체를 래핑하는 데 사용할 수 있는 생성자를 제공합니다. SAPI 구조체는 샌드박스 라이브러리 호출에 사용할 수 있는 ::sapi::v::Ptr 객체를 가져오기 위해 SAPI 포인터에 설명된 모든 메서드를 제공합니다.
아래 코드 스니펫은 구조가 초기화된 후 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));
…
기존 구조체에 포인터가 포함된 경우 이러한 포인터는 샌드박스 내 주소를 가리킵니다. 따라서 호스트 코드에서 액세스할 수 있게 되기 전에 Sandboxee 데이터를 전송해야 합니다.
SAPI 배열
템플릿 ::sapi::v::Array는 var_array.h에 문서화되어 있습니다. 이 템플릿은 기존 요소 배열을 래핑하는 데 사용할 수 있는 생성자와 배열을 동적으로 생성하는 생성자 두 개를 제공합니다.
이 코드 스니펫 (sum 예에서 가져옴)은 이 객체가 소유하지 않은 배열을 래핑하는 생성자의 사용을 보여줍니다.
int arr[10];
sapi::v::Array<int> iarr(arr, ABSL_ARRAYSIZE(arr));
다음 코드 스니펫은 배열을 동적으로 만드는 데 사용되는 생성자의 예를 보여줍니다.
sapi::v::Array<uint8_t> buffer(PNG_IMAGE_SIZE(*image.mutable_data()));
SAPI 배열은 샌드박스 라이브러리 호출에 사용할 수 있는 ::sapi::v::Ptr 객체를 가져오기 위해 SAPI 포인터에 설명된 모든 메서드를 제공합니다.
달리 명시되지 않는 한 이 페이지의 콘텐츠에는 Creative Commons Attribution 4.0 라이선스에 따라 라이선스가 부여되며, 코드 샘플에는 Apache 2.0 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 Google Developers 사이트 정책을 참조하세요. 자바는 Oracle 및/또는 Oracle 계열사의 등록 상표입니다.
최종 업데이트: 2025-07-26(UTC)
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["필요한 정보가 없음","missingTheInformationINeed","thumb-down"],["너무 복잡함/단계 수가 너무 많음","tooComplicatedTooManySteps","thumb-down"],["오래됨","outOfDate","thumb-down"],["번역 문제","translationIssue","thumb-down"],["샘플/코드 문제","samplesCodeIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-07-26(UTC)"],[[["\u003cp\u003eSandboxed API (SAPI) provides C++ classes (SAPI Types) to enable the Host Code to interact with memory in the Sandboxed Library, particularly for pointers, structures, and arrays.\u003c/p\u003e\n"],["\u003cp\u003eSAPI Pointers (\u003ccode\u003ePtrNone\u003c/code\u003e, \u003ccode\u003ePtrBefore\u003c/code\u003e, \u003ccode\u003ePtrAfter\u003c/code\u003e, \u003ccode\u003ePtrBoth\u003c/code\u003e) control the synchronization of memory between the Host Code and the Sandboxed Library before and after API calls.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003e::sapi::v::Struct\u003c/code\u003e template allows wrapping existing structures for use in sandboxed calls, requiring pointer synchronization for sandboxee data accessibility.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003e::sapi::v::Array\u003c/code\u003e template enables working with arrays in sandboxed environments, offering constructors for wrapping existing arrays and dynamic array creation.\u003c/p\u003e\n"],["\u003cp\u003eRefer to the \u003ccode\u003evar_*.h\u003c/code\u003e header files in the SAPI project source code for a detailed overview of all available SAPI Types and their usage.\u003c/p\u003e\n"]]],[],null,["Introduction\n\nAs explained on the [Overview](/code-sandboxing/sandboxed-api) page, the Host\nCode makes RPC calls to the Sandboxed Library. Sandboxing results in a memory\nseparation between the processes, and thus the Host Code cannot directly access\nmemory in the Sandboxed Library.\n\nIn order to make sure that the Host Code can access variables and memory blocks\nin a remote process and to make the implementation of the main logic code\nsimpler, SAPI provides a comprehensive set of C++ classes. However, in many\ncases you will also be able to use native C-types.\n\nThe need for the special types (SAPI Types) arises when passing pointers to\nsimple types and memory blocks (structures, arrays).\n\nFor example, when calling a function taking a pointer, the pointer must be\nconverted into a corresponding pointer inside the Sandboxed Library's memory.\nThe below code snippet visualises this scenario. Instead of an array of three\nintegers, a `::sapi::v::Array\u003cint\u003e` object is created which can then be passed\nin the Sandboxed Library's API call: \n\n int arr[3] = {1, 2, 3};\n sapi::v::Array\u003cint\u003e sarr(arr, ABSL_ARRAYSIZE(arr));\n\nFor a comprehensive overview of all available SAPI Types, review the `var_*.h`\nheader files in the [SAPI project source\ncode](https://github.com/google/sandboxed-api/tree/master/sandboxed_api). These\nheader files provide classes and templates representing various types of data,\ne.g.:\n\n- `::sapi::v::UChar` represents well-known unsigned chars\n- `::sapi::v::Array\u003cint\u003e` represents an array of integers\n\nSAPI Types\n\nThis section introduces three SAPI Types that are commonly seen in Host Code.\n\nSAPI Pointers\n\nIf a function to be sandboxed requires passing a pointer, this pointer should be\nobtained from one of the `PtrXXX()` methods below. These methods are implemented\nby the SAPI variable classes.\n\n| Pointer Types ||\n|-----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `::PtrNone()` | Doesn't synchronize the underlying memory between the Host Code process and the Sandboxed Library process when passed to a sandboxed API function. |\n| `::PtrBefore()` | Synchronizes the memory of the object it points to **before** the sandboxed API function call takes place. This means the local memory of the pointed variable will be transferred to the Sandboxed Library process before the call is initiated. |\n| `::PtrAfter()` | Synchronizes the memory of the object it points to **after** the sandboxed API function call takes place. This means the remote memory of the pointed variable will be transferred to the Host Code process memory **after** the call has been completed. |\n| `::PtrBoth()` | Combines the functionality of `::PtrBefore()` and `::PtrAfter()`. |\n\nThe documentation for SAPI pointers can be found\n[here](https://github.com/google/sandboxed-api/blob/main/sandboxed_api/var_pointable.h).\n\nSAPI Struct\n\nThe template `::sapi::v::Struct` is documented in\n[var_struct.h](https://github.com/google/sandboxed-api/blob/main/sandboxed_api/var_struct.h).\nIt provides a constructor that can be used to wrap existing structures. SAPI\nStruct provides all methods outlined in [SAPI Pointers](#sapi_pointers) to\nobtain a `::sapi::v::Ptr` object that can be used for sandboxed library calls.\n\nThe code snippet below shows a structure being initiated and then passed to a\nsandboxed function call in the [zlib\nexample](https://github.com/google/sandboxed-api/blob/main/sandboxed_api/examples/zlib/main_zlib.cc): \n\n sapi::v::Struct\u003csapi::zlib::z_stream\u003e strm;\n ...\n if (ret = api.deflateInit_(strm.PtrBoth(), Z_DEFAULT_COMPRESSION,\n version.PtrBefore(), sizeof(sapi::zlib::z_stream));\n ...\n\nIf your existing struct contains pointers, then those pointers will point to\naddresses in the Sandboxee. In consequence, you will have to transfer Sandboxee\ndata before it becomes accessible to the Host Code.\n\nSAPI Arrays\n\nThe template `::sapi::v::Array` is documented in\n[var_array.h](https://github.com/google/sandboxed-api/blob/main/sandboxed_api/var_array.h).\nIt provides two constructors, one that can be used to wrap existing arrays of\nelements, and another one to dynamically create an array.\n\nThis code snippet (taken from the [sum\nexample](/code-sandboxing/sandboxed-api/examples#sum)) shows the use of the\nconstructor that wraps around an array which is not owned by this object: \n\n int arr[10];\n sapi::v::Array\u003cint\u003e iarr(arr, ABSL_ARRAYSIZE(arr));\n\nThis code snippet shows an example of the constructor used to dynamically create\nan array: \n\n sapi::v::Array\u003cuint8_t\u003e buffer(PNG_IMAGE_SIZE(*image.mutable_data()));\n\nSAPI Array provides all methods outlined in [SAPI Pointers](#sapi_pointers) to\nobtain a `::sapi::v::Ptr` object that can be used for sandboxed library calls."]]
