鸿蒙开发 UDMF开发指导 (C/C++)

场景介绍

统一数据管理框架(UDMF):提供了数据跨应用、跨设备交互标准,定义了跨应用、跨设备数据交互过程中的数据语言,提升数据交互效率。提供安全、标准化数据流通通路,支持不同级别的数据访问权限与生命周期管理策略,实现高效的数据跨应用、跨设备共享。

基本概念

  • 标准化数据类型:Uniform Type Descriptor,简称UTD。主要针对同一种数据类型,提供统一定义,即标准数据类型描述符,定义了包括标识数据类型的ID、类型归属关系等相关信息,用于解决HarmonyOS系统中的类型模糊问题。一般用于过滤或者识别某一种数据类型的场景,比如文件预览、文件分享等。
  • 标准化数据结构:Uniform Type Structure,简称UDS。主要针对部分标准化数据类型定义了统一的数据内容结构,并明确了对应的描述信息。应用间使用标准化数据结构进行数据交互后,将遵从统一的解析标准,可有效减少适配相关的工作量。一般用于跨应用跨设备间的数据交互,比如拖拽。
  • 统一数据记录: Unified Record,对UDMF支持的数据内容的抽象定义,例如一条文本记录、一条图片记录等。
  • 统一数据对象: Unified Data,用于封装一组数据记录UnifiedRecord。
  • 统一数据提供者: Unified Data Provider,配置到统一数据记录中,用来提供UDS数据。通常用于数据的延迟发送场景,让UDS数据在数据使用方从统一数据记录中实际获取时才发生数据的转移。

约束限制

  • UDMF支持批量数据记录的分组管理,每个分组整体大小不超过200MB,其中PlainText、Hyperlink、HTML内单个属性值数据上限20M。
  • 向统一数据记录中添加用户自定义数据时,所添加的数据大小不超过100MB。
  • 向UDMF数据库中写入数据时,定义的唯一标识符的内存大小不小于512字节。

接口说明

详细的接口说明请参考 UDMF接口文档 。

接口名称描述
OH_Utd* OH_Utd_Create(const char* typeId)创建一个指向统一数据类型描述符OH_Utd的指针。
void OH_Utd_Destroy(OH_Utd* pThis)销毁指向统一数据类型描述符OH_Utd的指针。
const char** OH_Utd_GetTypesByFilenameExtension(const char* extension, unsigned int* count)通过文件后缀名获取标准化数据类型ID。
const char** OH_Utd_GetTypesByMimeType(const char* mimeType, unsigned int* count)通过MIME类型获取标准化数据类型ID。
bool OH_Utd_Equals(OH_Utd* utd1, OH_Utd* utd2)判断两种标准化数据类型是否相等。
void OH_Utd_DestroyStringList(const char** list, unsigned int count)销毁字符串列表数据。
OH_UdsHyperlink* OH_UdsHyperlink_Create()创建一个指向标准化数据结构超链接类型OH_UdsHyperlink的指针。
void OH_UdsHyperlink_Destroy(OH_UdsHyperlink* pThis)销毁指向标准化数据结构超链接类型OH_UdsHyperlink的指针。
const char* OH_UdsHyperlink_GetType(OH_UdsHyperlink* pThis)获取OH_UdsHyperlink中的标准化数据类型ID。
const char* OH_UdsHyperlink_GetUrl(OH_UdsHyperlink* pThis)获取OH_UdsHyperlink中的链接URL。
const char* OH_UdsHyperlink_GetDescription(OH_UdsHyperlink* pThis)获取OH_UdsHyperlink中的链接内容描述。
int OH_UdsHyperlink_SetUrl(OH_UdsHyperlink* pThis, const char* url)设置OH_UdsHyperlink中的链接URL。
int OH_UdsHyperlink_SetDescription(OH_UdsHyperlink* pThis, const char* description)设置OH_UdsHyperlink中的链接内容描述。
OH_UdmfData* OH_UdmfData_Create()创建一个指向统一数据对象OH_UdmfData的指针。
void OH_UdmfData_Destroy(OH_UdmfData* pThis)销毁指向统一数据对象OH_UdmfData的指针。
int OH_UdmfData_AddRecord(OH_UdmfData* pThis, OH_UdmfRecord* record)向OH_UdmfData中增加一条OH_UdmfRecord数据记录。
bool OH_UdmfData_HasType(OH_UdmfData* pThis, const char* type)判断统一数据对象OH_UdmfData是否存在指定类型。
OH_UdmfRecord** OH_UdmfData_GetRecords(OH_UdmfData* pThis, unsigned int* count)获取OH_UdmfData中全部的数据记录。
OH_UdmfRecord* OH_UdmfRecord_Create()创建一个指向统一数据记录OH_UdmfRecord的指针。
void OH_UdmfRecord_Destroy(OH_UdmfRecord* pThis)销毁指向统一数据记录OH_UdmfRecord的指针。
int OH_UdmfRecord_AddHyperlink(OH_UdmfRecord* pThis, OH_UdsHyperlink* hyperlink)向OH_UdmfRecord添加超链接类型数据。
char** OH_UdmfRecord_GetTypes(OH_UdmfRecord* pThis, unsigned int* count)获取OH_UdmfRecord中全部的数据类型。
int OH_UdmfRecord_GetHyperlink(OH_UdmfRecord* pThis, OH_UdsHyperlink* hyperlink)获取OH_UdmfRecord中超链接类型数据。
int OH_Udmf_GetUnifiedData(const char* key, Udmf_Intention intention, OH_UdmfData* unifiedData)从UDMF数据库中获取数据。
int OH_Udmf_SetUnifiedData(Udmf_Intention intention, OH_UdmfData* unifiedData, char* key, unsigned int keyLen)向UDMF数据库中写入数据。
OH_UdmfRecordProvider* OH_UdmfRecordProvider_Create()创建一个指向统一数据提供者的指针。

int OH_UdmfRecordProvider_SetData(OH_UdmfRecordProvider* provider, void* context, const OH_UdmfRecordProvider_GetData callback, const UdmfData_Finalize finalize)

设置统一数据提供者的回调函数。
int OH_UdmfRecord_SetProvider(OH_UdmfRecord* pThis, const char* const* types, unsigned int count, OH_UdmfRecordProvider* provider)将统一数据提供者配置到OH_UdmfRecord中。


添加动态链接库

CMakeLists.txt中添加以下lib。

libudmf.so

引用头文件

#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>

通过不同方式获取纯文本类型数据

下面以获取纯文本数据的查询场景为例,说明如何使用UTD

  1. 通过后缀名“.txt”获取UTD的typeId。
  2. 通过MIME类型“text/plain”获取UTD的typeId。
  3. 使用以上两个步骤获取到的typeId创建UTD实例对象。
  4. 比较UTD实例对象是否相等。
  5. 使用结束后,删除上述步骤中产生的指针。
// 1. 通过文件后缀名获取纯文本类型的UTD的typeId
unsigned int typeIds1Count = 0;
const char** typeIds1 = OH_Utd_GetTypesByFilenameExtension(".txt", &typeIds1Count);
printf("the count of typeIds1 is %u", typeIds1Count);
// 2. 通过MIME类型获取typeId
unsigned int typeIds2Count = 0;
const char** typeIds2 = OH_Utd_GetTypesByMimeType("text/plain", &typeIds2Count);
printf("the count of typeIds2 is %u", typeIds2Count);
// 3. 使用以上两个步骤获取到的typeId创建UTD实例对象。
OH_Utd* utd1 = OH_Utd_Create(typeIds1[0]);
OH_Utd* utd2 = OH_Utd_Create(typeIds2[0]);
// 4. 比较两种方式获取到的typeId对应的UTD是否相同
bool isEquals = OH_Utd_Equals(utd1, utd2);
if (isEquals) {
    printf("utd1 == utd2");
} else {
    printf("utd1 != utd2");
}
// 5. 销毁OH_Utd_GetTypesByFilenameExtension与OH_Utd_GetFilenameExtensions函数获取到的指针,同时销毁UTD指针
OH_Utd_DestroyStringList(typeIds1, typeIds1Count);
OH_Utd_DestroyStringList(typeIds2, typeIds2Count);
OH_Utd_Destroy(utd1);
OH_Utd_Destroy(utd2);

使用UDMF发送UDS数据

下面以发送超链接hyperlink类型数据场景为例,说明如何使用UDS与UDMF。

  1. 创建超链接hyperlink数据的UDS数据结构。
  2. 设置hyperlink中的URL和描述信息。
  3. 将hyperlink数据放入数据记录OH_UdmfRecord中。
  4. 将数据记录OH_UdmfRecord添加到统一数据OH_UdmfData中。
  5. 保存以上数据至数据库中,得到返回的key值。
  6. 使用结束后,删除上述步骤中产生的指针。
// 1. 创建超链接hyperlink数据的UDS数据结构。
OH_UdsHyperlink* hyperlink = OH_UdsHyperlink_Create();
// 2. 设置hyperlink中的URL和描述信息。
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. 创建OH_UdmfRecord对象,并向OH_UdmfRecord中添加超链接类型数据。
OH_UdmfRecord* record = OH_UdmfRecord_Create();
if (OH_UdmfRecord_AddHyperlink(record, hyperlink) != Udmf_ErrCode::UDMF_E_OK) {
    printf("Add hyperlink to record error!");
}
// 4. 创建OH_UdmfData对象,并向OH_UdmfData中添加OH_UdmfRecord。
OH_UdmfData* data = OH_UdmfData_Create();
if (OH_UdmfData_AddRecord(data, record) != Udmf_ErrCode::UDMF_E_OK) {
    printf("Add record to data error!");
}
// 5. 构建数据,将数据写入数据库中,得到返回的key值。
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. 使用完成后销毁指针。
OH_UdsHyperlink_Destroy(hyperlink);
OH_UdmfRecord_Destroy(record);
OH_UdmfData_Destroy(data);

使用UDMF接收UDS数据

下面继续以获取超链接hyperlink类型数据场景为例,说明如何使用UDS与UDMF。

  1. 创建统一数据OH_UdmfData,用来承载数据库中读取的数据。
  2. 通过key值从数据库中获取到数据。
  3. 判断数据中是否有hyperlink类型的数据。
  4. 获取OH_UdmfData中的数据记录,并从数据记录中获取hyperlink数据。
  5. 读取hyperlink数据中的各项信息。
  6. 使用结束后,删除上述步骤中产生的指针。
// 1. 创建统一数据OH_UdmfData。
OH_UdmfData* readData = OH_UdmfData_Create();
// 此处key为示例,不可直接使用,其值应与OH_Udmf_SetUnifiedData接口中获取到的key值保持一致。
char key[] = {"udmf://Drag/com.ohos.test/0123456789"};
// 2. 通过key值从数据库中获取到数据。
if (OH_Udmf_GetUnifiedData(key, Udmf_Intention::UDMF_INTENTION_DRAG, readData) != Udmf_ErrCode::UDMF_E_OK) {
    printf("Failed to get data.");
    return;
}
// 3. 判断OH_UdmfData是否有对应的类型。
if (!OH_UdmfData_HasType(readData, UDMF_META_HYPERLINK)) {
    printf("There is no hyperlink type in data.");
    return;
}
// 4. 获取数据记录和hyperlink数据。
unsigned int recordsCount = 0;
OH_UdmfRecord** records = OH_UdmfData_GetRecords(readData, &recordsCount);
printf("the count of records count is %u", recordsCount);
// 创建hyperlink的UDS,用来承载record中读取出来的hyperlink数据。
OH_UdsHyperlink* hyperlink = OH_UdsHyperlink_Create();
// 获取records中的元素。
for (int i = 0; i < recordsCount; i++) {
    // 获取OH_UdmfRecord类型列表。
    unsigned int recordTypeIdCount = 0;
    char** typeIdsFromRecord = OH_UdmfRecord_GetTypes(records[i], &recordTypeIdCount);
    for (unsigned int j = 0; j < recordTypeIdCount; j++) {
        // 从OH_UdmfRecord中获取超链接类型数据。
        if (strcmp(typeIdsFromRecord[j], UDMF_META_HYPERLINK) == 0) {
            // 获取hyperlink数据。
            if (OH_UdmfRecord_GetHyperlink(records[i], hyperlink) != Udmf_ErrCode::UDMF_E_OK) {
                printf("Fail get hyperlink from record!");
            }
        }
    }
}
// 5. 读取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. 销毁指针。
OH_UdsHyperlink_Destroy(hyperlink);
OH_UdmfData_Destroy(readData);

使用UDMF延迟发送UDS数据

定义UDS数据提供函数
下面以超链接hyperlink类型数据场景为例,说明如何定义一个提供UDS数据的回调函数。

  1. 定义OH_UdmfRecordProvider的数据提供函数。
  2. 在数据提供函数中,创建hyperlink类型的UDS数据结构。
  3. 设置hyperlink中的URL和描述信息。
  4. 定义OH_UdmfRecordProvider实例注销回调函数。
// 为了代码可读性,代码中省略了各个步骤操作结果的校验,实际开发中需要确认每次调用的成功。
// 1. 获取数据时触发的提供UDS数据的回调函数。
static void* GetDataCallback(void* context, const char* type) {
    if (strcmp(type, UDMF_META_PLAIN_TEXT)) {
        // 2. 创建超链接hyperlink数据的UDS数据结构。
        OH_UdsHyperlink* hyperlink = OH_UdsHyperlink_Create();
        // 3. 设置hyperlink中的URL和描述信息。
        OH_UdsHyperlink_SetUrl(hyperlink, "www.demo.com");
        OH_UdsHyperlink_SetDescription(hyperlink, "This is the description.");
        return hyperlink;
    }
    return nullptr;
}
// 4. OH_UdmfRecordProvider销毁时触发的回调函数。
static void ProviderFinalizeCallback(void* context) { printf("OH_UdmfRecordProvider finalize."); }

延迟发送UDS数据
下面以延迟发送超链接hyperlink类型数据场景为例,说明如何使用OH_UdmfRecordProvider与UDMF。需要注意,此步骤完成后超链接类型数据并未真正写入数据库,只有当数据使用者从OH_UdmfRecord中获取OH_UdsHyperlink时,才会触发上文定义的GetDataCallback数据提供函数,从中得到数据。

  1. 创建一个OH_UdmfRecordProvider,并设置它的数据提供函数和销毁时的回调函数。
  2. 创建一个OH_UdmfRecord对象,并将OH_UdmfRecordProvider配置到其中。
  3. 创建一个OH_UdmfData对象,并向OH_UdmfData中添加OH_UdmfRecord。
  4. 构建数据,将数据写入数据库中,得到返回的Key值。
  5. 使用结束后,删除上述步骤中产生的指针。
// 为了代码可读性,代码中省略了各个步骤操作结果的校验,实际开发中需要确认每次调用的成功。
// 1. 创建一个统一数据提供者,并配置它提供数据、销毁时的两个回调函数。
OH_UdmfRecordProvider* provider = OH_UdmfRecordProvider_Create();
OH_UdmfRecordProvider_SetData(provider, (void* )provider, GetDataCallback, ProviderFinalizeCallback);

// 2. 创建一个OH_UdmfRecord对象,并将OH_UdmfRecordProvider配置到其中。
OH_UdmfRecord* record = OH_UdmfRecord_Create();
const char* types[1] = {UDMF_META_HYPERLINK};
OH_UdmfRecord_SetProvider(record, types, 1, provider);

// 3. 创建OH_UdmfData对象,并向OH_UdmfData中添加OH_UdmfRecord。
OH_UdmfData* data = OH_UdmfData_Create();
OH_UdmfData_AddRecord(data, record);

// 4. 构建数据,将数据写入数据库中,得到返回的Key值。
char key[UDMF_KEY_BUFFER_LEN] = {0};
OH_Udmf_SetUnifiedData(Udmf_Intention::UDMF_INTENTION_DRAG, data, key, sizeof(key));
printf("key = %s", key);

// 5. 使用完成后销毁指针。
OH_UdmfRecord_Destroy(record);
OH_UdmfData_Destroy(data);

最后:

如果还有不知道从哪里开始入手了解鸿蒙开发技术、想要更深的掌握鸿蒙开发技术知识点的朋友们,或者是转行求职人员还在为面试问题而犯难的,可以动动手指进来参考一下针对‌鸿蒙开发学习‌而设计的系统性学习方案,涵盖基础入门到进阶实战项目相关学习文档:https://docs.qq.com/doc/DSk9ZeU9RTUhETm53

评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值