वैरिएबल गाइड

परिचय

खास जानकारी पेज पर बताया गया है कि होस्ट कोड, सैंडबॉक्स की गई लाइब्रेरी को आरपीसी कॉल करता है. सैंडबॉक्सिंग की वजह से, प्रोसेस के बीच मेमोरी अलग हो जाती है. इसलिए, होस्ट कोड सीधे तौर पर सैंडबॉक्स की गई लाइब्रेरी में मौजूद मेमोरी को ऐक्सेस नहीं कर सकता.

यह पक्का करने के लिए कि होस्ट कोड, रिमोट प्रोसेस में मौजूद वैरिएबल और मेमोरी ब्लॉक को ऐक्सेस कर सके और मुख्य लॉजिक कोड को आसानी से लागू किया जा सके, SAPI C++ क्लास का एक पूरा सेट उपलब्ध कराता है. हालांकि, कई मामलों में नेटिव सी-टाइप का इस्तेमाल भी किया जा सकेगा.

जब पॉइंटर को सामान्य टाइप और मेमोरी ब्लॉक (स्ट्रक्चर, ऐरे) में पास किया जाता है, तब खास टाइप (सैपी टाइप) की ज़रूरत होती है.

उदाहरण के लिए, पॉइंटर लेने वाले फ़ंक्शन को कॉल करते समय, पॉइंटर को सैंडबॉक्स की गई लाइब्रेरी की मेमोरी में मौजूद पॉइंटर में बदलना होगा. नीचे दिए गए कोड स्निपेट में, इस स्थिति को दिखाया गया है. तीन पूर्णांकों की ऐरे के बजाय, एक ::sapi::v::Array<int> ऑब्जेक्ट बनाया जाता है. इसके बाद, इसे सैंडबॉक्स की गई लाइब्रेरी के एपीआई कॉल में पास किया जा सकता है:

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

उपलब्ध सभी SAPI टाइप के बारे में पूरी जानकारी पाने के लिए, var_*.hSAPI प्रोजेक्ट के सोर्स कोड में मौजूद हेडर फ़ाइलें देखें. ये हेडर फ़ाइलें, अलग-अलग तरह के डेटा को दिखाने वाली क्लास और टेंप्लेट उपलब्ध कराती हैं. जैसे:

• ::sapi::v::UChar से, बिना हस्ताक्षर वाले जाने-माने वर्णों के बारे में पता चलता है
• ::sapi::v::Array<int> पूर्णांकों की एक कैटगरी दिखाता है

SAPI के टाइप

इस सेक्शन में, तीन तरह के SAPI के बारे में बताया गया है. ये SAPI, होस्ट कोड में आम तौर पर दिखते हैं.

SAPI पॉइंटर

अगर सैंडबॉक्स किए जाने वाले किसी फ़ंक्शन के लिए पॉइंटर पास करना ज़रूरी है, तो यह पॉइंटर नीचे दिए गए PtrXXX() तरीकों में से किसी एक से हासिल किया जाना चाहिए. इन तरीकों को SAPI वैरिएबल क्लास लागू करती हैं.

पॉइंटर के टाइप
::PtrNone()	सैंडबॉक्स किए गए एपीआई फ़ंक्शन को पास किए जाने पर, होस्ट कोड प्रोसेस और सैंडबॉक्स की गई लाइब्रेरी प्रोसेस के बीच की मेमोरी को सिंक नहीं करता है.
::PtrBefore()	यह उस ऑब्जेक्ट की मेमोरी को सिंक करता है जिसे यह पॉइंट करता है. ऐसा सैंडबॉक्स किए गए एपीआई फ़ंक्शन कॉल के पहले होता है. इसका मतलब है कि कॉल शुरू होने से पहले, पॉइंट किए गए वैरिएबल की लोकल मेमोरी को सैंडबॉक्स लाइब्रेरी प्रोसेस में ट्रांसफ़र कर दिया जाएगा.
::PtrAfter()	यह सैंडबॉक्स किए गए एपीआई फ़ंक्शन कॉल के बाद, उस ऑब्जेक्ट की मेमोरी को सिंक करता है जिसे यह पॉइंट करता है. इसका मतलब है कि पॉइंट किए गए वैरिएबल की रिमोट मेमोरी, कॉल पूरा होने के बाद होस्ट कोड प्रोसेस मेमोरी में ट्रांसफ़र हो जाएगी.
::PtrBoth()	इसमें ::PtrBefore() और ::PtrAfter(), दोनों की सुविधाएं मिलती हैं.

SAPI पॉइंटर के बारे में दस्तावेज़ यहां देखा जा सकता है.

SAPI Struct

टेंप्लेट ::sapi::v::Struct के बारे में var_struct.h में बताया गया है. यह एक कंस्ट्रक्टर उपलब्ध कराता है, जिसका इस्तेमाल मौजूदा स्ट्रक्चर को रैप करने के लिए किया जा सकता है. SAPI Struct, ::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));
…

अगर आपके मौजूदा स्ट्रक्चर में पॉइंटर शामिल हैं, तो वे पॉइंटर सैंडबॉक्सी में मौजूद पतों की ओर पॉइंट करेंगे. इसलिए, आपको सैंडबॉक्सी के डेटा को ट्रांसफ़र करना होगा, ताकि होस्ट कोड इसे ऐक्सेस कर सके.

SAPI कलेक्शन

टेंप्लेट ::sapi::v::Array के बारे में var_array.h में बताया गया है. यह दो कंस्ट्रक्टर उपलब्ध कराता है. इनमें से एक का इस्तेमाल, एलिमेंट के मौजूदा ऐरे को रैप करने के लिए किया जा सकता है. वहीं, दूसरे का इस्तेमाल डाइनैमिक तरीके से ऐरे बनाने के लिए किया जा सकता है.

यह कोड स्निपेट (sum example से लिया गया) दिखाता है कि कंस्ट्रक्टर का इस्तेमाल कैसे किया जाता है. यह कंस्ट्रक्टर, उस ऐरे को रैप करता है जिसका मालिकाना हक इस ऑब्जेक्ट के पास नहीं है:

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 Array, ::sapi::v::Ptr ऑब्जेक्ट पाने के लिए SAPI पॉइंटर में बताए गए सभी तरीके उपलब्ध कराता है. इस ऑब्जेक्ट का इस्तेमाल, सैंडबॉक्स की गई लाइब्रेरी कॉल के लिए किया जा सकता है.