Package io.flutter.plugin.common

## Interface BinaryMessenger

- All Known Implementing Classes:
    `DartExecutor`, `FlutterNativeView`, `FlutterView`

      public interface BinaryMessenger

  Facility for communicating with Flutter using asynchronous message passing with binary messages. The Flutter Dart code should use BinaryMessages to participate.

  `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 Also:
    `, which supports message passing with Strings and semi-structured messages.`, `, which supports communication using asynchronous method invocation.`, `, which supports communication using event streams.`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface | Description
    --- | --- | ---
    `static interface` | `BinaryMessenger.BinaryMessageHandler` | Handler for incoming binary messages from Flutter.
    `static interface` | `BinaryMessenger.BinaryReply` | Binary message reply callback.
    `static interface` | `BinaryMessenger.TaskQueue` | An abstraction over the threading policy used to invoke message handlers.
    `static class` | `BinaryMessenger.TaskQueueOptions` | Options that control how a TaskQueue should operate and be created.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `default void` | `disableBufferingIncomingMessages()` | Disables the ability to queue messages received from Dart.
    `default void` | `enableBufferingIncomingMessages()` | Enables the ability to queue messages received from Dart.
    `default BinaryMessenger.TaskQueue` | `makeBackgroundTaskQueue()` | Creates a TaskQueue that executes the tasks serially on a background thread.
    `default BinaryMessenger.TaskQueue` | `makeBackgroundTaskQueue​(BinaryMessenger.TaskQueueOptions options)` | Creates a TaskQueue that executes the tasks serially on a background thread.
    `void` | `send​(String channel, ByteBuffer message)` | Sends a binary message to the Flutter application.
    `void` | `send​(String channel, ByteBuffer message, BinaryMessenger.BinaryReply callback)` | Sends a binary message to the Flutter application, optionally expecting a reply.
    `void` | `setMessageHandler​(String channel, BinaryMessenger.BinaryMessageHandler handler)` | Registers a handler to be invoked when the Flutter application sends a message to its host platform.
    `default void` | `setMessageHandler​(String channel, BinaryMessenger.BinaryMessageHandler handler, BinaryMessenger.TaskQueue taskQueue)` | Registers a handler to be invoked when the Flutter application sends a message to its host platform.

- - ### Method Detail

    - #### makeBackgroundTaskQueue

          @UiThread
          default BinaryMessenger.TaskQueue makeBackgroundTaskQueue()

      Creates a TaskQueue that executes the tasks serially on a background thread.

      There is no guarantee that the tasks will execute on the same thread, just that execution is serial. This is could be problematic if your code relies on ThreadLocal storage or introspection about what thread is actually executing.

    - #### makeBackgroundTaskQueue

          @UiThread
          default BinaryMessenger.TaskQueue makeBackgroundTaskQueue​(BinaryMessenger.TaskQueueOptions options)

      Creates a TaskQueue that executes the tasks serially on a background thread.

      `BinaryMessenger.TaskQueueOptions` can be used to configure the task queue to execute tasks concurrently. Doing so can be more performant, though users need to ensure that the task handlers are thread-safe.

    - #### send

          @UiThread
          void send​(@NonNull
                    String channel,
                    @Nullable
                    ByteBuffer message)

      Sends a binary message to the Flutter application.
      Parameters:
        `channel` - the name `String` of the logical channel used for the message.
        `message` - the message payload, a direct-allocated `ByteBuffer` with the message bytes between position zero and current position, or null.

    - #### send

          @UiThread
          void send​(@NonNull
                    String channel,
                    @Nullable
                    ByteBuffer message,
                    @Nullable
                    BinaryMessenger.BinaryReply callback)

      Sends a binary message to the Flutter application, optionally expecting a reply.

      Any uncaught exception thrown by the reply callback will be caught and logged.

      Parameters:
        `channel` - the name `String` of the logical channel used for the message.
        `message` - the message payload, a direct-allocated `ByteBuffer` with the message bytes between position zero and current position, or null.
        `callback` - a `BinaryMessenger.BinaryReply` callback invoked when the Flutter application responds to the message, possibly null.

    - #### setMessageHandler

          @UiThread
          void setMessageHandler​(@NonNull
                                 String channel,
                                 @Nullable
                                 BinaryMessenger.BinaryMessageHandler handler)

      Registers a handler to be invoked when the Flutter application sends a message to its host platform.

      Registration overwrites any previous registration for the same channel name. Use a null handler to deregister.

      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.

      Parameters:
        `channel` - the name `String` of the channel.
        `handler` - a `BinaryMessenger.BinaryMessageHandler` to be invoked on incoming messages, or null.

    - #### setMessageHandler

          @UiThread
          default void setMessageHandler​(@NonNull
                                         String channel,
                                         @Nullable
                                         BinaryMessenger.BinaryMessageHandler handler,
                                         @Nullable
                                         BinaryMessenger.TaskQueue taskQueue)

      Registers a handler to be invoked when the Flutter application sends a message to its host platform.

      Registration overwrites any previous registration for the same channel name. Use a null handler to deregister.

      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.

      Parameters:
        `channel` - the name `String` of the channel.
        `handler` - a `BinaryMessenger.BinaryMessageHandler` to be invoked on incoming messages, or null.
        `taskQueue` - a `BinaryMessenger.TaskQueue` that specifies what thread will execute the handler. Specifying null means execute on the platform thread.

    - #### enableBufferingIncomingMessages

          default void enableBufferingIncomingMessages()

      Enables the ability to queue messages received from Dart.

      This is useful when there are pending channel handler registrations. For example, Dart may be initialized concurrently, and prior to the registration of the channel handlers. This implies that Dart may start sending messages while plugins are being registered.

    - #### disableBufferingIncomingMessages

          default void disableBufferingIncomingMessages()

      Disables the ability to queue messages received from Dart.

      This can be used after all pending channel handlers have been registered.