1# Pasteboard
2
3
4## 概述
5
6系统剪贴板支持复制和粘贴多种类型的数据。 可以使用此模块接口操作纯文本、HTML、URI、像素图片等其他类型的数据。
7
8**起始版本：** 13
9
10
11## 汇总
12
13
14### 文件
15
16| 名称 | 描述 |
17| -------- | -------- |
18| [oh_pasteboard.h](oh__pasteboard_8h.md) | 提供访问系统剪贴板的接口、数据结构、枚举类型。 |
19| [oh_pasteboard_err_code.h](oh__pasteboard__err__code_8h.md) | 声明剪贴板框架错误码信息。 |
20
21
22### 类型定义
23
24| 名称 | 描述 |
25| -------- | -------- |
26| typedef enum [Pasteboard_NotifyType](#pasteboard_notifytype) [Pasteboard_NotifyType](#pasteboard_notifytype) | 剪贴板的数据变更类型。  |
27| typedef void(\* [Pasteboard_Notify](#pasteboard_notify)) (void \*context, [Pasteboard_NotifyType](#pasteboard_notifytype) type) | 定义剪贴板内容变更时触发的回调函数。  |
28| typedef void(\* [Pasteboard_Finalize](#pasteboard_finalize)) (void \*context) | 定义用于释放上下文的回调函数，剪贴板数据变更观察者对象销毁时触发。  |
29| typedef struct [OH_PasteboardObserver](#oh_pasteboardobserver) [OH_PasteboardObserver](#oh_pasteboardobserver) | 定义剪贴板数据变更观察者。  |
30| typedef struct [OH_Pasteboard](#oh_pasteboard) [OH_Pasteboard](#oh_pasteboard) | 定义剪贴板对象，用以操作系统剪贴板。  |
31| typedef enum [PASTEBOARD_ErrCode](#pasteboard_errcode) [PASTEBOARD_ErrCode](#pasteboard_errcode) | 错误码信息。  |
32
33
34### 枚举
35
36| 名称 | 描述 |
37| -------- | -------- |
38| [Pasteboard_NotifyType](#pasteboard_notifytype) { NOTIFY_LOCAL_DATA_CHANGE = 1, NOTIFY_REMOTE_DATA_CHANGE = 2 } | 剪贴板的数据变更类型。  |
39| [PASTEBOARD_ErrCode](#pasteboard_errcode) {<br/>ERR_OK = 0, ERR_PERMISSION_ERROR = 201, ERR_INVALID_PARAMETER = 401, ERR_DEVICE_NOT_SUPPORTED = 801,<br/>ERR_INNER_ERROR = 12900000, ERR_BUSY = 12900003<br/>} | 错误码信息。  |
40
41
42### 函数
43
44| 名称 | 描述 |
45| -------- | -------- |
46| [OH_PasteboardObserver](#oh_pasteboardobserver) \* [OH_PasteboardObserver_Create](#oh_pasteboardobserver_create) () | 创建一个剪贴板数据变更观察者[OH_PasteboardObserver](#oh_pasteboardobserver)指针及实例对象。  |
47| int [OH_PasteboardObserver_Destroy](#oh_pasteboardobserver_destroy) ([OH_PasteboardObserver](#oh_pasteboardobserver) \*observer) | 销毁剪贴板数据变更观察者[OH_PasteboardObserver](#oh_pasteboardobserver)指针指向的实例对象。  |
48| int [OH_PasteboardObserver_SetData](#oh_pasteboardobserver_setdata) ([OH_PasteboardObserver](#oh_pasteboardobserver) \*observer, void \*context, const [Pasteboard_Notify](#pasteboard_notify) callback, const [Pasteboard_Finalize](#pasteboard_finalize) finalize) | 向剪贴板数据变更观察者设置回调函数。  |
49| [OH_Pasteboard](#oh_pasteboard) \* [OH_Pasteboard_Create](#oh_pasteboard_create) () | 创建剪贴板[OH_Pasteboard](#oh_pasteboard)指针及实例对象。  |
50| void [OH_Pasteboard_Destroy](#oh_pasteboard_destroy) ([OH_Pasteboard](#oh_pasteboard) \*pasteboard) | 销毁剪贴板[OH_Pasteboard](#oh_pasteboard)实例对象。  |
51| int [OH_Pasteboard_Subscribe](#oh_pasteboard_subscribe) ([OH_Pasteboard](#oh_pasteboard) \*pasteboard, int type, const [OH_PasteboardObserver](#oh_pasteboardobserver) \*observer) | 订阅剪贴板的数据变更事件。  |
52| int [OH_Pasteboard_Unsubscribe](#oh_pasteboard_unsubscribe) ([OH_Pasteboard](#oh_pasteboard) \*pasteboard, int type, const [OH_PasteboardObserver](#oh_pasteboardobserver) \*observer) | 取消对剪贴板数据变更事件的订阅。  |
53| bool [OH_Pasteboard_IsRemoteData](#oh_pasteboard_isremotedata) ([OH_Pasteboard](#oh_pasteboard) \*pasteboard) | 判断剪贴板中的数据是否来自远端设备。  |
54| int [OH_Pasteboard_GetDataSource](#oh_pasteboard_getdatasource) ([OH_Pasteboard](#oh_pasteboard) \*pasteboard, char \*source, unsigned int len) | 获取剪贴板中数据的数据源。  |
55| bool [OH_Pasteboard_HasType](#oh_pasteboard_hastype) ([OH_Pasteboard](#oh_pasteboard) \*pasteboard, const char \*type) | 判断剪贴板中是否有指定类型的数据。  |
56| bool [OH_Pasteboard_HasData](#oh_pasteboard_hasdata) ([OH_Pasteboard](#oh_pasteboard) \*pasteboard) | 判断剪贴板中是否有数据。  |
57| OH_UdmfData \* [OH_Pasteboard_GetData](#oh_pasteboard_getdata) ([OH_Pasteboard](#oh_pasteboard) \*pasteboard, int \*status) | 获取剪贴板中的数据。  |
58| int [OH_Pasteboard_SetData](#oh_pasteboard_setdata) ([OH_Pasteboard](#oh_pasteboard) \*pasteboard, OH_UdmfData \*data) | 将统一数据对象数据写入剪贴板。  |
59| int [OH_Pasteboard_ClearData](#oh_pasteboard_cleardata) ([OH_Pasteboard](#oh_pasteboard) \*pasteboard) | 清空剪贴板中的数据。  |
60| char ** [OH_Pasteboard_GetMimeTypes](#oh_pasteboard_getmimetypes) ([OH_Pasteboard](#oh_pasteboard) \*pasteboard, unsigned int *count) | 获取剪切板中的MIME类型。  |
61
62
63## 类型定义说明
64
65
66### OH_Pasteboard
67
68```
69typedef struct OH_Pasteboard OH_Pasteboard
70```
71**描述：**
72
73定义剪贴板对象，用以操作系统剪贴板。
74
75**起始版本：** 13
76
77
78### OH_PasteboardObserver
79
80```
81typedef struct OH_PasteboardObserver OH_PasteboardObserver
82```
83**描述：**
84
85定义剪贴板数据变更观察者。
86
87**起始版本：** 13
88
89
90### PASTEBOARD_ErrCode
91
92```
93typedef enum PASTEBOARD_ErrCode PASTEBOARD_ErrCode
94```
95**描述：**
96
97错误码信息。
98
99**起始版本：** 13
100
101
102### Pasteboard_Finalize
103
104```
105typedef void(* Pasteboard_Finalize) (void *context)
106```
107**描述：**
108
109定义用于释放上下文的回调函数，剪贴板数据变更观察者对象销毁时触发。
110
111**起始版本：** 13
112
113**参数:**
114
115| 名称 | 描述 |
116| -------- | -------- |
117| context | 要释放的上下文指针。  |
118
119
120### Pasteboard_Notify
121
122```
123typedef void(* Pasteboard_Notify) (void *context, Pasteboard_NotifyType type)
124```
125**描述：**
126
127定义剪贴板内容变更时触发的回调函数。
128
129**起始版本：** 13
130
131**参数:**
132
133| 名称 | 描述 |
134| -------- | -------- |
135| context | 上下文信息，由函数[OH_PasteboardObserver_SetData](#oh_pasteboardobserver_setdata)传入。  |
136| type | 数据变更的类型。详见：[Pasteboard_NotifyType](#pasteboard_notifytype)。  |
137
138
139### Pasteboard_NotifyType
140
141```
142typedef enum Pasteboard_NotifyType Pasteboard_NotifyType
143```
144**描述：**
145
146剪贴板的数据变更类型。
147
148**起始版本：** 13
149
150
151## 枚举类型说明
152
153
154### PASTEBOARD_ErrCode
155
156```
157enum PASTEBOARD_ErrCode
158```
159**描述：**
160
161错误码信息。
162
163**起始版本：** 13
164
165| 枚举值 | 描述 |
166| -------- | -------- |
167| ERR_OK  | 执行成功。  ||
168| ERR_PERMISSION_ERROR  | 权限校验失败。  ||
169| ERR_INVALID_PARAMETER  | 非法参数。  ||
170| ERR_DEVICE_NOT_SUPPORTED  | 设备能力不支持。  ||
171| ERR_INNER_ERROR  | 内部错误。  ||
172| ERR_BUSY  | 系统忙。  ||
173
174
175### Pasteboard_NotifyType
176
177```
178enum Pasteboard_NotifyType
179```
180**描述：**
181
182剪贴板的数据变更类型。
183
184**起始版本：** 13
185
186| 枚举值 | 描述 |
187| -------- | -------- |
188| NOTIFY_LOCAL_DATA_CHANGE  | 本地设备剪贴板数据变更。  ||
189| NOTIFY_REMOTE_DATA_CHANGE  | 组网内的非本地设备剪贴板数据变更。  ||
190
191
192## 函数说明
193
194
195### OH_Pasteboard_ClearData()
196
197```
198int OH_Pasteboard_ClearData (OH_Pasteboard * pasteboard)
199```
200**描述：**
201
202清空剪贴板中的数据。
203
204**起始版本：** 13
205
206**参数:**
207
208| 名称 | 描述 |
209| -------- | -------- |
210| pasteboard | 表示指向剪贴板[OH_Pasteboard](#oh_pasteboard)实例的指针。  |
211
212**返回：**
213
214返回执行的错误码。错误码定义详见[PASTEBOARD_ErrCode](#pasteboard_errcode)。 若返回ERR_OK，表示指向成功。 若返回ERR_INVALID_PARAMETER，表示传入了无效参数。
215
216**参见：**
217
218[OH_Pasteboard](#oh_pasteboard)
219
220[PASTEBOARD_ErrCode](#pasteboard_errcode)
221
222
223### OH_Pasteboard_Create()
224
225```
226OH_Pasteboard* OH_Pasteboard_Create ()
227```
228**描述：**
229
230创建剪贴板[OH_Pasteboard](#oh_pasteboard)指针及实例对象。
231
232**起始版本：** 13
233
234**返回：**
235
236执行成功则返回一个指向剪贴板[OH_Pasteboard](#oh_pasteboard)实例对象的指针，否则返回nulllptr。
237
238**参见：**
239
240[OH_Pasteboard](#oh_pasteboard)
241
242
243### OH_Pasteboard_Destroy()
244
245```
246void OH_Pasteboard_Destroy (OH_Pasteboard * pasteboard)
247```
248**描述：**
249
250销毁剪贴板[OH_Pasteboard](#oh_pasteboard)实例对象。
251
252**起始版本：** 13
253
254**参数:**
255
256| 名称 | 描述 |
257| -------- | -------- |
258| pasteboard | 表示指向剪贴板[OH_Pasteboard](#oh_pasteboard)实例的指针。  |
259
260**参见：**
261
262[OH_Pasteboard](#oh_pasteboard)
263
264
265### OH_Pasteboard_GetData()
266
267```
268OH_UdmfData* OH_Pasteboard_GetData (OH_Pasteboard * pasteboard, int * status )
269```
270**描述：**
271
272获取剪贴板中的数据。
273
274**起始版本：** 13
275
276**参数:**
277
278| 名称 | 描述 |
279| -------- | -------- |
280| pasteboard | 表示指向剪贴板[OH_Pasteboard](#oh_pasteboard)实例的指针。  |
281| status | 该参数是输出参数，表示执行的错误码。错误码定义详见[PASTEBOARD_ErrCode](#pasteboard_errcode)。  |
282
283**返回：**
284
285执行成功时返回统一数据对象**OH_UdmfData**实例的指针。否则返回空指针。
286
287**参见：**
288
289[OH_Pasteboard](#oh_pasteboard)
290
291OH_UdmfData
292
293[PASTEBOARD_ErrCode](#pasteboard_errcode)
294
295
296### OH_Pasteboard_GetDataSource()
297
298```
299int OH_Pasteboard_GetDataSource (OH_Pasteboard * pasteboard, char * source, unsigned int len )
300```
301**描述：**
302
303获取剪贴板中数据的数据源。
304
305**起始版本：** 13
306
307**参数:**
308
309| 名称 | 描述 |
310| -------- | -------- |
311| pasteboard | 表示指向剪贴板[OH_Pasteboard](#oh_pasteboard)实例的指针。  |
312| source | 该参数是输出参数，表示剪贴板中数据的数据源字符串。  |
313| len | 该参数是输出参数，表示数据源字符串的长度。  |
314
315**返回：**
316
317返回执行的错误码。错误码定义详见[PASTEBOARD_ErrCode](#pasteboard_errcode)。 若返回ERR_OK，表示指向成功。 若返回ERR_INVALID_PARAMETER，表示传入了无效参数。
318
319**参见：**
320
321[OH_Pasteboard](#oh_pasteboard)
322
323[PASTEBOARD_ErrCode](#pasteboard_errcode)
324
325
326### OH_Pasteboard_HasData()
327
328```
329bool OH_Pasteboard_HasData (OH_Pasteboard * pasteboard)
330```
331**描述：**
332
333判断剪贴板中是否有数据。
334
335**起始版本：** 13
336
337**参数:**
338
339| 名称 | 描述 |
340| -------- | -------- |
341| pasteboard | 表示指向剪贴板[OH_Pasteboard](#oh_pasteboard)实例的指针。  |
342
343**返回：**
344
345返回剪贴板中是否有数据。返回true表示剪贴板中有数据，返回false表示剪贴板中没有数据。
346
347**参见：**
348
349[OH_Pasteboard](#oh_pasteboard)
350
351
352### OH_Pasteboard_HasType()
353
354```
355bool OH_Pasteboard_HasType (OH_Pasteboard * pasteboard, const char * type )
356```
357**描述：**
358
359判断剪贴板中是否有指定类型的数据。
360
361**起始版本：** 13
362
363**参数:**
364
365| 名称 | 描述 |
366| -------- | -------- |
367| pasteboard | 表示指向剪贴板[OH_Pasteboard](#oh_pasteboard)实例的指针。  |
368| type | 表示要检查的数据类型。  |
369
370**返回：**
371
372返回剪贴板中是否有指定类型的数据。返回true表示剪贴板中包含指定类型的数据，返回false表示剪贴板中没有指定类型的数据。
373
374**参见：**
375
376[OH_Pasteboard](#oh_pasteboard)
377
378
379### OH_Pasteboard_IsRemoteData()
380
381```
382bool OH_Pasteboard_IsRemoteData (OH_Pasteboard * pasteboard)
383```
384**描述：**
385
386判断剪贴板中的数据是否来自远端设备。
387
388**起始版本：** 13
389
390**参数:**
391
392| 名称 | 描述 |
393| -------- | -------- |
394| pasteboard | 表示指向剪贴板[OH_Pasteboard](#oh_pasteboard)实例的指针。  |
395
396**返回：**
397
398返回剪贴板中的数据是否来自远端设备。返回true表示剪贴板中的数据来自远端设备，返回false表示剪贴板中数据来自本端设备。
399
400**参见：**
401
402[OH_Pasteboard](#oh_pasteboard)
403
404
405### OH_Pasteboard_SetData()
406
407```
408int OH_Pasteboard_SetData (OH_Pasteboard * pasteboard, OH_UdmfData * data )
409```
410**描述：**
411
412将统一数据对象数据写入剪贴板。
413
414**起始版本：** 13
415
416**参数:**
417
418| 名称 | 描述 |
419| -------- | -------- |
420| pasteboard | 表示指向剪贴板[OH_Pasteboard](#oh_pasteboard)实例的指针。  |
421| data | 表示指向统一数据对象**OH_UdmfData**实例的指针。  |
422
423**返回：**
424
425返回执行的错误码。错误码定义详见[PASTEBOARD_ErrCode](#pasteboard_errcode)。 若返回ERR_OK，表示指向成功。 若返回ERR_INVALID_PARAMETER，表示传入了无效参数。
426
427**参见：**
428
429[OH_Pasteboard](#oh_pasteboard)
430
431OH_UdmfData
432
433[PASTEBOARD_ErrCode](#pasteboard_errcode)
434
435
436### OH_Pasteboard_Subscribe()
437
438```
439int OH_Pasteboard_Subscribe (OH_Pasteboard * pasteboard, int type, const OH_PasteboardObserver * observer )
440```
441**描述：**
442
443订阅剪贴板的数据变更事件。
444
445**起始版本：** 13
446
447**参数:**
448
449| 名称 | 描述 |
450| -------- | -------- |
451| pasteboard | 表示指向剪贴板[OH_Pasteboard](#oh_pasteboard)实例的指针。  |
452| type | 表示订阅的剪贴板数据变更类型，详见：[Pasteboard_NotifyType](#pasteboard_notifytype)。  |
453| observer | 表示指向剪贴板数据变更观察者[OH_PasteboardObserver](#oh_pasteboardobserver)实例的指针。 它指定了剪贴板数据变更时触发的回调函数，详见：[OH_PasteboardObserver](#oh_pasteboardobserver)。  |
454
455**返回：**
456
457返回执行的错误码。错误码定义详见[PASTEBOARD_ErrCode](#pasteboard_errcode)。 若返回ERR_OK，表示指向成功。 若返回ERR_INVALID_PARAMETER，表示传入了无效参数。
458
459**参见：**
460
461[OH_Pasteboard](#oh_pasteboard)
462
463[OH_PasteboardObserver](#oh_pasteboardobserver)
464
465[Pasteboard_NotifyType](#pasteboard_notifytype)
466
467[PASTEBOARD_ErrCode](#pasteboard_errcode)
468
469
470### OH_Pasteboard_Unsubscribe()
471
472```
473int OH_Pasteboard_Unsubscribe (OH_Pasteboard * pasteboard, int type, const OH_PasteboardObserver * observer )
474```
475**描述：**
476
477取消对剪贴板数据变更事件的订阅。
478
479**起始版本：** 13
480
481**参数:**
482
483| 名称 | 描述 |
484| -------- | -------- |
485| pasteboard | 表示指向剪贴板[OH_Pasteboard](#oh_pasteboard)实例的指针。  |
486| type | 表示订阅的剪贴板数据变更类型，详见：[Pasteboard_NotifyType](#pasteboard_notifytype)。  |
487| observer | 表示指向剪贴板数据变更观察者[OH_PasteboardObserver](#oh_pasteboardobserver)实例的指针。 它指定了剪贴板数据变更时触发的回调函数，详见：[OH_PasteboardObserver](#oh_pasteboardobserver)。  |
488
489**返回：**
490
491返回执行的错误码。错误码定义详见[PASTEBOARD_ErrCode](#pasteboard_errcode)。 若返回ERR_OK，表示指向成功。 若返回ERR_INVALID_PARAMETER，表示传入了无效参数。
492
493**参见：**
494
495[OH_Pasteboard](#oh_pasteboard)
496
497[OH_PasteboardObserver](#oh_pasteboardobserver)
498
499[Pasteboard_NotifyType](#pasteboard_notifytype)
500
501[PASTEBOARD_ErrCode](#pasteboard_errcode)
502
503
504### OH_PasteboardObserver_Create()
505
506```
507OH_PasteboardObserver* OH_PasteboardObserver_Create ()
508```
509**描述：**
510
511创建一个剪贴板数据变更观察者[OH_PasteboardObserver](#oh_pasteboardobserver)指针及实例对象。
512
513**起始版本：** 13
514
515**返回：**
516
517执行成功时返回一个指向剪贴板数据变更观察者[OH_PasteboardObserver](#oh_pasteboardobserver)实例对象的指针，否则返回空指针。 当不再需要使用指针时，请使用[OH_PasteboardObserver_Destroy](#oh_pasteboardobserver_destroy)销毁实例对象，否则会导致内存泄漏。
518
519**参见：**
520
521[OH_PasteboardObserver](#oh_pasteboardobserver)
522
523
524### OH_PasteboardObserver_Destroy()
525
526```
527int OH_PasteboardObserver_Destroy (OH_PasteboardObserver * observer)
528```
529**描述：**
530
531销毁剪贴板数据变更观察者[OH_PasteboardObserver](#oh_pasteboardobserver)指针指向的实例对象。
532
533**起始版本：** 13
534
535**参数:**
536
537| 名称 | 描述 |
538| -------- | -------- |
539| observer | 表示指向剪贴板数据变更观察者[OH_PasteboardObserver](#oh_pasteboardobserver)实例的指针。  |
540
541**返回：**
542
543返回执行的错误码。错误码定义详见[PASTEBOARD_ErrCode](#pasteboard_errcode)。 若返回ERR_OK，表示指向成功。 若返回ERR_INVALID_PARAMETER，表示传入了无效参数。
544
545**参见：**
546
547[OH_PasteboardObserver](#oh_pasteboardobserver)
548
549[PASTEBOARD_ErrCode](#pasteboard_errcode)
550
551
552### OH_PasteboardObserver_SetData()
553
554```
555int OH_PasteboardObserver_SetData (OH_PasteboardObserver * observer, void * context, const Pasteboard_Notify callback, const Pasteboard_Finalize finalize )
556```
557**描述：**
558
559向剪贴板数据变更观察者设置回调函数。
560
561**起始版本：** 13
562
563**参数:**
564
565| 名称 | 描述 |
566| -------- | -------- |
567| observer | 表示指向剪贴板数据变更观察者[OH_PasteboardObserver](#oh_pasteboardobserver)实例的指针。  |
568| context | 表示指向上下文数据的指针，将作为第一个参数传入[Pasteboard_Notify](#pasteboard_notify)。  |
569| callback | 表示数据变更回调函数。详见：[Pasteboard_Notify](#pasteboard_notify)。  |
570| finalize | 表示可选的回调函数，可以用于剪贴板数据变更观察者销毁时释放上下文数据。详见：[Pasteboard_Finalize](#pasteboard_finalize)。  |
571
572**返回：**
573
574返回执行的错误码。错误码定义详见[PASTEBOARD_ErrCode](#pasteboard_errcode)。 若返回ERR_OK，表示指向成功。 若返回ERR_INVALID_PARAMETER，表示传入了无效参数。
575
576**参见：**
577
578[OH_PasteboardObserver](#oh_pasteboardobserver)
579
580[Pasteboard_Notify](#pasteboard_notify)
581
582[PASTEBOARD_ErrCode](#pasteboard_errcode)
583
584### OH_Pasteboard_GetMimeTypes()
585
586```
587char ** OH_Pasteboard_GetMimeTypes (OH_Pasteboard * pasteboard, unsigned int * count)
588```
589**描述：**
590
591获取剪切板中的MIME类型。
592
593**起始版本：** 14
594
595**参数:**
596
597| 名称 | 描述 |
598| -------- | -------- |
599| pasteboard | 表示指向剪贴板[OH_Pasteboard](#oh_pasteboard)实例的指针。  |
600| count | 该参数是输出参数，结果集中的类型数量会写入该变量。  |
601
602**返回：**
603
604执行成功时返回剪切板所有内容的MIME类型，否则返回nullptr。
605
606本接口返回对象的生命周期由入参对象pasteboard管理，应用调用[OH_Pasteboard_Destroy](#oh_pasteboard_destroy)销毁入参对象pasteboard时同步释放本接口返回的结果，不允许应用主动释放。
607
608入参对象pasteboard只保存本接口最新返回的结果，接口历史调用获得的结果将失效。
609
610**参见：**
611
612[OH_Pasteboard](#oh_pasteboard)
613