Add tizen_interop_callbacks (#19)

Co-authored-by: Jakub Siewierski <[email protected]>
Co-authored-by: Swift Kim <[email protected]>

.clang-format

@@ -0,0 +1 @@
+BasedOnStyle: Google

README.md

@@ -66,6 +66,15 @@ int freeMemory = using((Arena arena) {
   }
   return 0;
 });
+
+// Both sync and async callbacks are supported as long as they are called on
+// the same thread.
+tizen.storage_foreach_device_supported(
+    Pointer.fromFunction(_storageDevice, false), nullptr);
+
+// Callbacks that are called outside the current thread will cause the error:
+// "Cannot invoke native callback outside an isolate".
+// See the tizen_interop_callbacks package for a solution.
 ```
 
 

packages/tizen_interop_callbacks/.gitignore

@@ -0,0 +1,28 @@
+# Miscellaneous
+*.class
+*.log
+*.pyc
+*.swp
+.DS_Store
+.atom/
+.buildlog/
+.history
+.svn/
+migrate_working_dir/
+
+# IntelliJ related
+*.iml
+*.ipr
+*.iws
+.idea/
+
+# VS Code related
+.vscode/
+
+# Flutter/Dart/Pub related
+# Libraries should not include pubspec.lock, per https://dart.dev/guides/libraries/private-files#pubspeclock.
+/pubspec.lock
+**/doc/api/
+.dart_tool/
+.packages
+build/

packages/tizen_interop_callbacks/CHANGELOG.md

@@ -0,0 +1,3 @@
+## 0.1.0
+
+* Initial release.

packages/tizen_interop_callbacks/LICENSE

@@ -0,0 +1,25 @@
+Copyright (c) 2023 Samsung Electronics Co., Ltd. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above
+      copyright notice, this list of conditions and the following
+      disclaimer in the documentation and/or other materials provided
+      with the distribution.
+    * Neither the name of the copyright holder nor the names of the
+      contributors may be used to endorse or promote products derived
+      from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

packages/tizen_interop_callbacks/README.md

@@ -0,0 +1,58 @@
+# tizen_interop_callbacks
+
+A Flutter plugin to resolve issues related to the error message: `Cannot invoke native callback outside an isolate`.
+
+This package is designed to be used with the [`tizen_interop`](https://pub.dev/packages/tizen_interop) package.
+Similarly to `tizen_interop`, this package has no build time dependency on a specific Tizen profile or version.
+
+## Usage
+
+1. Add this package and `tizen_interop` as dependencies in your `pubspec.yaml` file.
+
+   ```yaml
+   dependencies:
+     ffi: ^2.0.1
+     tizen_interop: ^0.2.6
+     tizen_interop_callbacks: ^0.1.0
+   ```
+
+2. In your Dart code, import the packages:
+
+   ```dart
+   import 'dart:ffi';
+   import 'package:tizen_interop/4.0/tizen.dart';
+   import 'package:tizen_interop_callbacks/tizen_interop_callbacks.dart';
+   ```
+
+3. Instantiate the `TizenInteropCallbacks` class. This should be done in the root isolate - the thread where your `main()` is called.
+
+   ```dart
+   final callbacks = TizenInteropCallbacks();
+   ```
+
+4. Implement your callback in Dart and register it with `TizenInteropCallbacks`:
+
+   ```dart
+   final callback = _callbacks.register<Void Function(Int32, Pointer<Void>, Pointer<Void>)>(
+     'device_changed_cb',
+     Pointer.fromFunction(_batteryChanged),
+   );
+   ```
+
+   The native function type to be used in `register<>()` can be obtained by checking
+   the definition of the related callback type - the `device_changed_cb` in this case.
+
+5. Pass the obtained callback pointer and user_data to the Native API function:
+
+   > **Warning**
+   >
+   > Both `interopCallback` and `interopUserData` must be passed. The callback handling implementation relies on the `interopUserData`.
+   > The only exceptions are a few callbacks that do not accept `user_data` parameters.
+
+   ```dart
+   final ret = tizen.device_add_callback(
+     device_callback_e.DEVICE_CALLBACK_BATTERY_CAPACITY,
+     callback.interopCallback,
+     callback.interopUserData,
+   );
+   ```

packages/tizen_interop_callbacks/analysis_options.yaml

@@ -0,0 +1 @@
+include: package:flutter_lints/flutter.yaml

packages/tizen_interop_callbacks/example/.gitignore

@@ -0,0 +1,42 @@
+# Miscellaneous
+*.class
+*.log
+*.pyc
+*.swp
+.DS_Store
+.atom/
+.buildlog/
+.history
+.svn/
+migrate_working_dir/
+
+# IntelliJ related
+*.iml
+*.ipr
+*.iws
+.idea/
+
+# VS Code related
+.vscode/
+
+# Flutter/Dart/Pub related
+**/doc/api/
+**/ios/Flutter/.last_build_id
+.dart_tool/
+.flutter-plugins
+.flutter-plugins-dependencies
+.packages
+.pub-cache/
+.pub/
+/build/
+
+# Symbolication related
+app.*.symbols
+
+# Obfuscation related
+app.*.map.json
+
+# Android Studio will place build artifacts here
+/android/app/debug
+/android/app/profile
+/android/app/release

packages/tizen_interop_callbacks/example/README.md

@@ -0,0 +1,34 @@
+# tizen_interop_callbacks_example
+
+Demonstrates how to use the tizen_interop_callbacks plugin.
+
+## Introduction
+
+This application consists of 2 tabs showing:
+
+### Battery status
+
+Here, a typical scenario is shown. We need to receive callbacks, but the Tizen Native API
+invokes the callback from another thread. Trying to pass a function pointer obtained
+by [`Pointer.fromFunction()`](https://api.flutter.dev/flutter/dart-ffi/Pointer/fromFunction.html)
+to [`device_add_callback()`](https://docs.tizen.org/application/native/api/mobile/4.0/group__CAPI__SYSTEM__DEVICE__CALLBACK__MODULE.html#ga89a756a9c46fb670f603d79b66af6cf0)
+will cause an error when the callback is called.
+Therefore, `TizenInteropCallbacks` is used to obtain a native proxy callback that can be run in any thread.
+
+You can run the example on a Tizen emulator and use the Control Panel to simulate
+changes to the battery level and status.
+
+### Camera preview resolutions
+
+Here, a workaround for a locking issue is presented. Usually, a foreach API function would call the callback synchronously.
+Thus, `TizenInteropCallbacks` would not be needed at all.
+
+However, [`camera_foreach_supported_preview_resolution()`](https://docs.tizen.org/application/native/api/mobile/4.0/group__CAPI__MEDIA__CAMERA__CAPABILITY__MODULE.html#gaccca0251a0432ca8752be09b400b9b3b)
+locks the calling thread and invokes the given callback in another thread.
+Therefore, we need to use `TizenInteropCallbacks` and call the API in a different isolate.
+This isolate will be blocked while our root isolate is processing the callbacks.
+
+Notice that `TizenInteropCallbacks` is only accessed in the root isolate and
+the `RegisteredCallback` is passed to the spawned isolate.
+Our Dart callback runs in the root isolate, so we have full and safe access
+to all its objects.

packages/tizen_interop_callbacks/example/lib/battery.dart

@@ -0,0 +1,134 @@
+// Copyright 2023 Samsung Electronics Co., Ltd. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+// ignore_for_file: public_member_api_docs, avoid_print
+
+import 'dart:ffi';
+
+import 'package:ffi/ffi.dart';
+import 'package:flutter/material.dart';
+import 'package:tizen_interop/4.0/tizen.dart';
+import 'package:tizen_interop_callbacks/tizen_interop_callbacks.dart';
+
+class BatteryTab extends StatefulWidget {
+  const BatteryTab({super.key});
+
+  @override
+  State<BatteryTab> createState() => _BatteryTabState();
+}
+
+class _BatteryTabState extends State<BatteryTab> {
+  final TizenInteropCallbacks _callbacks = TizenInteropCallbacks();
+
+  late final RegisteredCallback<
+      Void Function(Int32, Pointer<Void>, Pointer<Void>)> _chargingCallback;
+  late final RegisteredCallback<
+      Void Function(Int32, Pointer<Void>, Pointer<Void>)> _levelCallback;
+
+  bool? _batteryCharging;
+  int _batteryLevel = 0;
+
+  static void _batteryChanged(
+    int type,
+    Pointer<Void> value,
+    Pointer<Void> userData,
+  ) {
+    final state =
+        TizenInteropCallbacks.getUserObject<_BatteryTabState>(userData)!;
+    if (type == device_callback_e.DEVICE_CALLBACK_BATTERY_CHARGING) {
+      state._batteryCharging = value.address != 0;
+    } else if (type == device_callback_e.DEVICE_CALLBACK_BATTERY_CAPACITY) {
+      state._batteryLevel = value.address;
+    }
+    state.setState(() {});
+  }
+
+  @override
+  void initState() {
+    super.initState();
+
+    _chargingCallback = _callbacks.register(
+      'device_changed_cb',
+      Pointer.fromFunction(_batteryChanged),
+      userObject: this,
+      blocking: true,
+    );
+    int ret = tizen.device_add_callback(
+      device_callback_e.DEVICE_CALLBACK_BATTERY_CHARGING,
+      _chargingCallback.interopCallback,
+      _chargingCallback.interopUserData,
+    );
+    if (ret != 0) {
+      final error = tizen.get_error_message(ret).toDartString();
+      print('Failed to add battery charging callback: $error');
+    }
+
+    _levelCallback = _callbacks.register(
+      'device_changed_cb',
+      Pointer.fromFunction(_batteryChanged),
+      userObject: this,
+    );
+    ret = tizen.device_add_callback(
+      device_callback_e.DEVICE_CALLBACK_BATTERY_CAPACITY,
+      _levelCallback.interopCallback,
+      _levelCallback.interopUserData,
+    );
+    if (ret != 0) {
+      final error = tizen.get_error_message(ret).toDartString();
+      print('Failed to add battery level callback: $error');
+    }
+
+    using((Arena arena) {
+      Pointer<Int> percent = arena();
+      int ret = tizen.device_battery_get_percent(percent);
+      if (ret == 0) {
+        _batteryLevel = percent.value;
+      } else {
+        final error = tizen.get_error_message(ret).toDartString();
+        print('Failed to read battery level: $error');
+      }
+
+      Pointer<Bool> charging = arena();
+      ret = tizen.device_battery_is_charging(charging);
+      if (ret == 0) {
+        _batteryCharging = charging.value;
+      } else {
+        final error = tizen.get_error_message(ret).toDartString();
+        print('Failed to read battery charging status: $error');
+      }
+      setState(() {});
+    });
+  }
+
+  @override
+  void dispose() {
+    tizen.device_remove_callback(
+      device_callback_e.DEVICE_CALLBACK_BATTERY_CAPACITY,
+      _levelCallback.interopCallback,
+    );
+    tizen.device_remove_callback(
+      device_callback_e.DEVICE_CALLBACK_BATTERY_CHARGING,
+      _chargingCallback.interopCallback,
+    );
+    _callbacks.unregister(_levelCallback);
+    _callbacks.unregister(_chargingCallback);
+
+    super.dispose();
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    String status = 'Unknown';
+    if (_batteryCharging != null) {
+      status = _batteryCharging! ? 'Charging' : 'Discharging';
+    }
+    return Column(
+      mainAxisAlignment: MainAxisAlignment.center,
+      children: [
+        Text('Battery status: $status'),
+        if (_batteryCharging != null) Text('Battery level: $_batteryLevel%')
+      ],
+    );
+  }
+}

packages/tizen_interop_callbacks/example/lib/main.dart

@@ -0,0 +1,38 @@
+// Copyright 2023 Samsung Electronics Co., Ltd. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import 'package:flutter/material.dart';
+
+import 'battery.dart';
+import 'preview_resolutions.dart';
+
+void main() {
+  runApp(const MyApp());
+}
+
+class MyApp extends StatelessWidget {
+  const MyApp({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return MaterialApp(
+      home: DefaultTabController(
+        length: 2,
+        child: Scaffold(
+          appBar: AppBar(
+            title: const Text('Tizen Interop Callbacks Example'),
+            bottom: const TabBar(tabs: [
+              Tab(icon: Icon(Icons.battery_charging_full)),
+              Tab(icon: Icon(Icons.camera)),
+            ]),
+          ),
+          body: const TabBarView(children: [
+            BatteryTab(),
+            PreviewResolutionsTab(),
+          ]),
+        ),
+      ),
+    );
+  }
+}