عيّنة: 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 ".");
يخضع كل من المحتوى وعيّنات التعليمات البرمجية في هذه الصفحة للتراخيص الموضحّة في ترخيص استخدام المحتوى. إنّ Java وOpenJDK هما علامتان تجاريتان مسجَّلتان لشركة Oracle و/أو الشركات التابعة لها.
تاريخ التعديل الأخير: 2025-07-26 (حسب التوقيت العالمي المتفَّق عليه)
[[["يسهُل فهم المحتوى.","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 (حسب التوقيت العالمي المتفَّق عليه)"],[],[],null,["# Sample: hello-jni\n\nThis sample guides you through hello-jni, a minimal\nC/C++ application built with the NDK. This sample is in the [hello-jni](https://github.com/android/ndk-samples/tree/android-mk/hello-jni) directory\nof ndk-samples repo, inside [android-mk branch](https://github.com/android/ndk-samples/tree/android-mk).\n\nAndroid.mk\n----------\n\nThe following two lines provide the name of the native source file, along\nwith the name of the shared library to build. The full name of the built\nlibrary is `libhello-jni.so`, once the build system adds the\n`lib` prefix and the `.so` extension. \n\n```\nLOCAL_SRC_FILES := hello-jni.c\nLOCAL_MODULE := hello-jni\n```\n\nFor more information about what the `Android.mk` file does, and how to use it, see\n[Android.mk](/ndk/guides/android_mk).\n\nApplication.mk\n--------------\n\nThis line tells the build system the CPU and architecture against which to build. In this\nexample, the build system builds for all supported architectures. \n\n```\nAPP_ABI := all\n```\n\nFor more information about the `Application.mk` file, and how to use it, see\n[Application.mk](/ndk/guides/application_mk).\n\nJava-side Implementation\n------------------------\n\nThe `helloJNI.java` file is located in `hellojni/src/com/example/hellojni/`. It calls\na function to retrieve a string from the native side, then displays it on the screen.\n\nThe source code contains three lines of particular interest to the NDK user.\nThey are presented here in the order in which they are used, rather than by\nline order.\n\nThis function call loads the `.so` file upon application startup. \n\n### Kotlin\n\n```kotlin\nSystem.loadLibrary(\"hello-jni\")\n```\n\n### Java\n\n```java\nSystem.loadLibrary(\"hello-jni\");\n```\n\nThe `native` keyword in this method declaration tells the\nvirtual machine that the function is in the shared library (that is, implemented on the native\nside). \n\n### Kotlin\n\n```kotlin\nexternal fun stringFromJNI(): String\n```\n\n### Java\n\n```java\npublic native String stringFromJNI();\n```\n\nThe Android framework calls the function loaded and declared in the\nprevious steps, displaying the string on the screen. \n\n### Kotlin\n\n```kotlin\ntv.text = stringFromJNI()\n```\n\n### Java\n\n```java\ntv.setText( stringFromJNI() );\n```\n\nC-side Implementation\n---------------------\n\nThe `hello-jni.c` file is located in `hello-jni/jni/`. It contains a function that\nreturns a string that [the Java side requested](#ji)). The function declaration is as\nfollows: \n\n```c++\nJNIEXPORT jstring JNICALL\nJava_com_example_hellojni_HelloJni_stringFromJNI( JNIEnv* env,\n jobject thiz )\n```\n\nThis declaration corresponds to the native function declared in the\nJava source code. The return type, `jstring`, is a data type defined\nin the\n[Java Native\nInterface Specification](http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/jniTOC.html). It is not actually a string, but a\npointer to a Java string.\n\nAfter `jstring` comes the function name, which is based on the\nJava function name and the path to the file containing it. Construct it\naccording to the following rules:\n\n- Prepend `Java_` to it.\n- Describe the filepath relative to the top-level source directory.\n- Use underscores in place of forward slashes.\n- Omit the `.java` file extension.\n- After the last underscore, append the function name.\n\nFollowing these rules, this example uses the function name\n`Java_com_example_hellojni_HelloJni_stringFromJNI`. This name refers to a Java\nfunction called `stringFromJNI()`, which resides in\n`hellojni/src/com/example/hellojni/HelloJni.java`.\n\n`JNIEnv*` is the pointer to the VM, and\n`jobject` is a pointer to the implicit `this` object passed from\nthe Java side.\n\nThe following line calls the VM API `(*env)`, and passes it a return value:\nthat is, the string that the function on the Java side had requested. \n\n```c++\nreturn (*env)-\u003eNewStringUTF(env, \"Hello from JNI !\nCompiled with ABI \" ABI \".\");\n```"]]
