标准化数据结构 (C/C++)
===============

#### 场景介绍

针对[UTD标准化数据类型](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-utd-h)中的部分常见类型，为了方便业务使用，提供了标准化数据结构。例如，系统定义的桌面图标类型（标准化数据类型标识为'OH\_UdsAppItem'）明确定义了相关描述信息。

某些业务场景下应用可以直接使用我们具体定义的UTD标准化数据结构，例如跨应用拖拽场景。拖出方应用可以按照标准化数据结构将拖拽数据写入[绑定拖拽事件](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ndk-drag-event)，拖入方应用从拖拽事件中读取拖拽数据并按照标准化数据结构进行数据的解析。这使得不同应用间的数据交互遵从相同的标准定义，有效减少了跨应用数据交互的开发工作量。

#### 基本概念

*   **标准化数据结构**：Unified Data Structure，简称UDS。主要针对部分标准化数据类型定义了统一的数据内容结构，并明确了对应的描述信息。应用间使用标准化数据结构进行数据交互后，将遵从统一的解析标准，可有效减少适配相关的工作量。一般用于跨应用跨设备间的数据交互，比如拖拽。

#### 接口说明

详细的接口说明请参考[标准化数据结构相关接口](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-uds-h)。

| 接口名称 | 描述 |
| :-- | :-- |
| OH\_UdmfData\* OH\_UdmfData\_Create() | 创建统一数据对象指针及实例对象 |
| OH\_UdmfRecord\* OH\_UdmfRecord\_Create() | 创建统一数据记录指针及实例对象 |
| OH\_UdsPlainText\* OH\_UdsPlainText\_Create() | 创建纯文本类型指针及实例对象 |
| int OH\_UdmfRecord\_GetPlainText(OH\_UdmfRecord\* pThis, OH\_UdsPlainText\* plainText) | 从统一数据记录中获取纯文本类型 |
| int OH\_UdsPlainText\_SetContent(OH\_UdsPlainText\* pThis, const char\* content) | 设置纯文本类型中的纯文本内容参数 |
| int OH\_UdmfRecord\_AddPlainText(OH\_UdmfRecord\* pThis, OH\_UdsPlainText\* plainText) | 添加纯文本类型数据至统一数据记录中 |
| int OH\_UdmfData\_AddRecord(OH\_UdmfData\* pThis, OH\_UdmfRecord\* record) | 添加一个数据记录到统一数据对象中 |
| OH\_UdsFileUri\* OH\_UdsFileUri\_Create() | 创建文件Uri类型指针及实例对象 |
| int OH\_UdsFileUri\_SetFileUri(OH\_UdsFileUri\* pThis, const char\* fileUri) | 设置文件Uri类型对象的Uri信息 |
| int OH\_UdsFileUri\_SetFileType(OH\_UdsFileUri\* pThis, const char\* fileType) | 设置文件Uri类型对象的文件类型 |
| int OH\_UdmfRecord\_AddFileUri(OH\_UdmfRecord\* pThis, OH\_UdsFileUri\* fileUri) | 增加文件Uri类型数据至统一数据记录中 |
| int OH\_Udmf\_SetUnifiedData(Udmf\_Intention intention, OH\_UdmfData\* unifiedData,char\* key, unsigned int keyLen) | 从统一数据管理框架数据库中写入统一数据对象数据 |
| void OH\_UdsPlainText\_Destroy(OH\_UdsPlainText\* pThis) | 销毁纯文本类型数据指针指向的实例对象 |
| void OH\_UdmfData\_Destroy(OH\_UdmfData\* pThis) | 销毁统一数据对象指针指向的实例对象 |
| void OH\_UdsFileUri\_Destroy(OH\_UdsFileUri\* pThis) | 销毁文件Uri类型的实例对象 |

#### 添加动态链接库

CMakeLists.txt中添加以下库。

libudmf.so, libhilog\_ndk.z.so

#### 引用头文件

#include <database/udmf/uds.h>
#include <database/udmf/udmf.h>
#include <database/udmf/udmf\_meta.h>
#include <database/udmf/udmf\_err\_code.h>
#include <hilog/log.h>

#undef LOG\_TAG
#define LOG\_TAG "MY\_LOG"

#### 纯文本类型数据结构的使用

1.  创建PlainText对象指针。
2.  添加PlainText内容。
3.  获取数据。
4.  使用完成后销毁指针。

// 1.创建PlainText对象指针
OH\_UdmfRecord \*plainTextRecord = OH\_UdmfRecord\_Create();
if (plainTextRecord == nullptr) {
    return Udmf\_ErrCode::UDMF\_ERR;
}
OH\_UdsPlainText \*plainText = OH\_UdsPlainText\_Create();
if (plainText == nullptr) {
    OH\_UdmfRecord\_Destroy(plainTextRecord);
    return Udmf\_ErrCode::UDMF\_ERR;
}
char content\[\] = "hello world";

// 2.添加PlainText内容
int32\_t ret = OH\_UdsPlainText\_SetContent(plainText, content);
if (ret != Udmf\_ErrCode::UDMF\_E\_OK) {
    OH\_LOG\_ERROR(LOG\_APP, "OH\_UdsPlainText\_SetContent error!");
    OH\_UdsPlainText\_Destroy(plainText);
    OH\_UdmfRecord\_Destroy(plainTextRecord);
    return ret;
}
ret = OH\_UdmfRecord\_AddPlainText(plainTextRecord, plainText);
if (ret != Udmf\_ErrCode::UDMF\_E\_OK) {
    OH\_LOG\_ERROR(LOG\_APP, "OH\_UdmfRecord\_AddPlainText error!");
    OH\_UdsPlainText\_Destroy(plainText);
    OH\_UdmfRecord\_Destroy(plainTextRecord);
    return ret;
}

// 3.获取PlainText数据
OH\_UdsPlainText \*plainText2 = OH\_UdsPlainText\_Create();
ret = OH\_UdmfRecord\_GetPlainText(plainTextRecord, plainText2);
if (ret != Udmf\_ErrCode::UDMF\_E\_OK) {
    OH\_LOG\_ERROR(LOG\_APP, "OH\_UdmfRecord\_GetPlainText error!");
    OH\_UdsPlainText\_Destroy(plainText);
    OH\_UdmfRecord\_Destroy(plainTextRecord);
    OH\_UdsPlainText\_Destroy(plainText2);
    return ret;
}
const char \*content2 = OH\_UdsPlainText\_GetContent(plainText2);
if (content2 != nullptr) {
    OH\_LOG\_INFO(LOG\_APP, "content = %{public}s.", content2);
}
// 4.使用完成后销毁指针。
OH\_UdsPlainText\_Destroy(plainText);
OH\_UdmfRecord\_Destroy(plainTextRecord);
OH\_UdsPlainText\_Destroy(plainText2);

#### fileUri类型的数据结构的使用

1.  创建fileUri类型的数据结构。
2.  设置fileUri中的URL和描述信息。
3.  创建OH\_UdmfRecord对象，并向OH\_UdmfRecord中添加fileUri类型数据。
4.  获取fileUri数据。
5.  使用完成后销毁指针。

// 1.创建fileUri类型的数据结构
const char \*uri = "https://xxx/xx/xx.jpg";
OH\_UdsFileUri \*fileUri = OH\_UdsFileUri\_Create();
if (fileUri == nullptr) {
    return Udmf\_ErrCode::UDMF\_ERR;
}
// 2. 设置fileUri中的URL和描述信息。
int32\_t ret = OH\_UdsFileUri\_SetFileUri(fileUri, uri);
if (ret != Udmf\_ErrCode::UDMF\_E\_OK) {
    OH\_UdsFileUri\_Destroy(fileUri);
    return ret;
}
ret = OH\_UdsFileUri\_SetFileType(fileUri, UDMF\_META\_IMAGE);
if (ret != Udmf\_ErrCode::UDMF\_E\_OK) {
    OH\_UdsFileUri\_Destroy(fileUri);
    return ret;
}
// 3. 创建OH\_UdmfRecord对象，并向OH\_UdmfRecord中添加fileUri类型数据。
OH\_UdmfRecord \*record = OH\_UdmfRecord\_Create();
if (record == nullptr) {
    OH\_UdsFileUri\_Destroy(fileUri);
    return Udmf\_ErrCode::UDMF\_ERR;
}
ret = OH\_UdmfRecord\_AddFileUri(record, fileUri);
if (ret != Udmf\_ErrCode::UDMF\_E\_OK) {
    OH\_UdsFileUri\_Destroy(fileUri);
    OH\_UdmfRecord\_Destroy(record);
    return ret;
}
// 4. 获取fileUri数据。
OH\_UdsFileUri \*fileUri1 = OH\_UdsFileUri\_Create();
if (fileUri1 == nullptr) {
    OH\_UdsFileUri\_Destroy(fileUri);
    OH\_UdmfRecord\_Destroy(record);
    return Udmf\_ErrCode::UDMF\_ERR;
}
ret = OH\_UdmfRecord\_GetFileUri(record, fileUri1);
if (ret != Udmf\_ErrCode::UDMF\_E\_OK) {
    OH\_UdsFileUri\_Destroy(fileUri);
    OH\_UdmfRecord\_Destroy(record);
    OH\_UdsFileUri\_Destroy(fileUri1);
    return ret;
}
const char \*fileUriStr = OH\_UdsFileUri\_GetFileUri(fileUri1);
if (fileUriStr != nullptr) {
    OH\_LOG\_INFO(LOG\_APP, "fileUri1 = %{public}s.", fileUriStr);
}
// 5. 使用完成后销毁指针。
OH\_UdsFileUri\_Destroy(fileUri);
OH\_UdmfRecord\_Destroy(record);
OH\_UdsFileUri\_Destroy(fileUri1);