عيّنة: hello-jni

ترشدك هذه العينة خلال استخدام hello-jni، وهو تطبيق برمجي بسيط مكتوب بلغة C/C++ تم إنشاؤه باستخدام حزمة NDK. يمكنك العثور على هذا المثال في الدليل hello-jni من مستودع ndk-samples، ضمن فرع android-mk.

Android.mk

يقدّم السطران التاليان اسم ملف المصدر الأصلي، بالإضافة إلى اسم المكتبة المشتركة المطلوب إنشاؤها. يكون الاسم الكامل للمكتبة المنشأة هو libhello-jni.so، وذلك بعد أن يضيف نظام التصميم البادئة lib والإضافة .so.

LOCAL_SRC_FILES := hello-jni.c
LOCAL_MODULE    := hello-jni

لمزيد من المعلومات حول وظيفة ملف Android.mk وكيفية استخدامه، راجِع Android.mk.

Application.mk

يُخبر هذا السطر نظام الإنشاء بوحدة المعالجة المركزية والبنية التي سيتم الإنشاء وفقًا لها. في هذا المثال، ينشئ نظام الإنشاء جميع التصاميم المعمارية المتوافقة.

APP_ABI := all

لمزيد من المعلومات عن ملف Application.mk وكيفية استخدامه، يُرجى الاطّلاع على Application.mk.

التنفيذ من جانب Java

يقع ملف helloJNI.java في hellojni/src/com/example/hellojni/. ويُستخدَم دالّة لاسترداد سلسلة من الجانب الأصلي، ثم يتم عرضها على الشاشة.

تحتوي شفرة المصدر على ثلاثة أسطر ذات أهمية خاصة لمستخدم NDK. ويتم عرضها هنا بالترتيب الذي يتم استخدامه به، وليس بالترتيب المتعلّق بالملف الشخصي.

يؤدي استدعاء الدالة هذا إلى تحميل ملف .so عند بدء تشغيل التطبيق.

Kotlin

System.loadLibrary("hello-jni")

Java

System.loadLibrary("hello-jni");

تُعلم الكلمة الرئيسية native في بيان الطريقة التلقائية الآلة بأنّ الدالة متوفّرة في المكتبة المشترَكة (أي أنّها مُطبَّقة على الصعيد الأصلي).

Kotlin

external fun stringFromJNI(): String

Java

public native String stringFromJNI();

يستدعي إطار عمل Android الدالة التي تم تحميلها وتحديدها في الخطوات السابقة، ما يؤدي إلى عرض السلسلة على الشاشة.

Kotlin

tv.text = stringFromJNI()

Java

tv.setText( stringFromJNI() );

التنفيذ من الجانب C

يقع ملف hello-jni.c في hello-jni/jni/. يحتوي على دالة تُعيد سلسلة طلبها جانب Java). تعريف الدالة على النحو التالي:

JNIEXPORT jstring JNICALL
Java_com_example_hellojni_HelloJni_stringFromJNI( JNIEnv* env,
                                                  jobject thiz )

يتجاوب هذا التعريف مع الدالة الأصلية المُعلَنة في رمز مصدر Java. نوع الإرجاع، jstring، هو نوع بيانات محدّد في مواصفات واجهة Java Native. وهي ليست سلسلة، بل هي مُشير إلى سلسلة Java.

بعد الرمز jstring، يأتي اسم الدالة، والذي يستند إلى اسم دالة Java ومسار الملف الذي يحتوي عليها. أنشئ النموذج وفقًا للقواعد التالية:

  • أضِف Java_ في بداية العنوان.
  • يُرجى وصف مسار الملف بالنسبة إلى الدليل المصدر من المستوى الأعلى.
  • استخدِم شرطات سفلية بدلاً من الشُرطات المائلة للأمام.
  • احذف امتداد الملف .java.
  • أضِف اسم الدالة بعد آخر شرطة سفلية.

بعد اتّباع هذه القواعد، يستخدم هذا المثال اسم الدالة Java_com_example_hellojni_HelloJni_stringFromJNI. يشير هذا الاسم إلى دالة Java تُسمى stringFromJNI()، والتي تقع في hellojni/src/com/example/hellojni/HelloJni.java.

JNIEnv* هو المؤشر إلى الجهاز الافتراضي، وjobject هو مؤشر إلى كائن this الضمني الذي تم تمريره من جانب Java.

يستدعي السطر التالي السمة (*env) لواجهة برمجة التطبيقات VM API، ويمرره قيمة عرض: أي السلسلة التي طلبتها الدالة في جانب Java.

return (*env)->NewStringUTF(env, "Hello from JNI !
Compiled with ABI " ABI ".");