| // 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 androidx.annotation.NonNull; |
| import androidx.annotation.Nullable; |
| import androidx.annotation.UiThread; |
| import java.nio.ByteBuffer; |
| |
| /** |
| * Facility for communicating with Flutter using asynchronous message passing with binary messages. |
| * The Flutter Dart code should use <a |
| * href="https://api.flutter.dev/flutter/services/BinaryMessages-class.html">BinaryMessages</a> to |
| * participate. |
| * |
| * <p>{@code BinaryMessenger} is expected to be utilized from a single thread throughout the |
| * duration of its existence. If created on the main thread, then all invocations should take place |
| * on the main thread. If created on a background thread, then all invocations should take place on |
| * that background thread. |
| * |
| * @see BasicMessageChannel , which supports message passing with Strings and semi-structured |
| * messages. |
| * @see MethodChannel , which supports communication using asynchronous method invocation. |
| * @see EventChannel , which supports communication using event streams. |
| */ |
| public interface BinaryMessenger { |
| /** |
| * An abstraction over the threading policy used to invoke message handlers. |
| * |
| * <p>These are generated by calling methods like {@link |
| * BinaryMessenger#makeBackgroundTaskQueue()} and can be passed into platform channels' |
| * constructors to control the threading policy for handling platform channels' messages. |
| */ |
| public interface TaskQueue {} |
| |
| /** |
| * Creates a TaskQueue that executes the tasks serially on a background thread. |
| * |
| * <p>There is no guarantee that the tasks will execute on the same thread, just that execution is |
| * serial. |
| */ |
| @UiThread |
| TaskQueue makeBackgroundTaskQueue(); |
| |
| /** |
| * Sends a binary message to the Flutter application. |
| * |
| * @param channel the name {@link String} of the logical channel used for the message. |
| * @param message the message payload, a direct-allocated {@link ByteBuffer} with the message |
| * bytes between position zero and current position, or null. |
| */ |
| @UiThread |
| void send(@NonNull String channel, @Nullable ByteBuffer message); |
| |
| /** |
| * Sends a binary message to the Flutter application, optionally expecting a reply. |
| * |
| * <p>Any uncaught exception thrown by the reply callback will be caught and logged. |
| * |
| * @param channel the name {@link String} of the logical channel used for the message. |
| * @param message the message payload, a direct-allocated {@link ByteBuffer} with the message |
| * bytes between position zero and current position, or null. |
| * @param callback a {@link BinaryReply} callback invoked when the Flutter application responds to |
| * the message, possibly null. |
| */ |
| @UiThread |
| void send(@NonNull String channel, @Nullable ByteBuffer message, @Nullable BinaryReply callback); |
| |
| /** |
| * Registers a handler to be invoked when the Flutter application sends a message to its host |
| * platform. |
| * |
| * <p>Registration overwrites any previous registration for the same channel name. Use a null |
| * handler to deregister. |
| * |
| * <p>If no handler has been registered for a particular channel, any incoming message on that |
| * channel will be handled silently by sending a null reply. |
| * |
| * @param channel the name {@link String} of the channel. |
| * @param handler a {@link BinaryMessageHandler} to be invoked on incoming messages, or null. |
| * @param taskQueue a {@link BinaryMessenger.TaskQueue} that specifies what thread will execute |
| * the handler. Specifying null means execute on the platform thread. |
| */ |
| @UiThread |
| void setMessageHandler( |
| @NonNull String channel, |
| @Nullable BinaryMessageHandler handler, |
| @Nullable TaskQueue taskQueue); |
| |
| /** Handler for incoming binary messages from Flutter. */ |
| interface BinaryMessageHandler { |
| /** |
| * Handles the specified message. |
| * |
| * <p>Handler implementations must reply to all incoming messages, by submitting a single reply |
| * message to the given {@link BinaryReply}. Failure to do so will result in lingering Flutter |
| * reply handlers. The reply may be submitted asynchronously. |
| * |
| * <p>Any uncaught exception thrown by this method will be caught by the messenger |
| * implementation and logged, and a null reply message will be sent back to Flutter. |
| * |
| * @param message the message {@link ByteBuffer} payload, possibly null. |
| * @param reply A {@link BinaryReply} used for submitting a reply back to Flutter. |
| */ |
| @UiThread |
| void onMessage(@Nullable ByteBuffer message, @NonNull BinaryReply reply); |
| } |
| |
| /** |
| * Binary message reply callback. Used to submit a reply to an incoming message from Flutter. Also |
| * used in the dual capacity to handle a reply received from Flutter after sending a message. |
| */ |
| interface BinaryReply { |
| /** |
| * Handles the specified reply. |
| * |
| * @param reply the reply payload, a direct-allocated {@link ByteBuffer} or null. Senders of |
| * outgoing replies must place the reply bytes between position zero and current position. |
| * Reply receivers can read from the buffer directly. |
| */ |
| void reply(@Nullable ByteBuffer reply); |
| } |
| } |