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