feat: add msg conversion in graph (#202)

Co-authored-by: Hu Yueh-Wei <wei.hu.tw@gmail.com>

core/include_internal/ten_runtime/extension/extension_info/extension_info.h

@@ -37,7 +37,7 @@ typedef struct ten_extension_info_t {
   // The definition of properties in the graph related to the current extension.
   ten_value_t *property;
 
-  ten_list_t msg_conversions;  // ten_msg_conversion_t
+  ten_list_t msg_conversion_contexts;  // ten_msg_conversion_context_t
 } ten_extension_info_t;
 
 TEN_RUNTIME_PRIVATE_API ten_extension_info_t *ten_extension_info_create(void);

core/include_internal/ten_runtime/extension/msg_handling.h

@@ -11,7 +11,7 @@
 #include "ten_utils/lib/smart_ptr.h"
 
 typedef struct ten_extension_t ten_extension_t;
-typedef struct ten_msg_conversion_operation_t ten_msg_conversion_operation_t;
+typedef struct ten_msg_conversion_t ten_msg_conversion_t;
 
 TEN_RUNTIME_PRIVATE_API void ten_extension_handle_in_msg(ten_extension_t *self,
-                                                       ten_shared_ptr_t *msg);
+                                                         ten_shared_ptr_t *msg);

core/include_internal/ten_runtime/msg_conversion/msg_and_its_result_conversion.h

@@ -0,0 +1,25 @@
+//
+// Copyright © 2024 Agora
+// This file is part of TEN Framework, an open source project.
+// Licensed under the Apache License, Version 2.0, with certain conditions.
+// Refer to the "LICENSE" file in the root directory for more information.
+//
+#pragma once
+
+#include "ten_runtime/ten_config.h"
+
+#include "ten_utils/lib/smart_ptr.h"
+
+typedef struct ten_msg_conversion_t ten_msg_conversion_t;
+
+typedef struct ten_msg_and_its_result_conversion_t {
+  ten_shared_ptr_t *msg;
+  ten_msg_conversion_t *result_conversion;
+} ten_msg_and_its_result_conversion_t;
+
+TEN_RUNTIME_PRIVATE_API ten_msg_and_its_result_conversion_t *
+ten_msg_and_its_result_conversion_create(
+    ten_shared_ptr_t *msg, ten_msg_conversion_t *result_conversion);
+
+TEN_RUNTIME_PRIVATE_API void ten_msg_and_its_result_conversion_destroy(
+    ten_msg_and_its_result_conversion_t *self);

core/include_internal/ten_runtime/msg_conversion/msg_and_result_conversion.h

@@ -0,0 +1,34 @@
+//
+// Copyright © 2024 Agora
+// This file is part of TEN Framework, an open source project.
+// Licensed under the Apache License, Version 2.0, with certain conditions.
+// Refer to the "LICENSE" file in the root directory for more information.
+//
+#pragma once
+
+#include "ten_runtime/ten_config.h"
+
+#include "ten_utils/lib/json.h"
+#include "ten_utils/value/value.h"
+
+typedef struct ten_msg_conversion_t ten_msg_conversion_t;
+
+typedef struct ten_msg_and_result_conversion_t {
+  ten_msg_conversion_t *msg;
+  ten_msg_conversion_t *result;
+} ten_msg_and_result_conversion_t;
+
+TEN_RUNTIME_PRIVATE_API void ten_msg_and_result_conversion_destroy(
+    ten_msg_and_result_conversion_t *self);
+
+TEN_RUNTIME_PRIVATE_API ten_msg_and_result_conversion_t *
+ten_msg_and_result_conversion_from_json(ten_json_t *json, ten_error_t *err);
+
+TEN_RUNTIME_PRIVATE_API ten_json_t *ten_msg_and_result_conversion_to_json(
+    ten_msg_and_result_conversion_t *self, ten_error_t *err);
+
+TEN_RUNTIME_PRIVATE_API ten_msg_and_result_conversion_t *
+ten_msg_and_result_conversion_from_value(ten_value_t *value, ten_error_t *err);
+
+TEN_RUNTIME_PRIVATE_API ten_value_t *ten_msg_and_result_conversion_to_value(
+    ten_msg_and_result_conversion_t *self, ten_error_t *err);

core/include_internal/ten_runtime/msg_conversion/msg_conversion/base.h

@@ -0,0 +1,55 @@
+//
+// Copyright © 2024 Agora
+// This file is part of TEN Framework, an open source project.
+// Licensed under the Apache License, Version 2.0, with certain conditions.
+// Refer to the "LICENSE" file in the root directory for more information.
+//
+#pragma once
+
+#include "ten_runtime/ten_config.h"
+
+#include "ten_utils/lib/json.h"
+#include "ten_utils/lib/smart_ptr.h"
+#include "ten_utils/value/value.h"
+
+typedef struct ten_msg_conversion_t ten_msg_conversion_t;
+
+typedef ten_shared_ptr_t *(*ten_msg_conversion_func_t)(
+    ten_msg_conversion_t *operation, ten_shared_ptr_t *msg, ten_error_t *err);
+
+/**
+ * If the desired message conversion is beyond the capabilities of the TEN
+ * runtime, an extension can be used to handle the conversion. To avoid having
+ * message conversion logic intrude into other extensions, a dedicated extension
+ * specifically for message conversion can be implemented. This standalone
+ * extension should be designed with enough flexibility to accommodate various
+ * conversion needs.
+ */
+typedef enum TEN_MSG_CONVERSION_TYPE {
+  TEN_MSG_CONVERSION_TYPE_INVALID,
+
+  TEN_MSG_CONVERSION_TYPE_PER_PROPERTY,
+} TEN_MSG_CONVERSION_TYPE;
+
+typedef struct ten_msg_conversion_t {
+  TEN_MSG_CONVERSION_TYPE type;
+  ten_msg_conversion_func_t operation;
+} ten_msg_conversion_t;
+
+TEN_RUNTIME_PRIVATE_API void ten_msg_conversion_destroy(
+    ten_msg_conversion_t *self);
+
+TEN_RUNTIME_PRIVATE_API ten_msg_conversion_t *ten_msg_conversion_from_json(
+    ten_json_t *json, ten_error_t *err);
+
+TEN_RUNTIME_PRIVATE_API ten_json_t *ten_msg_conversion_to_json(
+    ten_msg_conversion_t *self, ten_error_t *err);
+
+TEN_RUNTIME_PRIVATE_API ten_msg_conversion_t *ten_msg_conversion_from_value(
+    ten_value_t *value, ten_error_t *err);
+
+TEN_RUNTIME_PRIVATE_API ten_value_t *ten_msg_conversion_to_value(
+    ten_msg_conversion_t *self, ten_error_t *err);
+
+TEN_RUNTIME_PRIVATE_API ten_shared_ptr_t *ten_msg_conversion_convert(
+    ten_msg_conversion_t *self, ten_shared_ptr_t *msg, ten_error_t *err);

core/include_internal/ten_runtime/msg_conversion/msg_conversion/per_property/fixed_value.h

@@ -0,0 +1,50 @@
+//
+// Copyright © 2024 Agora
+// This file is part of TEN Framework, an open source project.
+// Licensed under the Apache License, Version 2.0, with certain conditions.
+// Refer to the "LICENSE" file in the root directory for more information.
+//
+#pragma once
+
+#include "ten_runtime/ten_config.h"
+
+#include "ten_utils/value/value.h"
+
+// {
+//   "path": "...",
+//   "conversion_mode": "fixed_value",
+//   "value": "..."
+// }
+typedef struct ten_msg_conversion_per_property_rule_fixed_value_t {
+  ten_value_t *value;
+} ten_msg_conversion_per_property_rule_fixed_value_t;
+
+TEN_RUNTIME_PRIVATE_API void
+ten_msg_conversion_per_property_rule_fixed_value_deinit(
+    ten_msg_conversion_per_property_rule_fixed_value_t *self);
+
+TEN_RUNTIME_PRIVATE_API bool
+ten_msg_conversion_per_property_rule_fixed_value_convert(
+    ten_msg_conversion_per_property_rule_fixed_value_t *self,
+    ten_shared_ptr_t *new_cmd, const char *new_msg_property_path,
+    ten_error_t *err);
+
+TEN_RUNTIME_PRIVATE_API bool
+ten_msg_conversion_per_property_rule_fixed_value_from_json(
+    ten_msg_conversion_per_property_rule_fixed_value_t *self, ten_json_t *json,
+    ten_error_t *err);
+
+TEN_RUNTIME_PRIVATE_API bool
+ten_msg_conversion_per_property_rule_fixed_value_to_json(
+    ten_msg_conversion_per_property_rule_fixed_value_t *self, ten_json_t *json,
+    ten_error_t *er);
+
+TEN_RUNTIME_PRIVATE_API bool
+ten_msg_conversion_per_property_rule_fixed_value_from_value(
+    ten_msg_conversion_per_property_rule_fixed_value_t *self,
+    ten_value_t *value, ten_error_t *err);
+
+TEN_RUNTIME_PRIVATE_API void
+ten_msg_conversion_per_property_rule_fixed_value_to_value(
+    ten_msg_conversion_per_property_rule_fixed_value_t *self,
+    ten_value_t *value);

core/include_internal/ten_runtime/msg_conversion/msg_conversion/per_property/from_original.h

@@ -0,0 +1,52 @@
+//
+// Copyright © 2024 Agora
+// This file is part of TEN Framework, an open source project.
+// Licensed under the Apache License, Version 2.0, with certain conditions.
+// Refer to the "LICENSE" file in the root directory for more information.
+//
+#pragma once
+
+#include "ten_runtime/ten_config.h"
+
+#include "ten_utils/lib/smart_ptr.h"
+#include "ten_utils/lib/string.h"
+#include "ten_utils/value/value.h"
+
+// {
+//   "path": "...",
+//   "conversion_mode": "from_original",
+//   "original_path": "..."
+// }
+typedef struct ten_msg_conversion_per_property_rule_from_original_t {
+  ten_string_t original_path;
+} ten_msg_conversion_per_property_rule_from_original_t;
+
+TEN_RUNTIME_PRIVATE_API void
+ten_msg_conversion_per_property_rule_from_original_deinit(
+    ten_msg_conversion_per_property_rule_from_original_t *self);
+
+TEN_RUNTIME_PRIVATE_API bool
+ten_msg_conversion_per_property_rule_from_original_convert(
+    ten_msg_conversion_per_property_rule_from_original_t *self,
+    ten_shared_ptr_t *msg, ten_shared_ptr_t *new_msg,
+    const char *new_msg_property_path, ten_error_t *err);
+
+TEN_RUNTIME_PRIVATE_API void
+ten_msg_conversion_per_property_rule_from_original_from_json(
+    ten_msg_conversion_per_property_rule_from_original_t *self,
+    ten_json_t *json);
+
+TEN_RUNTIME_PRIVATE_API bool
+ten_msg_conversion_per_property_rule_from_original_to_json(
+    ten_msg_conversion_per_property_rule_from_original_t *self,
+    ten_json_t *json, ten_error_t *err);
+
+TEN_RUNTIME_PRIVATE_API bool
+ten_msg_conversion_per_property_rule_from_original_from_value(
+    ten_msg_conversion_per_property_rule_from_original_t *self,
+    ten_value_t *value, ten_error_t *err);
+
+TEN_RUNTIME_PRIVATE_API void
+ten_msg_conversion_per_property_rule_from_original_to_value(
+    ten_msg_conversion_per_property_rule_from_original_t *self,
+    ten_value_t *value);

core/include_internal/ten_runtime/msg_conversion/msg_conversion/per_property/per_property.h

@@ -0,0 +1,53 @@
+//
+// Copyright © 2024 Agora
+// This file is part of TEN Framework, an open source project.
+// Licensed under the Apache License, Version 2.0, with certain conditions.
+// Refer to the "LICENSE" file in the root directory for more information.
+//
+#pragma once
+
+#include "ten_runtime/ten_config.h"
+
+#include "include_internal/ten_runtime/msg_conversion/msg_conversion/base.h"
+#include "ten_utils/lib/json.h"
+#include "ten_utils/value/value.h"
+
+typedef struct ten_msg_conversion_per_property_rules_t
+    ten_msg_conversion_per_property_rules_t;
+
+// {
+//   "type": "per_property",
+//   "rules": [{
+//     "path": "...",
+//     "conversion_mode": "from_original",
+//     "original_path": "..."
+//   },{
+//     "path": "...",
+//     "conversion_mode": "fixed_value",
+//     "value": "..."
+//   }]
+// }
+typedef struct ten_msg_conversion_per_property_t {
+  ten_msg_conversion_t base;
+  ten_msg_conversion_per_property_rules_t *rules;
+} ten_msg_conversion_per_property_t;
+
+TEN_RUNTIME_PRIVATE_API ten_msg_conversion_per_property_t *
+ten_msg_conversion_per_property_create(
+    ten_msg_conversion_per_property_rules_t *rules);
+
+TEN_RUNTIME_PRIVATE_API void ten_msg_conversion_per_property_destroy(
+    ten_msg_conversion_per_property_t *self);
+
+TEN_RUNTIME_PRIVATE_API ten_msg_conversion_per_property_t *
+ten_msg_conversion_per_property_from_json(ten_json_t *json, ten_error_t *err);
+
+TEN_RUNTIME_PRIVATE_API ten_json_t *ten_msg_conversion_per_property_to_json(
+    ten_msg_conversion_per_property_t *self, ten_error_t *err);
+
+TEN_RUNTIME_PRIVATE_API ten_msg_conversion_per_property_t *
+ten_msg_conversion_per_property_from_value(ten_value_t *value,
+                                           ten_error_t *err);
+
+TEN_RUNTIME_PRIVATE_API ten_value_t *ten_msg_conversion_per_property_to_value(
+    ten_msg_conversion_per_property_t *self, ten_error_t *err);