الإبلاغ عن حالة العمل

يوضّح لك هذا الدليل كيفية الإبلاغ عن حالة طلب عمل تم تشغيله في خدمة في الخلفية إلى المكوّن الذي أرسل الطلب. ويتيح لك هذا الإجراء مثلاً الإبلاغ عن حالة الطلب في واجهة المستخدم الخاصة بعنصر Activity. والطريقة المقترَحة لإرسال الحالة وتلقّيها هي استخدام علامة LocalBroadcastManager، التي تجعل محتوى البث مقتصرًا على مكونات Intent في تطبيقك الخاص.

الإبلاغ عن الحالة من JobIntentService

لإرسال حالة طلب عمل في JobIntentService إلى مكوّنات أخرى، أنشِئ أولاً Intent تحتوي على الحالة في بياناته الموسّعة. كخيار، يمكنك إضافة إجراء ومعرّف موارد منتظم (URI) للبيانات إلى Intent هذا.

بعد ذلك، أرسِل Intent من خلال الاتصال على LocalBroadcastManager.sendBroadcast(). يؤدي ذلك إلى إرسال Intent إلى أي مكوّن في تطبيقك تم تسجيله لاستلامه. للحصول على مثيل من LocalBroadcastManager، يمكنك طلب getInstance().

مثلاً:

...
// Defines a custom Intent action
const val BROADCAST_ACTION = "com.example.android.threadsample.BROADCAST"
...
// Defines the key for the status "extra" in an Intent
const val EXTENDED_DATA_STATUS = "com.example.android.threadsample.STATUS"
...
class RSSPullService : JobIntentService() {
    ...
    /*
     * Creates a new Intent containing a Uri object
     * BROADCAST_ACTION is a custom Intent action
     */
    val localIntent = Intent(BROADCAST_ACTION).apply {
        // Puts the status into the Intent
        putExtra(EXTENDED_DATA_STATUS, status)
    }
    // Broadcasts the Intent to receivers in this app.
    LocalBroadcastManager.getInstance(this).sendBroadcast(localIntent)
    ...
}

public final class Constants {
    ...
    // Defines a custom Intent action
    public static final String BROADCAST_ACTION =
        "com.example.android.threadsample.BROADCAST";
    ...
    // Defines the key for the status "extra" in an Intent
    public static final String EXTENDED_DATA_STATUS =
        "com.example.android.threadsample.STATUS";
    ...
}
public class RSSPullService extends JobIntentService {
...
    /*
     * Creates a new Intent containing a Uri object
     * BROADCAST_ACTION is a custom Intent action
     */
    Intent localIntent =
            new Intent(Constants.BROADCAST_ACTION)
            // Puts the status into the Intent
            .putExtra(Constants.EXTENDED_DATA_STATUS, status);
    // Broadcasts the Intent to receivers in this app.
    LocalBroadcastManager.getInstance(this).sendBroadcast(localIntent);
...
}

الخطوة التالية هي معالجة عناصر Intent للبث الواردة في المكوِّن الذي أرسل طلب العمل الأصلي.

تلقّي عمليات بث الحالة من JobIntentService

لتلقّي عناصر Intent للبث، استخدِم الفئة الفرعية BroadcastReceiver. في الفئة الفرعية، نفِّذ طريقة معاودة الاتصال BroadcastReceiver.onReceive() التي تستدعيها LocalBroadcastManager عند تلقّي Intent. يمرر LocalBroadcastManager إشارة Intent الواردة إلى BroadcastReceiver.onReceive().

مثلاً:

// Broadcast receiver for receiving status updates from the IntentService.
private class DownloadStateReceiver : BroadcastReceiver() {

    override fun onReceive(context: Context, intent: Intent) {
        ...
        /*
         * Handle Intents here.
         */
        ...
    }
}

// Broadcast receiver for receiving status updates from the IntentService.
private class DownloadStateReceiver extends BroadcastReceiver
{
    // Called when the BroadcastReceiver gets an Intent it's registered to receive
    @Override
    public void onReceive(Context context, Intent intent) {
...
        /*
         * Handle Intents here.
         */
...
    }
}

بعد تحديد السمة BroadcastReceiver، يمكنك تحديد الفلاتر التي تتطابق مع إجراءات وفئات وبيانات محدّدة. لإجراء ذلك، أنشِئ IntentFilter. يوضّح المقتطف الأول هذا كيفية تحديد الفلتر:

// Class that displays photos
class DisplayActivity : FragmentActivity() {
    ...
    override fun onCreate(savedInstanceState: Bundle?) {
        ...
        super.onCreate(savedInstanceState)
        ...
        // The filter's action is BROADCAST_ACTION
        var statusIntentFilter = IntentFilter(BROADCAST_ACTION).apply {
            // Adds a data filter for the HTTP scheme
            addDataScheme("http")
        }
        ...

// Class that displays photos
public class DisplayActivity extends FragmentActivity {
    ...
    public void onCreate(Bundle stateBundle) {
        ...
        super.onCreate(stateBundle);
        ...
        // The filter's action is BROADCAST_ACTION
        IntentFilter statusIntentFilter = new IntentFilter(
                Constants.BROADCAST_ACTION);

        // Adds a data filter for the HTTP scheme
        statusIntentFilter.addDataScheme("http");
        ...

لتسجيل السمة BroadcastReceiver وIntentFilter في النظام، احصل على مثيل LocalBroadcastManager واستدعِ طريقة registerReceiver() الخاصة بها. يوضّح المقتطف التالي طريقة تسجيل BroadcastReceiver وIntentFilter الخاصة به:

        // Instantiates a new DownloadStateReceiver
        val downloadStateReceiver = DownloadStateReceiver()
        // Registers the DownloadStateReceiver and its intent filters
        LocalBroadcastManager.getInstance(this)
                .registerReceiver(downloadStateReceiver, statusIntentFilter)
        ...

        // Instantiates a new DownloadStateReceiver
        DownloadStateReceiver downloadStateReceiver =
                new DownloadStateReceiver();
        // Registers the DownloadStateReceiver and its intent filters
        LocalBroadcastManager.getInstance(this).registerReceiver(
                downloadStateReceiver,
                statusIntentFilter);
        ...

ويمكن لعنصر BroadcastReceiver واحد معالجة أكثر من نوع واحد من عناصر البث Intent، ولكلٍّ منها إجراء خاص به. تتيح لك هذه الميزة تنفيذ رمز مختلف لكل إجراء، بدون الحاجة إلى تحديد BroadcastReceiver منفصل لكل إجراء. لتحديد سمة IntentFilter أخرى للسمة BroadcastReceiver نفسها، يمكنك إنشاء IntentFilter وتكرار المكالمة مع registerReceiver(). مثلاً:

        /*
         * Instantiates a new action filter.
         * No data filter is needed.
         */
        statusIntentFilter = IntentFilter(ACTION_ZOOM_IMAGE)
        // Registers the receiver with the new filter
        LocalBroadcastManager.getInstance(this)
                .registerReceiver(downloadStateReceiver, statusIntentFilter)

        /*
         * Instantiates a new action filter.
         * No data filter is needed.
         */
        statusIntentFilter = new IntentFilter(Constants.ACTION_ZOOM_IMAGE);
        // Registers the receiver with the new filter
        LocalBroadcastManager.getInstance(this).registerReceiver(
                downloadStateReceiver,
                statusIntentFilter);

لا يؤدي إرسال بث Intent إلى بدء Activity أو استئنافه. إنّ السمة BroadcastReceiver في Activity تتلقّى عناصر Intent وتعالجها حتى عندما يكون تطبيقك يعمل في الخلفية، ولكنها لا تفرض استخدام تطبيقك في المقدّمة. إذا كنت تريد إبلاغ المستخدم بحدث وقع في الخلفية عندما لم يكن تطبيقك مرئيًا، استخدِم Notification. لا يتم بدء Activity مطلقًا ردًا على بث Intent وارد.