קצה עורפי AIDL הוא יעד ליצירת קוד stub. כשמשתמשים בקובצי AIDL, תמיד משתמשים בהם בשפה מסוימת עם סביבת זמן ריצה ספציפית. בהתאם ל: צריך להשתמש בקצוות עורפיים שונים של AIDL.
בטבלה הבאה, היציבות של ממשק ה-API מתייחסת ליכולת לכתוב קוד לפי ממשק ה-API הזה, כך שאפשר יהיה להעביר את הקוד בנפרד מהקובץ הבינארי system.img
libbinder.so
.
ל-AIDL יש את הקצוות העורפיים הבאים:
קצה עורפי | Language | ממשק API | מערכות build |
---|---|---|---|
Java | Java | SDK/SystemApi (יציב*) | הכל |
NDK | C++ | libbinder_ndk (יציבה*) | aidl_interface |
על"ט | C++ | libbinder (לא יציב) | הכל |
Rust | Rust | libbinder_rs (stable*) | aidl_interface |
- פלטפורמות ה-API האלה יציבות, אבל רבים מממשקי ה-API כמו אלה של שירות שמורים לשימוש פנימי בפלטפורמה, ולא זמינים תרגום מכונה. למידע נוסף על השימוש ב-AIDL באפליקציות, עיינו במסמכי התיעוד למפתחים.
- הקצה העורפי של Rust הושק ב-Android 12. ה הקצה העורפי NDK זמין החל מ-Android 10.
- ארגז החלודה מבוסס על
libbinder_ndk
, מה שמאפשר לו יציב ונייד. מודולי APEX משתמשים ב-binder crate באותו אופן שבו משתמשים בו כל הגורמים האחרים בצד המערכת. החלק של Rust מקובץ ב-APEX ונשלח בתוכו. הפעולה הזו תלויה ב-libbinder_ndk.so
במחיצת המערכת.
פיתוח מערכות
בהתאם לקצה העורפי, יש שתי דרכים להדר את AIDL ל-stub פרטים נוספים על מערכות ה-build אפשר למצוא חומר עזר בנושא מודול Soong.
מערכת build מרכזית
בכל מודול של Android.bp cc_
או java_
(או בכל מודול של Android.mk
שווה ערך),
ניתן לציין קובצי .aidl
כקובצי מקור. במקרה הזה, נתוני Java/CPP
נעשה שימוש בקצוות העורפיים של AIDL (לא בקצה העורפי NDK), ובמחלקות להשתמש
קובצי AIDL תואמים נוספים למודול באופן אוטומטי. אפשר לציין במודולים האלה אפשרויות כמו local_include_dirs
, שמציינת למערכת ה-build את נתיב הבסיס לקובצי AIDL באותו מודול, בקבוצה aidl:
. חשוב לזכור שאפשר להשתמש בקצה העורפי של Rust רק עם Rust. rust_
מודולים
מטופלות בצורה שונה כי קובצי AIDL לא מוגדרים כקובצי מקור.
במקום זאת, המודול aidl_interface
מפיק rustlib
שנקרא
<aidl_interface name>-rust
שאפשר לקשר אליו. למידע נוסף, ראו הדוגמה ל-Rust AIDL.
aidl_interface
הסוגים שבהם נעשה שימוש במערכת ה-build הזו צריכים להיות מובנים. כדי שהמבנה יהיה מובנה, על מגרשים להכיל שדות באופן ישיר ולא להיות הצהרות על סוגים מוגדרים ישירות בשפות היעד. במאמר Structured versus stable AIDL מוסבר איך AIDL מובנה משתלב עם AIDL יציב.
סוגים
אפשר להתייחס למהדר aidl
כאל הטמעת עזר של סוגים.
כשיוצרים ממשק, צריך להפעיל את aidl --lang=<backend> ...
כדי לראות
את קובץ הממשק שנוצר. כשמשתמשים במודול aidl_interface
, אפשר לראות
הפלט בפלט out/soong/.intermediates/<path to module>/
.
סוג Java/AIDL | סוג C++ | סוג NDK | סוג החלודה |
---|---|---|---|
בוליאני | בוליאני | בוליאני | בוליאני |
בייט | int8_t | int8_t | i8 |
תו | char16_t | char16_t | u16 |
INT | int32_t | int32_t | i32 |
ארוך | int64_t | int64_t | i64 |
float | float | float | f32 |
double | double | כפול | f64 |
מחרוזת | android::String16 | std::string | מחרוזת |
android.os.Parcelable | android::Parcelable | לא רלוונטי | לא רלוונטי |
איבינדר | android::IBinder | ndk::SpAIBinder | binder::SpIBinder |
ט[] | std::vector<T> | std::vector<T> | In: &[T] Out: Vec<T> |
byte[] | std::vector<uint8_t> | std::vector<int8_t>1 | In: &[u8] חוץ: Vec<u8> |
רשימה<T> | std::vector<T>2 | std::vector<T>3 | In: &[T]4 חוץ: Vec<T> |
FileDescriptor | android::base::unique_fd | לא רלוונטי | binder::parcel::ParcelFileDescriptor |
ParcelFileDescriptor | android::os::ParcelFileDescriptor | ndk::ScopedFileDescriptor | binder::parcel::ParcelFileDescriptor |
סוג הממשק (T) | android::sp<T> | std::shared_ptr<T>7 | binder::Strong |
סוג החבילה (T) | T | T | T |
סוג איחוד (T)5 | T | T | T |
T[N] 6 | std::array<T, N> | std::array<T, N> | [T; לא] |
1. בגרסה Android 12 ואילך, מערכי בייטים משתמשים ב-uint8_t במקום ב-int8_t מסיבות תאימות.
2. הקצה העורפי של C++ תומך ב-List<T>
כאשר T
הוא אחד מהערכים String
,
IBinder
, ParcelFileDescriptor
או חבילה. ב-Android 13 ואילך, T
יכול להיות כל סוג שאינו פרימיטיבי (כולל סוגי ממשק) מלבד מערכי נתונים. ב-AOSP מומלץ להשתמש בסוגים של מערכי נתונים כמו T[]
, כי הם פועלים בכל הקצוות העורפיים.
3. הקצה העורפי של NDK תומך ב-List<T>
כאשר T
הוא אחד מהערכים String
, ParcelFileDescriptor
או parcelable. ב-Android 13
ואילך, T
יכול להיות כל טיפוס שאינו פרימיטיבי מלבד מערכים.
4. הסוגים מועברים בצורה שונה עבור קוד חלודה, בהתאם הם קלט (ארגומנט) או פלט (ערך מוחזר).
5. סוגי האיחוד נתמכים ב-Android 12 וגם גבוהה יותר.
6. ב-Android מגרסה 13 ואילך יש תמיכה במערכים בגודל קבוע. למערכים בגודל קבוע יכולים להיות כמה מאפיינים (למשל int[3][4]
).
בקצה העורפי של Java, מערכים בגודל קבוע מיוצגים כסוגי מערך.
7. כדי ליצור אובייקט SharedRefBase
של binder, צריך להשתמש ב-
SharedRefBase::make\<My\>(... args ...)
. הפונקציה הזו יוצרת אובייקט std::shared_ptr\<T\>
שמנוהל גם הוא באופן פנימי, למקרה שהמַאגר הוא בבעלות של תהליך אחר. יצירת האובייקט בדרכים אחרות גורמת לבעלות כפולה.
כיוון תנועה (כניסה/יציאה/יציאה)
כשמציינים את סוגי הארגומנטים לפונקציות, אפשר להגדיר
אותם בתור in
, out
או inout
. ההגדרה הזו קובעת באיזה כיוון המידע מועבר בקריאה ל-IPC. in
הוא כיוון ברירת המחדל, והוא מציין שהנתונים
שהועבר מהמתקשר אל מקבל הקריאה החוזרת. המשמעות של out
היא שהנתונים מועברים
אל המתקשר. inout
הוא שילוב של שניהם. עם זאת, צוות Android ממליץ להימנע משימוש במפריד הארגומנט inout
.
אם משתמשים ב-inout
עם ממשק בגרסה קודמת ועם צד נמען ישן יותר, השדות הנוספים שנמצאים רק בצד הקורא מתאפסים לערכי ברירת המחדל שלהם. ב-Rust, ל-inout
רגיל מוקצה &mut Vec<T>
, ול-inout
מסוג רשימה מוקצה &mut Vec<T>
.
interface IRepeatExamples {
MyParcelable RepeatParcelable(MyParcelable token); // implicitly 'in'
MyParcelable RepeatParcelableWithIn(in MyParcelable token);
void RepeatParcelableWithInAndOut(in MyParcelable param, out MyParcelable result);
void RepeatParcelableWithInOut(inout MyParcelable param);
}
UTF8/UTF16
בקצה העורפי של CPP אפשר לבחור אם מחרוזות יהיו בפורמט utf-8 או utf-16. הצהרה
מחרוזות בתור @utf8InCpp String
ב-AIDL כדי להמיר אותן באופן אוטומטי ל-utf-8.
קצוות העורפיים של NDK ו-Rust תמיד משתמשים במחרוזות utf-8. מידע נוסף על
את ההערה utf8InCpp
, ראו הערות ב-AIDL.
מאפיין המציין אם ערך יכול להיות ריק (nullability)
ב-@nullable
אפשר להוסיף הערות לסוגים שיכולים להיות null.
למידע נוסף על ההערה nullable
, ראו הערות ב-AIDL.
מגרשים בהתאמה אישית
חבילה בהתאמה אישית היא חבילה שמוטמעת באופן ידני ביעד בקצה העורפי. יש להשתמש במגרשים בהתאמה אישית רק כשמנסים להוסיף תמיכה לאחרים של חבילה מותאמת אישית שכבר קיימת, ואי אפשר לשנות אותם.
כדי להצהיר על מגרש בהתאמה אישית כדי ש-AIDL ידע עליו, ה-AIDL הצהרת parcelable נראית כך:
package my.pack.age;
parcelable Foo;
כברירת מחדל, המדיניות הזו מצהירה על חבילת Java שבה my.pack.age.Foo
הוא Java
של סיווג Parcelable
.
כדי להצהיר על צד לקוח (back-end) בהתאמה אישית של CPP שאפשר לשלוח ב-AIDL, משתמשים ב-cpp_header
:
package my.pack.age;
parcelable Foo cpp_header "my/pack/age/Foo.h";
ההטמעה ב-C++ ב-my/pack/age/Foo.h
נראית כך:
#include <binder/Parcelable.h>
class MyCustomParcelable : public android::Parcelable {
public:
status_t writeToParcel(Parcel* parcel) const override;
status_t readFromParcel(const Parcel* parcel) override;
std::string toString() const;
friend bool operator==(const MyCustomParcelable& lhs, const MyCustomParcelable& rhs);
friend bool operator!=(const MyCustomParcelable& lhs, const MyCustomParcelable& rhs);
};
כדי להצהיר על רכיב NDK בהתאמה אישית שאפשר לשלוח ב-AIDL, משתמשים ב-ndk_header
:
package my.pack.age;
parcelable Foo ndk_header "android/pack/age/Foo.h";
ההטמעה של NDK ב-android/pack/age/Foo.h
נראית כך:
#include <android/binder_parcel.h>
class MyCustomParcelable {
public:
binder_status_t writeToParcel(AParcel* _Nonnull parcel) const;
binder_status_t readFromParcel(const AParcel* _Nonnull parcel);
std::string toString() const;
friend bool operator==(const MyCustomParcelable& lhs, const MyCustomParcelable& rhs);
friend bool operator!=(const MyCustomParcelable& lhs, const MyCustomParcelable& rhs);
};
ב-Android 15, כדי להצהיר על רכיב Rust מותאם אישית שאפשר לחלק לחלקים ב-AIDL, משתמשים ב-rust_type
:
package my.pack.age;
@RustOnlyStableParcelable parcelable Foo rust_type "rust_crate::Foo";
הטמעת חלודה ב-rust_crate/src/lib.rs
נראית כך:
use binder::{
binder_impl::{BorrowedParcel, UnstructuredParcelable},
impl_deserialize_for_unstructured_parcelable, impl_serialize_for_unstructured_parcelable,
StatusCode,
};
#[derive(Clone, Debug, Eq, PartialEq)]
struct Foo {
pub bar: String,
}
impl UnstructuredParcelable for Foo {
fn write_to_parcel(&self, parcel: &mut BorrowedParcel) -> Result<(), StatusCode> {
parcel.write(&self.bar)?;
Ok(())
}
fn from_parcel(parcel: &BorrowedParcel) -> Result<Self, StatusCode> {
let bar = parcel.read()?;
Ok(Self { bar })
}
}
impl_deserialize_for_unstructured_parcelable!(Foo);
impl_serialize_for_unstructured_parcelable!(Foo);
לאחר מכן אפשר להשתמש בחבילה הזו כסוג בקובצי AIDL, אבל זה לא
שנוצר על ידי AIDL. מספקים אופרטורים <
ו-==
ל-parcelables בהתאמה אישית לקצה העורפי של CPP/NDK כדי להשתמש בהם ב-union
.
ערכי ברירת מחדל
במגרשים מובנים אפשר להצהיר ערכי ברירת מחדל לכל שדה בפרימיטיבים,
String
, ומערכים מהסוגים האלה.
parcelable Foo {
int numField = 42;
String stringField = "string value";
char charValue = 'a';
...
}
כשחסרים ערכי ברירת מחדל בקצה העורפי של Java, השדות ממוּענים לערכי אפס עבור טיפוסים פרימיטיביים ול-null
עבור טיפוסים לא פרימיטיביים.
בקצוות עורפי אחרים, השדות מופעלים עם ערכי ברירת מחדל מוגדרים מראש כשלא מוגדרים ערכי ברירת מחדל. לדוגמה, בקצה העורפי של C++, שדות String
מאתחלים כמחרוזת ריקה ושדות List<T>
מאתחלים כ-vector<T>
ריק. השדות @nullable
מאותחלים כשדות null-value.
טיפול בשגיאות
מערכת ההפעלה Android מספקת סוגי שגיאות מובְנים לשירותים שאפשר להשתמש בהם בדיווח על שגיאות. הפרטים האלה משמשים את binder, ויכול להיות שהם ישמשו את כל השירותים שמטמיעים ממשק binder. השימוש בהן מתועד היטב בהגדרת AIDL והם לא דורשים סטטוס או סוג החזרה בהגדרת המשתמש.
פרמטרים של פלט עם שגיאות
כשפונקציית AIDL מדווחת על שגיאה, יכול להיות שהפונקציה לא תופעל או
לשנות פרמטרים של פלט. ספציפית, ניתן לשנות פרמטרים של פלט אם
שמתרחשת במהלך שחרור החבילה ולא במהלך העיבוד
של העסקה עצמה. באופן כללי, כשמקבלים שגיאה מ-AIDL
הפונקציה, את כל הפרמטרים inout
ו-out
וגם את הערך המוחזר (
פועל כמו פרמטר out
בקצוות עורפיים מסוימים)
מצב בלתי מוגבל.
באילו ערכי שגיאה להשתמש
אפשר להשתמש ברבים מערכי השגיאה המובנים בכל ממשקי AIDL, אבל יש ערכי שגיאה מסוימים שמקבלים טיפול מיוחד. לדוגמה, EX_UNSUPPORTED_OPERATION
וגם
אפשר להשתמש ב-EX_ILLEGAL_ARGUMENT
כשהם מתארים את מצב השגיאה, אבל
אין להשתמש ב-EX_TRANSACTION_FAILED
מפני שהוא נחשב למיוחד על ידי
בתשתית הבסיסית. מידע נוסף על הערכים המובנים האלה זמין בהגדרות הספציפיות לקצה העורפי.
אם לממשק AIDL נדרשים ערכי שגיאה נוספים שלא מכוסים בסוגים המובנים של השגיאות, אפשר להשתמש בשגיאה המובנית המיוחדת לשירות שמאפשרת לכלול ערך שגיאה ספציפי לשירות שהוגדר על ידי המשתמש. בדרך כלל, השגיאות הספציפיות לשירות מוגדרות בממשק AIDL כ-enum
שמגובות על ידי const int
או int
, והן לא מנותחות על ידי ה-binder.
ב-Java, השגיאות ממופות לחריגות, כמו android.os.RemoteException
. עבור
חריגים ספציפיים לשירות, Java משתמש ב-android.os.ServiceSpecificException
יחד עם השגיאה שהוגדרה על ידי המשתמש.
קוד מקורי ב-Android לא משתמש בחריגים. הקצה העורפי של CPP משתמש ב-android::binder::Status
. הקצה העורפי של NDK משתמש ב-ndk::ScopedAStatus
. הכול
שנוצרה על ידי AIDL, מחזירה אחד מהפרטים הבאים, שמייצגים את הסטטוס
. הקצה העורפי של Rust משתמש באותם ערכי קוד חריגים כמו ה-NDK, אבל
ממירה אותן לשגיאות מקוריות ב-Rust (StatusCode
, ExceptionCode
) לפני
ולהעביר אותן למשתמש. בשגיאות ספציפיות לשירות, הערך המוחזר של Status
או ScopedAStatus
כולל את הערך EX_SERVICE_SPECIFIC
יחד עם השגיאה שהוגדרה על ידי המשתמש.
סוגי השגיאות המובנים מופיעים בקובצים הבאים:
קצה עורפי | הגדרה |
---|---|
Java | android/os/Parcel.java |
על"ט | binder/Status.h |
NDK | android/binder_status.h |
Rust | android/binder_status.h |
שימוש בקצוות עורפיים שונים
ההוראות האלה ספציפיות לקוד של פלטפורמת Android. הדוגמאות האלה כוללות
סוג מוגדר, my.package.IFoo
. להוראות איך להשתמש בקצה העורפי Rust:
בדוגמה של Rust AIDL
בדפוסי החלודה של Android
הדף הזה.
סוגי ייבוא
בין שהסוג המוגדר הוא ממשק, אובייקט שניתן לחלוקה או אובייקט יוניון, אפשר לייבא אותו ב-Java:
import my.package.IFoo;
או בקצה העורפי של הקישור לדף מוצר ב-CSS:
#include <my/package/IFoo.h>
או בקצה העורפי של NDK (שימו לב למרחב השמות הנוסף aidl
):
#include <aidl/my/package/IFoo.h>
או בקצה העורפי של Rust:
use my_package::aidl::my::package::IFoo;
למרות שאפשר לייבא סוג מקונן ב-Java, בקצוות העורפיים של CPP/NDK צריך
כוללים את הכותרת עבור סוג הרמה הבסיסית (root). לדוגמה, כשמייבאים סוג בתצוגת עץ Bar
שמוגדר ב-my/package/IFoo.aidl
(IFoo
הוא סוג הבסיס של הקובץ), צריך לכלול את <my/package/IFoo.h>
לקצה העורפי של CPP (או את <aidl/my/package/IFoo.h>
לקצה העורפי של NDK).
הטמעת שירותים
כדי להטמיע שירות, צריך לרשת מהכיתה הילידים של הסטאב. הכיתה הזו קוראת פקודות ממנהל ההתקן של הקישור ומבצעת את השיטות להטמיע. נניח שיש לכם קובץ AIDL כזה:
package my.package;
interface IFoo {
int doFoo();
}
ב-Java, עליך להרחיב מהכיתה הזו:
import my.package.IFoo;
public class MyFoo extends IFoo.Stub {
@Override
int doFoo() { ... }
}
בקצה העורפי של CPP:
#include <my/package/BnFoo.h>
class MyFoo : public my::package::BnFoo {
android::binder::Status doFoo(int32_t* out) override;
}
בקצה העורפי של NDK (שימו לב למרחב השמות הנוסף aidl
):
#include <aidl/my/package/BnFoo.h>
class MyFoo : public aidl::my::package::BnFoo {
ndk::ScopedAStatus doFoo(int32_t* out) override;
}
בקצה העורפי של Rust:
use aidl_interface_name::aidl::my::package::IFoo::{BnFoo, IFoo};
use binder;
/// This struct is defined to implement IRemoteService AIDL interface.
pub struct MyFoo;
impl Interface for MyFoo {}
impl IFoo for MyFoo {
fn doFoo(&self) -> binder::Result<()> {
...
Ok(())
}
}
או באמצעות Rust אסינכרוני:
use aidl_interface_name::aidl::my::package::IFoo::{BnFoo, IFooAsyncServer};
use binder;
/// This struct is defined to implement IRemoteService AIDL interface.
pub struct MyFoo;
impl Interface for MyFoo {}
#[async_trait]
impl IFooAsyncServer for MyFoo {
async fn doFoo(&self) -> binder::Result<()> {
...
Ok(())
}
}
רישום לקבלת שירותים
בדרך כלל, שירותים בפלטפורמת Android רשומים בתהליך servicemanager
. בנוסף לממשקי ה-API הבאים, חלק מממשקי ה-API בודקים את השירות (כלומר, הם מחזירים תשובה מיד אם השירות לא זמין).
פרטים מדויקים מופיעים בממשק servicemanager
המתאים. אפשר לבצע את הפעולות האלה רק כשמפעילים הידור לפלטפורמת Android.
ב-Java:
import android.os.ServiceManager;
// registering
ServiceManager.addService("service-name", myService);
// return if service is started now
myService = IFoo.Stub.asInterface(ServiceManager.checkService("service-name"));
// waiting until service comes up (new in Android 11)
myService = IFoo.Stub.asInterface(ServiceManager.waitForService("service-name"));
// waiting for declared (VINTF) service to come up (new in Android 11)
myService = IFoo.Stub.asInterface(ServiceManager.waitForDeclaredService("service-name"));
בקצה העורפי של CPP:
#include <binder/IServiceManager.h>
// registering
defaultServiceManager()->addService(String16("service-name"), myService);
// return if service is started now
status_t err = checkService<IFoo>(String16("service-name"), &myService);
// waiting until service comes up (new in Android 11)
myService = waitForService<IFoo>(String16("service-name"));
// waiting for declared (VINTF) service to come up (new in Android 11)
myService = waitForDeclaredService<IFoo>(String16("service-name"));
בקצה העורפי של NDK (שימו לב למרחב השמות הנוסף aidl
):
#include <android/binder_manager.h>
// registering
binder_exception_t err = AServiceManager_addService(myService->asBinder().get(), "service-name");
// return if service is started now
myService = IFoo::fromBinder(ndk::SpAIBinder(AServiceManager_checkService("service-name")));
// is a service declared in the VINTF manifest
// VINTF services have the type in the interface instance name.
bool isDeclared = AServiceManager_isDeclared("android.hardware.light.ILights/default");
// wait until a service is available (if isDeclared or you know it's available)
myService = IFoo::fromBinder(ndk::SpAIBinder(AServiceManager_waitForService("service-name")));
בקצה העורפי של Rust:
use myfoo::MyFoo;
use binder;
use aidl_interface_name::aidl::my::package::IFoo::BnFoo;
fn main() {
binder::ProcessState::start_thread_pool();
// [...]
let my_service = MyFoo;
let my_service_binder = BnFoo::new_binder(
my_service,
BinderFeatures::default(),
);
binder::add_service("myservice", my_service_binder).expect("Failed to register service?");
// Does not return - spawn or perform any work you mean to do before this call.
binder::ProcessState::join_thread_pool()
}
בקצה העורפי האסינכרוני של Rust, עם סביבת זמן ריצה עם שרשור יחיד:
use myfoo::MyFoo;
use binder;
use binder_tokio::TokioRuntime;
use aidl_interface_name::aidl::my::package::IFoo::BnFoo;
#[tokio::main(flavor = "current_thread")]
async fn main() {
binder::ProcessState::start_thread_pool();
// [...]
let my_service = MyFoo;
let my_service_binder = BnFoo::new_async_binder(
my_service,
TokioRuntime(Handle::current()),
BinderFeatures::default(),
);
binder::add_service("myservice", my_service_binder).expect("Failed to register service?");
// Sleeps forever, but does not join the binder threadpool.
// Spawned tasks will run on this thread.
std::future::pending().await
}
הבדל חשוב אחד מהאפשרויות האחרות הוא שלא קוראים ל-join_thread_pool
כשמשתמשים ב-Rust אסינכרוני ובזמן ריצה עם ליבה חד-תלולית. הדבר
כי צריך לתת לטוקיו שרשור שבו הוא יכול לבצע משימות שנוצרו על ידי AI. לחשבון
בדוגמה הזו, ה-thread הראשי ישרת את המטרה הזו. כל המשימות שנוצרות באמצעות tokio::spawn
יתבצעו בשרשור הראשי.
בקצה העורפי של Rust עם זמן ריצה מרובה-ליבות:
use myfoo::MyFoo;
use binder;
use binder_tokio::TokioRuntime;
use aidl_interface_name::aidl::my::package::IFoo::BnFoo;
#[tokio::main(flavor = "multi_thread", worker_threads = 2)]
async fn main() {
binder::ProcessState::start_thread_pool();
// [...]
let my_service = MyFoo;
let my_service_binder = BnFoo::new_async_binder(
my_service,
TokioRuntime(Handle::current()),
BinderFeatures::default(),
);
binder::add_service("myservice", my_service_binder).expect("Failed to register service?");
// Sleep forever.
tokio::task::block_in_place(|| {
binder::ProcessState::join_thread_pool();
});
}
בסביבת זמן הריצה של Tokio עם כמה שרשורים, המשימות שנוצרות לא פועלות בשרשור הראשי. לכן, מומלץ להפעיל את join_thread_pool
בשרשור הראשי כדי שהשרשור הראשי לא יהיה פשוט במצב חוסר פעילות. צריך לסיים את השיחה
block_in_place
כדי לצאת מההקשר האסינכרוני.
קישור למוות
אתם יכולים לבקש לקבל התראה כששירות שמארח מסמך binder מושבת. כך אפשר למנוע דליפה של שרתי proxy לקריאה חוזרת או לסייע בשחזור שגיאות. יש לבצע את הקריאות האלה באובייקטים של שרת proxy של binder.
- ב-Java, משתמשים ב-
android.os.IBinder::linkToDeath
. - בקצה העורפי של CPP, משתמשים ב-
android::IBinder::linkToDeath
. - בקצה העורפי של NDK, צריך להשתמש ב-
AIBinder_linkToDeath
. - בקצה העורפי של Rust, יוצרים אובייקט
DeathRecipient
ואז קוראיםmy_binder.link_to_death(&mut my_death_recipient)
. חשוב לזכור של-DeathRecipient
יש בעלות על פונקציית ה-callback, ולכן צריך לשמור על האובייקט הזה בחיים כל עוד רוצים לקבל התראות.
פרטי המתקשר
כשמקבלים קריאה של kernel binder, פרטי המתקשר זמינים בכמה ממשקי API. ה-PID (או מזהה התהליך) מתייחס למזהה התהליך ב-Linux של התהליך ששולח את העסקה. ה-UID (או מזהה המשתמש) מתייחס למזהה המשתמש ב-Linux. כשמקבלים שיחה חד-כיוונית, ה-PID של השיחה הוא 0. כשהן לא נמצאות בהקשר של עסקה ב-binder, הפונקציות האלה מחזירות את ה-PID וה-UID של התהליך הנוכחי.
בקצה העורפי של Java:
... = Binder.getCallingPid();
... = Binder.getCallingUid();
בקצה העורפי של CPP:
... = IPCThreadState::self()->getCallingPid();
... = IPCThreadState::self()->getCallingUid();
ב-back-end של NDK:
... = AIBinder_getCallingPid();
... = AIBinder_getCallingUid();
כשמטמיעים את הממשק בקצה העורפי של Rust, מציינים את הפרטים הבאים (במקום לאפשר לו להשתמש בערך ברירת המחדל):
... = ThreadState::get_calling_pid();
... = ThreadState::get_calling_uid();
דוחות באגים ו-API לניפוי באגים בשירותים
כשמפעילים דוחות באגים (לדוגמה, באמצעות adb bugreport
), הם אוספים מידע מכל רחבי המערכת כדי לעזור בניפוי באגים בבעיות שונות.
בשירותי AIDL, דוחות הבאגים משתמשים בקובץ הבינארי dumpsys
בכל השירותים שמתאימים ל-Service Manager כדי לדחוף את המידע שלהם לדוח הבאג. אפשר גם להשתמש ב-dumpsys
בשורת הפקודה כדי לקבל מידע משירות עם dumpsys SERVICE [ARGS]
. בקצה העורפי C++ ו-Java,
הוא יכול לשלוט בסדר שבו השירותים מושמטים באמצעות ארגומנטים נוספים
אל addService
. אפשר גם להשתמש ב-dumpsys --pid SERVICE
כדי לקבל את ה-PID של שירות במהלך ניפוי באגים.
כדי להוסיף פלט מותאם אישית לשירות, אפשר לשנות את השיטה dump
באובייקט השרת, כמו שמטמיעים כל שיטה אחרת של IPC שמוגדרת בקובץ AIDL. כשעושים זאת, צריך להגביל את ההעלאה לאפליקציה
הרשאה android.permission.DUMP
או להגביל את ההעברה למזהי UID ספציפיים.
בקצה העורפי של Java:
@Override
protected void dump(@NonNull FileDescriptor fd, @NonNull PrintWriter fout,
@Nullable String[] args) {...}
בקצה העורפי של CPP:
status_t dump(int, const android::android::Vector<android::String16>&) override;
ב-back-end של NDK:
binder_status_t dump(int fd, const char** args, uint32_t numArgs) override;
כשמטמיעים את הממשק בקצה העורפי של Rust, מציינים את הפרטים הבאים (במקום לאפשר לו להשתמש בערך ברירת המחדל):
fn dump(&self, mut file: &File, args: &[&CStr]) -> binder::Result<()>
קבלה דינמית של מתאר ממשק
מתאר הממשק מזהה את סוג הממשק. האפשרות הזו שימושית בזמן ניפוי באגים או כשיש קישור לא ידוע.
ב-Java, אפשר לקבל את מתאר הממשק עם קוד כמו:
service = /* get ahold of service object */
... = service.asBinder().getInterfaceDescriptor();
בקצה העורפי של CPP:
service = /* get ahold of service object */
... = IInterface::asBinder(service)->getInterfaceDescriptor();
הקצוות העורפיים של NDK ו-Rust לא תומכים ביכולת הזו.
קבלה סטטית של מתאר ממשק
לפעמים (למשל, כשרושמים שירותי @VintfStability
), צריך
מהו מתאר הממשק באופן סטטי. ב-Java אפשר לקבל
מתאר באמצעות הוספת קוד כמו:
import my.package.IFoo;
... IFoo.DESCRIPTOR
בקצה העורפי של CPP:
#include <my/package/BnFoo.h>
... my::package::BnFoo::descriptor
בקצה העורפי של NDK (שימו לב למרחב השמות הנוסף aidl
):
#include <aidl/my/package/BnFoo.h>
... aidl::my::package::BnFoo::descriptor
בקצה העורפי של Rust:
aidl::my::package::BnFoo::get_descriptor()
טווח של מניה (enum)
בקצוות עורפיים מקוריים אפשר לשנות את הערכים האפשריים של enum מופעלת. בגלל שיקולים לגבי גודל הקוד, האפשרות הזו לא נתמכת ב-Java.
ל-MyEnum
של enum שמוגדר ב-AIDL, האיטרציה מסופקת באופן הבא.
בקצה העורפי של CPP:
::android::enum_range<MyEnum>()
בקצה העורפי של NDK:
::ndk::enum_range<MyEnum>()
בקצה העורפי של Rust:
MyEnum::enum_values()
ניהול שרשורים
כל מופע של libbinder
בתהליך שומר על מאגר חוטים אחד. ברוב התרחישים לדוגמה, צריך להגדיר מאגר חוטים אחד בלבד, שכל הקצוות העורפיים ישתפו בו.
החריג היחיד הוא כאשר קוד הספק עשוי לטעון עותק נוסף של libbinder
כדי לדבר עם /dev/vndbinder
. מכיוון שהיא נמצאת בצומת נפרד של Binder, מאגר השרשור לא משותף.
לקצה העורפי של Java, הגודל של מאגר השרשור יכול רק לגדול (כי הוא כבר התחיל):
BinderInternal.setMaxThreads(<new larger value>);
עבור הקצה העורפי של CPP, הפעולות הבאות זמינות:
// set max threadpool count (default is 15)
status_t err = ProcessState::self()->setThreadPoolMaxThreadCount(numThreads);
// create threadpool
ProcessState::self()->startThreadPool();
// add current thread to threadpool (adds thread to max thread count)
IPCThreadState::self()->joinThreadPool();
באופן דומה, בקצה העורפי של NDK:
bool success = ABinderProcess_setThreadPoolMaxThreadCount(numThreads);
ABinderProcess_startThreadPool();
ABinderProcess_joinThreadPool();
בקצה העורפי של Rust:
binder::ProcessState::start_thread_pool();
binder::add_service("myservice", my_service_binder).expect("Failed to register service?");
binder::ProcessState::join_thread_pool();
כשמשתמשים בקצה העורפי של Rust עם תמיכה ב-async, צריך שני מאגרי חוטים: binder ו-Tokio.
כלומר, אפליקציות שמשתמשות ב-Rust אסינכרוני צריכות שיקולים מיוחדים
במיוחד כשמשתמשים ב-join_thread_pool
. מידע נוסף זמין בקטע בנושא רישום שירותים.
שמות שמורים
C++ , Java ו-Rust שומרים כמה שמות כמילות מפתח או כשמות ספציפיים לשפה
לשימוש. אמנם AIDL לא אוכף הגבלות על סמך כללי שפה, אבל
שמות של שדות או גופנים שתואמים לשם שמור עלולים להוביל להידור
ב-C++ או ב-Java. ב-Rust, השם של השדה או הסוג משתנה באמצעות התחביר של 'מזהה גולמי', שאפשר לגשת אליו באמצעות הקידומת r#
.
מומלץ להימנע משימוש בשמות שמורים בהגדרות ה-AIDL, במידת האפשר, כדי למנוע קישורים לא ארגונומיים או כשל קומפילציה מוחלט.
אם כבר שמרתם שמות בהגדרות ה-AIDL, תוכלו לשנות את השמות של השדות בבטחה בלי לפגוע בתאימות לפרוטוקול. יכול להיות שתצטרכו לעדכן את הקוד כדי להמשיך בתהליך ה-build, אבל כל התוכניות שכבר נוצרו ימשיכו לפעול.
שמות שכדאי להימנע מהם: