Широковещательные приемники в Xamarin.AndroidBroadcast Receivers in Xamarin.Android

В этом разделе описывается использование широковещательного приемника.This section discusses how to use a Broadcast Receiver.

Общие сведения о широковещательный приемникBroadcast Receiver Overview

Объект широковещательный приемник — это Android компонент, который позволяет приложению реагировать на сообщения (Android Intent ), передаваемого Android операционной системой или приложением.A broadcast receiver is an Android component that allows an application to respond to messages (an Android Intent) that are broadcast by the Android operating system or by an application. Выполните широковещательных рассылок публикации и подписки модели – событие вызывает вещания для публикации и полученных те компоненты, которые заинтересованы в событии.Broadcasts follow a publish-subscribe model – an event causes a broadcast to be published and received by those components that are interested in the event.

Android определяет два типа пакетов:Android identifies two types of broadcasts:

  • Явные вещания – этих типов широковещательного предназначенных для конкретного приложения.Explicit broadcast – These types of broadcasts target a specific application. Явные вещания чаще всего используется для запуска действия.The most common use of an explicit broadcast is to start an Activity. Пример явной вещания, когда приложению нужен для набора номера телефона; она передает объект Intent, ориентированном на Android и pass вдоль номер телефона, устанавливать приложение.An example of an explicit broadcast when an app needs to dial a phone number; it will dispatch an Intent that targets the Phone app on Android and pass along the phone number to be dialed. В приложение для телефона Android будет перенаправлять цель.Android will then route the intent to the Phone app.
  • Неявные вещания – презентации доставлены ко всем приложениям на устройстве.Implicit broadcast – These broadcasts are dispatched to all apps on the device. Например неявные вещания, ACTION_POWER_CONNECTED намерение.An example of an implicit broadcast is the ACTION_POWER_CONNECTED intent. В этой описаны публикуется каждый раз, когда Android обнаруживает, что на устройстве зарядки.This intent is published each time Android detects that the battery on the device is charging. Android будет маршрутизации этого намерения ко всем приложениям, которые зарегистрированы для данного события.Android will route this intent to all apps that have registered for this event.

Широковещательный получатель является подклассом BroadcastReceiver типа и его необходимо переопределить OnReceive метод.The broadcast receiver is a subclass of the BroadcastReceiver type and it must override the OnReceive method. Android будет выполняться OnReceive в основном потоке, поэтому этот метод должны разрабатываться выполняться быстро.Android will execute OnReceive on the main thread, so this method should be designed to execute quickly. Следует соблюдать осторожность при создании процесса потоков в OnReceive потому, что Android может завершить процесс при завершении метода.Care should be taken when spawning threads in OnReceive because Android may terminate the process when the method finishes. Если широковещательный получатель должен выполнять длительных рабочих, то рекомендуется запланировать задания с помощью JobScheduler или диспетчер заданий Firebase.If a broadcast receiver must perform long running work then it is recommended to schedule a job using the JobScheduler or the Firebase Job Dispatcher. Планирование работы с заданием будут рассмотрены отдельные руководства.Scheduling work with a job will be discussed in a separate guide.

Фильтром намерений используется для регистрации широковещательный приемник Android правильной передачи сообщений.An intent filter is used to register a broadcast receiver so that Android can properly route messages. Во время выполнения можно указать фильтр намерений (это иногда называется контекст зарегистрирован получателя или как динамической регистрации) или он может быть статически определен в манифесте Android ( регистрации манифеста получателя).The intent filter can be specified at runtime (this is sometimes referred to as a context-registered receiver or as dynamic registration) or it can be statically defined in the Android Manifest (a manifest-registered receiver). Xamarin.Android предоставляет C# атрибут, IntentFilterAttribute, которая статически зарегистрирует фильтр намерений (это будет рассматриваться более подробно далее в этом руководстве).Xamarin.Android provides a C# attribute, IntentFilterAttribute, that will statically register the intent filter (this will be discussed in more detail later in this guide). Начиная с Android 8.0, он не поддерживается для приложения для статически регистрации для неявного вещания.Starting in Android 8.0, it is not possible for an application to statically register for an implicit broadcast.

Основное различие между регистрации манифеста получателя, а получатель контекст зарегистрирован —, что получатель контекст зарегистрирован будет отвечать только на широковещательный трафик во время работы приложения, пока получатель зарегистрированный манифест может отвечать на осуществляет широковещательную передачу, несмотря на то, что приложение может не работать.The primary difference between the manifest-registered receiver and the context-registered receiver is that a context-registered receiver will only respond to broadcasts while an application is running, while a manifest-registered receiver can respond to broadcasts even though the app may not be running.

Существует два набора API для отправки широковещательных рассылок и управления ими широковещательный приемник.There are two sets of APIs for managing a broadcast receiver and sending broadcasts:

  1. ContextAndroid.Content.Context Класс может использоваться для регистрации широковещательный получатель, который будет реагировать на события уровня системы.Context – The Android.Content.Context class can be used to register a broadcast receiver that will respond to system-wide events. Context Также используется для публикации широковещательных рассылок всей системы.The Context is also used to publish system-wide broadcasts.
  2. LocalBroadcastManager – API-интерфейс, который доступен через пакет NuGet библиотеки поддержки Xamarin v4.LocalBroadcastManager – This is an API that is available through the Xamarin Support Library v4 NuGet package. Этот класс используется для вещания и широковещательных получателей, изолированы в контексте приложения, которое их использует.This class is used to keep broadcasts and broadcast receivers isolated in the context of the application that is using them. Этот класс может быть полезно для предотвращения отвечать на широковещательные рассылки только для приложений и отправки сообщений в приемники, закрытый других приложений.This class can be useful for preventing other applications from responding to application-only broadcasts or sending messages to private receivers.

Широковещательный получатель не может отображать диалоговые окна, и это настоятельно не рекомендуется, чтобы начать действия из широковещательных получателей.A broadcast receiver may not display dialogs, and it is strongly discouraged to start an activity from within a broadcast receiver. Если широковещательный получатель должен уведомлять пользователя, его следует опубликовать уведомление.If a broadcast receiver must notify the user, then it should publish a notification.

Не поддерживается для привязки к или запустить службу в широковещательный приемник.It is not possible to bind to or start a service from within a broadcast receiver.

В этом руководстве рассматриваются способы создания широковещательный приемник и зарегистрировать его, чтобы оно может получить широковещательных рассылок.This guide will cover how to create a broadcast receiver and how to register it so that it may receive broadcasts.

Создание получателя рассылкиCreating a Broadcast Receiver

Чтобы создать широковещательный приемник в Xamarin.Android, приложение должно подкласс BroadcastReceiver класса, создавать его с BroadcastReceiverAttributeи Переопределите OnReceive метод:To create a broadcast receiver in Xamarin.Android, an application should subclass the BroadcastReceiver class, adorn it with the BroadcastReceiverAttribute, and override the OnReceive method:

[BroadcastReceiver(Enabled = true, Exported = false)]
public class SampleReceiver : BroadcastReceiver
{
    public override void OnReceive(Context context, Intent intent)
    {
        // Do stuff here.

        String value = intent.GetStringExtra("key");
    }
}

Когда Xamarin.Android компилирует класс, он также будет обновлен AndroidManifest необходимые метаданные для регистрации приемника.When Xamarin.Android compiles the class, it will also update the AndroidManifest with the necessary meta-data to register the receiver. Для статически зарегистрированные широковещательный приемник Enabled правильно, должно быть присвоено true, в противном случае Android будет невозможно создать экземпляр приемника.For a statically-registered broadcast receiver, the Enabled properly must be set to true, otherwise Android will not be able to create an instance of the receiver.

Exported Свойство управляет ли широковещательный получатель может получать сообщения из вне приложения.The Exported property controls whether the broadcast receiver can receive messages from outside the application. Если свойство не задано явным образом, значение по умолчанию свойства определяется на основе при наличии фильтры намерения, связанные с широковещательный приемник Android.If the property is not explicitly set, the default value of the property is determined by Android based on if there are any intent-filters associated with the broadcast receiver. Если есть хотя бы один фильтр намерения для широковещательных получателей, а затем Android предполагается, что Exported свойство true.If there is at least one intent-filter for the broadcast receiver then Android will assume that the Exported property is true. Если не намерение-фильтры, связанные с широковещательных получателей, то Android предполагает, что значение является false.If there are no intent-filters associated with the broadcast receiver, then Android will assume that the value is false.

OnReceive Метод получает ссылку на Intent , был отправлен для широковещательных получателей.The OnReceive method receives a reference to the Intent that was dispatched to the broadcast receiver. В результате возможна для отправителя способа для передачи значений широковещательных получателей.This makes is possible for the sender of the intent to pass values to the broadcast receiver.

Статически регистрация широковещательного приемника с фильтром намерениеStatically registering a Broadcast Receiver with an Intent Filter

Когда BroadcastReceiver снабжен IntentFilterAttribute , Xamarin.Android для добавления необходимой <intent-filter> элемент Android манифеста во время компиляции.When a BroadcastReceiver is decorated with the IntentFilterAttribute, Xamarin.Android will add the necessary <intent-filter> element to the Android manifest at compile time. Ниже приведен пример широковещательный приемник, который будет выполняться после завершения загрузки (если пользователю были предоставлены соответствующие разрешения Android) устройства:The following snippet is an example of a broadcast receiver that will run when a device has finished booting (if the appropriate Android permissions were granted by the user):

[BroadcastReceiver(Enabled = true)]
[IntentFilter(new[] { Android.Content.Intent.ActionBootCompleted })]
public class MyBootReceiver : BroadcastReceiver
{
    public override void OnReceive(Context context, Intent intent)
    {
        // Work that should be done when the device boots.     
    }
}

Можно также создать фильтр намерений, будут отвечать на настраиваемые цели.It is also possible to create an intent filter that will respond to custom intents. Рассмотрим следующий пример.Consider the following example:

[BroadcastReceiver(Enabled = true)]
[IntentFilter(new[] { "com.xamarin.example.TEST" })]
public class MySampleBroadcastReceiver : BroadcastReceiver
{
    public override void OnReceive(Context context, Intent intent)
    {
        // Do stuff here
    }
}

Приложений, предназначенных для Android 8.0 (уровень API 26) или более поздней версии не может зарегистрировать статически неявное широковещательной передачи.Apps that target Android 8.0 (API level 26) or higher may not statically register for an implicit broadcast. Приложения могут по-прежнему статически регистрироваться для явной широковещательной передачи.Apps may still statically register for an explicit broadcast. Имеется небольшой список неявных широковещательные рассылки, которые будут исключены из этих ограничений.There is a small list of implicit broadcasts that are exempt from this restriction. Эти исключения описаны в неявное широковещательных исключения руководство в документации по Android.These exceptions are described in the Implicit Broadcast Exceptions guide in the Android documentation. Приложения, которые хотели бы неявное широковещательные рассылки необходимо выполнить динамически с помощью RegisterReceiver метод.Apps that are interested in implicit broadcasts must do so dynamically using the RegisterReceiver method. Это описано далее.This is described next.

Регистрация контекста широковещательный приемникContext-Registering a Broadcast Receiver

Контекст регистрации (также называется динамической регистрации) приемника выполняется путем вызова RegisterReceiver метод и широковещательных получателей должен выполнить отмену регистрации с вызовом UnregisterReceiver метод.Context-registration (also referred to as dynamic registration) of a receiver is performed by invoking the RegisterReceiver method, and the broadcast receiver must be unregistered with a call to the UnregisterReceiver method. Чтобы предотвратить происходит утечка ресурсов, важно отменять регистрацию получателя, если он больше не нужны для контекста (действие или службы).To prevent leaking resources, it is important to unregister the receiver when it is no longer relevant for the context (the Activity or service). Например служба может широковещательный объекта intent, чтобы указать действие, которое будет отображаться для пользователя доступны обновления.For example, a service may broadcast an intent to inform an Activity that updates are available to be displayed to the user. В начале действия его зарегистрировать для этих целей.When the Activity starts, it would register for those Intents. Когда действие перемещается в фоновом режиме, и больше не отображается для пользователя, необходимо отменить регистрацию получателя, так как пользовательский Интерфейс для отображения обновлений больше не отображается.When the Activity is moved into the background and no longer visible to the user, it should unregister the receiver because the UI for displaying the updates is no longer visible. В следующем фрагменте кода приведен пример того, как регистрировать и отменять регистрацию широковещательный приемник в контексте действия:The following code snippet is an example of how to register and unregister a broadcast receiver in the context of an Activity:

[Activity(Label = "MainActivity", MainLauncher = true, Icon = "@mipmap/icon")]
public class MainActivity: Activity 
{
    MySampleBroadcastReceiver receiver;

    protected override void OnCreate(Bundle savedInstanceState)
    {
        base.OnCreate(savedInstanceState);
        receiver = new MySampleBroadcastReceiver()

        // Code omitted for clarity
    }

    protected override OnResume() 
    {
        base.OnResume();
        RegisterReceiver(receiver, new IntentFilter("com.xamarin.example.TEST"));
        // Code omitted for clarity
    }

    protected override OnPause() 
    {
        UnregisterReceiver(receiver);
        // Code omitted for clarity
        base.OnPause();
    }
}

В предыдущем примере, когда действие поступает на переднем плане, он будет зарегистрирован широковещательный приемник, который будет прослушивать пользовательских намерение с помощью OnResume метод жизненного цикла.In the previous example, when the Activity comes into the foreground, it will register a broadcast receiver that will listen for a custom intent by using the OnResume lifecycle method. Действия при перемещении в фоновом режиме, OnPause() метод будет отменена регистрация получателя.As the Activity moves into the background, the OnPause() method will unregister the receiver.

Публикация вещанияPublishing a Broadcast

Вещание могут быть опубликованы все приложения, установленные на устройстве, создавая объект намерения и распределения их с SendBroadcast или SendOrderedBroadcast метод.A broadcast may be published to all apps installed on the device creating an Intent object and dispatching it with the SendBroadcast or the SendOrderedBroadcast method.

  1. Методы Context.SendBroadcast – существует несколько реализаций этого метода.Context.SendBroadcast methods – There are several implementations of this method. Эти методы будут разосланы целью всей системы.These methods will broadcast the intent to the entire system. Широковещательные приемники, которые будут получать цель в неопределенном порядке.Broadcast receivers that will receive the intent in an indeterminate order. Это обеспечивает значительную гибкость, но означает, что другие приложения могут зарегистрироваться и получать цель.This provides a great deal of flexibility but means that it is possible for other applications to register and receive the intent. Это может представлять угрозу безопасности.This can pose a potential security risk. Приложения, нужно реализовать сложения безопасности для предотвращения несанкционированного доступа.Applications may need to implement addition security to prevent unauthorized access. Одно из возможных решений является использование LocalBroadcastManager которого будет только перенаправления сообщений, отправляемых в закрытый пространстве приложения.One possible solution is to use the LocalBroadcastManager which will only dispatch messages within the private space of the app. В этом фрагменте кода приведен пример того, как для отправки объекта intent, с помощью одного из SendBroadcast методы:This code snippet is one example of how to dispatch an intent using one of the SendBroadcast methods:

    Intent message = new Intent("com.xamarin.example.TEST");
    // If desired, pass some values to the broadcast receiver.
    message.PutExtra("key", "value");
    SendBroadcast(message);
    

    В этом фрагменте приведен еще один пример отправки вещания с помощью Intent.SetAction метод для идентификации действия:This snippet is another example of sending a broadcast by using the Intent.SetAction method to identify the action:

    Intent intent = new Intent();
    intent.SetAction("com.xamarin.example.TEST");
    intent.PutExtra("key", "value");
    SendBroadcast(intent);
    
  2. Context.SendOrderedBroadcast – это метод очень похожа на Context.SendBroadcast, с разницей, что цель будет опубликованных во время для приемников, в том порядке, что получатели были зарегистрированы.Context.SendOrderedBroadcast – This is method is very similar to Context.SendBroadcast, with the difference being that the intent will be published one at time to receivers, in the order that the receivers were registered.

LocalBroadcastManagerLocalBroadcastManager

V4 библиотека поддержки Xamarin предоставляет вспомогательный класс с именем LocalBroadcastManager .The Xamarin Support Library v4 provides a helper class called LocalBroadcastManager. LocalBroadcastManager Предназначен для приложений, которые не хотите отправлять или получать широковещательные пакеты из других приложений на устройстве.The LocalBroadcastManager is intended for apps that do not want to send or receive broadcasts from other apps on the device. LocalBroadcastManager Только будет публиковать сообщения в контексте приложения и только для этих широковещательных получателей, которые зарегистрированы в LocalBroadcastManager.The LocalBroadcastManager will only publish messages within the context of the application, and only to those broadcast receivers that are registered with the LocalBroadcastManager. В этом фрагменте кода приведен пример регистрации широковещательный приемник с LocalBroadcastManager:This code snippet is an example of registering a broadcast receiver with LocalBroadcastManager:

Android.Support.V4.Content.LocalBroadcastManager.GetInstance(this). RegisterReceiver(receiver, new IntentFilter("com.xamarin.example.TEST"));

Другие приложения на устройстве не может принимать сообщения, которые публикуются с LocalBroadcastManager.Other apps on the device cannot receive the messages that are published with the LocalBroadcastManager. В этом фрагменте кода показано, как для отправки в намерения с помощью LocalBroadcastManager:This code snippet shows how to dispatch an Intent using the LocalBroadcastManager:

Intent message = new Intent("com.xamarin.example.TEST");
// If desired, pass some values to the broadcast receiver.
message.PutExtra("key", "value");
Android.Support.V4.Content.LocalBroadcastManager.GetInstance(this).SendBroadcast(message);