Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 32 additions & 14 deletions en/api/framework/feature/feature_framework.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,12 @@

In QuickApp development, new capabilities need to be added to QuickApps, and these capabilities are written in C/C++. The Feature framework is a framework, SDK, and toolset that helps system developers extend functionality for QuickApps.

<img src="./figures/feature_framework.png" alt="Feature Framework Architecture Diagram" style="zoom: 80%;" />
The overall architecture is organized into the following layers, from top to bottom:

- **JS Layer** — QuickApp (user JS code)
- **Framework Layer** — QuickApp Framework (together with the QuickApp Engine) and Feature Framework
- **Native Layer** — Feature implementations written in C/C++
- **OS Layer** — openvela

## Feature Framework Capabilities

Expand Down Expand Up @@ -41,13 +46,24 @@ From a system perspective, the Feature concepts:

#### Runtime Concept Model

Each Feature can associate Native data, with different associated content. The runtime concept model is as follows:
Each Feature can associate Native data, with different associated content:

<img src="./figures/feature_running.png" alt="Feature Runtime Concept Model" style="zoom: 67%;" />
- **Module** is purely internal to the Native side and is never exposed to the JS environment.
- **Prototype** appears in JS as a `JSObject`, but cannot be used directly from JS. On the Native side, it holds `prototype Native data` whose lifetime matches the app.
- **Instance** also appears in JS as a `JSObject`, and on the Native side holds `instance Native data` whose lifetime matches the instance itself.

#### Feature Lifecycle

<img src="./figures/feature_life.png" alt="Feature Lifecycle Diagram" style="zoom:80%;" />
The Feature lifecycle consists of six events, listed below in the order they occur:

| Event | Triggered When | Notes |
| ---------------------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| **`onRegister`** (Module Registration) | When the system starts up, or when `FeatureManagerRegister` is called | Do not perform long / complex tasks during registration, otherwise system startup will slow down |
| **`onCreate`** (Prototype Creation) | The first time the app uses the Feature | Do not expect this function to be called at app startup |
| **`onRequire`** (Instance Creation) | When the app calls `require` for this Feature | Feature instance initialization can be done here |
| **`onDettach`** (Instance Destruction) | When a Feature instance is destroyed (page exit, app exit, etc.) | Feature teardown is non-deterministic; do not defer recycling of temporary data to this point |
| **`onDestroy`** (Prototype Destruction) | When the app exits | App-wide global data is recycled here |
| **`onUnregister`** (Module Unregistered) | When the Feature is unregistered | Do not rely on this callback; it may never be called |

### Feature Framework Interface Capabilities

Expand All @@ -71,23 +87,25 @@ The Feature framework helps developers create Feature Prototypes and Instances.

From JS to Native, the Feature framework provides parameter conversion capabilities, converting JS parameters to plain parameters. The following table shows the basic conversion capabilities:

| JS Type | C Type | Description |
| ------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| number/boolean | int, float, double, bool | JS number types exist as floating point. Based on JIDL description, they can be converted to compatible types like int, float. Converting to int/bool causes loss of decimal part |
| string | FtString | `const char*` typedef |
| object | struct pointer / FtAny pointer | If a struct is defined in JIDL, converts to the corresponding C struct pointer; if defined as object/any type in JIDL, defined as FtAny pointer |
| array | FtArray pointer | Converts to a C structure FtArray |
| function | FtCallbackId | Converts to an integer representing CallbackId |
| promise | FtPromiseId | Converts to an integer representing PromiseId |
| JS Type | C Type | Description |
| -------------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| number/boolean | int, float, double, bool | JS number types exist as floating point. Based on JIDL description, they can be converted to compatible types like int, float. Converting to int/bool causes loss of decimal part |
| string | FtString | `const char*` typedef |
| object | struct pointer / FtAny pointer | If a struct is defined in JIDL, converts to the corresponding C struct pointer; if defined as object/any type in JIDL, defined as FtAny pointer |
| array | FtArray pointer | Converts to a C structure FtArray |
| function | FtCallbackId | Converts to an integer representing CallbackId |
| promise | FtPromiseId | Converts to an integer representing PromiseId |

---

- Pointer objects have built-in reference counting and can be released via `FeatureDupValue` and `FeatureFreeValue`.
- Pointers passed through parameters do not need additional release.

The following diagram shows the management mechanism for Callbacks and Promises:
The Feature framework internally manages Callback and Promise objects, hiding the implementation details:

<img src="./figures/callback_promise_manager.png" alt="Callback and Promise Management Mechanism" style="zoom: 50%;" />
- Feature developers receive opaque IDs (`FtCallbackId` / `FtPromiseId`) instead of direct references to JS Function or Promise objects.
- The real JS Function and Promise instances are held inside the Feature framework (not visible to developers), together with reference counting.
- IDs act as indices into the internal tables, and the framework is responsible for reclaiming them.

The Feature framework achieves two goals by hiding details:

Expand Down
Binary file modified en/api/framework/feature/figures/Asynchronous_model.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified en/api/framework/feature/figures/JIDL.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file not shown.
Binary file not shown.
Binary file modified en/api/framework/feature/figures/feature_instance.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file removed en/api/framework/feature/figures/feature_life.png
Binary file not shown.
Binary file not shown.
Binary file modified en/api/framework/feature/figures/feature_static.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
4 changes: 0 additions & 4 deletions en/api/framework/quickapp/basic.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,10 +15,6 @@ This document introduces the overall design, implementation approach, and techni
- [Xiaomi openvela QuickApp Development Manual](https://iot.mi.com/vela/quickapp/zh/content/intro.html) — Complete development guide for application developers
- [Feature Framework API](../feature/index.md) — Native extension APIs for QuickApp (JS and C/C++ interop)

## Overall Architecture

![QuickApp Framework Architecture](figures/basic_structure.png)

## Build Configuration

The application framework itself has few configuration items, but has many dependencies. Among the dependencies, the renderer has the most requirements. For specific configuration, please refer to the documentation provided by the graphics team.
Expand Down
Binary file not shown.
Binary file modified en/api/framework/telephony/figures/TapiWork.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
30 changes: 24 additions & 6 deletions zh-cn/api/framework/feature/feature_framework.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,12 @@

在快应用(Quick App)开发中,需要为快应用增加一些新的能力,这些能力通过 C/C++ 语言编写。Feature 框架是一个帮助系统开发者为快应用扩展功能的框架、SDK 以及工具集。

<img src="./figures/feature_framework.png" alt="Feature 框架整体架构图" style="zoom: 80%;" />
整体架构从上到下分为以下几层:

- **JS 层** —— 快应用(用户编写的 JS 代码)
- **框架层** —— 快应用框架(及快应用引擎)、Feature 框架
- **Native 层** —— Feature 的 C/C++ 实现
- **操作系统层** —— openvela

## 二、Feature 框架能力

Expand Down Expand Up @@ -41,13 +46,24 @@ Feature 有 3 层概念:

#### 运行时概念模型

每个 Feature 都可以关联 Native 数据,所关联的内容有所区别。运行时概念模型如下
每个 Feature 都可以关联 Native 数据,所关联的内容有所区别:

<img src="./figures/feature_running.png" alt="Feature 运行时概念模型" style="zoom: 67%;" />
- **Module** 完全位于 Native 侧,不暴露给 JS 环境。
- **Prototype** 在 JS 中以 `JSObject` 形式呈现,但不能直接在 JS 中使用。在 Native 侧持有 `prototype Native 数据`,生命周期与 APP 一致。
- **Instance** 在 JS 中也以 `JSObject` 形式呈现,在 Native 侧持有 `instance Native 数据`,生命周期与 Instance 本身一致。

#### Feature 的生命周期

<img src="./figures/feature_life.png" alt="Feature 生命周期示意图" style="zoom:80%;" />
Feature 的生命周期包含 6 个事件,按发生顺序依次如下:

| 事件 | 触发时机 | 注意事项 |
| ----------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------ |
| **`onRegister`**(Module 注册) | 系统启动时调用,或者调用 `FeatureManagerRegister` 函数时触发 | 注册时不可执行长复杂任务,否则会导致系统启动变慢 |
| **`onCreate`**(Prototype 创建) | APP 第一次使用 Feature 时调用 | 不可期望该函数在 APP 启动时调用 |
| **`onRequire`**(Instance 创建) | APP Require 该 Feature 时调用 | 可在此做 Feature 实例初始化 |
| **`onDettach`**(Instance 销毁) | Feature 实例被销毁时(Page 退出、APP 退出等) | Feature 退出有一定不确定性,临时数据不能拖延到此刻回收 |
| **`onDestroy`**(Prototype 销毁) | APP 退出时调用 | 此处 APP 全局数据回收 |
| **`onUnregister`**(Module 被注销) | Feature 注销时调用 | 不可依赖此回调,该回调可能不会被调用 |

### 2、Feature 框架提供的接口能力

Expand Down Expand Up @@ -85,9 +101,11 @@ Feature 框架帮助开发者创建 Feature 的 Prototype 和 Instance。
- 指针对象自带引用计数,可以通过 `FeatureDupValue` 和 `FeatureFreeValue` 来释放。
- 通过参数传递的指针,不需要额外释放。

下图展示了对 Callback 和 Promise 的管理机制
Feature 框架内部对 Callback 和 Promise 做了统一管理,隐藏实现细节

<img src="./figures/callback_promise_manager.png" alt="Callback 和 Promise 管理机制" style="zoom: 50%;" />
- Feature 开发者拿到的是不透明的整数 ID(`FtCallbackId` / `FtPromiseId`),而不是 JS Function 或 Promise 对象本身。
- 真正的 JS Function 和 Promise 对象由 Feature 框架内部(开发者不可见)持有,并带有引用计数。
- ID 作为索引指向内部表,资源的回收由框架负责。

Feature 框架通过隐藏细节,达到两个目的:

Expand Down
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
4 changes: 0 additions & 4 deletions zh-cn/api/framework/quickapp/basic.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,10 +15,6 @@ openvela 快应用(QuickApp)框架(以下简称"应用框架"),是 ope
- [小米 openvela 快应用开发手册](https://iot.mi.com/vela/quickapp/zh/content/intro.html) — 面向应用开发者的完整开发指南
- [Feature 框架 API](../feature/index.md) — 快应用的 Native 扩展 API(JS 与 C/C++ 互调)

## 整体架构

![快应用框架整体架构图](figures/basic_structure.png)

## 编译配置

应用框架本身的配置项不多,但依赖项较多。依赖项中渲染器的依赖较多,具体配置请参考图形组提供的文档。
Expand Down
Binary file not shown.
Loading