README.md
1# RingtoneLibrary
2
3- [Introduction](#section1158716411637)
4- [Directory Structure](#section161941989596)
5- [Repositories Involved](#section1533973044317)
6
7## Introduction<a name="section1158716411637"></a>
8**Figures 1** RingtoneLibrary architecture
9
10**ringtone\_library** repository provides a set of easy-to-use APIs for setting and getting ringtone information.
11RingtoneLibrary APIs can only be used internally.
12
13The various capabilities can be categorized as below:
14- Read ringtone information
15- Set and remove customized ringtone
16- Read ringtone list, include system ringtone and customized ringtone
17- Scan the system prebuilt ringtone directories
18
19## Directory Structure<a name="section161941989596"></a>
20The structure of the repository directory is as follows:
21```
22/foundation/multimedia/ringtone_library/ # RingtoneLibrary code
23├── frameworks # Framework code
24├── interfaces # API implementation
25│ └── inner_api # Internal Native API implementation
26├── LICENSE # License file
27├── services # RingtoneLibrary function implementation
28│ ├── ringtone_backup # RingtoneLibrary backup implementation
29│ ├── ringtone_data_extension # DatashareExtension implementation
30│ ├── ringtone_dfx # DFX implementation
31│ ├── ringtone_helper # Helper class
32│ └── ringtone_scanner # Scanner implementation
33└── test # Test code
34```
35
36## Repositories Involved<a name="section1533973044317"></a>
37**[multimedia/ringtone_library](https://gitee.com/openharmony/multimedia_ringtone_library)**
38
README_zh.md
1# RingtoneLibrary组件
2
3- [简介](#section1158716411637)
4- [目录](#section161941989596)
5- [使用说明](#usage-guidelines)
6- [相关仓](#section1533973044317)
7
8## 简介<a name="section1158716411637"></a>
9**ringtone\_library** 仓库提供了一系列易用的接口用于设定及获取系统铃音信息。
10**ringtone\_library** 提供了标准DataShareExtension接口，支持存储及查询通过SystemSoundManager设置的自定义来电/闹钟/短信/系统通知铃音文件。
11系统应用及音乐开放能力RingtoneKit通过SystemSoundManager设置及查询自定义铃音，非系统应用通过音乐开放能力RingtoneKit设置及查询自定义铃音。
12
13**图1** ringtonelibrary组件架构图
14
15
16支持能力列举如下：
17- 读取铃音内容
18- 存储和删除自定义铃音
19- 读取铃音列表，包含系统铃音和自定义铃音
20- 扫描系统预制铃音目录
21
22## 目录<a name="section161941989596"></a>
23仓库目录结构如下：
24```
25/foundation/multimedia/ringtone_library/ # 铃音库组件代码
26├── frameworks # 框架代码
27├── interfaces # 接口代码
28│ └── inner_api # 内部native接口
29├── LICENSE # 证书文件
30├── services # 铃音库服务实现
31│ ├── ringtone_backup # 铃音库备份升级服务
32│ ├── ringtone_data_extension # 扩展插件接口
33│ ├── ringtone_dfx # DFX实现
34│ ├── ringtone_helper # 辅助类
35│ └── ringtone_scanner # 扫描功能实现
36└── test # 测试代码
37```
38
39## 使用说明<a name="usage-guidelines"></a>
40### 概述
41提供铃音列表的增、删、改、查等接口，可以通过Uri("datashare:///ringtone/ringtone")对铃音列表进行操作。
42接口参数主要有对象类型的Uri、DataSharePredicates和DataShareValuesBucket等。
43
44使用接口功能前，需要先获取DataShareHelper
45```cpp
46auto saManager = SystemAbilityManagerClient::GetInstance().GetSystemAbilityManager();
47auto remoteObj = saManager->GetSystemAbility(systemAbilityId);
48std::shared_ptr<DataShare::DataShareHelper> datashareHelper = DataShare::DataShareHelper::Creator(remoteObj, "datashare:///ringtone/ringtone");
49```
50
51### 新增铃音接口
52#### datashareHelper->Insert(const Uri &uri, const DataShareValuesBucket &value);
53
54- 参数描述
55
56 | 名称 | 读写属性 | 类型 | 必填 | 描述 |
57 | -------- | -------- | ---------------------- | ---- | ------------------------------ |
58 | uri | 只读 | Uri& | 是 | 铃音库操作Uri("datashare:///ringtone/ringtone") |
59 | value | 只读 | DataShareValuesBucket& | 是 | 数据库字段key-value对象 |
60
61- 返回值
62
63 来电铃音id
64
65- 示例
66 ```cpp
67 Uri ringtoneUri("datashare:///ringtone/ringtone");
68 int32_t index = 0;
69 const int32_t count = 10;
70 const int64_t ringtoneSize = 1022;
71 const int type = 2;
72 const int64_t addedTime = 1559276453;
73 const int64_t modifiedTime = 1559276455;
74 const int64_t takenTime = 1559276457;
75 const int durationTime = 112;
76 DataShareValuesBucket valuesBucket;
77 valuesBucket.Put(RINGTONE_COLUMN_DATA,
78 static_cast<string>("/path_to_target/test_ringtone.ogg"));
79 valuesBucket.Put(RINGTONE_COLUMN_SIZE, static_cast<int64_t>(ringtoneSize));
80 valuesBucket.Put(RINGTONE_COLUMN_DISPLAY_NAME, static_cast<string>("test_ringtone.ogg");
81 valuesBucket.Put(RINGTONE_COLUMN_TITLE, static_cast<string>("test_ringtone"));
82 valuesBucket.Put(RINGTONE_COLUMN_MEDIA_TYPE, static_cast<int>(type));
83 valuesBucket.Put(RINGTONE_COLUMN_TONE_TYPE, static_cast<int>(type));
84 valuesBucket.Put(RINGTONE_COLUMN_MIME_TYPE, static_cast<string>("ogg"));
85 valuesBucket.Put(RINGTONE_COLUMN_SOURCE_TYPE, static_cast<int>(1));
86 valuesBucket.Put(RINGTONE_COLUMN_DATE_ADDED, static_cast<int64_t>(addedTime));
87 valuesBucket.Put(RINGTONE_COLUMN_DATE_MODIFIED, static_cast<int64_t>(modifiedTime));
88 valuesBucket.Put(RINGTONE_COLUMN_DATE_TAKEN, static_cast<int64_t>(takenTime));
89 valuesBucket.Put(RINGTONE_COLUMN_DURATION, static_cast<int>(durationTime));
90 valuesBucket.Put(RINGTONE_COLUMN_SHOT_TONE_TYPE, static_cast<int>(1));
91 valuesBucket.Put(RINGTONE_COLUMN_SHOT_TONE_SOURCE_TYPE, static_cast<int>(type));
92 valuesBucket.Put(RINGTONE_COLUMN_NOTIFICATION_TONE_TYPE, static_cast<int>(1));
93 valuesBucket.Put(RINGTONE_COLUMN_NOTIFICATION_TONE_SOURCE_TYPE, static_cast<int>(type));
94 valuesBucket.Put(RINGTONE_COLUMN_RING_TONE_TYPE, static_cast<int>(1));
95 valuesBucket.Put(RINGTONE_COLUMN_RING_TONE_SOURCE_TYPE, static_cast<int>(type));
96 valuesBucket.Put(RINGTONE_COLUMN_ALARM_TONE_TYPE, static_cast<int>(1));
97 valuesBucket.Put(RINGTONE_COLUMN_ALARM_TONE_SOURCE_TYPE, static_cast<int>(type));
98 int32_t ret = dataShareHelper->Insert(ringtoneUri, valuesBucket);
99 ```
100
101### 删除铃音接口
102#### datashareHelper->Delete(const Uri &uri, const DataSharePredicates &predicates);
103
104- Delete参数描述
105
106 | 名称 | 读写属性 | 类型 | 必填 | 描述 |
107 | -------- | -------- | ---------------------- | ---- | ------------------------------ |
108 | uri | 只读 | Uri& | 是 | 铃音库操作Uri("datashare:///ringtone/ringtone") |
109 | condition | 只读 | DataSharePredicates& | 是 | 数据库删除条件 |
110
111- 返回值
112
113 删除的铃音数量
114
115- 示例
116
117 ```cpp
118 Uri ringtoneUri("datashare:///ringtone/ringtone");
119 DataShare::DataSharePredicates deletePredicates;
120 deletePredicates.SetWhereClause(RINGTONE_COLUMN_TONE_ID + " = ? ");
121 deletePredicates.SetWhereArgs({ to_string(1) });
122 int32_t ret = g_dataShareHelper->Delete(ringtoneUri, deletePredicates);
123 ```
124
125### 修改铃音接口
126#### datashareHelper->Update(const Uri &uri, const DataSharePredicates &predicates, const DataShareValuesBucket &value);
127
128- Update参数描述
129
130 | 名称 | 读写属性 | 类型 | 必填 | 描述 |
131 | -------- | -------- | ---------------------- | ---- | ------------------------------ |
132 | uri | 只读 | Uri& | 是 | 具体操作的uri |
133 | condition | 只读 | DataSharePredicates& | 是 | 数据库更新条件 |
134 | value | 只读 | DataShareValuesBucket& | 是 | 数据库字段key-value对象 |
135
136- 返回值
137
138 修改的铃音数量
139
140- 示例
141 ```cpp
142 Uri ringtoneUri("datashare:///ringtone/ringtone");
143 DataShare::DataSharePredicates updatePredicates;
144 updatePredicates.SetWhereClause(RINGTONE_COLUMN_TONE_ID + " = ? ");
145 updatePredicates.SetWhereArgs({ to_string(1) });
146 DataShareValuesBucket updateValuesBucket;
147 updateValuesBucket.Put(RINGTONE_COLUMN_SHOT_TONE_TYPE, 0);
148 updateValuesBucket.Put(RINGTONE_COLUMN_SHOT_TONE_SOURCE_TYPE, 0);
149 int32_t ret = dataShareHelper->Update(ringtoneUri, deletePredicates, updateValuesBucket);
150 ```
151
152### 查询铃音接口
153#### datashareHelper->Query(const Uri &uri, const DataSharePredicates &predicates, std::vector<std::string> &columns, DatashareBusinessError &businessError);
154
155- Query参数描述
156
157 | 名称 | 读写属性 | 类型 | 必填 | 描述 |
158 | -------- | -------- | ---------------------- | ---- | ------------------------------ |
159 | uri | 只读 | Uri& | 是 | 铃音库操作Uri("datashare:///ringtone/ringtone") |
160 | condition | 只读 | DataSharePredicates& | 是 | 查询条件 |
161 | resultColumns | 只读 | std::vector<std::string>& | 是 | 需要查询的列字段名称 |
162 | businessError | 只读 | DatashareBusinessError& | 是 | 异常代码 |
163
164- 返回值
165 数据库ResultSet结果集
166
167- 示例
168 ```cpp
169 Uri ringtoneUri("datashare:///ringtone/ringtone");
170 int errCode = 0;
171 DatashareBusinessError businessError;
172 DataSharePredicates queryPredicates;
173 queryPredicates.EqualTo(RINGTONE_COLUMN_SHOT_TONE_TYPE, to_string(1));
174 vector<string> columns = {
175 { RINGTONE_COLUMN_TONE_ID },
176 { RINGTONE_COLUMN_DISPLAY_NAME },
177 { RINGTONE_COLUMN_DATE_ADDED },
178 { RINGTONE_COLUMN_SHOT_TONE_TYPE }
179 };
180 auto resultSet = dataShareHelper->Query(ringtoneUri, queryPredicates, columns, &businessError);
181 ```
182### RingtoneLibrary数据库表结构
183|字段名|类型|描述|
184|---|---|---|
185|ringtone_id|INTEGER|主键，数据库自增|
186|data|TEXT|铃音文件存储路径|
187|size|BITINT|铃音文件大小|
188|display_name|TEXT|title+后缀|
189|title|TEXT|铃音名称|
190|media_type|TEXT|媒体类型，音频类为2|
191|tone_type|INTEGER|ALARM = 0, RINGTONE = 1, NOTIFICATION = 2, NOTIFICATION可以设置为短信和通知|
192|mime_type|TEXT|UTI类型|
193|source_type|INTEGER|系统预制(1)，用户自定义(2)|
194|date_added|BIGINT|时间戳，添加时间|
195|date_modified|BIGINT|时间戳，修改时间|
196|date_taken|BIGINT|时间戳，创建时间|
197|duration|INTEGER|时长，毫秒值|
198|shot_tone_type|INTEGER|短信铃音类型： 非短信音(0)，卡1短信音(1)，卡2短信音(2)，双卡短信音(3)|
199|shot_tone_source_type|INTEGER|系统设置(1)，用户设置(2)|
200|notification_tone_type|INTEGER|通知音铃音类型： 非通知音(0)，通知音(1)|
201|notification_tone_source_type|INTEGER|系统设置(1)，用户设置(2)|
202|ring_tone_type|INTEGER|通话铃音类型： 非通话铃音(0)，卡1铃音(1)，卡2铃音(2)，双卡铃音(3)|
203|ring_tone_source_type|INTEGER|系统设置(1)，用户设置(2)|
204|alarm_tone_type|INTEGER|闹钟铃音类型： 非闹钟铃音(0)，闹钟铃音(1)|
205|alarm_tone_source_type|INTEGER|系统设置(1)，用户设置(2)|
206
207
208## 相关仓<a name="section1533973044317"></a>
209**[multimedia/ringtone_library](https://gitee.com/openharmony/multimedia_ringtone_library)**
210**[multimedia/player_framework](https://gitee.com/openharmony/multimedia_player_framework)**
211
