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