Use the term 'handler' for registering callbacks. (#18269)

This is the term used in the Dart code and which callback is more commonly used
in GLib matching the Dart code will make developers life easier.

Author: robert-ancell

shell/platform/linux/fl_binary_messenger.cc

@@ -22,23 +22,23 @@ struct _FlBinaryMessenger {
 G_DEFINE_TYPE(FlBinaryMessenger, fl_binary_messenger, G_TYPE_OBJECT)
 
 typedef struct {
-  FlBinaryMessengerCallback callback;
-  gpointer user_data;
+  FlBinaryMessengerMessageHandler message_handler;
+  gpointer message_handler_data;
 } PlatformMessageHandler;
 
 PlatformMessageHandler* platform_message_handler_new(
-    FlBinaryMessengerCallback callback,
+    FlBinaryMessengerMessageHandler handler,
     gpointer user_data) {
-  PlatformMessageHandler* handler = static_cast<PlatformMessageHandler*>(
+  PlatformMessageHandler* self = static_cast<PlatformMessageHandler*>(
       g_malloc0(sizeof(PlatformMessageHandler)));
-  handler->callback = callback;
-  handler->user_data = user_data;
-  return handler;
+  self->message_handler = handler;
+  self->message_handler_data = user_data;
+  return self;
 }
 
 void platform_message_handler_free(gpointer data) {
-  PlatformMessageHandler* handler = static_cast<PlatformMessageHandler*>(data);
-  g_free(handler);
+  PlatformMessageHandler* self = static_cast<PlatformMessageHandler*>(data);
+  g_free(self);
 }
 
 struct _FlBinaryMessengerResponseHandle {
@@ -47,16 +47,16 @@ struct _FlBinaryMessengerResponseHandle {
 
 static FlBinaryMessengerResponseHandle* response_handle_new(
     const FlutterPlatformMessageResponseHandle* response_handle) {
-  FlBinaryMessengerResponseHandle* handle =
+  FlBinaryMessengerResponseHandle* self =
       static_cast<FlBinaryMessengerResponseHandle*>(
           g_malloc0(sizeof(FlBinaryMessengerResponseHandle)));
-  handle->response_handle = response_handle;
+  self->response_handle = response_handle;
 
-  return handle;
+  return self;
 }
 
-static void response_handle_free(FlBinaryMessengerResponseHandle* handle) {
-  g_free(handle);
+static void response_handle_free(FlBinaryMessengerResponseHandle* self) {
+  g_free(self);
 }
 
 G_DEFINE_AUTOPTR_CLEANUP_FUNC(FlBinaryMessengerResponseHandle,
@@ -67,7 +67,7 @@ static void engine_weak_notify_cb(gpointer user_data, GObject* object) {
   self->engine = nullptr;
 }
 
-static gboolean fl_binary_messenger_platform_message_callback(
+static gboolean fl_binary_messenger_platform_message_cb(
     FlEngine* engine,
     const gchar* channel,
     GBytes* message,
@@ -83,7 +83,8 @@ static gboolean fl_binary_messenger_platform_message_callback(
   if (handler == nullptr)
     return FALSE;
 
-  handler->callback(self, channel, message, handle, handler->user_data);
+  handler->message_handler(self, channel, message, handle,
+                           handler->message_handler_data);
 
   return TRUE;
 }
@@ -120,24 +121,24 @@ FlBinaryMessenger* fl_binary_messenger_new(FlEngine* engine) {
   g_object_weak_ref(G_OBJECT(engine), engine_weak_notify_cb, self);
 
   fl_engine_set_platform_message_handler(
-      engine, fl_binary_messenger_platform_message_callback, self);
+      engine, fl_binary_messenger_platform_message_cb, self);
 
   return self;
 }
 
 G_MODULE_EXPORT void fl_binary_messenger_set_message_handler_on_channel(
     FlBinaryMessenger* self,
     const gchar* channel,
-    FlBinaryMessengerCallback callback,
+    FlBinaryMessengerMessageHandler handler,
     gpointer user_data) {
   g_return_if_fail(FL_IS_BINARY_MESSENGER(self));
   g_return_if_fail(channel != nullptr);
-  g_return_if_fail(callback != nullptr);
 
-  PlatformMessageHandler* handler =
-      platform_message_handler_new(callback, user_data);
-  g_hash_table_replace(self->platform_message_handlers, g_strdup(channel),
-                       handler);
+  if (handler != nullptr)
+    g_hash_table_replace(self->platform_message_handlers, g_strdup(channel),
+                         platform_message_handler_new(handler, user_data));
+  else
+    g_hash_table_remove(self->platform_message_handlers, channel);
 }
 
 G_MODULE_EXPORT gboolean fl_binary_messenger_send_response(

shell/platform/linux/fl_engine.cc

@@ -27,8 +27,8 @@ struct _FlEngine {
   FLUTTER_API_SYMBOL(FlutterEngine) engine;
 
   // Function to call when a platform message is received
-  FlEnginePlatformMessageCallback platform_message_callback;
-  gpointer platform_message_callback_data;
+  FlEnginePlatformMessageHandler platform_message_handler;
+  gpointer platform_message_handler_data;
 };
 
 G_DEFINE_QUARK(fl_engine_error_quark, fl_engine_error)
@@ -92,7 +92,7 @@ static bool fl_engine_gl_clear_current(void* user_data) {
   return result;
 }
 
-static uint32_t fl_engine_gl_fbo_callback(void* user_data) {
+static uint32_t fl_engine_gl_get_fbo(void* user_data) {
   FlEngine* self = static_cast<FlEngine*>(user_data);
   return fl_renderer_get_fbo(self->renderer);
 }
@@ -111,9 +111,9 @@ static bool fl_engine_runs_task_on_current_thread(void* user_data) {
   return self->thread == g_thread_self();
 }
 
-static void fl_engine_post_task_callback(FlutterTask task,
-                                         uint64_t target_time_nanos,
-                                         void* user_data) {
+static void fl_engine_post_task(FlutterTask task,
+                                uint64_t target_time_nanos,
+                                void* user_data) {
   FlEngine* self = static_cast<FlEngine*>(user_data);
 
   g_autoptr(GSource) source =
@@ -126,28 +126,27 @@ static void fl_engine_post_task_callback(FlutterTask task,
   g_source_attach(source, nullptr);
 }
 
-static void fl_engine_platform_message_callback(
-    const FlutterPlatformMessage* message,
-    void* user_data) {
+static void fl_engine_platform_message_cb(const FlutterPlatformMessage* message,
+                                          void* user_data) {
   FlEngine* self = FL_ENGINE(user_data);
 
   gboolean handled = FALSE;
-  if (self->platform_message_callback != nullptr) {
+  if (self->platform_message_handler != nullptr) {
     g_autoptr(GBytes) data =
         g_bytes_new(message->message, message->message_size);
-    handled = self->platform_message_callback(
+    handled = self->platform_message_handler(
         self, message->channel, data, message->response_handle,
-        self->platform_message_callback_data);
+        self->platform_message_handler_data);
   }
 
   if (!handled)
     fl_engine_send_platform_message_response(self, message->response_handle,
                                              nullptr, nullptr);
 }
 
-static void fl_engine_platform_message_response_callback(const uint8_t* data,
-                                                         size_t data_length,
-                                                         void* user_data) {
+static void fl_engine_platform_message_response_cb(const uint8_t* data,
+                                                   size_t data_length,
+                                                   void* user_data) {
   g_autoptr(GTask) task = G_TASK(user_data);
   g_task_return_pointer(task, g_bytes_new(data, data_length),
                         (GDestroyNotify)g_bytes_unref);
@@ -198,15 +197,15 @@ gboolean fl_engine_start(FlEngine* self, GError** error) {
   config.open_gl.gl_proc_resolver = fl_engine_gl_proc_resolver;
   config.open_gl.make_current = fl_engine_gl_make_current;
   config.open_gl.clear_current = fl_engine_gl_clear_current;
-  config.open_gl.fbo_callback = fl_engine_gl_fbo_callback;
+  config.open_gl.fbo_callback = fl_engine_gl_get_fbo;
   config.open_gl.present = fl_engine_gl_present;
 
   FlutterTaskRunnerDescription platform_task_runner = {};
   platform_task_runner.struct_size = sizeof(FlutterTaskRunnerDescription);
   platform_task_runner.user_data = self;
   platform_task_runner.runs_task_on_current_thread_callback =
       fl_engine_runs_task_on_current_thread;
-  platform_task_runner.post_task_callback = fl_engine_post_task_callback;
+  platform_task_runner.post_task_callback = fl_engine_post_task;
   platform_task_runner.identifier = kPlatformTaskRunnerIdentifier;
 
   FlutterCustomTaskRunners custom_task_runners = {};
@@ -217,7 +216,7 @@ gboolean fl_engine_start(FlEngine* self, GError** error) {
   args.struct_size = sizeof(FlutterProjectArgs);
   args.assets_path = fl_dart_project_get_assets_path(self->project);
   args.icu_data_path = fl_dart_project_get_icu_data_path(self->project);
-  args.platform_message_callback = fl_engine_platform_message_callback;
+  args.platform_message_callback = fl_engine_platform_message_cb;
   args.custom_task_runners = &custom_task_runners;
 
   FlutterEngineResult result = FlutterEngineInitialize(
@@ -240,13 +239,13 @@ gboolean fl_engine_start(FlEngine* self, GError** error) {
 
 void fl_engine_set_platform_message_handler(
     FlEngine* self,
-    FlEnginePlatformMessageCallback callback,
+    FlEnginePlatformMessageHandler handler,
     gpointer user_data) {
   g_return_if_fail(FL_IS_ENGINE(self));
-  g_return_if_fail(callback != nullptr);
+  g_return_if_fail(handler != nullptr);
 
-  self->platform_message_callback = callback;
-  self->platform_message_callback_data = user_data;
+  self->platform_message_handler = handler;
+  self->platform_message_handler_data = user_data;
 }
 
 gboolean fl_engine_send_platform_message_response(
@@ -288,7 +287,7 @@ void fl_engine_send_platform_message(FlEngine* self,
     task = g_task_new(self, cancellable, callback, user_data);
 
     FlutterEngineResult result = FlutterPlatformMessageCreateResponseHandle(
-        self->engine, fl_engine_platform_message_response_callback, task,
+        self->engine, fl_engine_platform_message_response_cb, task,
         &response_handle);
     if (result != kSuccess) {
       g_task_return_new_error(task, fl_engine_error_quark(),

shell/platform/linux/fl_engine_private.h

@@ -26,18 +26,18 @@ typedef enum {
 GQuark fl_engine_error_quark(void) G_GNUC_CONST;
 
 /**
- * FlEnginePlatformMessageCallback:
+ * FlEnginePlatformMessageHandler:
  * @engine: a #FlEngine
  * @channel: channel message received on.
  * @message: message content received from Dart
  * @response_handle: a handle to respond to the message with
- * @user_data: (closure): data provided when registering this callback
+ * @user_data: (closure): data provided when registering this handler
  *
  * Function called when platform messages are received.
  *
  * Returns: %TRUE if message has been accepted.
  */
-typedef gboolean (*FlEnginePlatformMessageCallback)(
+typedef gboolean (*FlEnginePlatformMessageHandler)(
     FlEngine* engine,
     const gchar* channel,
     GBytes* message,
@@ -58,18 +58,18 @@ FlEngine* fl_engine_new(FlDartProject* project, FlRenderer* renderer);
 /**
  * fl_engine_set_platform_message_handler:
  * @engine: a #FlEngine
- * @callback: function to call when a platform message is received
- * @user_data: (closure): user data to pass to @callback
+ * @handler: function to call when a platform message is received
+ * @user_data: (closure): user data to pass to @handler
  *
- * Register a callback to handle platform messages. Call
+ * Register a handler to handle platform messages. Call
  * fl_engine_send_platform_message_response() when this message should be
  * responded to. Ownership of #FlutterPlatformMessageResponseHandle is
  * transferred to the caller, and the call must be responded to to avoid
  * memory leaks.
  */
 void fl_engine_set_platform_message_handler(
     FlEngine* engine,
-    FlEnginePlatformMessageCallback callback,
+    FlEnginePlatformMessageHandler handler,
     gpointer user_data);
 
 /**
@@ -119,7 +119,7 @@ void fl_engine_send_mouse_pointer_event(FlEngine* engine,
 /**
  * fl_engine_send_platform_message_response:
  * @engine: a #FlEngine
- * @response_handle: handle that was provided in the callback.
+ * @handle: handle that was provided in #FlEnginePlatformMessageHandler
  * @response: (allow-none): response to send or %NULL for an empty response.
  * @error: (allow-none): #GError location to store the error occurring, or %NULL
  * to ignore.

shell/platform/linux/public/flutter_linux/fl_binary_messenger.h

@@ -35,18 +35,17 @@ G_DECLARE_FINAL_TYPE(FlBinaryMessenger,
 typedef struct _FlBinaryMessengerResponseHandle FlBinaryMessengerResponseHandle;
 
 /**
- * FlBinaryMessengerCallback:
+ * FlBinaryMessengerMessageHandler:
  * @messenger: a #FlBinaryMessenger
  * @channel: channel message received on
  * @message: message content received from Dart
  * @response_handle: (transfer full): a handle to respond to the message with
- * @user_data: (closure): data provided when registering this callback
+ * @user_data: (closure): data provided when registering this handler
  *
  * Function called when platform messages are received. The receiver must
- * respond to the message to avoid leaking the handle, see the documentation on
- * the code that generated the callback as to which function to call.
+ * call fl_binary_messenger_send_response() to avoid leaking the handle.
  */
-typedef void (*FlBinaryMessengerCallback)(
+typedef void (*FlBinaryMessengerMessageHandler)(
     FlBinaryMessenger* messenger,
     const gchar* channel,
     GBytes* message,
@@ -57,8 +56,9 @@ typedef void (*FlBinaryMessengerCallback)(
  * fl_binary_messenger_set_platform_message_handler:
  * @binary_messenger: a #FlBinaryMessenger
  * @channel: channel to listen on
- * @callback: function to call when a message is received on this channel
- * @user_data: (closure): user data to pass to @callback
+ * @handler: (allow-none): function to call when a message is received on this
+ * channel or %NULL to disable a handler
+ * @user_data: (closure): user data to pass to @handler
  *
  * Set the function called when a platform message is received on the given
  * channel. Call fl_binary_messenger_send_response() when the message is
@@ -68,14 +68,14 @@ typedef void (*FlBinaryMessengerCallback)(
 void fl_binary_messenger_set_message_handler_on_channel(
     FlBinaryMessenger* messenger,
     const gchar* channel,
-    FlBinaryMessengerCallback callback,
+    FlBinaryMessengerMessageHandler handler,
     gpointer user_data);
 
 /**
  * fl_binary_messenger_send_response:
  * @binary_messenger: a #FlBinaryMessenger
  * @response_handle: (transfer full): handle that was provided in a
- * #FlBinaryMessengerCallback
+ * #FlBinaryMessengerMessageHandler
  * @response: (allow-none): response to send or %NULL for an empty response
  * @error: (allow-none): #GError location to store the error occurring, or %NULL
  * to ignore