Improve crashes if messenger APIs are used incorrectly (#39041)

* Clarify messenger APIs

* Feedback

Author: loic-sharma

shell/platform/common/client_wrapper/include/flutter/method_channel.h

@@ -91,9 +91,10 @@ class MethodChannel {
   // Registers a handler that should be called any time a method call is
   // received on this channel. A null handler will remove any previous handler.
   //
-  // Note that the MethodChannel does not own the handler, and will not
-  // unregister it on destruction, so the caller is responsible for
-  // unregistering explicitly if it should no longer be called.
+  // The handler will be owned by the underlying BinaryMessageHandler.
+  // Destroying the MethodChannel will not unregister the handler, so
+  // the caller is responsible for unregistering explicitly if the handler
+  // stops being valid before the engine is destroyed.
   void SetMethodCallHandler(MethodCallHandler<T> handler) const {
     if (!handler) {
       messenger_->SetMessageHandler(name_, nullptr);

shell/platform/common/public/flutter_messenger.h

@@ -58,6 +58,8 @@ FLUTTER_EXPORT bool FlutterDesktopMessengerSend(
     const uint8_t* message,
     const size_t message_size);
 
+// Sends a binary message to the Flutter side on the specified channel.
+// The |reply| callback will be executed when a response is received.
 FLUTTER_EXPORT bool FlutterDesktopMessengerSendWithReply(
     FlutterDesktopMessengerRef messenger,
     const char* channel,

shell/platform/windows/flutter_windows.cc

@@ -265,6 +265,9 @@ bool FlutterDesktopMessengerSendWithReply(FlutterDesktopMessengerRef messenger,
                                           const size_t message_size,
                                           const FlutterDesktopBinaryReply reply,
                                           void* user_data) {
+  FML_DCHECK(FlutterDesktopMessengerIsAvailable(messenger))
+      << "Messenger must reference a running engine to send a message";
+
   return flutter::FlutterDesktopMessenger::FromRef(messenger)
       ->GetEngine()
       ->SendPlatformMessage(channel, message, message_size, reply, user_data);
@@ -283,6 +286,9 @@ void FlutterDesktopMessengerSendResponse(
     const FlutterDesktopMessageResponseHandle* handle,
     const uint8_t* data,
     size_t data_length) {
+  FML_DCHECK(FlutterDesktopMessengerIsAvailable(messenger))
+      << "Messenger must reference a running engine to send a response";
+
   flutter::FlutterDesktopMessenger::FromRef(messenger)
       ->GetEngine()
       ->SendPlatformMessageResponse(handle, data, data_length);
@@ -292,6 +298,9 @@ void FlutterDesktopMessengerSetCallback(FlutterDesktopMessengerRef messenger,
                                         const char* channel,
                                         FlutterDesktopMessageCallback callback,
                                         void* user_data) {
+  FML_DCHECK(FlutterDesktopMessengerIsAvailable(messenger))
+      << "Messenger must reference a running engine to set a callback";
+
   flutter::FlutterDesktopMessenger::FromRef(messenger)
       ->GetEngine()
       ->message_dispatcher()