Android APIs के लिए लाइब्रेरी रैपर Android गेम डेवलपमेंट किट का हिस्सा.

लाइब्रेरी रैपर एक कमांड-लाइन टूल (सीएलआई) है, जो सी-भाषा को जनरेट करता है Java में लिखे गए Android APIs के लिए रैपर कोड. आप इसका इस्तेमाल कर सकते हैं मैन्युअल तरीके से ज़रूरत के बिना Java API को कॉल करने के लिए, नेटिव Android ऐप्लिकेशन में कोड Java नेटिव इंटरफ़ेस या जेएनआई बनाएं. इस टूल से डेवलपमेंट की प्रक्रिया आसान हो सकती है ऐसे Android ऐप्लिकेशन जो मुख्य रूप से C या C++ में लिखे गए हैं.

यह टूल, इमेज में मौजूद सार्वजनिक सिंबल के लिए C कोड जनरेट करके काम करता है आपकी दी गई Java संग्रह (JAR) फ़ाइलें या टूल में तय की गई क्लास कॉन्फ़िगरेशन फ़ाइल या फिर दोनों का इस्तेमाल करता है. टूल से जनरेट किया गया कोड Java की जगह नहीं ले लेता एपीआई; यह आपके C कोड और Java के बीच पुल का काम करता है. आपका ऐप्लिकेशन अब भी मौजूद है यह ज़रूरी है कि आपने जिन Java लाइब्रेरी को रैप किया है उन्हें आपके प्रोजेक्ट में शामिल किया जाए.

डाउनलोड करें

लाइब्रेरी रैपर संग्रह डाउनलोड करें और इसके कॉन्टेंट को डायरेक्ट्री में अनपैक करें आपकी पसंद के हिसाब से.

वाक्य-विन्यास

लाइब्रेरी रैपर टूल में यह कमांड लाइन सिंटैक्स होता है:

java -jar lw.jar \
  [-i jar-file-to-be-wrapped] \
  [-o output-path] \
  [-c config-file] \
  [-fa allow-list-file] \
  [-fb block-list-file] \
  [--skip_deprecated_symbols]

रैपर कॉन्फ़िगरेशन फ़ाइल

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

{
  // An array of type-specific configs. A type config is useful when a user wants to map
  // a Java type to a manually defined C type without generating the code. For example, when a developer
  // has their own implementation of the "java.lang.String" class, they can tell the generator to use it
  // instead of generating it.
  "type_configs": [
    {
      // [Required] Name of a fully qualified Java type.
      "java_type": "java.lang.String",
      // The C type that the java_type will be mapped to.
      "map_to": "MyOwnStringImplementation",
      // A header file that contains the declaration of the "map_to" type.
      "source_of_definition": "my_wrappers/my_own_string_implementation.h",
      // Controls if a value should be passed by pointer or value.
      "pass_by_value": false
    }
  ],
  // An array of package-specific configs.
  "package_configs": [
    {
      // [Required] A name of a Java package that this section regards. A wildchar * can be used at the
      // end of the package name to apply this config to all packages whose name starts with this value.
      "package_name": "androidx.core.app*",
      // A subdirectory relative to the root directory where the generated code will be located.
      "sub_directory": "androidx_generated/",
      // If true, the generated file structure reflects the package name. For example, files generated
      // for the package com.google.tools will be placed in the directory com/google/tools/.
      "file_location_by_package_name": true,
      // A prefix added to all class names from this package.
      "code_prefix": "Gen",
      // A prefix added to all generated file names from this package.
      "file_prefix": = "gen_"
    }
  ],
  // An array of manually defined classes for wrapping. Defining classes manually is useful when a
  // jar file with desired classes are not available or a user needs to wrap just a small part of an SDK.
  "custom_classes": [
    {
      // [Required] A fully-qualified Java class name. To define inner class, use symbol "$", for example
      // "class com.example.OuterClass$InnerClass".
      "class_name": "class java.util.ArrayList<T>",
      // List of methods.
      "methods": [
        "ArrayList()", // Example of a constructor.
        "boolean add(T e)", // Example of a method that takes a generic parameter.
        "T get(int index)", // Example of a method that returns a generic parameter.
        "int size()" // Example of parameterless method.
      ]
    },
  ]
}

फ़ाइलें फ़िल्टर करें

आपको जिन JAR फ़ाइलों को रैप करना है उनसे कुछ सिंबल को बाहर रखने से मदद मिल सकती है. आपने लोगों तक पहुंचाया मुफ़्त में आपके कॉन्फ़िगरेशन में, सिंबल शामिल न करने के लिए कोई फ़िल्टर फ़ाइल तय कर सकता है. फ़िल्टर फ़ाइल एक सामान्य टेक्स्ट फ़ाइल होती है, जहां हर लाइन किसी सिंबल के बारे में बताती है जिसे रैप करना है. फ़ाइलों को फ़िल्टर करने की सुविधा नीचे दिया गया सिंटैक्स:

java-symbol-name java-jni-type-signature

फ़िल्टर फ़ाइल का एक उदाहरण नीचे दिया गया है:

# Class filter
java.util.ArrayList Ljava.util.ArrayList;

# Method filter
java.util.ArrayList.lastIndexOf (Ljava.lang.Object;)I

# Field filter
android.view.KeyEvent.KEYCODE_ENTER I

कॉन्फ़िगरेशन के लिए फ़िल्टर फ़ाइल उपलब्ध कराई जाती है, जिसमें सिंबल शामिल किए जाते हैं -fa पैरामीटर का इस्तेमाल करने की अनुमति है, जबकि ब्लॉक किए गए सिंबल -fb का इस्तेमाल करके इस्तेमाल किए जा सकते हैं पैरामीटर. दोनों पैरामीटर एक साथ इस्तेमाल किए जा सकते हैं. अगर दोनों फ़िल्टर अगर किसी सिंबल को अनुमति वाली फ़िल्टर फ़ाइल में तय किया गया है, तो उसे रैप कर दिया जाएगा और यह ब्लॉक फ़िल्टर फ़ाइल में मौजूद नहीं है.

उदाहरण के तौर पर

मान लें कि आपको JAR फ़ाइल ChatLibrary.jar को रैप करना होगा, जिसमें निम्न श्रेणी:

public class ChatManager {
  public static void sendMessage(int userId, String message) {...}
}

आपके C प्रोजेक्ट में आपको इस JAR के लिए एक नेटिव रैपर जनरेट करना होगा. इससे, रनटाइम के दौरान कॉल करने के लिए अपने नेटिव Android ऐप्लिकेशन का इस्तेमाल करें. इसका उपयोग करके यह कोड जनरेट करें: लाइब्रेरी रैपर नीचे दिए गए निर्देश से मिलेगा:

java -jar lw.jar -i ChatLibrary.jar -o ./generated_code/

ऊपर दिया गया निर्देश, डायरेक्ट्री में C सोर्स कोड जनरेट करता है ./generated_code. जनरेट की गई फ़ाइल chat_manager.h में इससे मिलता-जुलता कोड है होगा, जिससे आप अपने प्रोजेक्ट में लाइब्रेरी को कॉल कर सकेंगे:

#include "java/lang/string.h"

typedef struct ChatManager_ ChatManager;
void ChatManager_sendMessage(int32_t user_id, String* message);

उदाहरण के तौर पर ज़्यादा जानकारी के लिए, लाइब्रेरी रैपर गाइड देखें.

टूल की जानकारी

नीचे दिए सेक्शन में, लाइब्रेरी रैपर के बारे में ज़्यादा जानकारी दी गई है काम करता है.

आउटपुट डायरेक्ट्री का स्ट्रक्चर

सभी C सोर्स और हेडर फ़ाइलें, उन सबडायरेक्ट्री में मौजूद होती हैं जो रैप की गई Java क्लास का पैकेज नाम. उदाहरण के लिए, बताया गया JAR java.lang.Integer, डायरेक्ट्री में जनरेट किया गया है ./java/lang/integer.[h/cc].

इस आउटपुट व्यवहार को कंट्रोल करने के लिए, टूल के कॉन्फ़िगरेशन फ़ाइल में सेव किया गया था.

ऑब्जेक्ट का लाइफ़साइकल

Java ऑब्जेक्ट, C कोड में ओपेक पॉइंटर के रूप में दिखाए जाते हैं. इन्हें रैपर कहा जाता है. रैपर, संबंधित Java ऑब्जेक्ट के लिए JNI संदर्भ मैनेज करता है. रैपर कैन नीचे दी गई स्थितियों में बनाए जाएंगे:

• फ़ंक्शन को कॉल करके किसी मौजूदा JNI संदर्भ को रैप करके MyClass_wrapJniReference(jobject jobj). फ़ंक्शन दी गई पहचान फ़ाइल का मालिकाना हक नहीं लेता है, लेकिन खुद एक पहचान फ़ाइल बनाता है ग्लोबल जेएनआई रेफ़रंस का इस्तेमाल करें.
• नया ऑब्जेक्ट बनाकर, जो किसी कंस्ट्रक्टर को कॉल करने के बराबर है जावा: MyClass_construct()
• किसी फ़ंक्शन से नया रैपर रिटर्न करके, उदाहरण के लिए: Score* Leaderboard_getScore(Leaderboard* instance, String* leaderboard_name) अभी तक किसी भी व्यक्ति ने चेक इन नहीं किया है

लंबे समय तक इस्तेमाल न किए जाने पर, आपको सभी रैपर को नष्ट करना होगा. ऐसा करने के लिए, destroy() फ़ंक्शन MyClass_destroy(MyClass* instance).

रैपर देने वाले फ़ंक्शन, हर कॉल के लिए एक नई मेमोरी तय करते हैं, भले ही रैपर एक ही Java इंस्टेंस दिखाते हों.

उदाहरण के लिए, जब Java तरीका Singleton.getInstance() हमेशा उसी इंस्टेंस में, C साइड पर मौजूद मिलता-जुलता फ़ंक्शन एक नया इंस्टेंस बनाएगा के लिए रैपर का इस्तेमाल किया जाता है:

Singleton* singleton_a = Singleton_getInsance();
Singleton* singleton_b = Singleton_getInsance();

// singleton_a and singleton_b are different pointers, even though they represent the same Java instance.

उन क्लास को मैनेज करना जिनका रेफ़रंस नहीं दिया गया है

जब किसी दिए गए JAR में कोई क्लास नहीं मिलती है, तो लाइब्रेरी रैपर एक इस तरह का इस्तेमाल करते समय, ओपेक पॉइंटर को बुनियादी तौर पर लागू किया जा सकता है. साथ ही, इसमें ये तरीके भी शामिल होते हैं:

• wrapJniReference()
• getJniReference()
• destroy()

कोड जनरेट करने के बारे में जानकारी

इस्तेमाल किए जाने पर, लाइब्रेरी रैपर, नीचे दिए गए सार्वजनिक सिंबल के आधार पर C कोड जनरेट करता है उन JAR फ़ाइलों को शामिल करें जिन्हें आपने टूल उपलब्ध कराया है. जनरेट किए गए C कोड में अंतर हो सकता है रैप किए हुए Java कोड से उदाहरण के लिए, C में OOP, सामान्य टाइप, मेथड ओवरलोडिंग या Java की अन्य सुविधाएं शामिल हैं.

इन स्थितियों को दिखाने वाला जनरेट किया गया C कोड, होना चाहिए, जो C डेवलपर के लिए उम्मीद के मुताबिक हो. नीचे दिए गए सेक्शन में दिए गए उदाहरणों में, देखें कि यह टूल Java कोड से C कैसे जनरेट कर सकता है. नोट: कोड स्निपेट के नीचे दिए गए उदाहरणों में C/C++ और Java कोड शामिल हैं स्निपेट. इन स्निपेट का मकसद सिर्फ़ यह बताना है कि टूल हर स्थिति के लिए कोड जनरेट करता है.

कक्षाएं

क्लास को C में ओपेक पॉइंटर के तौर पर दिखाया जाता है:

typedef struct MyClass_ MyClass;

public class MyClass { ... }

ओपेक पॉइंटर के इंस्टेंस, रैपर के तौर पर इस्तेमाल किए जाते हैं. रैपर टूल हर क्लास के लिए अतिरिक्त सहायता फ़ंक्शन जनरेट करता है. पिछले उदाहरण के लिए क्लास MyClass, ये फ़ंक्शन जनरेट होते हैं:

// Wraps a JNI reference with MyClass. The 'jobj' must represent MyClass on the Java side.
MyClass* MyClass_wrapJniReference(jobject jobj);

// Return JNI reference associated with the 'MyClass' pointer.
jobject MyClass_getJniReference(const MyClass* object);

// Destroys the object and releases underlying JNI reference.
void MyClass_destroy(const MyClass* object);

कंस्ट्रक्टर

सार्वजनिक या डिफ़ॉल्ट कंस्ट्रक्टर वाली क्लास, खास का इस्तेमाल करके दिखाई जाती हैं फ़ंक्शन:

MyClass* MyClass_construct(String* data);

public class MyClass {
  public MyClass(String data) { ... }
}

माटिंग में इस्तेमाल हुए तरीके

तरीकों को सामान्य फ़ंक्शन के तौर पर दिखाया जाता है. फ़ंक्शन के नाम में क्लास का मूल नाम. नॉन-स्टैटिक इंस्टेंस तरीकों को दिखाने वाले फ़ंक्शन में पहले पैरामीटर के तौर पर, यह Java ऑब्जेक्ट को दिखाने वाली स्ट्रक्चर के पॉइंटर के तौर पर चालू होता है जिसकी ओर से फ़ंक्शन को कॉल किया गया है. यह तरीका, this के जैसा है पॉइंटर.

Result* MyClass_doAction(const MyClass* my_class_instance, int32_t action_id, String* data);
int32_t MyClass_doAction(int32_t a, int32_t b);

public class MyClass {
  public Result doAction(int actionId, String data) { ... }
  public static int doCalculations(int a, int b) { ... }
}

इनर क्लास

इनर क्लास को सामान्य क्लास के नज़दीक से दिखाया जाता है. हालांकि, क्लास के नाम को संबंधित C स्ट्रक्चर में, बाहरी क्लास के एक से ज़्यादा क्रम वाले नाम शामिल होते हैं:

typedef struct MyClass_InnerClass_ MyClass_InnerClass;

public class MyClass {
  public class InnerClass {...}
}

इनर क्लास मेथड

इनर क्लास मेथड को इस तरह दिखाया गया है:

bool MyClass_InnerClass_setValue(MyClass_InnerClass* my_class_inner_class_instance, int32_t value);

public class MyClass {
  public class InnerClass {
    public boolean setValue(int value) { ... }
  }
}

सामान्य टाइप

लाइब्रेरी रैपर, सामान्य टाइप को सीधे तौर पर रैप नहीं करता है. इसके बजाय, यह टूल सिर्फ़ सामान्य टाइप इंस्टैंशिएशन के लिए रैपर जनरेट करता है.

उदाहरण के लिए, जब किसी एपीआई में क्लास MyGeneric<T> मौजूद होती है और वहां दो इस क्लास के इंस्टैंशिएशन, जैसे कि MyGeneric<Integer> और MyGeneric<String>, इन दो इंस्टैंशिएशन के लिए रैपर जनरेट होते हैं. यह इसका मतलब है कि आप इसका इस्तेमाल करके MyGeneric<T> टाइप के नए इंस्टैंशिएट नहीं कर सकते अलग-अलग तरह के कॉन्फ़िगरेशन. यह उदाहरण देखें:

// result.h

typedef struct Result_Integer_ Result_Integer;
typedef struct Result_Float_ Result_Float;

Integer* Result_Integer_getResult(const Result_Integer* instance);
Float* Result_Float_getResult(const Result_Float* instance);

// data_processor.h

typedef struct DataProcessor_ DataProcessor;

Result_Integer* DataProcessor_processIntegerData(const DataProcessor* instance);
Result_Float* DataProcessor_processFloatData(constDataProcessor* instance);

public class Result<T> {
  public T getResult();
}

public class DataProcessor {
  public Result<Integer> processIntegerData();
  public Result<Float> processFloatData();
}

इंटरफ़ेस लागू करना

सी इंटरफ़ेस लागू करने के लिए implementInterface() पर कॉल करें और कॉलबैक फ़ंक्शन का इस्तेमाल करें. सिर्फ़ इंटरफ़ेस लागू किए जा सकते हैं इस तरीके से; क्लास और ऐब्सट्रैक्ट क्लास का इस्तेमाल नहीं किया जा सकता. ज़्यादा जानकारी के लिए, नीचे दिया गया उदाहरण:

// observer.h

typedef struct Observer_ Observer;
typedef void (*Observer_onAction1Callback)();
typedef void (*Observer_onAction2Callback)(int32_t data);

Observer* Observer_implementInterface(
Observer_onAction1Callback observer_on_action1_callback,
Observer_onAction2Callback observer_on_action2_callback);

public interface Observer {
  void onAction1();
  void onAction2(int data);
}

public class Subject {
  public void registerObserver(Observer observer);
}

इस्तेमाल का उदाहरण:

void onAction1() {
  // Handle action 1
}

void onAction2(int32_t data) {
  // Handle action 2
}

Observer* observer = Observer_implementInterface(onAction1, onAction2);
Subject_registerObserver(subject, observer);

सीमाएं

लाइब्रेरी रैपर टूल बीटा वर्शन में है. आपको इन समस्याओं का सामना करना पड़ सकता है सीमाएं:

असमर्थित Java निर्माण

लाइब्रेरी रैपर बीटा वर्शन में ये कंस्ट्रक्ट काम नहीं करते:

• मेथड ओवरलोडिंग

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

• टेंप्लेट वाले तरीके

• static final int और static final String के अलावा दूसरे फ़ील्ड

• श्रेणियां

संभावित नाम टकराव

C कोड में Java क्लास को दिखाए जाने के तरीके की वजह से, बहुत कम मामलों में समस्या होती है. उदाहरण के लिए, क्लास Foo<Bar> और इनर Foo क्लास के अंदर क्लास Bar को C के एक ही चिह्न से दिखाया जाता है: typedef struct Foo_Bar_ Foo_Bar;

सहायता

अगर आपको लाइब्रेरी रैपर में कोई समस्या मिलती है, तो कृपया हमें बताएं.