1# 使用剪贴板进行复制粘贴 (C/C++)
2
3## 场景介绍
4
5剪贴板为开发者提供数据的复制粘贴能力。支持对纯文本、超本文、URI等内容的操作。
6
7## 基本概念
8
9- **OH_PasteboardObserver**：剪贴板数据变更观察者对象，用以监听剪贴板数据变更事件。
10- **OH_Pasteboard**：剪贴板对象，用来进行查询、写入等操作。
11- **OH_UdmfData**：统一数据对象，详见[UDMF开发指导 (C/C++)](../../database/native-unified-data-management-framework-guidelines.md)。
12
13## 约束限制
14
15- 单次写入剪贴板的数据大小不能超过128MB。
16- 为保证剪贴板数据的准确性，同一时间只能支持一个复制操作。
17- 当前支持的数据类型：纯文本类型(OH_UdsPlainText)、超文本标记语言类型(OH_UdsHtml)、文件Uri类型(OH_UdsFileUri)、像素图片类型(OH_UdsPixelMap)、超链接类型(OH_UdsHyperlink)、桌面图标类型(OH_UdsAppItem)、自定义类型。JS接口与NDK接口支持数据类型不完全一致，使用时须匹配接口支持类型，详情见[JS接口与NDK接口数据类型对应关系](../pasteboard/use_pasteboard_to_copy_and_paste.md)。
18- 自定义类型数据在复制粘贴时，指定的类型名称不能和已有的类型名称重复。
19- API version 12及之后，系统为提升用户隐私安全保护能力，剪贴板读取接口增加[权限管控](get-pastedata-permission-guidelines.md)。
20- API version 12中新增的复制、粘贴接口[setUnifiedData](../../reference/apis-basic-services-kit/js-apis-pasteboard.md#setunifieddata12)/[getUnifiedData](../../reference/apis-basic-services-kit/js-apis-pasteboard.md#getunifieddata12)，和本文档中的复制、粘贴接口`OH_Pasteboard_SetData`/`OH_Pasteboard_GetData`，当前相互独立，进行写入、读取操作时请使用对应配套接口。
21
22## 接口说明
23
24详细接口见[Pasteboard文档](../../reference/apis-basic-services-kit/_pasteboard.md)。
25
26| 接口名称                                                     | 描述                                                    |
27| ------------------------------------------------------------ | ------------------------------------------------------- |
28| OH_PasteboardObserver* OH_PasteboardObserver_Create()        | 创建一个剪贴板数据变更观察者对象。                      |
29| OH_PasteboardObserver_Destroy(OH_PasteboardObserver* observer) | 销毁剪贴板数据变更观察者对象。                          |
30| int OH_PasteboardObserver_SetData(OH_PasteboardObserver* observer, void* context, const Pasteboard_Notify callback, const Pasteboard_Finalize finalize) | 将剪贴板变更回调函数设置到剪贴板数据变更观察者对象中。  |
31| OH_Pasteboard* OH_Pasteboard_Create()                        | 创建一个剪贴板实例。                                    |
32| void OH_Pasteboard_Destroy(OH_Pasteboard* pasteboard)        | 销毁剪贴板实例。                                        |
33| int OH_Pasteboard_Subscribe(OH_Pasteboard* pasteboard, int type, const OH_PasteboardObserver* observer) | 订阅剪贴板的数据变更。                                  |
34| int OH_Pasteboard_Unsubscribe(OH_Pasteboard* pasteboard, int type, const OH_PasteboardObserver* observer) | 取消对剪贴板数据变更的订阅。                            |
35| bool OH_Pasteboard_IsRemoteData(OH_Pasteboard* pasteboard)   | 判断剪贴板中的数据是否来自远端设备。                    |
36| int OH_Pasteboard_GetDataSource(OH_Pasteboard* pasteboard, char* source, unsigned int len) | 获取剪贴板中数据的数据源。                              |
37| bool OH_Pasteboard_HasType(OH_Pasteboard* pasteboard, const char* type) | 判断剪贴板中是否有指定类型的数据。                      |
38| bool OH_Pasteboard_HasData(OH_Pasteboard* pasteboard)        | 检查剪贴板中是否有数据。                                |
39| OH_UdmfData* OH_Pasteboard_GetData(OH_Pasteboard* pasteboard, int* status) | 获取剪贴板中的数据。                                    |
40| int OH_Pasteboard_SetData(OH_Pasteboard* pasteboard, OH_UdmfData* data) | 向剪贴板中写入数据。                                    |
41| int OH_Pasteboard_ClearData(OH_Pasteboard* pasteboard)       | 清空剪贴板中的数据。                                    |
42| void (\*Pasteboard_Notify)(void\* context, Pasteboard_NotifyType type) | 剪贴板中数据变更回调函数。                              |
43| void (\*Pasteboard_Finalize)(void\* context)                 | 剪贴板数据变更观察者对象销毁时，释放context上下文资源。 |
44
45## 开发步骤
46
471. 添加动态链接库。
48
49   ```CMake
50   # CMakeLists.txt中添加以下lib
51   libudmf.so
52   libpasteboard.so
53   ```
54
552. 引用头文件。
56
57   ```c
58   #include <cstdio>
59   #include <database/pasteboard/oh_pasteboard.h>
60   #include <database/udmf/udmf.h>
61   #include <database/udmf/uds.h>
62   ```
63
643. 定义剪贴板变化监听的回调函数。
65
66   ```c
67   // 定义剪贴板数据内容变更时的通知回调函数
68   static void Pasteboard_Notify_impl2(void* context, Pasteboard_NotifyType type)
69   {
70     printf("Pasteboard_NotifyType, type: %d", type);
71   }
72   // 定义剪贴板数据变更观察者对象销毁时的通知回调函数
73   static void Pasteboard_Finalize_impl2(void* context)
74   {
75     printf("callback: Pasteboard_Finalize");
76   }
77   ```
78
794. 订阅剪贴板变化。
80
81   ```c
82   // 1. 创建一个剪贴板实例
83   OH_Pasteboard* pasteboard = OH_Pasteboard_Create();
84   // 2. 创建一个剪贴板数据变更观察者实例
85   OH_PasteboardObserver* observer = OH_PasteboardObserver_Create();
86   // 3. 将两个回调函数设置到观察者实例
87   OH_PasteboardObserver_SetData(observer, (void* )pasteboard, Pasteboard_Notify_impl2, Pasteboard_Finalize_impl2);
88   // 4. 设置对剪贴板本端数据变化的订阅
89   OH_Pasteboard_Subscribe(pasteboard, NOTIFY_LOCAL_DATA_CHANGE, observer);
90   ```
91
925. 向剪贴板写入数据。
93
94   ```c
95   // 1. 创建一个剪贴板实例
96   OH_Pasteboard* pasteboard = OH_Pasteboard_Create();
97
98   // 2. 创建OH_UdmfRecord对象，并向OH_UdmfRecord中添加文本类型数据
99   OH_UdsPlainText* plainText = OH_UdsPlainText_Create();
100   OH_UdsPlainText_SetContent(plainText, "Hello world!");
101   OH_UdmfRecord* record = OH_UdmfRecord_Create();
102   OH_UdmfRecord_AddPlainText(record, plainText);
103
104   // 3. 创建OH_UdmfData对象，并向OH_UdmfData中添加OH_UdmfRecord
105   OH_UdmfData* data = OH_UdmfData_Create();
106   OH_UdmfData_AddRecord(data, record);
107
108   // 4. 将数据写入剪贴板
109   OH_Pasteboard_SetData(pasteboard, data);
110
111   // 5. 使用完销毁指针
112   OH_UdsPlainText_Destroy(plainText);
113   OH_UdmfRecord_Destroy(record);
114   OH_UdmfData_Destroy(data);
115   OH_Pasteboard_Destroy(pasteboard);
116   ```
117
1186. 从剪贴板读取数据。
119
120   ```c
121   // 1. 创建一个剪贴板实例
122   OH_Pasteboard* pasteboard = OH_Pasteboard_Create();
123   // 2. 判断剪贴板中有是否有文本类型数据
124   bool hasPlainTextData = OH_Pasteboard_HasType(pasteboard, "text/plain");
125   if (hasPlainTextData) {
126     // 3. 从剪贴板中获取统一类型数据OH_UdmfData
127     int ret = 0;
128     OH_UdmfData* udmfData = OH_Pasteboard_GetData(pasteboard, &ret);
129     // 4. 从OH_UdmfData中获取第一个数据记录
130     OH_UdmfRecord* record = OH_UdmfData_GetRecord(udmfData, 0);
131     // 5. 从数据记录中获取文本数据内容
132     OH_UdsPlainText* plainText = OH_UdsPlainText_Create();
133     OH_UdmfRecord_GetPlainText(record, plainText);
134     const char* content = OH_UdsPlainText_GetContent(plainText);
135     printf("Get plain text success. content: %s", content);
136     // 5. 使用完销毁指针
137     OH_UdsPlainText_Destroy(plainText);
138     OH_UdmfData_Destroy(udmfData);
139   }
140   OH_Pasteboard_Destroy(pasteboard);
141   ```
142