UDMF Development (C/C++)

Introduction

The 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.

Basic Concepts

• UTD
  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.

• UDS
  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.

• Unified record
  A unified record is abstract definition of a piece of data supported by the UDMF, for example, a text record or an image record.

• Unified data
  A unified data object encapsulates multiple unified records.

• Unified data provider
  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.

Constraints

• 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.
• The size of customized data to be added to a unified record cannot exceed 100 MB.
• 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.

Available APIs

For details about the APIs, see UDMF.

Adding Dynamic Link Libraries

Add the following library to CMakeLists.txt.

libudmf.so

Including Header Files

#include <cstdio>
#include <cstring>
#include <database/udmf/utd.h>
#include <database/udmf/uds.h>
#include <database/udmf/udmf.h>
#include <database/udmf/udmf_meta.h>
#include <database/udmf/udmf_err_code.h>

Obtaining Plaintext Data in Different Ways

The following walks you through on how to use the UTD to obtain plaintext data. 1. Obtain typeId of the UTD based on the file name extension .txt. 2. Obtain typeId of the UTD based on the MIME type text/plain. 3. Use the typeIds obtained to create two UTD instances. 4. Check whether the two UTD instances are the same. 5. Destroy the pointers created.

// 1. Obtain typeId of the UTD based on the file name extension .txt.
unsigned int typeIds1Count = 0;
const char** typeIds1 = OH_Utd_GetTypesByFilenameExtension(".txt", &typeIds1Count);
printf("the count of typeIds1 is %u", typeIds1Count);
// 2. Obtain typeId based on the MIME type.
unsigned int typeIds2Count = 0;
const char** typeIds2 = OH_Utd_GetTypesByMimeType("text/plain", &typeIds2Count);
printf("the count of typeIds2 is %u", typeIds2Count);
// 3. Use the typeIds obtained to create two UTD instances.
OH_Utd* utd1 = OH_Utd_Create(typeIds1[0]);
OH_Utd* utd2 = OH_Utd_Create(typeIds2[0]);
// 4. Check whether the two UTD instances are the same.
bool isEquals = OH_Utd_Equals(utd1, utd2);
if (isEquals) {
    printf("utd1 == utd2");
} else {
    printf("utd1 != utd2");
}
// 5. Destroy the pointers obtained by OH_Utd_GetTypesByFilenameExtension and OH_Utd_GetFilenameExtensions and the UTD pointers.
OH_Utd_DestroyStringList(typeIds1, typeIds1Count);
OH_Utd_DestroyStringList(typeIds2, typeIds2Count);
OH_Utd_Destroy(utd1);
OH_Utd_Destroy(utd2);

Sending UDS Data

To send hyperlink data, perform the following steps: 1. Create a UDS for hyperlink data. 2. Set the URL and description for the hyperlink. 3. Write the hyperlink data into an OH_UdmfRecord instance. 4. Add the OH_UdmfRecord instance to an OH_UdmfData instance. 5. Save the data to the database. The key of the data saved to the database is returned. 6. Destroy the pointers created.

// 1. Create a UDS for hyperlink data.
OH_UdsHyperlink* hyperlink = OH_UdsHyperlink_Create();
// 2. Set the URL and description for the hyperlink.
if (OH_UdsHyperlink_SetUrl(hyperlink, "www.demo.com") != Udmf_ErrCode::UDMF_E_OK) {
    printf("Hyperlink set url error!");
}
if (OH_UdsHyperlink_SetDescription(hyperlink, "This is the description.") != Udmf_ErrCode::UDMF_E_OK) {
    printf("Hyperlink set description error!");
}
// 3. Create an OH_UdmfRecord object and add the hyperlink type data to the OH_UdmfRecord object.
OH_UdmfRecord* record = OH_UdmfRecord_Create();
if (OH_UdmfRecord_AddHyperlink(record, hyperlink) != Udmf_ErrCode::UDMF_E_OK) {
    printf("Add hyperlink to record error!");
}
// 4. Create an OH_UdmfData object and add OH_UdmfRecord to it.
OH_UdmfData* data = OH_UdmfData_Create();
if (OH_UdmfData_AddRecord(data, record) != Udmf_ErrCode::UDMF_E_OK) {
    printf("Add record to data error!");
}
// 5. Construct and write data to the database. The key of the data is returned.
char key[UDMF_KEY_BUFFER_LEN] = {0};
if (OH_Udmf_SetUnifiedData(Udmf_Intention::UDMF_INTENTION_DRAG, data, key, sizeof(key)) != Udmf_ErrCode::UDMF_E_OK) {
    printf("Set data error!");
}
printf("key = %s", key);
// 6. Destroy all the pointers created.
OH_UdsHyperlink_Destroy(hyperlink);
OH_UdmfRecord_Destroy(record);
OH_UdmfData_Destroy(data);

Obtaining UDS Data

To obtain the UDS from a hyperlink instance, perform the following steps: 1. Create an OH_UdmfData instance to hold the data read from the database. 2. Obtain data from the database based on the key. 3. Check whether data of the hyperlink type exists. 4. Obtain a record from OH_UdmfData, and then obtain hyperlink data from the data record. 5. Obtain information in the hyperlink data. 6. Destroy the pointers created.

// 1. Create an OH_UdmfData instance.
OH_UdmfData* readData = OH_UdmfData_Create();
// The key here is an example and cannot be directly used. The key must be the same as that returned by OH_Udmf_SetUnifiedData.
char key[] = {"udmf://Drag/com.ohos.test/0123456789"};
// 2. Obtain data from the database based on the key.
if (OH_Udmf_GetUnifiedData(key, Udmf_Intention::UDMF_INTENTION_DRAG, readData) != Udmf_ErrCode::UDMF_E_OK) {
    printf("Failed to get data.");
    return;
}
// 3. Check whether OH_UdmfData has hyperlink data.
if (!OH_UdmfData_HasType(readData, UDMF_META_HYPERLINK)) {
    printf("There is no hyperlink type in data.");
    return;
}
// 4. Obtain the data record and hyperlink data.
unsigned int recordsCount = 0;
OH_UdmfRecord** records = OH_UdmfData_GetRecords(readData, &recordsCount);
printf("the count of records count is %u", recordsCount);
// Create a UDS to hold the hyperlink data read from the unified record.
OH_UdsHyperlink* hyperlink = OH_UdsHyperlink_Create();
// Obtain elements in records.
for (int i = 0; i < recordsCount; i++) {
    // Obtain the OH_UdmfRecord type list.
    unsigned int recordTypeIdCount = 0;
    char** typeIdsFromRecord = OH_UdmfRecord_GetTypes(records[i], &recordTypeIdCount);
    for (unsigned int j = 0; j < recordTypeIdCount; j++) {
        // Obtain the hyperlink type data from OH_UdmfRecord.
        if (strcmp(typeIdsFromRecord[j], UDMF_META_HYPERLINK) == 0) {
            // Obtain the hyperlink data.
            if (OH_UdmfRecord_GetHyperlink(records[i], hyperlink) != Udmf_ErrCode::UDMF_E_OK) {
                printf("Fail get hyperlink from record!");
            }
        }
    }
}
// 5. Read information in OH_UdsHyperlink.
printf("The hyperlink type id is : %s", OH_UdsHyperlink_GetType(hyperlink));
printf("The hyperlink url is : %s", OH_UdsHyperlink_GetUrl(hyperlink));
printf("The hyperlink description is : %s", OH_UdsHyperlink_GetDescription(hyperlink));
// 6. Destroy the pointers.
OH_UdsHyperlink_Destroy(hyperlink);
OH_UdmfData_Destroy(readData);

Delaying UDS Data Sending

Defining a Function for Providing UDS Data

The following uses hyperlink data as an example to describe how to define a callback function that provides UDS data. 1. Define a data providing function for OH_UdmfRecordProvider. 2. Create a UDS of the hyperlink type in the data providing function. 3. Set the URL and description for the hyperlink. 4. Define a callback function for destroying the OH_UdmfRecordProvider instance.

// 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.
// 1. Define a callback to be invoked to return the UDS data obtained.
static void* GetDataCallback(void* context, const char* type) {
    if (strcmp(type, UDMF_META_PLAIN_TEXT)) {
        // 2. Create a UDS for hyperlink data.
        OH_UdsHyperlink* hyperlink = OH_UdsHyperlink_Create();
        // 3. Set the URL and description for the hyperlink.
        OH_UdsHyperlink_SetUrl(hyperlink, "www.demo.com");
        OH_UdsHyperlink_SetDescription(hyperlink, "This is the description.");
        return hyperlink;
    }
    return nullptr;
}
// 4. Define a callback to be triggered when OH_UdmfRecordProvider is destroyed.
static void ProviderFinalizeCallback(void* context) { printf("OH_UdmfRecordProvider finalize."); }

Delaying UDS Data Sending

To 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.

1. Create an OH_UdmfRecordProvider instance and set a data providing function and a callback function for destroying it.
2. Create an OH_UdmfRecord object and configure OH_UdmfRecordProvider in this object.
3. Create an OH_UdmfData instance and add OH_UdmfRecord to it.
4. Construct and write data to the database. The key of the data is returned.
5. Destroy the pointers created.

// 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.
// 1. Create a OH_UdmfRecordProvider instance and configure two callback functions for providing data and destroying the instance.
OH_UdmfRecordProvider* provider = OH_UdmfRecordProvider_Create();
OH_UdmfRecordProvider_SetData(provider, (void* )provider, GetDataCallback, ProviderFinalizeCallback);

// 2. Create an OH_UdmfRecord object and configure OH_UdmfRecordProvider in this object.
OH_UdmfRecord* record = OH_UdmfRecord_Create();
const char* types[1] = {UDMF_META_HYPERLINK};
OH_UdmfRecord_SetProvider(record, types, 1, provider);

// 3. Create an OH_UdmfData object and add OH_UdmfRecord to it.
OH_UdmfData* data = OH_UdmfData_Create();
OH_UdmfData_AddRecord(data, record);

// 4. Construct and write data to the database. The key of the data is returned.
char key[UDMF_KEY_BUFFER_LEN] = {0};
OH_Udmf_SetUnifiedData(Udmf_Intention::UDMF_INTENTION_DRAG, data, key, sizeof(key));
printf("key = %s", key);

// 5. Destroy all the pointers created.
OH_UdmfRecord_Destroy(record);
OH_UdmfData_Destroy(data);

你可能感兴趣的鸿蒙文章

harmony 鸿蒙ArkData (Ark Data Management)

harmony 鸿蒙Access Control by Device and Data Level

harmony 鸿蒙Application Data Vectorization

harmony 鸿蒙AIP Overview

harmony 鸿蒙Application Data Persistence Overview

harmony 鸿蒙Database Backup and Restore

harmony 鸿蒙Database Encryption

harmony 鸿蒙Introduction to ArkData

harmony 鸿蒙Persisting Graph Store Data (for System Applications Only)

harmony 鸿蒙Persisting KV Store Data