1# UDMF Development (C/C++)
2
3
4## Introduction
5
6The Unified Data Management Framework (UDMF) defines the language and data standards for cross-application and cross-device data interaction, improving data interaction efficiency. It also provides secure and standard data transmission channels and supports different levels of data access permissions and lifecycle management policies. It helps implement efficient data sharing across applications and devices.
7
8
9## Basic Concepts
10
11- UTD<br>A Uniform Type Descriptor (UTD) defines data of the same type to eliminate data type ambiguity. It contains the data type ID and types to which the current data type belongs. The UTD is generally used to filter or identify the data type in scenarios such as file preview and file sharing.
12
13- UDS<br>A uniform data struct (UDS) defines the data of a certain type (specified by a UTD). Uniform data structs allow unified parsing standards to be used in data interaction, which minimizes the adaptation workload. Uniform data structs are used for data interaction across applications and devices, such as, the drag-and-drop operations.
14
15- Unified record<br>A unified record is abstract definition of a piece of data supported by the UDMF, for example, a text record or an image record.
16
17- Unified data<br>A unified data object encapsulates multiple unified records.
18
19- Unified data provider<br>The unified data provider is configured in a unified record to provide UDS data. It is usually used in deferred data transmission, in which the UDS data is transferred only when the data consumer obtains data from the unified data record.
20
21
22## Constraints
23
24- The UDMF supports management of batch data records. Each unified data object cannot exceed 200 MB. The maximum size of a single property in **PlainText**, **Hyperlink**, or **HTML** is 20 MB.
25- The size of customized data to be added to a unified record cannot exceed 100 MB.
26- When data is written to the UDMF database, the memory size of the unique identifier (key) must be greater than or equal to 512 bytes.
27
28
29
30## Available APIs
31
32For details about the APIs, see [UDMF](../reference/apis-arkdata/_u_d_m_f.md).
33
34| API                                                          | Description                                                  |
35| ------------------------------------------------------------ | ------------------------------------------------------------ |
36| OH_Utd* OH_Utd_Create(const char* typeId)                    | Creates a pointer to an **OH_Utd** instance.                 |
37| void OH_Utd_Destroy(OH_Utd* pThis)                           | Destroys the pointer to an **OH_Utd** instance.              |
38| const char** OH_Utd_GetTypesByFilenameExtension(const char* extension, unsigned int* count) | Obtains the uniform data types by file name extension.       |
39| const char** OH_Utd_GetTypesByMimeType(const char* mimeType, unsigned int* count) | Obtains the uniform data types by MIME type.                 |
40| bool OH_Utd_Equals(OH_Utd* utd1, OH_Utd* utd2)               | Checks whether two UTDs are the same.                        |
41| void OH_Utd_DestroyStringList(const char** list, unsigned int count) | Destroys a UTD list.                                         |
42| OH_UdsHyperlink* OH_UdsHyperlink_Create()                    | Creates a pointer to an **OH_UdsHyperlink** instance.        |
43| void OH_UdsHyperlink_Destroy(OH_UdsHyperlink* pThis)         | Destroys the pointer to an **OH_UdsHyperlink** instance.     |
44| const char* OH_UdsHyperlink_GetType(OH_UdsHyperlink* pThis)  | Obtains the UTD ID from an **OH_UdsHyperlink** instance.     |
45| const char* OH_UdsHyperlink_GetUrl(OH_UdsHyperlink* pThis)   | Obtains the URL from an **OH_UdsHyperlink** instance.        |
46| const char* OH_UdsHyperlink_GetDescription(OH_UdsHyperlink* pThis) | Obtains the link description from an **OH_UdsHyperlink** instance. |
47| int OH_UdsHyperlink_SetUrl(OH_UdsHyperlink* pThis, const char* url) | Sets the URL for an **OH_UdsHyperlink** instance.            |
48| int OH_UdsHyperlink_SetDescription(OH_UdsHyperlink* pThis, const char* description) | Sets the link description for an **OH_UdsHyperlink** instance. |
49| OH_UdmfData* OH_UdmfData_Create()                            | Creates a pointer to an **OH_UdmfData** instance.            |
50| void OH_UdmfData_Destroy(OH_UdmfData* pThis)                 | Destroys the pointer to an **OH_UdmfData** instance.         |
51| int OH_UdmfData_AddRecord(OH_UdmfData* pThis, OH_UdmfRecord* record) | Add an **OH_UdmfRecord** to an **OH_UdmfData** instance.     |
52| bool OH_UdmfData_HasType(OH_UdmfData* pThis, const char* type) | Checks whether the specified type exists in an **OH_UdmfData** instance. |
53| OH_UdmfRecord** OH_UdmfData_GetRecords(OH_UdmfData* pThis, unsigned int* count) | Obtains all data records from an **OH_UdmfData** instance.   |
54| OH_UdmfRecord* OH_UdmfRecord_Create()                        | Creates a pointer to an **OH_UdmfRecord** instance.          |
55| void OH_UdmfRecord_Destroy(OH_UdmfRecord* pThis)             | Destroys the pointer to an **OH_UdmfRecord** instance.       |
56| int OH_UdmfRecord_AddHyperlink(OH_UdmfRecord* pThis, OH_UdsHyperlink* hyperlink) | Adds hyperlink data to an **OH_UdmfRecord** instance.        |
57| char** OH_UdmfRecord_GetTypes(OH_UdmfRecord* pThis, unsigned int* count) | Obtains all data types in an **OH_UdmfRecord** instance.     |
58| int OH_UdmfRecord_GetHyperlink(OH_UdmfRecord* pThis, OH_UdsHyperlink* hyperlink) | Obtains the hyperlink data from an **OH_UdmfRecord** instance. |
59| int OH_Udmf_GetUnifiedData(const char* key, Udmf_Intention intention, OH_UdmfData* unifiedData) | Obtains data from the UDMF database.                         |
60| int OH_Udmf_SetUnifiedData(Udmf_Intention intention, OH_UdmfData* unifiedData, char* key, unsigned int keyLen) | Sets data in the UDMF database.                              |
61| OH_UdmfRecordProvider* OH_UdmfRecordProvider_Create()        | Creates a pointer to the unified data provider instance.     |
62| int OH_UdmfRecordProvider_SetData(OH_UdmfRecordProvider* provider, void* context, const OH_UdmfRecordProvider_GetData callback, const UdmfData_Finalize finalize) | Sets a callback for the unified data provider.               |
63| int OH_UdmfRecord_SetProvider(OH_UdmfRecord* pThis, const char* const* types, unsigned int count, OH_UdmfRecordProvider* provider) | Sets the unified data provider in an **OH_UdmfRecord** instance. |
64
65
66## Adding Dynamic Link Libraries
67
68Add the following library to **CMakeLists.txt**.
69
70```txt
71libudmf.so
72```
73
74## Including Header Files
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## Obtaining Plaintext Data in Different Ways
86
87To use the UTD to obtain plaintext data, perform the following steps:
881. Obtain **typeId** of the UTD based on the file name extension **.txt**.
892. Obtain **typeId** of the UTD based on the MIME type **text/plain**.
903. Use the **typeId**s obtained to create two UTD instances.
914. Check whether the two UTD instances are the same.
925. Destroy the pointers created.
93
94```c
95// 1. Obtain typeId of the UTD based on the file name extension .txt.
96unsigned int typeIds1Count = 0;
97const char** typeIds1 = OH_Utd_GetTypesByFilenameExtension(".txt", &typeIds1Count);
98printf("the count of typeIds1 is %u", typeIds1Count);
99// 2. Obtain typeId based on the MIME type.
100unsigned int typeIds2Count = 0;
101const char** typeIds2 = OH_Utd_GetTypesByMimeType("text/plain", &typeIds2Count);
102printf("the count of typeIds2 is %u", typeIds2Count);
103// 3. Use the typeIds obtained to create two UTD instances.
104OH_Utd* utd1 = OH_Utd_Create(typeIds1[0]);
105OH_Utd* utd2 = OH_Utd_Create(typeIds2[0]);
106// 4. Check whether the two UTD instances are the same.
107bool isEquals = OH_Utd_Equals(utd1, utd2);
108if (isEquals) {
109    printf("utd1 == utd2");
110} else {
111    printf("utd1 != utd2");
112}
113// 5. Destroy the pointers obtained by OH_Utd_GetTypesByFilenameExtension and OH_Utd_GetFilenameExtensions and the UTD pointers.
114OH_Utd_DestroyStringList(typeIds1, typeIds1Count);
115OH_Utd_DestroyStringList(typeIds2, typeIds2Count);
116OH_Utd_Destroy(utd1);
117OH_Utd_Destroy(utd2);
118```
119
120## Sending UDS Data
121
122To send hyperlink data, perform the following steps:
1231. Create a UDS for hyperlink data.
1242. Set the URL and description for the hyperlink.
1253. Write the hyperlink data into an **OH_UdmfRecord** instance.
1264. Add the **OH_UdmfRecord** instance to an **OH_UdmfData** instance.
1275. Save the data to the database. The key of the data saved to the database is returned.
1286. Destroy the pointers created.
129
130```c
131// 1. Create a UDS for hyperlink data.
132OH_UdsHyperlink* hyperlink = OH_UdsHyperlink_Create();
133// 2. Set the URL and description for the hyperlink.
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. Create an OH_UdmfRecord object and add the hyperlink type data to the OH_UdmfRecord object.
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. Create an OH_UdmfData object and add OH_UdmfRecord to it.
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. Construct and write data to the database. The key of the data is returned.
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. Destroy all the pointers created.
157OH_UdsHyperlink_Destroy(hyperlink);
158OH_UdmfRecord_Destroy(record);
159OH_UdmfData_Destroy(data);
160```
161
162## Obtaining UDS Data
163
164To obtain the UDS from a hyperlink instance, perform the following steps:
1651. Create an **OH_UdmfData** instance to hold the data read from the database.
1662. Obtain data from the database based on the key.
1673. Check whether data of the hyperlink type exists.
1684. Obtain a record from **OH_UdmfData**, and then obtain hyperlink data from the data record.
1695. Obtain information in the hyperlink data.
1706. Destroy the pointers created.
171
172```c
173// 1. Create an OH_UdmfData instance.
174OH_UdmfData* readData = OH_UdmfData_Create();
175// The key here is an example and cannot be directly used. The key must be the same as that returned by OH_Udmf_SetUnifiedData.
176char key[] = {"udmf://Drag/com.ohos.test/0123456789"};
177// 2. Obtain data from the database based on the 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. Check whether OH_UdmfData has hyperlink data.
183if (!OH_UdmfData_HasType(readData, UDMF_META_HYPERLINK)) {
184    printf("There is no hyperlink type in data.");
185    return;
186}
187// 4. Obtain the data record and hyperlink data.
188unsigned int recordsCount = 0;
189OH_UdmfRecord** records = OH_UdmfData_GetRecords(readData, &recordsCount);
190printf("the count of records count is %u", recordsCount);
191// Create a UDS to hold the hyperlink data read from the unified record.
192OH_UdsHyperlink* hyperlink = OH_UdsHyperlink_Create();
193// Obtain elements in records.
194for (int i = 0; i < recordsCount; i++) {
195    // Obtain the OH_UdmfRecord type list.
196    unsigned int recordTypeIdCount = 0;
197    char** typeIdsFromRecord = OH_UdmfRecord_GetTypes(records[i], &recordTypeIdCount);
198    for (unsigned int j = 0; j < recordTypeIdCount; j++) {
199        // Obtain the hyperlink type data from OH_UdmfRecord.
200        if (strcmp(typeIdsFromRecord[j], UDMF_META_HYPERLINK) == 0) {
201            // Obtain the hyperlink data.
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. Read information in 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. Destroy the pointers.
213OH_UdsHyperlink_Destroy(hyperlink);
214OH_UdmfData_Destroy(readData);
215```
216
217## Delaying UDS Data Sending
218
219### Defining a Function for Providing UDS Data
220
221The following uses hyperlink data as an example to describe how to define a callback function that provides UDS data.
2221. Define a data providing function for **OH_UdmfRecordProvider**.
2232. Create a UDS of the hyperlink type in the data providing function.
2243. Set the URL and description for the hyperlink.
2254. Define a callback function for destroying the **OH_UdmfRecordProvider** instance.
226
227```c
228// For better code readability, the operation result verification of each step is omitted in the following code. In actual development, you need to check whether each call is successful.
229// 1. Define a callback to be invoked to return the UDS data obtained.
230static void* GetDataCallback(void* context, const char* type) {
231    if (strcmp(type, UDMF_META_PLAIN_TEXT)) {
232        // 2. Create a UDS for hyperlink data.
233        OH_UdsHyperlink* hyperlink = OH_UdsHyperlink_Create();
234        // 3. Set the URL and description for the hyperlink.
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. Define a callback to be triggered when OH_UdmfRecordProvider is destroyed.
242static void ProviderFinalizeCallback(void* context) { printf("OH_UdmfRecordProvider finalize."); }
243```
244
245### Delaying UDS Data Sending
246
247To delay the sending of the hyperlink data, perform the following steps: The **GetDataCallback** function is triggered to obtain data only when the data consumer obtains **OH_UdsHyperlink** from **OH_UdmfRecord**.
248
2491. Create an **OH_UdmfRecordProvider** instance and set a data providing function and a callback function for destroying it.
2502. Create an **OH_UdmfRecord** object and configure **OH_UdmfRecordProvider** in this object.
2513. Create an **OH_UdmfData** instance and add **OH_UdmfRecord** to it.
2524. Construct and write data to the database. The key of the data is returned.
2535. Destroy the pointers created.
254
255```c
256// For better code readability, the operation result verification of each step is omitted in the following code. In actual development, you need to check whether each call is successful.
257// 1. Create a OH_UdmfRecordProvider instance and configure two callback functions for providing data and destroying the instance.
258OH_UdmfRecordProvider* provider = OH_UdmfRecordProvider_Create();
259OH_UdmfRecordProvider_SetData(provider, (void* )provider, GetDataCallback, ProviderFinalizeCallback);
260
261// 2. Create an OH_UdmfRecord object and configure OH_UdmfRecordProvider in this object.
262OH_UdmfRecord* record = OH_UdmfRecord_Create();
263const char* types[1] = {UDMF_META_HYPERLINK};
264OH_UdmfRecord_SetProvider(record, types, 1, provider);
265
266// 3. Create an OH_UdmfData object and add OH_UdmfRecord to it.
267OH_UdmfData* data = OH_UdmfData_Create();
268OH_UdmfData_AddRecord(data, record);
269
270// 4. Construct and write data to the database. The key of the data is returned.
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. Destroy all the pointers created.
276OH_UdmfRecord_Destroy(record);
277OH_UdmfData_Destroy(data);
278```
279