engine/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>
 */
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.</p>
     *
     * @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>
         *
         * <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>
         *
         * <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}.
         *
         * 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.
         *
         * 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.
         *
         * 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>
         *
         * <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>
         *
         * <p>Overwrites any previously published value.</p>
         *
         * <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 android.support.v4.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.</p>
     */
    interface PluginRegistrantCallback {
        void registerWith(PluginRegistry registry);
    }
}