1 // Copyright 2013 The Flutter Authors. All rights reserved. 2 // Use of this source code is governed by a BSD-style license that can be 3 // found in the LICENSE file. 4 5 package io.flutter.plugin.common; 6 7 import android.support.annotation.NonNull; 8 import android.support.annotation.Nullable; 9 import android.support.annotation.UiThread; 10 11 import java.nio.ByteBuffer; 12 13 /** 14 * Facility for communicating with Flutter using asynchronous message passing with binary messages. 15 * The Flutter Dart code should use 16 * <a href="https://docs.flutter.io/flutter/services/BinaryMessages-class.html">BinaryMessages</a> 17 * to participate. 18 * <p> 19 * {@code BinaryMessenger} is expected to be utilized from a single thread throughout the duration 20 * of its existence. If created on the main thread, then all invocations should take place on the 21 * main thread. If created on a background thread, then all invocations should take place on that 22 * background thread. 23 * 24 * @see BasicMessageChannel , which supports message passing with Strings and semi-structured messages. 25 * @see MethodChannel , which supports communication using asynchronous method invocation. 26 * @see EventChannel , which supports communication using event streams. 27 */ 28 public interface BinaryMessenger { 29 /** 30 * Sends a binary message to the Flutter application. 31 * 32 * @param channel the name {@link String} of the logical channel used for the message. 33 * @param message the message payload, a direct-allocated {@link ByteBuffer} with the message bytes 34 * between position zero and current position, or null. 35 */ 36 @UiThread send(@onNull String channel, @Nullable ByteBuffer message)37 void send(@NonNull String channel, @Nullable ByteBuffer message); 38 39 /** 40 * Sends a binary message to the Flutter application, optionally expecting a reply. 41 * 42 * <p>Any uncaught exception thrown by the reply callback will be caught and logged.</p> 43 * 44 * @param channel the name {@link String} of the logical channel used for the message. 45 * @param message the message payload, a direct-allocated {@link ByteBuffer} with the message bytes 46 * between position zero and current position, or null. 47 * @param callback a {@link BinaryReply} callback invoked when the Flutter application responds to the 48 * message, possibly null. 49 */ 50 @UiThread send(@onNull String channel, @Nullable ByteBuffer message, @Nullable BinaryReply callback)51 void send(@NonNull String channel, @Nullable ByteBuffer message, @Nullable BinaryReply callback); 52 53 /** 54 * Registers a handler to be invoked when the Flutter application sends a message 55 * to its host platform. 56 * 57 * <p>Registration overwrites any previous registration for the same channel name. 58 * Use a null handler to deregister.</p> 59 * 60 * <p>If no handler has been registered for a particular channel, any incoming message on 61 * that channel will be handled silently by sending a null reply.</p> 62 * 63 * @param channel the name {@link String} of the channel. 64 * @param handler a {@link BinaryMessageHandler} to be invoked on incoming messages, or null. 65 */ 66 @UiThread setMessageHandler(@onNull String channel, @Nullable BinaryMessageHandler handler)67 void setMessageHandler(@NonNull String channel, @Nullable BinaryMessageHandler handler); 68 69 /** 70 * Handler for incoming binary messages from Flutter. 71 */ 72 interface BinaryMessageHandler { 73 /** 74 * Handles the specified message. 75 * 76 * <p>Handler implementations must reply to all incoming messages, by submitting a single reply 77 * message to the given {@link BinaryReply}. Failure to do so will result in lingering Flutter reply 78 * handlers. The reply may be submitted asynchronously.</p> 79 * 80 * <p>Any uncaught exception thrown by this method will be caught by the messenger implementation and 81 * logged, and a null reply message will be sent back to Flutter.</p> 82 * 83 * @param message the message {@link ByteBuffer} payload, possibly null. 84 * @param reply A {@link BinaryReply} used for submitting a reply back to Flutter. 85 */ 86 @UiThread onMessage(@ullable ByteBuffer message, @NonNull BinaryReply reply)87 void onMessage(@Nullable ByteBuffer message, @NonNull BinaryReply reply); 88 } 89 90 /** 91 * Binary message reply callback. Used to submit a reply to an incoming 92 * message from Flutter. Also used in the dual capacity to handle a reply 93 * received from Flutter after sending a message. 94 */ 95 interface BinaryReply { 96 /** 97 * Handles the specified reply. 98 * 99 * @param reply the reply payload, a direct-allocated {@link ByteBuffer} or null. Senders of 100 * outgoing replies must place the reply bytes between position zero and current position. 101 * Reply receivers can read from the buffer directly. 102 */ 103 @UiThread reply(@ullable ByteBuffer reply)104 void reply(@Nullable ByteBuffer reply); 105 } 106 } 107