1# UDMF开发指导（C/C++）
2
3
4## 场景介绍
5
6统一数据管理框架（UDMF）：提供了数据跨应用、跨设备交互标准，定义了跨应用、跨设备数据交互过程中的数据语言，提升数据交互效率。提供安全、标准化数据流通通路，支持不同级别的数据访问权限与生命周期管理策略，实现高效的数据跨应用、跨设备共享。
7
8
9## 基本概念
10
11- **标准化数据类型**：Uniform Type Descriptor，简称UTD。主要针对同一种数据类型，提供统一定义，即标准数据类型描述符，定义了包括标识数据类型的ID、类型归属关系等相关信息，用于解决OpenHarmony系统中的类型模糊问题。一般用于过滤或者识别某一种数据类型的场景，比如文件预览、文件分享等。
12
13- **标准化数据结构**：Unified Data Structure，简称UDS。主要针对部分标准化数据类型定义了统一的数据内容结构，并明确了对应的描述信息。应用间使用标准化数据结构进行数据交互后，将遵从统一的解析标准，可有效减少适配相关的工作量。一般用于跨应用跨设备间的数据交互，比如拖拽。
14
15- **统一数据记录**： Unified Record，对UDMF支持的数据内容的抽象定义，例如一条文本记录、一条图片记录等。
16
17- **统一数据对象**： Unified Data，用于封装一组数据记录Unified Record。
18
19- **统一数据提供者**: Unified Data Provider，配置到统一数据记录中，用来提供UDS数据。通常用于数据的延迟发送场景，让UDS数据在数据使用方从统一数据记录中实际获取时才发生数据的转移。
20
21
22## 约束限制
23
24- UDMF支持批量数据记录的分组管理，每个分组整体大小不超过200MB，其中PlainText、Hyperlink、HTML内单个属性值数据上限20MB。
25- 向统一数据记录中添加用户自定义数据时，所添加的数据大小不超过100MB。
26- 向UDMF数据库中写入数据时，定义的唯一标识符的内存大小不小于512字节。
27
28
29
30## 接口说明
31
32详细的接口说明请参考[UDMF接口文档](../reference/apis-arkdata/_u_d_m_f.md)。
33
34| 接口名称                                                     | 描述                                                        |
35| ------------------------------------------------------------ | ----------------------------------------------------------- |
36| OH_Utd* OH_Utd_Create(const char* typeId)                    | 创建一个指向统一数据类型描述符OH_Utd的指针。                |
37| void OH_Utd_Destroy(OH_Utd* pThis)                           | 销毁指向统一数据类型描述符OH_Utd的指针。                    |
38| const char** OH_Utd_GetTypesByFilenameExtension(const char* extension, unsigned int* count) | 通过文件后缀名获取标准化数据类型ID。                        |
39| const char** OH_Utd_GetTypesByMimeType(const char* mimeType, unsigned int* count) | 通过MIME类型获取标准化数据类型ID。                          |
40| bool OH_Utd_Equals(OH_Utd* utd1, OH_Utd* utd2)               | 判断两种标准化数据类型是否相等。                            |
41| void OH_Utd_DestroyStringList(const char** list, unsigned int count) | 销毁字符串列表数据。                                        |
42| OH_UdsHyperlink* OH_UdsHyperlink_Create()                    | 创建一个指向标准化数据结构超链接类型OH_UdsHyperlink的指针。 |
43| void OH_UdsHyperlink_Destroy(OH_UdsHyperlink* pThis)         | 销毁指向标准化数据结构超链接类型OH_UdsHyperlink的指针。     |
44| const char* OH_UdsHyperlink_GetType(OH_UdsHyperlink* pThis)  | 获取OH_UdsHyperlink中的标准化数据类型ID。                   |
45| const char* OH_UdsHyperlink_GetUrl(OH_UdsHyperlink* pThis)   | 获取OH_UdsHyperlink中的链接URL。                            |
46| const char* OH_UdsHyperlink_GetDescription(OH_UdsHyperlink* pThis) | 获取OH_UdsHyperlink中的链接内容描述。                       |
47| int OH_UdsHyperlink_SetUrl(OH_UdsHyperlink* pThis, const char* url) | 设置OH_UdsHyperlink中的链接URL。                            |
48| int OH_UdsHyperlink_SetDescription(OH_UdsHyperlink* pThis, const char* description) | 设置OH_UdsHyperlink中的链接内容描述。                       |
49| OH_UdmfData* OH_UdmfData_Create()                            | 创建一个指向统一数据对象OH_UdmfData的指针。                 |
50| void OH_UdmfData_Destroy(OH_UdmfData* pThis)                 | 销毁指向统一数据对象OH_UdmfData的指针。                     |
51| int OH_UdmfData_AddRecord(OH_UdmfData* pThis, OH_UdmfRecord* record) | 向OH_UdmfData中增加一条OH_UdmfRecord数据记录。              |
52| bool OH_UdmfData_HasType(OH_UdmfData* pThis, const char* type) | 判断统一数据对象OH_UdmfData是否存在指定类型。               |
53| OH_UdmfRecord** OH_UdmfData_GetRecords(OH_UdmfData* pThis, unsigned int* count) | 获取OH_UdmfData中全部的数据记录。                           |
54| OH_UdmfRecord* OH_UdmfRecord_Create()                        | 创建一个指向统一数据记录OH_UdmfRecord的指针。               |
55| void OH_UdmfRecord_Destroy(OH_UdmfRecord* pThis)             | 销毁指向统一数据记录OH_UdmfRecord的指针。                   |
56| int OH_UdmfRecord_AddHyperlink(OH_UdmfRecord* pThis, OH_UdsHyperlink* hyperlink) | 向OH_UdmfRecord添加超链接类型数据。                         |
57| char** OH_UdmfRecord_GetTypes(OH_UdmfRecord* pThis, unsigned int* count) | 获取OH_UdmfRecord中全部的数据类型。                         |
58| int OH_UdmfRecord_GetHyperlink(OH_UdmfRecord* pThis, OH_UdsHyperlink* hyperlink) | 获取OH_UdmfRecord中超链接类型数据。                         |
59| int OH_Udmf_GetUnifiedData(const char* key, Udmf_Intention intention, OH_UdmfData* unifiedData) | 从UDMF数据库中获取数据。                                    |
60| int OH_Udmf_SetUnifiedData(Udmf_Intention intention, OH_UdmfData* unifiedData, char* key, unsigned int keyLen) | 向UDMF数据库中写入数据。                                    |
61| OH_UdmfRecordProvider* OH_UdmfRecordProvider_Create()        | 创建一个指向统一数据提供者的指针。                          |
62| int OH_UdmfRecordProvider_SetData(OH_UdmfRecordProvider* provider, void* context, const OH_UdmfRecordProvider_GetData callback, const UdmfData_Finalize finalize) | 设置统一数据提供者的回调函数。                              |
63| int OH_UdmfRecord_SetProvider(OH_UdmfRecord* pThis, const char* const* types, unsigned int count, OH_UdmfRecordProvider* provider) | 将统一数据提供者配置到OH_UdmfRecord中。                     |
64
65
66## 添加动态链接库
67
68CMakeLists.txt中添加以下lib。
69
70```txt
71libudmf.so
72```
73
74## 引用头文件
75
76```c
77#include <cstdio>
78#include <cstring>
79#include <database/udmf/utd.h>
80#include <database/udmf/uds.h>
81#include <database/udmf/udmf.h>
82#include <database/udmf/udmf_meta.h>
83#include <database/udmf/udmf_err_code.h>
84```
85## 通过不同方式获取纯文本类型数据
86
87下面以获取纯文本数据的查询场景为例，说明如何使用UTD。
881. 通过后缀名“.txt”获取UTD的typeId。
892. 通过MIME类型“text/plain”获取UTD的typeId。
903. 使用以上两个步骤获取到的typeId创建UTD实例对象。
914. 比较UTD实例对象是否相等。
925. 使用结束后，删除上述步骤中产生的指针。
93
94```c
95// 1. 通过文件后缀名获取纯文本类型的UTD的typeId
96unsigned int typeIds1Count = 0;
97const char** typeIds1 = OH_Utd_GetTypesByFilenameExtension(".txt", &typeIds1Count);
98printf("the count of typeIds1 is %u", typeIds1Count);
99// 2. 通过MIME类型获取typeId
100unsigned int typeIds2Count = 0;
101const char** typeIds2 = OH_Utd_GetTypesByMimeType("text/plain", &typeIds2Count);
102printf("the count of typeIds2 is %u", typeIds2Count);
103// 3. 使用以上两个步骤获取到的typeId创建UTD实例对象。
104OH_Utd* utd1 = OH_Utd_Create(typeIds1[0]);
105OH_Utd* utd2 = OH_Utd_Create(typeIds2[0]);
106// 4. 比较两种方式获取到的typeId对应的UTD是否相同
107bool isEquals = OH_Utd_Equals(utd1, utd2);
108if (isEquals) {
109    printf("utd1 == utd2");
110} else {
111    printf("utd1 != utd2");
112}
113// 5. 销毁OH_Utd_GetTypesByFilenameExtension与OH_Utd_GetFilenameExtensions函数获取到的指针，同时销毁UTD指针
114OH_Utd_DestroyStringList(typeIds1, typeIds1Count);
115OH_Utd_DestroyStringList(typeIds2, typeIds2Count);
116OH_Utd_Destroy(utd1);
117OH_Utd_Destroy(utd2);
118```
119
120## 使用UDMF发送UDS数据
121
122下面以发送超链接hyperlink类型数据场景为例，说明如何使用UDS与UDMF。
1231. 创建超链接hyperlink数据的UDS数据结构。
1242. 设置hyperlink中的URL和描述信息。
1253. 将hyperlink数据放入数据记录OH_UdmfRecord中。
1264. 将数据记录OH_UdmfRecord添加到统一数据OH_UdmfData中。
1275. 保存以上数据至数据库中，得到返回的key值。
1286. 使用结束后，删除上述步骤中产生的指针。
129
130```c
131// 1. 创建超链接hyperlink数据的UDS数据结构。
132OH_UdsHyperlink* hyperlink = OH_UdsHyperlink_Create();
133// 2. 设置hyperlink中的URL和描述信息。
134if (OH_UdsHyperlink_SetUrl(hyperlink, "www.demo.com") != Udmf_ErrCode::UDMF_E_OK) {
135    printf("Hyperlink set url error!");
136}
137if (OH_UdsHyperlink_SetDescription(hyperlink, "This is the description.") != Udmf_ErrCode::UDMF_E_OK) {
138    printf("Hyperlink set description error!");
139}
140// 3. 创建OH_UdmfRecord对象，并向OH_UdmfRecord中添加超链接类型数据。
141OH_UdmfRecord* record = OH_UdmfRecord_Create();
142if (OH_UdmfRecord_AddHyperlink(record, hyperlink) != Udmf_ErrCode::UDMF_E_OK) {
143    printf("Add hyperlink to record error!");
144}
145// 4. 创建OH_UdmfData对象，并向OH_UdmfData中添加OH_UdmfRecord。
146OH_UdmfData* data = OH_UdmfData_Create();
147if (OH_UdmfData_AddRecord(data, record) != Udmf_ErrCode::UDMF_E_OK) {
148    printf("Add record to data error!");
149}
150// 5. 构建数据，将数据写入数据库中，得到返回的key值。
151char key[UDMF_KEY_BUFFER_LEN] = {0};
152if (OH_Udmf_SetUnifiedData(Udmf_Intention::UDMF_INTENTION_DRAG, data, key, sizeof(key)) != Udmf_ErrCode::UDMF_E_OK) {
153    printf("Set data error!");
154}
155printf("key = %s", key);
156// 6. 使用完成后销毁指针。
157OH_UdsHyperlink_Destroy(hyperlink);
158OH_UdmfRecord_Destroy(record);
159OH_UdmfData_Destroy(data);
160```
161
162## 使用UDMF接收UDS数据
163
164下面继续以获取超链接hyperlink类型数据场景为例，说明如何使用UDS与UDMF。
1651. 创建统一数据OH_UdmfData，用来承载数据库中读取的数据。
1662. 通过key值从数据库中获取到数据。
1673. 判断数据中是否有hyperlink类型的数据。
1684. 获取OH_UdmfData中的数据记录，并从数据记录中获取hyperlink数据。
1695. 读取hyperlink数据中的各项信息。
1706. 使用结束后，删除上述步骤中产生的指针。
171
172```c
173// 1. 创建统一数据OH_UdmfData。
174OH_UdmfData* readData = OH_UdmfData_Create();
175// 此处key为示例，不可直接使用，其值应与OH_Udmf_SetUnifiedData接口中获取到的key值保持一致。
176char key[] = {"udmf://Drag/com.ohos.test/0123456789"};
177// 2. 通过key值从数据库中获取到数据。
178if (OH_Udmf_GetUnifiedData(key, Udmf_Intention::UDMF_INTENTION_DRAG, readData) != Udmf_ErrCode::UDMF_E_OK) {
179    printf("Failed to get data.");
180    return;
181}
182// 3. 判断OH_UdmfData是否有对应的类型。
183if (!OH_UdmfData_HasType(readData, UDMF_META_HYPERLINK)) {
184    printf("There is no hyperlink type in data.");
185    return;
186}
187// 4. 获取数据记录和hyperlink数据。
188unsigned int recordsCount = 0;
189OH_UdmfRecord** records = OH_UdmfData_GetRecords(readData, &recordsCount);
190printf("the count of records count is %u", recordsCount);
191// 创建hyperlink的UDS，用来承载record中读取出来的hyperlink数据。
192OH_UdsHyperlink* hyperlink = OH_UdsHyperlink_Create();
193// 获取records中的元素。
194for (int i = 0; i < recordsCount; i++) {
195    // 获取OH_UdmfRecord类型列表。
196    unsigned int recordTypeIdCount = 0;
197    char** typeIdsFromRecord = OH_UdmfRecord_GetTypes(records[i], &recordTypeIdCount);
198    for (unsigned int j = 0; j < recordTypeIdCount; j++) {
199        // 从OH_UdmfRecord中获取超链接类型数据。
200        if (strcmp(typeIdsFromRecord[j], UDMF_META_HYPERLINK) == 0) {
201            // 获取hyperlink数据。
202            if (OH_UdmfRecord_GetHyperlink(records[i], hyperlink) != Udmf_ErrCode::UDMF_E_OK) {
203                printf("Fail get hyperlink from record!");
204            }
205        }
206    }
207}
208// 5. 读取OH_UdsHyperlink中的各项信息。
209printf("The hyperlink type id is : %s", OH_UdsHyperlink_GetType(hyperlink));
210printf("The hyperlink url is : %s", OH_UdsHyperlink_GetUrl(hyperlink));
211printf("The hyperlink description is : %s", OH_UdsHyperlink_GetDescription(hyperlink));
212// 6. 销毁指针。
213OH_UdsHyperlink_Destroy(hyperlink);
214OH_UdmfData_Destroy(readData);
215```
216
217## 使用UDMF延迟发送UDS数据
218
219### 定义UDS数据提供函数
220
221下面以超链接hyperlink类型数据场景为例，说明如何定义一个提供UDS数据的回调函数。
2221. 定义OH_UdmfRecordProvider的数据提供函数。
2232. 在数据提供函数中，创建hyperlink类型的UDS数据结构。
2243. 设置hyperlink中的URL和描述信息。
2254. 定义OH_UdmfRecordProvider实例注销回调函数。
226
227```c
228// 为了代码可读性，代码中省略了各个步骤操作结果的校验，实际开发中需要确认每次调用的成功。
229// 1. 获取数据时触发的提供UDS数据的回调函数。
230static void* GetDataCallback(void* context, const char* type) {
231    if (strcmp(type, UDMF_META_PLAIN_TEXT)) {
232        // 2. 创建超链接hyperlink数据的UDS数据结构。
233        OH_UdsHyperlink* hyperlink = OH_UdsHyperlink_Create();
234        // 3. 设置hyperlink中的URL和描述信息。
235        OH_UdsHyperlink_SetUrl(hyperlink, "www.demo.com");
236        OH_UdsHyperlink_SetDescription(hyperlink, "This is the description.");
237        return hyperlink;
238    }
239    return nullptr;
240}
241// 4. OH_UdmfRecordProvider销毁时触发的回调函数。
242static void ProviderFinalizeCallback(void* context) { printf("OH_UdmfRecordProvider finalize."); }
243```
244
245### 延迟发送UDS数据
246
247下面以延迟发送超链接hyperlink类型数据场景为例，说明如何使用OH_UdmfRecordProvider与UDMF。需要注意，此步骤完成后超链接类型数据并未真正写入数据库，只有当数据使用者从OH_UdmfRecord中获取OH_UdsHyperlink时，才会触发上文定义的`GetDataCallback`数据提供函数，从中得到数据。
248
2491. 创建一个OH_UdmfRecordProvider，并设置它的数据提供函数和销毁时的回调函数。
2502. 创建一个OH_UdmfRecord对象，并将OH_UdmfRecordProvider配置到其中。
2513. 创建一个OH_UdmfData对象，并向OH_UdmfData中添加OH_UdmfRecord。
2524. 构建数据，将数据写入数据库中，得到返回的Key值。
2535. 使用结束后，删除上述步骤中产生的指针。
254
255```c
256// 为了代码可读性，代码中省略了各个步骤操作结果的校验，实际开发中需要确认每次调用的成功。
257// 1. 创建一个统一数据提供者，并配置它提供数据、销毁时的两个回调函数。
258OH_UdmfRecordProvider* provider = OH_UdmfRecordProvider_Create();
259OH_UdmfRecordProvider_SetData(provider, (void* )provider, GetDataCallback, ProviderFinalizeCallback);
260
261// 2. 创建一个OH_UdmfRecord对象，并将OH_UdmfRecordProvider配置到其中。
262OH_UdmfRecord* record = OH_UdmfRecord_Create();
263const char* types[1] = {UDMF_META_HYPERLINK};
264OH_UdmfRecord_SetProvider(record, types, 1, provider);
265
266// 3. 创建OH_UdmfData对象，并向OH_UdmfData中添加OH_UdmfRecord。
267OH_UdmfData* data = OH_UdmfData_Create();
268OH_UdmfData_AddRecord(data, record);
269
270// 4. 构建数据，将数据写入数据库中，得到返回的Key值。
271char key[UDMF_KEY_BUFFER_LEN] = {0};
272OH_Udmf_SetUnifiedData(Udmf_Intention::UDMF_INTENTION_DRAG, data, key, sizeof(key));
273printf("key = %s", key);
274
275// 5. 使用完成后销毁指针。
276OH_UdmfRecord_Destroy(record);
277OH_UdmfData_Destroy(data);
278```