README.md
1# Call Manager<a name="EN-US_TOPIC_0000001105058232"></a>
2
3- [Introduction](#section117mcpsimp)
4- [Directory Structure](#section128mcpsimp)
5- [Constraints](#section131mcpsimp)
6- [Available APIs](#section136mcpsimp)
7- [Usage Guidelines](#section163mcpsimp)
8 - [Calling the dial API to Place a Call](#section113291522113518)
9
10- [Repositories Involved](#section227mcpsimp)
11
12## Introduction<a name="section117mcpsimp"></a>
13
14The Call Manager module mainly manages three types of calls: circuit switched \(CS\), IP multimedia subsystem \(IMS\), and over the top \(OTT\) calls. It is responsible for applying for the audio and video resources required for a call and resolving conflicts in a multi-channel call. The module consists of six parts: UI interaction \(CallServiceAbility\), service management \(CallManagerService\), call management \(Call Manager\), audio management \(Audio Manager\), video management \(Video Manager\), and Bluetooth management \(Bluetooth Manager\).
15
161. CallServiceAbility: Implements interaction with the call UI, for example, launching the keypad UI for dialup and reporting the incoming call status to the UI.
172. CallManagerService: starts and initializes the Call Manager.
183. Call Manager: processes downlink call operations \(such as dialup, answer, and onhook\) and uplink call status \(such as incoming call status and call waiting status\), and resolves conflicts that occur in a call.
194. Audio Manager: applies for audio resources for a call and releases the resources after the call ends. This part depends on the multimedia subsystem and needs to call its APIs to perform audio-related operations.
205. Video Manager: applies for video resources for a call and releases the resources after the call ends. This part depends on the multimedia subsystem and needs to call its APIs to perform video-related operations.
216. Bluetooth Manager: applies for Bluetooth resources for a call and releases the resources after the call ends. Besides, this part processes call operations initiated by Bluetooth devices, such as answering and ending calls.
22
23The following figure shows the architecture of the Call Manager module.
24
25**Figure 1** Architecture of the Call Manager module<a name="fig11440121615591"></a>
26
27
28
29
30## Directory Structure<a name="section128mcpsimp"></a>
31
32```
33/base/telephony/call_manager
34├─ frameworks # JS NAPIs
35├─ interfaces # External APIs
36│ ├─ innerkits # Internal APIs
37│ └─ kits # JS APIs
38├─ sa_profile # SA profile
39├─ services # Service code
40│ ├─ audio # Audio Manager code
41│ ├─ bluetooth # Bluetooth Manager code
42│ ├─ call # Call Manager code
43│ ├─ call_manager_service # CallManagerService code
44│ ├─ call_report # CallReport code
45│ ├─ call_setting # CallSetting code
46│ ├─ telephony_interaction # Telephony core service code
47│ └─ video # Video code
48├─ test # Unit test code
49└─ utils # Utilities
50```
51
52## Constraints<a name="section131mcpsimp"></a>
53
54- Programming language: JavaScript
55- In terms of software, this module needs to work with the Security subsystem, Multimedia subsystem, and Intelligent Soft Bus subsystem \(Bluetooth module\), as well as the telephony core service \(core\_service\) and cellular call module \(cellular\_call\).
56- In terms of hardware, the accommodating device must be equipped with a speaker or earphone, and a headset.
57
58## Available APIs<a name="section136mcpsimp"></a>
59
60**Table 1** External API provided by the Call Manager module
61
62<a name="table137mcpsimp"></a>
63<table><thead align="left"><tr id="row143mcpsimp"><th class="cellrowborder" valign="top" width="33.33333333333333%" id="mcps1.2.4.1.1"><p id="entry144mcpsimpp0"><a name="entry144mcpsimpp0"></a><a name="entry144mcpsimpp0"></a>Description</p>
64</th>
65<th class="cellrowborder" valign="top" width="33.33333333333333%" id="mcps1.2.4.1.2"><p id="entry145mcpsimpp0"><a name="entry145mcpsimpp0"></a><a name="entry145mcpsimpp0"></a>Description</p>
66</th>
67<th class="cellrowborder" valign="top" width="33.33333333333333%" id="mcps1.2.4.1.3"><p id="entry146mcpsimpp0"><a name="entry146mcpsimpp0"></a><a name="entry146mcpsimpp0"></a>Required Permission</p>
68</th>
69</tr>
70</thead>
71<tbody><tr id="row147mcpsimp"><td class="cellrowborder" valign="top" width="33.33333333333333%" headers="mcps1.2.4.1.1 "><p id="p143312519577"><a name="p143312519577"></a><a name="p143312519577"></a>function dial(phoneNumber: string, options: DialOptions, callback: AsyncCallback<boolean>): void;</p>
72</td>
73<td class="cellrowborder" valign="top" width="33.33333333333333%" headers="mcps1.2.4.1.2 "><p id="entry149mcpsimpp0"><a name="entry149mcpsimpp0"></a><a name="entry149mcpsimpp0"></a>Performs dialup operations.</p>
74</td>
75<td class="cellrowborder" valign="top" width="33.33333333333333%" headers="mcps1.2.4.1.3 "><p id="entry150mcpsimpp0"><a name="entry150mcpsimpp0"></a><a name="entry150mcpsimpp0"></a>ohos.permission.PLACE_CALL</p>
76</td>
77</tr>
78</tbody>
79</table>
80
81**Table 2** Parameters of the Dial API
82
83<a name="table18488202215170"></a>
84<table><thead align="left"><tr id="row748952217179"><th class="cellrowborder" valign="top" width="50%" id="mcps1.2.3.1.1"><p id="p1948942271710"><a name="p1948942271710"></a><a name="p1948942271710"></a>Parameter</p>
85</th>
86<th class="cellrowborder" valign="top" width="50%" id="mcps1.2.3.1.2"><p id="p1648972215173"><a name="p1648972215173"></a><a name="p1648972215173"></a>Description</p>
87</th>
88</tr>
89</thead>
90<tbody><tr id="row749092213171"><td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.1 "><p id="p14901222191720"><a name="p14901222191720"></a><a name="p14901222191720"></a>phoneNumber: string</p>
91</td>
92<td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.2 "><p id="p34906228170"><a name="p34906228170"></a><a name="p34906228170"></a>Phone number</p>
93</td>
94</tr>
95<tr id="row549011221176"><td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.1 "><p id="p44902223175"><a name="p44902223175"></a><a name="p44902223175"></a>options: DialOptions</p>
96</td>
97<td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.2 "><p id="p11490162241718"><a name="p11490162241718"></a><a name="p11490162241718"></a>Dialup options (For details, see the following table.)</p>
98</td>
99</tr>
100<tr id="row149072216176"><td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.1 "><p id="p5490152211715"><a name="p5490152211715"></a><a name="p5490152211715"></a>callback: AsyncCallback<boolean></p>
101</td>
102<td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.2 "><p id="p649002291718"><a name="p649002291718"></a><a name="p649002291718"></a>Asynchronous execution result. Value <strong id="b1400386820"><a name="b1400386820"></a><a name="b1400386820"></a>true</strong> indicates that the dialup is successful, and value <strong id="b022154719814"><a name="b022154719814"></a><a name="b022154719814"></a>false</strong> indicates that the dialup has failed.</p>
103</td>
104</tr>
105</tbody>
106</table>
107
108**Table 3** Parameter description of options: DialOptions
109
110<a name="table1322739190"></a>
111<table><thead align="left"><tr id="row193221031194"><th class="cellrowborder" valign="top" width="20%" id="mcps1.2.6.1.1"><p id="p203224311917"><a name="p203224311917"></a><a name="p203224311917"></a>Parameter</p>
112</th>
113<th class="cellrowborder" valign="top" width="20%" id="mcps1.2.6.1.2"><p id="p1639614810198"><a name="p1639614810198"></a><a name="p1639614810198"></a>Type</p>
114</th>
115<th class="cellrowborder" valign="top" width="20%" id="mcps1.2.6.1.3"><p id="p113221730191"><a name="p113221730191"></a><a name="p113221730191"></a>Description</p>
116</th>
117<th class="cellrowborder" valign="top" width="20%" id="mcps1.2.6.1.4"><p id="p153221330197"><a name="p153221330197"></a><a name="p153221330197"></a>Mandatory</p>
118</th>
119<th class="cellrowborder" valign="top" width="20%" id="mcps1.2.6.1.5"><p id="p632220310199"><a name="p632220310199"></a><a name="p632220310199"></a>Default Value</p>
120</th>
121</tr>
122</thead>
123<tbody><tr id="row123238311920"><td class="cellrowborder" valign="top" width="20%" headers="mcps1.2.6.1.1 "><p id="p932310311197"><a name="p932310311197"></a><a name="p932310311197"></a>extras</p>
124</td>
125<td class="cellrowborder" valign="top" width="20%" headers="mcps1.2.6.1.2 "><p id="p73966801911"><a name="p73966801911"></a><a name="p73966801911"></a>boolean</p>
126</td>
127<td class="cellrowborder" valign="top" width="20%" headers="mcps1.2.6.1.3 "><p id="p19821612162118"><a name="p19821612162118"></a><a name="p19821612162118"></a><strong id="b345117841310"><a name="b345117841310"></a><a name="b345117841310"></a>false</strong>: audio; <strong id="b1701410181319"><a name="b1701410181319"></a><a name="b1701410181319"></a>true</strong>: video</p>
128</td>
129<td class="cellrowborder" valign="top" width="20%" headers="mcps1.2.6.1.4 "><p id="p33231931191"><a name="p33231931191"></a><a name="p33231931191"></a>No</p>
130</td>
131<td class="cellrowborder" valign="top" width="20%" headers="mcps1.2.6.1.5 "><p id="p12323232197"><a name="p12323232197"></a><a name="p12323232197"></a>false</p>
132</td>
133</tr>
134</tbody>
135</table>
136
137## Usage Guidelines<a name="section163mcpsimp"></a>
138
139### Calling the dial API to Place a Call<a name="section113291522113518"></a>
140
1411. Construct the **phoneNumber** and **options** parameters.
1422. Call the **Dial** API in callback or Promise mode.
1433. Obtain the dialup result. The **Dial** API works in asynchronous mode. The dialup result is returned through the callback.
144
145 ```
146 import call from "@ohos.telephony.call";
147
148 let phoneNumber = "12312312312";
149
150 // Call the API in callback mode.
151 call.dial(phoneNumber, {extras: false}, (err, value) => {
152 if (err) {
153 // If the API call failed, err is not empty.
154 console.error(`failed to dial because ${err.message}`);
155 return;
156 }
157 // If the API call succeeded, err is empty.
158 console.log(`success to dial: ${value}`);
159 });
160
161 // Call the API in Promise mode.
162 let promise = call.dial(phoneNumber, {extras: false});
163 promise.then((value) => {
164 // The API call succeeded.
165 console.log(`success to dial: ${value}`);
166 }).catch((err) => {
167 // The API call failed.
168 console.error(`failed to dial because ${err.message}`);
169 });
170 ```
171
172
173## Repositories Involved<a name="section227mcpsimp"></a>
174
175[Telephony](https://gitee.com/openharmony/docs/blob/master/en/readme/telephony.md)
176
177**telephony_call_manager**
178
179[telephony_core_service](https://gitee.com/openharmony/telephony_core_service/blob/master/README.md)
180
181[telephony_cellular_call](https://gitee.com/openharmony/telephony_cellular_call/blob/master/README.md)
182
183[telephony_state_registry](https://gitee.com/openharmony/telephony_state_registry/blob/master/README.md)
README_zh.md
1# 通话管理<a name="ZH-CN_TOPIC_0000001105058232"></a>
2
3- [简介](#section117mcpsimp)
4- [目录](#section128mcpsimp)
5- [约束](#section131mcpsimp)
6- [接口说明](#section136mcpsimp)
7- [使用说明](#section163mcpsimp)
8 - [拨打电话接口调用流程及示例代码](#section113291522113518)
9
10- [相关仓](#section227mcpsimp)
11
12## 简介<a name="section117mcpsimp"></a>
13
14通话管理模块主要管理CS（Circuit Switch，电路交换）、IMS（IP Multimedia Subsystem，IP多媒体子系统）和OTT（over the top，OTT解决方案）三种类型的通话，负责申请通话所需要的音视频资源，并处理多路通话时产生的各种冲突。通话管理主要分为UI交互、服务管理、系统通话管理、通话音频管理、通话视频管理和蓝牙通话管理六大模块，各模块简介如下：
15
161. UI交互模块：负责和通话UI交互，如UI调用接口拨号，上报来电等状态给UI。
172. 服务管理模块：负责启动和初始化系统通话管理服务。
183. 系统通话管理模块：负责处理通话下行操作（如拨号、接听、挂断等）和上行状态（来电状态、呼叫等待状态等）的处理，并解决通话过程中产生的冲突。
194. 通话音频管理模块：负责通话时需要的音频资源的申请和释放，依赖多媒体子系统，需要调用多媒体子系统接口进行音频相关的操作。
205. 通话视频管理模块：负责通话时需要的视频资源的申请和释放，依赖多媒体子系统，需要调用多媒体子系统接口进行视频相关的操作。
216. 蓝牙通话管理模块：负责通话时需要的蓝牙资源的申请和释放，并处理蓝牙设备发起的通话操作，如接听和挂断等。
22
23其主要的结构及流程如下图所示：
24
25**图 1** 通话管理模块架构图<a name="fig11440121615591"></a>
26
27
28
29
30## 目录<a name="section128mcpsimp"></a>
31
32```
33/base/telephony/call_manager
34├─ frameworks # napi接口存放目录
35├─ interfaces # 对外部暴露的接口
36│ ├─ innerkits # 部件间的内部接口
37│ └─ kits # js接口存放目录
38├─ sa_profile # 启动配置文件
39├─ services # 服务内部代码
40│ ├─ audio # 音频管理相关代码
41│ ├─ bluetooth # 蓝牙通话相关代码
42│ ├─ call # 通话业务相关代码
43│ ├─ call_manager_service # 进程服务管理相关代码
44│ ├─ call_report # 通话状态等信息上报相关代码
45│ ├─ call_setting # 通话设置相关代码
46│ ├─ telephony_interaction # 电话核心服务交互相关代码
47│ └─ video # 视频管理相关代码
48├─ test # 单元测试相关代码
49└─ utils # 通用工具类
50```
51
52## 约束<a name="section131mcpsimp"></a>
53
54- 开发语言：JavaScript。
55- 软件上，需要与以下子系统和服务配合使用：安全子系统，多媒体子系统，软总线基础通信子系统\(蓝牙模块\)，Telephony核心服务（core\_service），蜂窝通话服务（cellular\_call）。
56- 硬件上，需要搭载的设备支持以下硬件：扬声器或听筒、麦克风。
57
58## 接口说明<a name="section136mcpsimp"></a>
59
60**表 1** 通话管理对外提供的接口
61
62<a name="table137mcpsimp"></a>
63<table><thead align="left"><tr id="row143mcpsimp"><th class="cellrowborder" valign="top" width="33.33333333333333%" id="mcps1.2.4.1.1"><p id="entry144mcpsimpp0"><a name="entry144mcpsimpp0"></a><a name="entry144mcpsimpp0"></a>接口内容</p>
64</th>
65<th class="cellrowborder" valign="top" width="33.33333333333333%" id="mcps1.2.4.1.2"><p id="entry145mcpsimpp0"><a name="entry145mcpsimpp0"></a><a name="entry145mcpsimpp0"></a>接口描述</p>
66</th>
67<th class="cellrowborder" valign="top" width="33.33333333333333%" id="mcps1.2.4.1.3"><p id="entry146mcpsimpp0"><a name="entry146mcpsimpp0"></a><a name="entry146mcpsimpp0"></a>所需权限</p>
68</th>
69</tr>
70</thead>
71<tbody><tr id="row147mcpsimp"><td class="cellrowborder" valign="top" width="33.33333333333333%" headers="mcps1.2.4.1.1 "><p id="p143312519577"><a name="p143312519577"></a><a name="p143312519577"></a>function dial(phoneNumber: string, options: DialOptions, callback: AsyncCallback<boolean>): void;</p>
72</td>
73<td class="cellrowborder" valign="top" width="33.33333333333333%" headers="mcps1.2.4.1.2 "><p id="entry149mcpsimpp0"><a name="entry149mcpsimpp0"></a><a name="entry149mcpsimpp0"></a>拨号接口，调用此接口可以进行拨号操作</p>
74</td>
75<td class="cellrowborder" valign="top" width="33.33333333333333%" headers="mcps1.2.4.1.3 "><p id="entry150mcpsimpp0"><a name="entry150mcpsimpp0"></a><a name="entry150mcpsimpp0"></a>ohos.permission.PLACE_CALL</p>
76</td>
77</tr>
78</tbody>
79</table>
80
81**表 2** 拨号接口参数说明
82
83<a name="table18488202215170"></a>
84<table><thead align="left"><tr id="row748952217179"><th class="cellrowborder" valign="top" width="50%" id="mcps1.2.3.1.1"><p id="p1948942271710"><a name="p1948942271710"></a><a name="p1948942271710"></a>参数</p>
85</th>
86<th class="cellrowborder" valign="top" width="50%" id="mcps1.2.3.1.2"><p id="p1648972215173"><a name="p1648972215173"></a><a name="p1648972215173"></a>描述</p>
87</th>
88</tr>
89</thead>
90<tbody><tr id="row749092213171"><td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.1 "><p id="p14901222191720"><a name="p14901222191720"></a><a name="p14901222191720"></a>phoneNumber: string</p>
91</td>
92<td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.2 "><p id="p34906228170"><a name="p34906228170"></a><a name="p34906228170"></a>电话号码</p>
93</td>
94</tr>
95<tr id="row549011221176"><td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.1 "><p id="p44902223175"><a name="p44902223175"></a><a name="p44902223175"></a>options: DialOptions</p>
96</td>
97<td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.2 "><p id="p11490162241718"><a name="p11490162241718"></a><a name="p11490162241718"></a>扩展参数（详见下表）</p>
98</td>
99</tr>
100<tr id="row149072216176"><td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.1 "><p id="p5490152211715"><a name="p5490152211715"></a><a name="p5490152211715"></a>callback: AsyncCallback<boolean></p>
101</td>
102<td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.2 "><p id="p649002291718"><a name="p649002291718"></a><a name="p649002291718"></a>异步执行结果，true表示执行成功，false表示执行失败</p>
103</td>
104</tr>
105</tbody>
106</table>
107
108**表 3** options: DialOptions参数说明
109
110<a name="table1322739190"></a>
111<table><thead align="left"><tr id="row193221031194"><th class="cellrowborder" valign="top" width="20%" id="mcps1.2.6.1.1"><p id="p203224311917"><a name="p203224311917"></a><a name="p203224311917"></a>参数</p>
112</th>
113<th class="cellrowborder" valign="top" width="20%" id="mcps1.2.6.1.2"><p id="p1639614810198"><a name="p1639614810198"></a><a name="p1639614810198"></a>类型</p>
114</th>
115<th class="cellrowborder" valign="top" width="20%" id="mcps1.2.6.1.3"><p id="p113221730191"><a name="p113221730191"></a><a name="p113221730191"></a>描述</p>
116</th>
117<th class="cellrowborder" valign="top" width="20%" id="mcps1.2.6.1.4"><p id="p153221330197"><a name="p153221330197"></a><a name="p153221330197"></a>是否必填</p>
118</th>
119<th class="cellrowborder" valign="top" width="20%" id="mcps1.2.6.1.5"><p id="p632220310199"><a name="p632220310199"></a><a name="p632220310199"></a>默认值</p>
120</th>
121</tr>
122</thead>
123<tbody><tr id="row123238311920"><td class="cellrowborder" valign="top" width="20%" headers="mcps1.2.6.1.1 "><p id="p932310311197"><a name="p932310311197"></a><a name="p932310311197"></a>extras</p>
124</td>
125<td class="cellrowborder" valign="top" width="20%" headers="mcps1.2.6.1.2 "><p id="p73966801911"><a name="p73966801911"></a><a name="p73966801911"></a>boolean</p>
126</td>
127<td class="cellrowborder" valign="top" width="20%" headers="mcps1.2.6.1.3 "><p id="p19821612162118"><a name="p19821612162118"></a><a name="p19821612162118"></a>false：音频 true：视频</p>
128</td>
129<td class="cellrowborder" valign="top" width="20%" headers="mcps1.2.6.1.4 "><p id="p33231931191"><a name="p33231931191"></a><a name="p33231931191"></a>否</p>
130</td>
131<td class="cellrowborder" valign="top" width="20%" headers="mcps1.2.6.1.5 "><p id="p12323232197"><a name="p12323232197"></a><a name="p12323232197"></a>false</p>
132</td>
133</tr>
134</tbody>
135</table>
136
137完整的JS API说明以及实例代码请参考：[拨打电话](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/js-reference/apis/js-apis-call.md)。
138## 使用说明<a name="section163mcpsimp"></a>
139
140### 拨打电话接口调用流程及示例代码<a name="section113291522113518"></a>
141
1421. 构造phoneNumber和options参数；
1432. 可以通过callback或者Promise的方式调用dial接口。
1443. 该接口为异步接口，相关执行结果会从callback中返回。
145
146 ```
147 import call from "@ohos.telephony.call";
148
149 let phoneNumber = "12312312312";
150
151 // 调用接口【callback方式】
152 call.dial(phoneNumber, {extras: false}, (err, value) => {
153 if (err) {
154 // 接口调用失败，err非空
155 console.error(`failed to dial because ${err.message}`);
156 return;
157 }
158 // 接口调用成功，err为空
159 console.log(`success to dial: ${value}`);
160 });
161
162 // 调用接口【Promise方式】
163 let promise = call.dial(phoneNumber, {extras: false});
164 promise.then((value) => {
165 // 接口调用成功，此处可以实现成功场景分支代码。
166 console.log(`success to dial: ${value}`);
167 }).catch((err) => {
168 // 接口调用失败，此处可以实现失败场景分支代码。
169 console.error(`failed to dial because ${err.message}`);
170 });
171 ```
172
173
174## 相关仓<a name="section227mcpsimp"></a>
175
176[电话服务子系统](https://gitee.com/openharmony/docs/blob/master/zh-cn/readme/%E7%94%B5%E8%AF%9D%E6%9C%8D%E5%8A%A1%E5%AD%90%E7%B3%BB%E7%BB%9F.md)
177
178**telephony_call_manager**
179
180[telephony_core_service](https://gitee.com/openharmony/telephony_core_service/blob/master/README_zh.md)
181
182[telephony_cellular_call](https://gitee.com/openharmony/telephony_cellular_call/blob/master/README_zh.md)
183
184[telephony_state_registry](https://gitee.com/openharmony/telephony_state_registry/blob/master/README_zh.md)
