README.md
1# Data Storage<a name="EN-US_TOPIC_0000001152064139"></a>
2
3- [Introduction](#section117mcpsimp)
4- [Directory Structure](#section124mcpsimp)
5- [Constraints](#section128mcpsimp)
6- [Usage](#section134mcpsimp)
7 - [Available APIs](#section136mcpsimp)
8 - [Permissions]( #section137mcpsimp)
9
10- [Usage Guidelines](#section163mcpsimp)
11 - [Parameters of the Insert API](#section1099113151207)
12 - [Parameters of the Delete API](#section1098113151208)
13 - [Parameters of the Update API](#section1099113151207)
14 - [Parameters of the Query API](#section1096113151208)
15 - [Sample Code](#section1558565082915)
16
17- [Repositories Involved](#section206mcpsimp)
18
19## Introduction<a name="section117mcpsimp"></a>
20
21The data storage module stores persistent data of key modules of the Telephony subsystem, such as the SIM cards and SMS modules, and provides the **DataShare** API for data access.
22
23**Figure 1** Architecture of the data storage module<a name="fig13267152558"></a>
24
25
26
27## Directory Structure<a name="section124mcpsimp"></a>
28
29```
30/base/telephony/data_storage # Data storage
31├─ BUILD.gn # Build script (gn)
32├─ README.md # Readme
33├─ common # Public and common files
34│ ├─ include
35│ └─ src
36├─ opkey # opkey framework
37│ ├─ include
38│ └─ src
39├─ pdp_profile # Network carrier
40│ ├─ include
41│ └─ src
42├─ sim # SIM card
43│ ├─ include
44│ └─ src
45├─ sms_mms # SMS/MMS
46│ ├─ include
47│ └─ src
48├─ ohos.build # Build code
49└─ test # Test code
50```
51
52## Constraints<a name="section128mcpsimp"></a>
53
54- Programming language: C++
55
56- Software constraints: This module must work with the Utils and Application Framework subsystems.
57
58- Hardware constraints: none
59
60- Use case: When a user needs to edit the persistent data stored in Telephony subsystem modules, such as the SIM card and SMS/MMS modules, your application can call the **Insert**, **Delete**, **Update**, and **Query** APIs provided by **DataShareHelper** as demanded.
61
62 You need to declare the corresponding permission for access to the specified URI.
63
64## Usage<a name="section134mcpsimp"></a>
65
66### Available APIs<a name="section136mcpsimp"></a>
67
68**Table 1** APIs provided by DataShareHelper
69
70<a name="table165976561598"></a>
71
72| API Definition | **Description**|
73| ------------------------------------------------------------ | ------------ |
74| int Insert(Uri &uri, const DataShare::DataShareValuesBucket &value) | Inserts data. |
75| int Delete(const Uri &uri, const DataShare::DataSharePredicates &predicates) | Deletes data. |
76| int Update(Uri &uri, const DataSharePredicates &predicates, const DataShareValuesBucket &value) | Updates data. |
77| std::shared_ptr\<DataShare::DataShareResultSet\> Query(Uri &uri, const DataSharePredicates &predicates, std::vector\<std::string\> &columns) | Queries data. |
78
79**Table 2** Required permissions
80
81<a name="table165976561598"></a>
82
83| Module | **Required Permission** |
84| -------------- | ------------------------------------------------------------ |
85| SMS/MMS module | ohos.permission.READ_MESSAGES |
86| SIM card module | ohos.permission.GET_TELEPHONY_STATE<br>ohos.permission.SET_TELEPHONY_STATE |
87| Network carrier module| ohos.permission.GET_TELEPHONY_STATE<br>ohos.permission.SET_TELEPHONY_STATE |
88| opkey module| ohos.permission.GET_TELEPHONY_STATE<br>ohos.permission.SET_TELEPHONY_STATE |
89
90## Usage Guidelines<a name="section163mcpsimp"></a>
91
92### Parameters of the Insert API<a name="section1099113151207"></a>
93
94**Table 3** Parameters of the Insert API
95
96<a name="table1234838197"></a>
97
98| Parameter | **Description** |
99| ----- | ------------------------------------- |
100| uri | Resource path. |
101| value | Data set. This field corresponds to the table structure field on which the current operation is performed.|
102
103### Parameters of the Delete API<a name="section1098113151208"></a>
104
105**Table 4** Parameters of the Delete API
106
107<a name="table1234838197"></a>
108
109| Parameter | Description |
110| ---------- | ------------------------------------- |
111| uri | Resource path. |
112| predicates | Conditions for data deletion. |
113
114### Parameters of the Update API<a name="section1097113151210"></a>
115
116**Table 5** Parameters of the Update API
117
118<a name="table1234838197"></a>
119
120| Parameter | Description |
121| ---------- | -------- |
122| uri | Resource path.|
123| predicates | Conditions for data updating.|
124| value | Data set. This field corresponds to the table structure field on which the current operation is performed.|
125
126### Parameters of the Query API<a name="section1096113151208"></a>
127
128**Table 6** Parameters of the Query API
129
130<a name="table1234838197"></a>
131
132| Parameter | Description |
133| ---------- | -------------- |
134| uri | Resource path. |
135| predicates | Conditions for data query. |
136| columns | Fields in the query result.|
137
138### Sample Code<a name="section1558565082915"></a>
139
140The following provides the procedure and sample code for you to query, insert, delete, or update SMS/MMS data:
141
1421. Call **SystemAbilityManagerClient** to obtain a **SystemAbilityManager** object.
1432. Call **saManager** to obtain an **IRemoteObject** object based on the specified service ID.
1443. Call **IRemoteObject** to create a **DataShareHelper** object.
1454. Call **DataShareHelper::Query** to query data, and call the other related APIs to process data.
146
147 Sample code for creating a **DataShareHelper** instance:
148 ```
149 std::shared_ptr<DataShare::DataShareHelper> DataStorageGtest::CreateDataShareHelper(
150 int32_t systemAbilityId, std::string &uri)
151 {
152 // Obtain a SystemAbilityManager instance through SystemAbilityManagerClient.
153 auto saManager = SystemAbilityManagerClient::GetInstance().GetSystemAbilityManager();
154 if (saManager == nullptr) {
155 DATA_STORAGE_LOGE("DataSimRdbHelper Get system ability mgr failed.");
156 return nullptr;
157 }
158 // Obtain an IRemoteObject.
159 auto remoteObj = saManager->GetSystemAbility(systemAbilityId);
160 while (remoteObj == nullptr) {
161 DATA_STORAGE_LOGE("DataSimRdbHelper GetSystemAbility Service Failed.");
162 return nullptr;
163 }
164 // Create a DataShareHelper instance.
165 return DataShare::DataShareHelper::Creator(remoteObj, uri);
166 }
167 ```
168 Sample code for querying SMS/MMS messages:
169 ```
170 std::shared_ptr<DataShare::DataShareResultSet> DataStorageGtest::SmsSelect(const std::shared_ptr<DataShare::DataShareHelper> &helper)
171 {
172 // Resource path
173 Uri uri("datashare:///com.ohos.smsmmsability/sms_mms/sms_mms_info");
174 // Fields in the query result
175 std::vector<std::string> columns;
176 // Phone number of the message sender
177 columns.push_back("sender_number");
178 // Message title
179 columns.push_back("msg_title");
180 // Message content
181 columns.push_back("msg_content");
182 // Query predicates
183 DataShare::DataSharePredicates predicates;
184 // Call the DataShareHelper::Query API to query data.
185 return helper->Query(uri, predicates, columns);
186 }
187 ```
188 Sample code for inserting SMS/MMS messages:
189 ```
190 int SmsInsert(std::shared_ptr<DataShare::DataShareHelper> &helper)
191 {
192 Uri uri("datashare:///com.ohos.smsmmsability/sms_mms/sms_mms_info");
193 DataShare::DataShareValuesBucket value;
194 // Phone number of the message recipient
195 value.Put(SmsMmsInfo::RECEIVER_NUMBER, "138XXXXXXXX");
196 // Message content
197 value.Put(SmsMmsInfo::MSG_CONTENT, "ceshi");
198 value.Put(SmsMmsInfo::GROUP_ID, 1);
199 return helper->Insert(uri, value);
200 }
201 ```
202 Sample code for deleting SMS/MMS messages:
203 ```
204 int SmsDelete(std::shared_ptr<DataShare::DataShareHelper> helper)
205 {
206 Uri uri("datashare:///com.ohos.smsmmsability/sms_mms/sms_mms_info");
207 DataShare::DataSharePredicates predicates;
208 // Delete the message whose MSG_ID is 1.
209 predicates.EqualTo(SmsMmsInfo::MSG_ID, "1");
210 return helper->Delete(uri, predicates);
211 }
212 ```
213 Sample code for updating SMS/MMS messages:
214 ```
215 int SmsUpdate(std::shared_ptr<DataShare::DataShareHelper> helper)
216 {
217 Uri uri("datashare:///com.ohos.smsmmsability/sms_mms/sms_mms_info");
218 DataShare::DataShareValuesBucket values;
219 // Message content
220 values.Put(SmsMmsInfo::MSG_CONTENT, "hi ohos");
221 DataShare::DataSharePredicates predicates;
222 // Message ID
223 predicates.EqualTo(SmsMmsInfo::MSG_ID, "1");
224 return helper->Update(uri, predicates, values);
225 }
226 ```
227
228
229## Repositories Involved<a name="section206mcpsimp"></a>
230
231[Telephony Subsystem](https://gitee.com/openharmony/docs/blob/master/en/readme/telephony.md)
232
233**telephony_data_storage**
234
235[telephony_core_service](https://gitee.com/openharmony/telephony_core_service/blob/master/README.md)
236
237[telephony_sms_mms](https://gitee.com/openharmony/telephony_sms_mms/blob/master/README.md)
238
239[telephony_cellular_call](https://gitee.com/openharmony/telephony_cellular_call/blob/master/README.md)
240
241[telephony_call_manager](https://gitee.com/openharmony/telephony_call_manager/blob/master/README.md)
242
