Android Interface Definition Language (AIDL)

שפת הגדרה לבניית ממשק Android‏ (AIDL) דומה לשפות IDL אחרות: היא מאפשרת להגדיר את ממשק התכנות שעליו הלקוח והשירות מסכימים כדי לתקשר זה עם זה באמצעות תקשורת בין תהליכים (IPC).

ב-Android, בדרך כלל לתהליך אחד אין גישה לזיכרון של תהליך אחר. כדי לדבר, הם צריכים לפרק את האובייקטים שלהם לפרימיטיבים שמערכת ההפעלה יכולה להבין, ולסדר את האובייקטים מעבר לגבול הזה בשבילכם. קשה לכתוב את הקוד הזה, ולכן מערכת Android מטפלת בו בעזרת AIDL.

הערה: צריך להשתמש ב-AIDL רק אם אתם מאפשרים ללקוחות מאפליקציות שונות לגשת לשירות שלכם לצורך IPC, ואתם רוצים לטפל במספר תהליכים בו-זמנית בשירות. אם אתם לא צריכים לבצע כתובות IPC בו-זמנית באפליקציות שונות, תוכלו להטמיע Binder כדי ליצור את הממשק. אם אתם רוצים לבצע IPC אבל לא צריכים לטפל במספר תהליכים, תוכלו להטמיע את הממשק באמצעות Messenger. עם זאת, חשוב להבין את השירותים המקושרים לפני שמטמיעים AIDL.

לפני שמתחילים לתכנן את ממשק ה-AIDL, חשוב לזכור שהקריאות לממשק AIDL הן קריאות ישירות לפונקציות. אל תניחו הנחות לגבי השרשור שבו מתרחשת השיחה. מה שקורה משתנה בהתאם לשאלה אם הקריאה היא משרשור בתהליך המקומי או בתהליך מרוחק:

  • קריאות שמבוצעות מהתהליך המקומי מתבצעות באותו חוט שבו מתבצעת הקריאה. אם זהו ה-thread הראשי של ממשק המשתמש, ה-thread הזה ממשיך לפעול בממשק AIDL. אם זהו חוט אחר, הוא זה שיריץ את הקוד בשירות. לכן, אם רק שרשראות מקומיות ניגשות לשירות, תוכלו לשלוט באופן מלא בשרשורים שפועלים בו. אבל אם זה המצב, אל תשתמשו ב-AIDL בכלל. במקום זאת, תוכלו ליצור את הממשק על ידי הטמעת Binder.
  • קריאות מתהליך מרוחק מועברות מאוסף השרשור (thread pool) שהפלטפורמה שומרת בתוך התהליך שלכם. חשוב להיות מוכנים לקבל שיחות נכנסות משרשורים לא מוכרים, עם כמה שיחות בו-זמנית. במילים אחרות, הטמעה של ממשק AIDL חייבת להיות בטוחה לחלוטין לשימוש בכמה שרשורים (thread-safe). קריאות שמתבצעות משרשור אחד באותו אובייקט מרוחק מגיעות לפי הסדר בצד של המקבל.
  • מילת המפתח oneway משנה את ההתנהגות של שיחות מרחוק. כשמשתמשים בו, שיחה מרחוק לא חסומה. הפעולה הזו שולחת את נתוני העסקאות וחוזרת באופן מיידי. הטמעת הממשק מקבלת את הקריאה הזו בסופו של דבר כקריאה רגילה מאוסף השרשור Binder, כקריאה רגילה מרחוק. אם משתמשים ב-oneway בשיחה מקומית, אין לכך השפעה והשיחה עדיין סינכרונית.

הגדרת ממשק AIDL

מגדירים את ממשק ה-AIDL בקובץ .aidl באמצעות התחביר של שפת התכנות Java, ולאחר מכן שומרים אותו בקוד המקור, בספרייה src/, גם באפליקציה שמארחת את השירות וגם בכל אפליקציה אחרת שמקושרת לשירות.

כשמפתחים כל אפליקציה שמכילה את הקובץ .aidl, הכלים של Android SDK יוצרים ממשק IBinder על סמך הקובץ .aidl ושומרים אותו בספרייה gen/ של הפרויקט. השירות צריך להטמיע את הממשק של IBinder בהתאם לצורך. לאחר מכן, אפליקציות הלקוח יכולות לקשר לשירות ולקרוא לשיטות מ-IBinder כדי לבצע IPC.

כדי ליצור שירות מוגבל באמצעות AIDL, מבצעים את השלבים שמפורטים בקטעים הבאים:

  1. יצירת הקובץ .aidl

    הקובץ הזה מגדיר את ממשק התכנות באמצעות חתימות שיטות.

  2. הטמעת הממשק

    הכלים של Android SDK יוצרים ממשק בשפת התכנות Java על סמך הקובץ .aidl. לממשק הזה יש מחלקה פנימית מופשטת בשם Stub שמרחיבה את Binder ומטמיעה שיטות מהממשק של AIDL. צריך להרחיב את המחלקה Stub ולהטמיע את השיטות.

  3. חשיפת הממשק ללקוחות

    כדי להחזיר את ההטמעה של המחלקה Stub, מטמיעים את Service ואת ברירת המחדל onBind().

זהירות: כל שינוי שתבצעו בממשק ה-AIDL אחרי הגרסה הראשונה חייב להיות תואם לאחור, כדי למנוע שיבושים באפליקציות אחרות שמשתמשות בשירות. כלומר, מכיוון שצריך להעתיק את הקובץ .aidl לאפליקציות אחרות כדי שתהיה להן גישה לממשק של השירות, צריך לשמור על תמיכה בממשק המקורי.

יצירת קובץ aidl.

ב-AIDL נעשה שימוש בתחביר פשוט שמאפשר להצהיר על ממשק עם שיטה אחת או יותר שיכולות לקבל פרמטרים ולהחזיר ערכים. הפרמטרים וערכי ההחזרה יכולים להיות מכל סוג, גם ממשקים אחרים שנוצרו באמצעות AIDL.

צריך ליצור את הקובץ .aidl באמצעות שפת התכנות Java. כל קובץ .aidl חייב להגדיר ממשק יחיד, והוא נדרש רק להצהרת הממשק ולחתימות של השיטות.

כברירת מחדל, ב-AIDL יש תמיכה בסוגי הנתונים הבאים:

  • כל הסוגים פרימיטיביים בשפת התכנות Java (למשל int, long, char, boolean, וכו')
  • מערכי כל סוגי הנתונים, כמו int[] או MyParcelable[]
  • String
  • CharSequence
  • List

    כל הרכיבים ב-List חייבים להיות מאחד מסוגי הנתונים הנתמכים ברשימה הזו, או מאחד הממשקים או ה-Parcelables האחרים שנוצרו באמצעות AIDL שהוגדרו. אפשר להשתמש ב-List ככיתה של סוג עם פרמטרים, כמו List<String>. המחלקה הקונקרטית בפועל שהצד השני מקבל היא תמיד ArrayList, למרות שהשיטה נוצרת לשימוש בממשק List.

  • Map

    כל הרכיבים ב-Map חייבים להיות מאחד מסוגי הנתונים הנתמכים ברשימה הזו, או מאחד הממשקים או ה-Parcelables האחרים שנוצרו באמצעות AIDL שהוגדרו. אין תמיכה במפות טיפוסים עם פרמטרים, כמו אלה בפורמט Map<String,Integer>. המחלקה הקונקרטית בפועל שהצד השני מקבל היא תמיד HashMap, למרות שהשיטה נוצרת לשימוש בממשק Map. כדאי להשתמש ב-Bundle כחלופה ל-Map.

צריך לכלול הצהרת import לכל סוג נוסף שלא מופיע קודם, גם אם הם מוגדרים באותה חבילה שמוגדרת בממשק שלכם.

כשמגדירים את ממשק השירות, חשוב לזכור:

  • ה-methods יכולות לכלול אפס פרמטרים או יותר, והן יכולות להחזיר ערך או ערך מבוטל.
  • כל הפרמטרים שאינם פרימיטיביים דורשים תג כיווני שמציין לאן הנתונים מועברים: in,‏ out או inout (ראו את הדוגמה שבהמשך).

    ממשקים ראשוניים, String, IBinder ו-AIDL הם in כברירת מחדל, ולא ניתן להגדיר אותם בדרכים אחרות.

    זהירות: הגבילו את הכיוון למה שבאמת חשוב, כי סידור פרמטרים יקר.

  • כל תגובות הקוד שכלולות בקובץ .aidl נכללות בממשק IBinder שנוצר, מלבד תגובות לפני הצהרות הייבוא והחבילה.
  • אפשר להגדיר קבועים מסוג String ו-int בממשק AIDL, כמו const int VERSION = 1;.
  • קריאות ל-method מועברות על ידי קוד transact(), שבדרך כלל מבוסס על אינדקס של method בממשק. בגלל שזה מקשה על ניהול גרסאות, אפשר להקצות באופן ידני את קוד הטרנזקציה ל-method: void method() = 10;.
  • צריך להוסיף הערות לארגומנטים ולסוגי ההחזרה שניתנים לאפס באמצעות @nullable.

קובץ .aidl לדוגמה:

// IRemoteService.aidl
package com.example.android;

// Declare any non-default types here with import statements.

/** Example service interface */
interface IRemoteService {
    /** Request the process ID of this service. */
    int getPid();

    /** Demonstrates some basic types that you can use as parameters
     * and return values in AIDL.
     */
    void basicTypes(int anInt, long aLong, boolean aBoolean, float aFloat,
            double aDouble, String aString);
}

שומרים את הקובץ .aidl בספריית src/ של הפרויקט. כשיוצרים את האפליקציה, כלי ה-SDK יוצרים את קובץ הממשק IBinder בספריית gen/ של הפרויקט. שם הקובץ שנוצר זהה לשם הקובץ .aidl, אבל עם הסיומת .java. לדוגמה, IRemoteService.aidl יוצר את IRemoteService.java.

אם אתם משתמשים ב-Android Studio, ה-build המצטבר יוצר את הכיתה של ה-binder כמעט באופן מיידי. אם אתם לא משתמשים ב-Android Studio, הכלי Gradle יוצר את הכיתה של ה-binder בפעם הבאה שתיצרו את האפליקציה. עליכם לבנות את הפרויקט באמצעות gradle assembleDebug או gradle assembleRelease ברגע שתסיימו לכתוב את הקובץ .aidl, כדי שהקוד יוכל לקשר לכיתה שנוצרה.

הטמעת הממשק

כשמפתחים את האפליקציה, הכלים של Android SDK יוצרים קובץ ממשק .java שנקרא על שם הקובץ .aidl. הממשק שנוצר כולל קבוצת משנה בשם Stub שנחשבת להטמעה מופשטת של ממשק ההורה שלה, כמו YourInterface.Stub, ומצהירה על כל השיטות בקובץ .aidl.

הערה: Stub גם מגדיר כמה שיטות מסייעות, בעיקר asInterface(), שמקבלת IBinder, בדרך כלל זו שמועברת לשיטת הקריאה החוזרת של הלקוח onServiceConnected(), ומחזירה מכונה של ממשק ה-stub. פרטים נוספים על ביצוע ההעברה הזו מופיעים בקטע קריאה לשיטת IPC.

כדי להטמיע את הממשק שנוצר מ-.aidl, מרחיבים את הממשק Binder שנוצר, למשל YourInterface.Stub, ומטמיעים את השיטות שעברו בירושה מקובץ .aidl.

דוגמה להטמעה של ממשק שנקרא IRemoteService, שמוגדר לפי הדוגמה הקודמת של IRemoteService.aidl, באמצעות מופע אנונימי:

Kotlin

private val binder = object : IRemoteService.Stub() {

    override fun getPid(): Int =
            Process.myPid()

    override fun basicTypes(
            anInt: Int,
            aLong: Long,
            aBoolean: Boolean,
            aFloat: Float,
            aDouble: Double,
            aString: String
    ) {
        // Does nothing.
    }
}

Java

private final IRemoteService.Stub binder = new IRemoteService.Stub() {
    public int getPid(){
        return Process.myPid();
    }
    public void basicTypes(int anInt, long aLong, boolean aBoolean,
        float aFloat, double aDouble, String aString) {
        // Does nothing.
    }
};

עכשיו binder הוא מופע של הכיתה Stub (Binder), שמגדיר את ממשק ה-IPC של השירות. בשלב הבא, המכונה הזו תהיה חשופה ללקוחות כדי שיוכלו לקיים אינטראקציה עם השירות.

חשוב לשים לב למספר כללים כשמטמיעים את ממשק AIDL:

  • אין ערובה שהקריאות הנכנסות יבוצעו ב-thread הראשי, לכן צריך לחשוב על שימוש בכמה threads כבר מההתחלה ולפתח את השירות בצורה שתהיה בטוחה ל-thread.
  • כברירת מחדל, קריאות IPC הן סינכרוניות. אם אתם יודעים שלשירות נדרשות יותר מכמה אלפיות שנייה כדי להשלים בקשה, אל תקראו לו מה-thread הראשי של הפעילות. יכול להיות שהאפליקציה תתקע, וכתוצאה מכך תופיע ב-Android תיבת הדו-שיח 'האפליקציה לא מגיבה'. קוראים לו משרשור נפרד בלקוח.
  • רק סוגי החריגים שמפורטים במסמכי העזרה של Parcel.writeException() נשלחים בחזרה למבצע הקריאה.

חשיפת הממשק ללקוחות

אחרי שמטמיעים את הממשק של השירות, צריך לחשוף אותו ללקוחות כדי שיוכלו לקשר אליו. כדי לחשוף את הממשק של השירות, מרחיבים את Service ומטמיעים את onBind() כדי להחזיר מופע של הכיתה שמטמיע את Stub שנוצר, כפי שמתואר בקטע הקודם. זהו שירות לדוגמה שחושף את הממשק לדוגמה של IRemoteService בפני לקוחות.

Kotlin

class RemoteService : Service() {

    override fun onCreate() {
        super.onCreate()
    }

    override fun onBind(intent: Intent): IBinder {
        // Return the interface.
        return binder
    }


    private val binder = object : IRemoteService.Stub() {
        override fun getPid(): Int {
            return Process.myPid()
        }

        override fun basicTypes(
                anInt: Int,
                aLong: Long,
                aBoolean: Boolean,
                aFloat: Float,
                aDouble: Double,
                aString: String
        ) {
            // Does nothing.
        }
    }
}

Java

public class RemoteService extends Service {
    @Override
    public void onCreate() {
        super.onCreate();
    }

    @Override
    public IBinder onBind(Intent intent) {
        // Return the interface.
        return binder;
    }

    private final IRemoteService.Stub binder = new IRemoteService.Stub() {
        public int getPid(){
            return Process.myPid();
        }
        public void basicTypes(int anInt, long aLong, boolean aBoolean,
            float aFloat, double aDouble, String aString) {
            // Does nothing.
        }
    };
}

עכשיו, כשלקוח, למשל פעילות, קורא ל-bindService() כדי להתחבר לשירות הזה, הקריאה החוזרת של הלקוח onServiceConnected() מקבלת את המכונה binder שמוחזרת באמצעות method onBind() של השירות.

בנוסף, ללקוח צריכה להיות גישה למחלקת הממשק. לכן, אם הלקוח והשירות נמצאים באפליקציות נפרדות, באפליקציית הלקוח צריכה להיות עותק של הקובץ .aidl בתיקייה src/, שמניב את הממשק android.os.Binder ומספק ללקוח גישה לשיטות AIDL.

כשהלקוח מקבל את IBinder בקריאה החוזרת (callback) של onServiceConnected(), הוא צריך לקרוא ל-YourServiceInterface.Stub.asInterface(service) כדי להמיר את הפרמטר שמוחזר לסוג YourServiceInterface:

Kotlin

var iRemoteService: IRemoteService? = null

val mConnection = object : ServiceConnection {

    // Called when the connection with the service is established.
    override fun onServiceConnected(className: ComponentName, service: IBinder) {
        // Following the preceding example for an AIDL interface,
        // this gets an instance of the IRemoteInterface, which we can use to call on the service.
        iRemoteService = IRemoteService.Stub.asInterface(service)
    }

    // Called when the connection with the service disconnects unexpectedly.
    override fun onServiceDisconnected(className: ComponentName) {
        Log.e(TAG, "Service has unexpectedly disconnected")
        iRemoteService = null
    }
}

Java

IRemoteService iRemoteService;
private ServiceConnection mConnection = new ServiceConnection() {
    // Called when the connection with the service is established.
    public void onServiceConnected(ComponentName className, IBinder service) {
        // Following the preceding example for an AIDL interface,
        // this gets an instance of the IRemoteInterface, which we can use to call on the service.
        iRemoteService = IRemoteService.Stub.asInterface(service);
    }

    // Called when the connection with the service disconnects unexpectedly.
    public void onServiceDisconnected(ComponentName className) {
        Log.e(TAG, "Service has unexpectedly disconnected");
        iRemoteService = null;
    }
};

דוגמאות נוספות לקוד זמינות בכיתה RemoteService.java ב- ApiDemos.

העברת אובייקטים דרך IPC

ב-Android 10 (רמת API 29 ואילך), אפשר להגדיר אובייקטים של Parcelable ישירות ב-AIDL. בנוסף, יש תמיכה בסוגים שנתמכים כארגומנטים של ממשק AIDL וב-Parcelables אחרים. כך אפשר לחסוך את העבודה הנוספת של כתיבת קוד שרשור ושל כיתה בהתאמה אישית באופן ידני. עם זאת, הפעולה הזו יוצרת גם struct ריק. אם רוצים להשתמש ב-accessors בהתאמה אישית או בפונקציות אחרות, צריך להטמיע את Parcelable במקום זאת.

package android.graphics;

// Declare Rect so AIDL can find it and knows that it implements
// the parcelable protocol.
parcelable Rect {
    int left;
    int top;
    int right;
    int bottom;
}

דוגמת הקוד שלמעלה יוצרת באופן אוטומטי מחלקה של Java עם שדות מספרים שלמים left, top, right ו-bottom. כל קוד ה-marshalling הרלוונטי מוטמע באופן אוטומטי, וניתן להשתמש באובייקט ישירות בלי להוסיף הטמעה.

אפשר גם לשלוח כיתה בהתאמה אישית מתהליך אחד לאחר דרך ממשק IPC. עם זאת, חשוב לוודא שהקוד של הכיתה זמין בצד השני של ערוץ ה-IPC, והכיתה צריכה לתמוך בממשק Parcelable. חשוב לתמוך ב-Parcelable כי הוא מאפשר למערכת Android לפרק אובייקטים לפרימיטיבים שאפשר לארגן ברצף בתוך תהליכים.

כדי ליצור סוג מותאם אישית שתומך ב-Parcelable:

  1. מוטמע את הממשק Parcelable במחלקה.
  2. מטמיעים את writeToParcel, שמקבלת את המצב הנוכחי של האובייקט וכותבת אותו ב-Parcel.
  3. מוסיפים למחלקה שדה סטטי בשם CREATOR, שהוא אובייקט שמטמיע את הממשק Parcelable.Creator.
  4. לבסוף, יוצרים קובץ .aidl שמצהיר על הכיתה שלכם לחלוקה, כפי שמוצג בקובץ Rect.aidl הבא.

    אם אתם משתמשים בתהליך build בהתאמה אישית, אל תוסיפו את הקובץ .aidl ל-build. בדומה לקובץ כותרת בשפת C, קובץ .aidl הזה לא עבר הידור.

AIDL משתמש בשיטות ובשדות האלה בקוד שהוא יוצר כדי לארגן את האובייקטים ולפרק אותם.

לדוגמה, זהו קובץ Rect.aidl ליצירת כיתה Rect שניתנת לחלוקה:

package android.graphics;

// Declare Rect so AIDL can find it and knows that it implements
// the parcelable protocol.
parcelable Rect;

זו דוגמה לאופן שבו הכיתה Rect מטמיעה את הפרוטוקול Parcelable.

Kotlin

import android.os.Parcel
import android.os.Parcelable

class Rect() : Parcelable {
    var left: Int = 0
    var top: Int = 0
    var right: Int = 0
    var bottom: Int = 0

    companion object CREATOR : Parcelable.Creator<Rect> {
        override fun createFromParcel(parcel: Parcel): Rect {
            return Rect(parcel)
        }

        override fun newArray(size: Int): Array<Rect?> {
            return Array(size) { null }
        }
    }

    private constructor(inParcel: Parcel) : this() {
        readFromParcel(inParcel)
    }

    override fun writeToParcel(outParcel: Parcel, flags: Int) {
        outParcel.writeInt(left)
        outParcel.writeInt(top)
        outParcel.writeInt(right)
        outParcel.writeInt(bottom)
    }

    private fun readFromParcel(inParcel: Parcel) {
        left = inParcel.readInt()
        top = inParcel.readInt()
        right = inParcel.readInt()
        bottom = inParcel.readInt()
    }

    override fun describeContents(): Int {
        return 0
    }
}

Java

import android.os.Parcel;
import android.os.Parcelable;

public final class Rect implements Parcelable {
    public int left;
    public int top;
    public int right;
    public int bottom;

    public static final Parcelable.Creator<Rect> CREATOR = new Parcelable.Creator<Rect>() {
        public Rect createFromParcel(Parcel in) {
            return new Rect(in);
        }

        public Rect[] newArray(int size) {
            return new Rect[size];
        }
    };

    public Rect() {
    }

    private Rect(Parcel in) {
        readFromParcel(in);
    }

    public void writeToParcel(Parcel out, int flags) {
        out.writeInt(left);
        out.writeInt(top);
        out.writeInt(right);
        out.writeInt(bottom);
    }

    public void readFromParcel(Parcel in) {
        left = in.readInt();
        top = in.readInt();
        right = in.readInt();
        bottom = in.readInt();
    }

    public int describeContents() {
        return 0;
    }
}

הסידור הפנימי של הכיתה Rect פשוט. כדאי לעיין בשיטות האחרות של Parcel כדי לראות אילו סוגים אחרים של ערכים אפשר לכתוב ב-Parcel.

אזהרה: חשוב לזכור את ההשלכות של קבלת נתונים מתהליכים אחרים על האבטחה. במקרה הזה, Rect קורא ארבעה מספרים מ-Parcel, אבל אתם צריכים לוודא שהם נמצאים בטווח הערכים הקבילים לכל מה שהמבצע מנסה לעשות. מידע נוסף על שמירה על אבטחת האפליקציה מפני תוכנות זדוניות זמין במאמר טיפים לאבטחה.

שיטות עם ארגומנטים מסוג Bundle שמכילים Parcelables

אם שיטת קריאה מקבלת אובייקט Bundle שצפוי להכיל אובייקטים שניתן לחלק, חשוב להגדיר את מעבד הטעינה של ה-Bundle על ידי קריאה ל-Bundle.setClassLoader(ClassLoader) לפני שמנסים לקרוא מה-Bundle. אחרת, ייתקלו ב-ClassNotFoundException למרות שהחבילה מוגדרת בצורה נכונה באפליקציה.

לדוגמה, שימו לב לקובץ .aidl לדוגמה הבא:

// IRectInsideBundle.aidl
package com.example.android;

/** Example service interface */
interface IRectInsideBundle {
    /** Rect parcelable is stored in the bundle with key "rect". */
    void saveRect(in Bundle bundle);
}
כפי שמוצג בהטמעה הבאה, הערך של ClassLoader מוגדר במפורש ב-Bundle לפני קריאת Rect:

Kotlin

private val binder = object : IRectInsideBundle.Stub() {
    override fun saveRect(bundle: Bundle) {
      bundle.classLoader = classLoader
      val rect = bundle.getParcelable<Rect>("rect")
      process(rect) // Do more with the parcelable.
    }
}

Java

private final IRectInsideBundle.Stub binder = new IRectInsideBundle.Stub() {
    public void saveRect(Bundle bundle){
        bundle.setClassLoader(getClass().getClassLoader());
        Rect rect = bundle.getParcelable("rect");
        process(rect); // Do more with the parcelable.
    }
};

קריאה לשיטת IPC

כדי להפעיל ממשק מרוחק שמוגדר באמצעות AIDL, מבצעים את השלבים הבאים בסיווג השיחה:

  1. כוללים את הקובץ .aidl בספרייה src/ של הפרויקט.
  2. להצהיר על מופע של הממשק IBinder, שנוצר על סמך ה-AIDL.
  3. הטמעה של ServiceConnection.
  4. קוראים ל-Context.bindService() ומעבירים את ההטמעה של ServiceConnection.
  5. בהטמעה של onServiceConnected(), מקבלים מכונה של IBinder בשם service. קוראים לפונקציה YourInterfaceName.Stub.asInterface((IBinder)service) כדי להמיר את הפרמטר שהוחזר לסוג YourInterface.
  6. קוראים לשיטות שהגדרתם בממשק. תמיד מלכודים חריגים מסוג DeadObjectException, שמושלכים כשהחיבור מתנתק. בנוסף, צריך לזהות חריגות מסוג SecurityException, שמתרחשות כשיש הגדרות AIDL סותרות בשני התהליכים שמעורבים בקריאה לשיטת ה-IPC.
  7. כדי להתנתק, קוראים ל-Context.unbindService() עם מופע הממשק.

חשוב לזכור את הנקודות הבאות כשקוראים לשירות IPC:

  • אובייקטים נספרים בהפניות בין תהליכים.
  • אפשר לשלוח אובייקטים אנונימיים בתור ארגומנטים של שיטות.

מידע נוסף על קישור לשירות זמין בסקירה הכללית על שירותים מקושרים.

לפניכם קוד לדוגמה שמראה קריאה לשירות שנוצר באמצעות AIDL, שנלקח מדוגמת השירות מרחוק בפרויקט ApiDemos.

Kotlin

private const val BUMP_MSG = 1

class Binding : Activity() {

    /** The primary interface you call on the service.  */
    private var mService: IRemoteService? = null

    /** Another interface you use on the service.  */
    internal var secondaryService: ISecondary? = null

    private lateinit var killButton: Button
    private lateinit var callbackText: TextView
    private lateinit var handler: InternalHandler

    private var isBound: Boolean = false

    /**
     * Class for interacting with the main interface of the service.
     */
    private val mConnection = object : ServiceConnection {

        override fun onServiceConnected(className: ComponentName, service: IBinder) {
            // This is called when the connection with the service is
            // established, giving us the service object we can use to
            // interact with the service.  We are communicating with our
            // service through an IDL interface, so get a client-side
            // representation of that from the raw service object.
            mService = IRemoteService.Stub.asInterface(service)
            killButton.isEnabled = true
            callbackText.text = "Attached."

            // We want to monitor the service for as long as we are
            // connected to it.
            try {
                mService?.registerCallback(mCallback)
            } catch (e: RemoteException) {
                // In this case, the service crashes before we can
                // do anything with it. We can count on soon being
                // disconnected (and then reconnected if it can be restarted)
                // so there is no need to do anything here.
            }

            // As part of the sample, tell the user what happened.
            Toast.makeText(
                    this@Binding,
                    R.string.remote_service_connected,
                    Toast.LENGTH_SHORT
            ).show()
        }

        override fun onServiceDisconnected(className: ComponentName) {
            // This is called when the connection with the service is
            // unexpectedly disconnected&mdash;that is, its process crashed.
            mService = null
            killButton.isEnabled = false
            callbackText.text = "Disconnected."

            // As part of the sample, tell the user what happened.
            Toast.makeText(
                    this@Binding,
                    R.string.remote_service_disconnected,
                    Toast.LENGTH_SHORT
            ).show()
        }
    }

    /**
     * Class for interacting with the secondary interface of the service.
     */
    private val secondaryConnection = object : ServiceConnection {

        override fun onServiceConnected(className: ComponentName, service: IBinder) {
            // Connecting to a secondary interface is the same as any
            // other interface.
            secondaryService = ISecondary.Stub.asInterface(service)
            killButton.isEnabled = true
        }

        override fun onServiceDisconnected(className: ComponentName) {
            secondaryService = null
            killButton.isEnabled = false
        }
    }

    private val mBindListener = View.OnClickListener {
        // Establish a couple connections with the service, binding
        // by interface names. This lets other applications be
        // installed that replace the remote service by implementing
        // the same interface.
        val intent = Intent(this@Binding, RemoteService::class.java)
        intent.action = IRemoteService::class.java.name
        bindService(intent, mConnection, Context.BIND_AUTO_CREATE)
        intent.action = ISecondary::class.java.name
        bindService(intent, secondaryConnection, Context.BIND_AUTO_CREATE)
        isBound = true
        callbackText.text = "Binding."
    }

    private val unbindListener = View.OnClickListener {
        if (isBound) {
            // If we have received the service, and hence registered with
            // it, then now is the time to unregister.
            try {
                mService?.unregisterCallback(mCallback)
            } catch (e: RemoteException) {
                // There is nothing special we need to do if the service
                // crashes.
            }

            // Detach our existing connection.
            unbindService(mConnection)
            unbindService(secondaryConnection)
            killButton.isEnabled = false
            isBound = false
            callbackText.text = "Unbinding."
        }
    }

    private val killListener = View.OnClickListener {
        // To kill the process hosting the service, we need to know its
        // PID.  Conveniently, the service has a call that returns
        // that information.
        try {
            secondaryService?.pid?.also { pid ->
                // Note that, though this API lets us request to
                // kill any process based on its PID, the kernel
                // still imposes standard restrictions on which PIDs you
                // can actually kill. Typically this means only
                // the process running your application and any additional
                // processes created by that app, as shown here. Packages
                // sharing a common UID are also able to kill each
                // other's processes.
                Process.killProcess(pid)
                callbackText.text = "Killed service process."
            }
        } catch (ex: RemoteException) {
            // Recover gracefully from the process hosting the
            // server dying.
            // For purposes of this sample, put up a notification.
            Toast.makeText(this@Binding, R.string.remote_call_failed, Toast.LENGTH_SHORT).show()
        }
    }

    // ----------------------------------------------------------------------
    // Code showing how to deal with callbacks.
    // ----------------------------------------------------------------------

    /**
     * This implementation is used to receive callbacks from the remote
     * service.
     */
    private val mCallback = object : IRemoteServiceCallback.Stub() {
        /**
         * This is called by the remote service regularly to tell us about
         * new values.  Note that IPC calls are dispatched through a thread
         * pool running in each process, so the code executing here is
         * NOT running in our main thread like most other things. So,
         * to update the UI, we need to use a Handler to hop over there.
         */
        override fun valueChanged(value: Int) {
            handler.sendMessage(handler.obtainMessage(BUMP_MSG, value, 0))
        }
    }

    /**
     * Standard initialization of this activity.  Set up the UI, then wait
     * for the user to interact with it before doing anything.
     */
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        setContentView(R.layout.remote_service_binding)

        // Watch for button taps.
        var button: Button = findViewById(R.id.bind)
        button.setOnClickListener(mBindListener)
        button = findViewById(R.id.unbind)
        button.setOnClickListener(unbindListener)
        killButton = findViewById(R.id.kill)
        killButton.setOnClickListener(killListener)
        killButton.isEnabled = false

        callbackText = findViewById(R.id.callback)
        callbackText.text = "Not attached."
        handler = InternalHandler(callbackText)
    }

    private class InternalHandler(
            textView: TextView,
            private val weakTextView: WeakReference<TextView> = WeakReference(textView)
    ) : Handler() {
        override fun handleMessage(msg: Message) {
            when (msg.what) {
                BUMP_MSG -> weakTextView.get()?.text = "Received from service: ${msg.arg1}"
                else -> super.handleMessage(msg)
            }
        }
    }
}

Java

public static class Binding extends Activity {
    /** The primary interface we are calling on the service. */
    IRemoteService mService = null;
    /** Another interface we use on the service. */
    ISecondary secondaryService = null;

    Button killButton;
    TextView callbackText;

    private InternalHandler handler;
    private boolean isBound;

    /**
     * Standard initialization of this activity. Set up the UI, then wait
     * for the user to interact with it before doing anything.
     */
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        setContentView(R.layout.remote_service_binding);

        // Watch for button taps.
        Button button = (Button)findViewById(R.id.bind);
        button.setOnClickListener(mBindListener);
        button = (Button)findViewById(R.id.unbind);
        button.setOnClickListener(unbindListener);
        killButton = (Button)findViewById(R.id.kill);
        killButton.setOnClickListener(killListener);
        killButton.setEnabled(false);

        callbackText = (TextView)findViewById(R.id.callback);
        callbackText.setText("Not attached.");
        handler = new InternalHandler(callbackText);
    }

    /**
     * Class for interacting with the main interface of the service.
     */
    private ServiceConnection mConnection = new ServiceConnection() {
        public void onServiceConnected(ComponentName className,
                IBinder service) {
            // This is called when the connection with the service is
            // established, giving us the service object we can use to
            // interact with the service.  We are communicating with our
            // service through an IDL interface, so get a client-side
            // representation of that from the raw service object.
            mService = IRemoteService.Stub.asInterface(service);
            killButton.setEnabled(true);
            callbackText.setText("Attached.");

            // We want to monitor the service for as long as we are
            // connected to it.
            try {
                mService.registerCallback(mCallback);
            } catch (RemoteException e) {
                // In this case the service crashes before we can even
                // do anything with it. We can count on soon being
                // disconnected (and then reconnected if it can be restarted)
                // so there is no need to do anything here.
            }

            // As part of the sample, tell the user what happened.
            Toast.makeText(Binding.this, R.string.remote_service_connected,
                    Toast.LENGTH_SHORT).show();
        }

        public void onServiceDisconnected(ComponentName className) {
            // This is called when the connection with the service is
            // unexpectedly disconnected&mdash;that is, its process crashed.
            mService = null;
            killButton.setEnabled(false);
            callbackText.setText("Disconnected.");

            // As part of the sample, tell the user what happened.
            Toast.makeText(Binding.this, R.string.remote_service_disconnected,
                    Toast.LENGTH_SHORT).show();
        }
    };

    /**
     * Class for interacting with the secondary interface of the service.
     */
    private ServiceConnection secondaryConnection = new ServiceConnection() {
        public void onServiceConnected(ComponentName className,
                IBinder service) {
            // Connecting to a secondary interface is the same as any
            // other interface.
            secondaryService = ISecondary.Stub.asInterface(service);
            killButton.setEnabled(true);
        }

        public void onServiceDisconnected(ComponentName className) {
            secondaryService = null;
            killButton.setEnabled(false);
        }
    };

    private OnClickListener mBindListener = new OnClickListener() {
        public void onClick(View v) {
            // Establish a couple connections with the service, binding
            // by interface names. This lets other applications be
            // installed that replace the remote service by implementing
            // the same interface.
            Intent intent = new Intent(Binding.this, RemoteService.class);
            intent.setAction(IRemoteService.class.getName());
            bindService(intent, mConnection, Context.BIND_AUTO_CREATE);
            intent.setAction(ISecondary.class.getName());
            bindService(intent, secondaryConnection, Context.BIND_AUTO_CREATE);
            isBound = true;
            callbackText.setText("Binding.");
        }
    };

    private OnClickListener unbindListener = new OnClickListener() {
        public void onClick(View v) {
            if (isBound) {
                // If we have received the service, and hence registered with
                // it, then now is the time to unregister.
                if (mService != null) {
                    try {
                        mService.unregisterCallback(mCallback);
                    } catch (RemoteException e) {
                        // There is nothing special we need to do if the service
                        // crashes.
                    }
                }

                // Detach our existing connection.
                unbindService(mConnection);
                unbindService(secondaryConnection);
                killButton.setEnabled(false);
                isBound = false;
                callbackText.setText("Unbinding.");
            }
        }
    };

    private OnClickListener killListener = new OnClickListener() {
        public void onClick(View v) {
            // To kill the process hosting our service, we need to know its
            // PID.  Conveniently, our service has a call that returns
            // that information.
            if (secondaryService != null) {
                try {
                    int pid = secondaryService.getPid();
                    // Note that, though this API lets us request to
                    // kill any process based on its PID, the kernel
                    // still imposes standard restrictions on which PIDs you
                    // can actually kill.  Typically this means only
                    // the process running your application and any additional
                    // processes created by that app as shown here. Packages
                    // sharing a common UID are also able to kill each
                    // other's processes.
                    Process.killProcess(pid);
                    callbackText.setText("Killed service process.");
                } catch (RemoteException ex) {
                    // Recover gracefully from the process hosting the
                    // server dying.
                    // For purposes of this sample, put up a notification.
                    Toast.makeText(Binding.this,
                            R.string.remote_call_failed,
                            Toast.LENGTH_SHORT).show();
                }
            }
        }
    };

    // ----------------------------------------------------------------------
    // Code showing how to deal with callbacks.
    // ----------------------------------------------------------------------

    /**
     * This implementation is used to receive callbacks from the remote
     * service.
     */
    private IRemoteServiceCallback mCallback = new IRemoteServiceCallback.Stub() {
        /**
         * This is called by the remote service regularly to tell us about
         * new values.  Note that IPC calls are dispatched through a thread
         * pool running in each process, so the code executing here is
         * NOT running in our main thread like most other things. So,
         * to update the UI, we need to use a Handler to hop over there.
         */
        public void valueChanged(int value) {
            handler.sendMessage(handler.obtainMessage(BUMP_MSG, value, 0));
        }
    };

    private static final int BUMP_MSG = 1;

    private static class InternalHandler extends Handler {
        private final WeakReference<TextView> weakTextView;

        InternalHandler(TextView textView) {
            weakTextView = new WeakReference<>(textView);
        }

        @Override
        public void handleMessage(Message msg) {
            switch (msg.what) {
                case BUMP_MSG:
                    TextView textView = weakTextView.get();
                    if (textView != null) {
                        textView.setText("Received from service: " + msg.arg1);
                    }
                    break;
                default:
                    super.handleMessage(msg);
            }
        }
    }
}