shell/platform/android/io/flutter/plugin/common/PluginRegistry.java

// Copyright 2013 The Flutter Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

package io.flutter.plugin.common;

import android.app.Activity;
import android.content.Context;
import android.content.Intent;
import io.flutter.embedding.engine.plugins.FlutterPlugin;
import io.flutter.embedding.engine.plugins.activity.ActivityAware;
import io.flutter.embedding.engine.plugins.activity.ActivityPluginBinding;
import io.flutter.plugin.platform.PlatformViewRegistry;
import io.flutter.view.FlutterNativeView;
import io.flutter.view.FlutterView;
import io.flutter.view.TextureRegistry;

/**
 * Registry used by plugins to set up interaction with Android APIs.
 *
 * <p>Flutter applications by default include an auto-generated and auto-updated plugin registrant
 * class (GeneratedPluginRegistrant) that makes use of a {@link PluginRegistry} to register
 * contributions from each plugin mentioned in the application's pubspec file. The generated
 * registrant class is, again by default, called from the application's main {@link Activity}, which
 * defaults to an instance of {@link io.flutter.app.FlutterActivity}, itself a {@link
 * PluginRegistry}.
 *
 * <p>This class is now deprecated. See https://flutter.dev/go/android-project-migration for
 * migration details.
 */
public interface PluginRegistry {
  /**
   * Returns a {@link Registrar} for receiving the registrations pertaining to the specified plugin.
   *
   * @param pluginKey a unique String identifying the plugin; typically the fully qualified name of
   *     the plugin's main class.
   */
  Registrar registrarFor(String pluginKey);

  /**
   * Returns whether the specified plugin is known to this registry.
   *
   * @param pluginKey a unique String identifying the plugin; typically the fully qualified name of
   *     the plugin's main class.
   * @return true if this registry has handed out a registrar for the specified plugin.
   */
  boolean hasPlugin(String pluginKey);

  /**
   * Returns the value published by the specified plugin, if any.
   *
   * <p>Plugins may publish a single value, such as an instance of the plugin's main class, for
   * situations where external control or interaction is needed. Clients are expected to know the
   * value's type.
   *
   * @param pluginKey a unique String identifying the plugin; typically the fully qualified name of
   *     the plugin's main class.
   * @return the published value, possibly null.
   */
  <T> T valuePublishedByPlugin(String pluginKey);

  /**
   * Receiver of registrations from a single plugin.
   *
   * <p>This registrar is for Flutter's v1 embedding. For instructions on migrating a plugin from
   * Flutter's v1 Android embedding to v2, visit http://flutter.dev/go/android-plugin-migration
   */
  interface Registrar {
    /**
     * Returns the {@link Activity} that forms the plugin's operating context.
     *
     * <p>Plugin authors should not assume the type returned by this method is any specific subclass
     * of {@code Activity} (such as {@link io.flutter.app.FlutterActivity} or {@link
     * io.flutter.app.FlutterFragmentActivity}), as applications are free to use any activity
     * subclass.
     *
     * <p>When there is no foreground activity in the application, this will return null. If a
     * {@link Context} is needed, use context() to get the application's context.
     *
     * <p>This registrar is for Flutter's v1 embedding. To access an {@code Activity} from a plugin
     * using the v2 embedding, see {@link ActivityPluginBinding#getActivity()}. To obtain an
     * instance of an {@link ActivityPluginBinding} in a Flutter plugin, implement the {@link
     * ActivityAware} interface. A binding is provided in {@link
     * ActivityAware#onAttachedToActivity(ActivityPluginBinding)} and {@link
     * ActivityAware#onReattachedToActivityForConfigChanges(ActivityPluginBinding)}.
     *
     * <p>For instructions on migrating a plugin from Flutter's v1 Android embedding to v2, visit
     * http://flutter.dev/go/android-plugin-migration
     */
    Activity activity();

    /**
     * Returns the {@link android.app.Application}'s {@link Context}.
     *
     * <p>This registrar is for Flutter's v1 embedding. To access a {@code Context} from a plugin
     * using the v2 embedding, see {@link
     * FlutterPlugin.FlutterPluginBinding#getApplicationContext()}
     *
     * <p>For instructions on migrating a plugin from Flutter's v1 Android embedding to v2, visit
     * http://flutter.dev/go/android-plugin-migration
     */
    Context context();

    /**
     * Returns the active {@link Context}.
     *
     * <p>This registrar is for Flutter's v1 embedding. In the v2 embedding, there is no concept of
     * an "active context". Either use the application {@code Context} or an attached {@code
     * Activity}. See {@link #context()} and {@link #activity()} for more details.
     *
     * <p>For instructions on migrating a plugin from Flutter's v1 Android embedding to v2, visit
     * http://flutter.dev/go/android-plugin-migration
     *
     * @return the current {@link #activity() Activity}, if not null, otherwise the {@link
     *     #context() Application}.
     */
    Context activeContext();

    /**
     * Returns a {@link BinaryMessenger} which the plugin can use for creating channels for
     * communicating with the Dart side.
     *
     * <p>This registrar is for Flutter's v1 embedding. To access a {@code BinaryMessenger} from a
     * plugin using the v2 embedding, see {@link
     * FlutterPlugin.FlutterPluginBinding#getBinaryMessenger()}
     *
     * <p>For instructions on migrating a plugin from Flutter's v1 Android embedding to v2, visit
     * http://flutter.dev/go/android-plugin-migration
     */
    BinaryMessenger messenger();

    /**
     * Returns a {@link TextureRegistry} which the plugin can use for managing backend textures.
     *
     * <p>This registrar is for Flutter's v1 embedding. To access a {@code TextureRegistry} from a
     * plugin using the v2 embedding, see {@link
     * FlutterPlugin.FlutterPluginBinding#getTextureRegistry()}
     *
     * <p>For instructions on migrating a plugin from Flutter's v1 Android embedding to v2, visit
     * http://flutter.dev/go/android-plugin-migration
     */
    TextureRegistry textures();

    /**
     * Returns the application's {@link PlatformViewRegistry}.
     *
     * <p>Plugins can use the platform registry to register their view factories.
     *
     * <p>This registrar is for Flutter's v1 embedding. To access a {@code PlatformViewRegistry}
     * from a plugin using the v2 embedding, see {@link
     * FlutterPlugin.FlutterPluginBinding#getPlatformViewRegistry()}
     *
     * <p>For instructions on migrating a plugin from Flutter's v1 Android embedding to v2, visit
     * http://flutter.dev/go/android-plugin-migration
     */
    PlatformViewRegistry platformViewRegistry();

    /**
     * Returns the {@link FlutterView} that's instantiated by this plugin's {@link #activity()
     * activity}.
     *
     * <p>This registrar is for Flutter's v1 embedding. The {@link FlutterView} referenced by this
     * method does not exist in the v2 embedding. Additionally, no {@code View} is exposed to any
     * plugins in the v2 embedding. Platform views can access their containing {@code View} using
     * the platform views APIs. If you have a use-case that absolutely requires a plugin to access
     * an Android {@code View}, please file a ticket on GitHub.
     *
     * <p>For instructions on migrating a plugin from Flutter's v1 Android embedding to v2, visit
     * http://flutter.dev/go/android-plugin-migration
     */
    FlutterView view();

    /**
     * Returns the file name for the given asset. The returned file name can be used to access the
     * asset in the APK through the {@link android.content.res.AssetManager} API.
     *
     * <p>TODO(mattcarroll): point this method towards new lookup method.
     *
     * @param asset the name of the asset. The name can be hierarchical
     * @return the filename to be used with {@link android.content.res.AssetManager}
     */
    String lookupKeyForAsset(String asset);

    /**
     * Returns the file name for the given asset which originates from the specified packageName.
     * The returned file name can be used to access the asset in the APK through the {@link
     * android.content.res.AssetManager} API.
     *
     * <p>TODO(mattcarroll): point this method towards new lookup method.
     *
     * @param asset the name of the asset. The name can be hierarchical
     * @param packageName the name of the package from which the asset originates
     * @return the file name to be used with {@link android.content.res.AssetManager}
     */
    String lookupKeyForAsset(String asset, String packageName);

    /**
     * Publishes a value associated with the plugin being registered.
     *
     * <p>The published value is available to interested clients via {@link
     * PluginRegistry#valuePublishedByPlugin(String)}.
     *
     * <p>Publication should be done only when client code needs to interact with the plugin in a
     * way that cannot be accomplished by the plugin registering callbacks with client APIs.
     *
     * <p>Overwrites any previously published value.
     *
     * <p>This registrar is for Flutter's v1 embedding. The concept of publishing values from
     * plugins is not supported in the v2 embedding.
     *
     * <p>For instructions on migrating a plugin from Flutter's v1 Android embedding to v2, visit
     * http://flutter.dev/go/android-plugin-migration
     *
     * @param value the value, possibly null.
     * @return this {@link Registrar}.
     */
    Registrar publish(Object value);

    /**
     * Adds a callback allowing the plugin to take part in handling incoming calls to {@code
     * Activity#onRequestPermissionsResult(int, String[], int[])} or {@code
     * androidx.core.app.ActivityCompat.OnRequestPermissionsResultCallback#onRequestPermissionsResult(int,
     * String[], int[])}.
     *
     * <p>This registrar is for Flutter's v1 embedding. To listen for permission results in the v2
     * embedding, use {@link
     * ActivityPluginBinding#addRequestPermissionsResultListener(RequestPermissionsResultListener)}.
     *
     * <p>For instructions on migrating a plugin from Flutter's v1 Android embedding to v2, visit
     * http://flutter.dev/go/android-plugin-migration
     *
     * @param listener a {@link RequestPermissionsResultListener} callback.
     * @return this {@link Registrar}.
     */
    Registrar addRequestPermissionsResultListener(RequestPermissionsResultListener listener);

    /**
     * Adds a callback allowing the plugin to take part in handling incoming calls to {@link
     * Activity#onActivityResult(int, int, Intent)}.
     *
     * <p>This registrar is for Flutter's v1 embedding. To listen for {@code Activity} results in
     * the v2 embedding, use {@link
     * ActivityPluginBinding#addActivityResultListener(ActivityResultListener)}.
     *
     * <p>For instructions on migrating a plugin from Flutter's v1 Android embedding to v2, visit
     * http://flutter.dev/go/android-plugin-migration
     *
     * @param listener an {@link ActivityResultListener} callback.
     * @return this {@link Registrar}.
     */
    Registrar addActivityResultListener(ActivityResultListener listener);

    /**
     * Adds a callback allowing the plugin to take part in handling incoming calls to {@link
     * Activity#onNewIntent(Intent)}.
     *
     * <p>This registrar is for Flutter's v1 embedding. To listen for new {@code Intent}s in the v2
     * embedding, use {@link ActivityPluginBinding#addOnNewIntentListener(NewIntentListener)}.
     *
     * <p>For instructions on migrating a plugin from Flutter's v1 Android embedding to v2, visit
     * http://flutter.dev/go/android-plugin-migration
     *
     * @param listener a {@link NewIntentListener} callback.
     * @return this {@link Registrar}.
     */
    Registrar addNewIntentListener(NewIntentListener listener);

    /**
     * Adds a callback allowing the plugin to take part in handling incoming calls to {@link
     * Activity#onUserLeaveHint()}.
     *
     * <p>This registrar is for Flutter's v1 embedding. To listen for leave hints in the v2
     * embedding, use {@link
     * ActivityPluginBinding#addOnUserLeaveHintListener(UserLeaveHintListener)}.
     *
     * <p>For instructions on migrating a plugin from Flutter's v1 Android embedding to v2, visit
     * http://flutter.dev/go/android-plugin-migration
     *
     * @param listener a {@link UserLeaveHintListener} callback.
     * @return this {@link Registrar}.
     */
    Registrar addUserLeaveHintListener(UserLeaveHintListener listener);

    /**
     * Adds a callback allowing the plugin to take part in handling incoming calls to {@link
     * Activity#onDestroy()}.
     *
     * <p>This registrar is for Flutter's v1 embedding. The concept of {@code View} destruction does
     * not exist in the v2 embedding. However, plugins in the v2 embedding can respond to {@link
     * ActivityAware#onDetachedFromActivityForConfigChanges()} and {@link
     * ActivityAware#onDetachedFromActivity()}, which indicate the loss of a visual context for the
     * running Flutter experience. Developers should implement {@link ActivityAware} for their
     * {@link FlutterPlugin} if such callbacks are needed. Also, plugins can respond to {@link
     * FlutterPlugin#onDetachedFromEngine(FlutterPlugin.FlutterPluginBinding)}, which indicates that
     * the given plugin has been completely disconnected from the associated Flutter experience and
     * should clean up any resources.
     *
     * <p>For instructions on migrating a plugin from Flutter's v1 Android embedding to v2, visit
     * http://flutter.dev/go/android-plugin-migration
     *
     * @param listener a {@link ViewDestroyListener} callback.
     * @return this {@link Registrar}.
     */
    // TODO(amirh): Add a line in the javadoc above that points to a Platform Views website guide
    // when one is available (but not a website API doc)
    Registrar addViewDestroyListener(ViewDestroyListener listener);
  }

  /**
   * Delegate interface for handling result of permissions requests on behalf of the main {@link
   * Activity}.
   */
  interface RequestPermissionsResultListener {
    /** @return true if the result has been handled. */
    boolean onRequestPermissionsResult(int requestCode, String[] permissions, int[] grantResults);
  }

  /** Delegate interface for handling activity results on behalf of the main {@link Activity}. */
  interface ActivityResultListener {
    /** @return true if the result has been handled. */
    boolean onActivityResult(int requestCode, int resultCode, Intent data);
  }

  /** Delegate interface for handling new intents on behalf of the main {@link Activity}. */
  interface NewIntentListener {
    /** @return true if the new intent has been handled. */
    boolean onNewIntent(Intent intent);
  }

  /** Delegate interface for handling user leave hints on behalf of the main {@link Activity}. */
  interface UserLeaveHintListener {
    void onUserLeaveHint();
  }

  /**
   * Delegate interface for handling an {@link Activity}'s onDestroy method being called. A plugin
   * that implements this interface can adopt the FlutterNativeView by retaining a reference and
   * returning true.
   */
  interface ViewDestroyListener {
    boolean onViewDestroy(FlutterNativeView view);
  }

  /**
   * Callback interface for registering plugins with a plugin registry.
   *
   * <p>For example, an Application may use this callback interface to provide a background service
   * with a callback for calling its GeneratedPluginRegistrant.registerWith method.
   */
  interface PluginRegistrantCallback {
    void registerWith(PluginRegistry registry);
  }
}