1# Pasteboard
2
3
4## Overview
5
6The **Pasteboard** module supports copying and pasting multiple types of data, including plain text, HTML, URI, and pixel map.
7
8**Since**: 13
9
10
11## Summary
12
13
14### Files
15
16| Name| Description|
17| -------- | -------- |
18| [oh_pasteboard.h](oh__pasteboard_8h.md) | Provides data structure, enum types, and APIs for accessing the system pasteboard.|
19| [oh_pasteboard_err_code.h](oh__pasteboard__err__code_8h.md) | Defines the error code information of the pasteboard.|
20
21
22### Types
23
24| Name| Description|
25| -------- | -------- |
26| typedef enum [Pasteboard_NotifyType](#pasteboard_notifytype) [Pasteboard_NotifyType](#pasteboard_notifytype) | Defines an enum for data change types of the pasteboard. |
27| typedef void(\* [Pasteboard_Notify](#pasteboard_notify)) (void \*context, [Pasteboard_NotifyType](#pasteboard_notifytype) type) | Defines a callback to be invoked when the pasteboard content changes. |
28| typedef void(\* [Pasteboard_Finalize](#pasteboard_finalize)) (void \*context) | Defines a callback to be invoked to release the context when the pasteboard observer object is destroyed. |
29| typedef struct [OH_PasteboardObserver](#oh_pasteboardobserver) [OH_PasteboardObserver](#oh_pasteboardobserver) | Defines the pasteboard observer. |
30| typedef struct [OH_Pasteboard](#oh_pasteboard) [OH_Pasteboard](#oh_pasteboard) | Define the pasteboard object to operate the system pasteboard. |
31| typedef enum [PASTEBOARD_ErrCode](#pasteboard_errcode) [PASTEBOARD_ErrCode](#pasteboard_errcode) | Defines an enum for the error codes used in the **Pasteboard** module. |
32
33
34### Enums
35
36| Name| Description|
37| -------- | -------- |
38| [Pasteboard_NotifyType](#pasteboard_notifytype) { NOTIFY_LOCAL_DATA_CHANGE = 1, NOTIFY_REMOTE_DATA_CHANGE = 2 } | Enumerates the data change types of the pasteboard. |
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>} | Enumerates the error codes. |
40
41
42### Functions
43
44| Name| Description|
45| -------- | -------- |
46| [OH_PasteboardObserver](#oh_pasteboardobserver) \* [OH_PasteboardObserver_Create](#oh_pasteboardobserver_create) () | Creates an [OH_PasteboardObserver](#oh_pasteboardobserver) instance and a pointer to it. |
47| int [OH_PasteboardObserver_Destroy](#oh_pasteboardobserver_destroy) ([OH_PasteboardObserver](#oh_pasteboardobserver) \*observer) | Destroys an [OH_PasteboardObserver](#oh_pasteboardobserver) instance and a pointer to it. |
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) | Sets a callback for the pasteboard observer. |
49| [OH_Pasteboard](#oh_pasteboard) \* [OH_Pasteboard_Create](#oh_pasteboard_create) () | Creates an [OH_Pasteboard](#oh_pasteboard) instance and a pointer to it. |
50| void [OH_Pasteboard_Destroy](#oh_pasteboard_destroy) ([OH_Pasteboard](#oh_pasteboard) \*pasteboard) | Destroys an [OH_Pasteboard](#oh_pasteboard) instance. |
51| int [OH_Pasteboard_Subscribe](#oh_pasteboard_subscribe) ([OH_Pasteboard](#oh_pasteboard) \*pasteboard, int type, const [OH_PasteboardObserver](#oh_pasteboardobserver) \*observer) | Subscribes to the pasteboard observer. |
52| int [OH_Pasteboard_Unsubscribe](#oh_pasteboard_unsubscribe) ([OH_Pasteboard](#oh_pasteboard) \*pasteboard, int type, const [OH_PasteboardObserver](#oh_pasteboardobserver) \*observer) | Unsubscribes from the pasteboard observer. |
53| bool [OH_Pasteboard_IsRemoteData](#oh_pasteboard_isremotedata) ([OH_Pasteboard](#oh_pasteboard) \*pasteboard) | Checks whether the pasteboard data comes from remote devices. |
54| int [OH_Pasteboard_GetDataSource](#oh_pasteboard_getdatasource) ([OH_Pasteboard](#oh_pasteboard) \*pasteboard, char \*source, unsigned int len) | Obtains the pasteboard data source. |
55| bool [OH_Pasteboard_HasType](#oh_pasteboard_hastype) ([OH_Pasteboard](#oh_pasteboard) \*pasteboard, const char \*type) | Checks whether the pasteboard contains data of the specified type. |
56| bool [OH_Pasteboard_HasData](#oh_pasteboard_hasdata) ([OH_Pasteboard](#oh_pasteboard) \*pasteboard) | Checks whether the pasteboard contains data. |
57| OH_UdmfData \* [OH_Pasteboard_GetData](#oh_pasteboard_getdata) ([OH_Pasteboard](#oh_pasteboard) \*pasteboard, int \*status) | Obtains data from the pasteboard. |
58| int [OH_Pasteboard_SetData](#oh_pasteboard_setdata) ([OH_Pasteboard](#oh_pasteboard) \*pasteboard, OH_UdmfData \*data) | Writes the unified data object to the pasteboard. |
59| int [OH_Pasteboard_ClearData](#oh_pasteboard_cleardata) ([OH_Pasteboard](#oh_pasteboard) \*pasteboard) | Clears data from the pasteboard. |
60| char ** [OH_Pasteboard_GetMimeTypes](#oh_pasteboard_getmimetypes) ([OH_Pasteboard](#oh_pasteboard) \*pasteboard, unsigned int *count) | Obtains the MIME type from the pasteboard.  |
61
62
63## Type Description
64
65
66### OH_Pasteboard
67
68```
69typedef struct OH_Pasteboard OH_Pasteboard
70```
71**Description**
72
73Define the pasteboard object to operate the system pasteboard.
74
75**Since**: 13
76
77
78### OH_PasteboardObserver
79
80```
81typedef struct OH_PasteboardObserver OH_PasteboardObserver
82```
83**Description**
84
85Defines the pasteboard observer.
86
87**Since**: 13
88
89
90### PASTEBOARD_ErrCode
91
92```
93typedef enum PASTEBOARD_ErrCode PASTEBOARD_ErrCode
94```
95**Description**
96
97Enumerates the error codes.
98
99**Since**: 13
100
101
102### Pasteboard_Finalize
103
104```
105typedef void(* Pasteboard_Finalize) (void *context)
106```
107**Description**
108
109Defines a callback to be invoked to release the context when the pasteboard observer object is destroyed.
110
111**Since**: 13
112
113**Parameters**
114
115| Name| Description|
116| -------- | -------- |
117| context | Pointer to the context to release. |
118
119
120### Pasteboard_Notify
121
122```
123typedef void(* Pasteboard_Notify) (void *context, Pasteboard_NotifyType type)
124```
125**Description**
126
127Defines a callback to be invoked when the pasteboard content changes.
128
129**Since**: 13
130
131**Parameters**
132
133| Name| Description|
134| -------- | -------- |
135| context | Context, which is passed in by the [OH_PasteboardObserver_SetData](#oh_pasteboardobserver_setdata) function. |
136| type | Data change type. For details, see [Pasteboard_NotifyType](#pasteboard_notifytype). |
137
138
139### Pasteboard_NotifyType
140
141```
142typedef enum Pasteboard_NotifyType Pasteboard_NotifyType
143```
144**Description**
145
146Enumerates the data change types of the pasteboard.
147
148**Since**: 13
149
150
151## Enum Description
152
153
154### PASTEBOARD_ErrCode
155
156```
157enum PASTEBOARD_ErrCode
158```
159**Description**
160
161Enumerates the error codes.
162
163**Since**: 13
164
165| Value| Description|
166| -------- | -------- |
167| ERR_OK  | The operation is successful. |
168| ERR_PERMISSION_ERROR  | Permission verification has failed. |
169| ERR_INVALID_PARAMETER  | Invalid parameter. |
170| ERR_DEVICE_NOT_SUPPORTED  | The device capability is not supported. |
171| ERR_INNER_ERROR  | Internal error. |
172| ERR_BUSY  | System busy. |
173
174
175### Pasteboard_NotifyType
176
177```
178enum Pasteboard_NotifyType
179```
180**Description**
181
182Enumerates the data change types of the pasteboard.
183
184**Since**: 13
185
186| Value| Description|
187| -------- | -------- |
188| NOTIFY_LOCAL_DATA_CHANGE  | The pasteboard data of the local device is changed. |
189| NOTIFY_REMOTE_DATA_CHANGE  | The pasteboard data of a non-local device on the network is changed. |
190
191
192## Function Description
193
194
195### OH_Pasteboard_ClearData()
196
197```
198int OH_Pasteboard_ClearData (OH_Pasteboard * pasteboard)
199```
200**Description**
201
202Clears data from the pasteboard.
203
204**Since**: 13
205
206**Parameters**
207
208| Name| Description|
209| -------- | -------- |
210| pasteboard | Pointer to an [OH_Pasteboard](#oh_pasteboard) instance. |
211
212**Returns**
213
214Returns an error code. For details, see [PASTEBOARD_ErrCode](#pasteboard_errcode).<br>Returns **ERR_OK** if the operation is successful.<br>Returns **ERR_INVALID_PARAMETER** if an invalid parameter is passed in.
215
216**See**
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**Description**
229
230Creates an [OH_Pasteboard](#oh_pasteboard) instance and a pointer to it.
231
232**Since**: 13
233
234**Returns**
235
236Returns a pointer to the [OH_Pasteboard](#oh_pasteboard) instance created if the operation is successful; returns **nullptr** otherwise.
237
238**See**
239
240[OH_Pasteboard](#oh_pasteboard)
241
242
243### OH_Pasteboard_Destroy()
244
245```
246void OH_Pasteboard_Destroy (OH_Pasteboard * pasteboard)
247```
248**Description**
249
250Destroys an [OH_Pasteboard](_pasteboard.md#oh_pasteboard) instance.
251
252**Since**: 13
253
254**Parameters**
255
256| Name| Description|
257| -------- | -------- |
258| pasteboard | Pointer to an [OH_Pasteboard](#oh_pasteboard) instance. |
259
260**See**
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**Description**
271
272Obtains data from the pasteboard.
273
274**Since**: 13
275
276**Parameters**
277
278| Name| Description|
279| -------- | -------- |
280| pasteboard | Pointer to an [OH_Pasteboard](#oh_pasteboard) instance. |
281| status | Output parameter, indicating the error code of the operation. For details, see [PASTEBOARD_ErrCode](#pasteboard_errcode). |
282
283**Returns**
284
285Returns a pointer to the **OH_UdmfData** instance obtained if the operation is successful; returns **nullptr** otherwise.
286
287**See**
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**Description**
302
303Obtains the pasteboard data source.
304
305**Since**: 13
306
307**Parameters**
308
309| Name| Description|
310| -------- | -------- |
311| pasteboard | Pointer to an [OH_Pasteboard](#oh_pasteboard) instance. |
312| source | Output parameter, indicating the source string of the pasteboard data. |
313| len | Output parameter, indicating the length of the data source string. |
314
315**Returns**
316
317Returns an error code. For details, see [PASTEBOARD_ErrCode](#pasteboard_errcode).<br>Returns **ERR_OK** if the operation is successful.<br>Returns **ERR_INVALID_PARAMETER** if an invalid parameter is passed in.
318
319**See**
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**Description**
332
333Checks whether the pasteboard contains data.
334
335**Since**: 13
336
337**Parameters**
338
339| Name| Description|
340| -------- | -------- |
341| pasteboard | Pointer to an [OH_Pasteboard](#oh_pasteboard) instance. |
342
343**Returns**
344
345Returns a Boolean value indicating whether the pasteboard contains data. The value **true** means the pasteboard contains data; the value **false** means the opposite.
346
347**See**
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**Description**
358
359Checks whether the pasteboard contains data of the specified type.
360
361**Since**: 13
362
363**Parameters**
364
365| Name| Description|
366| -------- | -------- |
367| pasteboard | Pointer to an [OH_Pasteboard](#oh_pasteboard) instance. |
368| type | Data type to be checked. |
369
370**Returns**
371
372Returns a Boolean value indicating whether the pasteboard contains data of the specified type. The value **true** means the pasteboard contains data of the specified type; the value **false** means the opposite.
373
374**See**
375
376[OH_Pasteboard](#oh_pasteboard)
377
378
379### OH_Pasteboard_IsRemoteData()
380
381```
382bool OH_Pasteboard_IsRemoteData (OH_Pasteboard * pasteboard)
383```
384**Description**
385
386Checks whether the pasteboard data comes from remote devices.
387
388**Since**: 13
389
390**Parameters**
391
392| Name| Description|
393| -------- | -------- |
394| pasteboard | Pointer to an [OH_Pasteboard](#oh_pasteboard) instance. |
395
396**Returns**
397
398Returns a Boolean value indicating whether the data is from a remote device. The value **true** means the data is from a remote device. The value **false** means the data is from the local device.
399
400**See**
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**Description**
411
412Writes the unified data object to the pasteboard.
413
414**Since**: 13
415
416**Parameters**
417
418| Name| Description|
419| -------- | -------- |
420| pasteboard | Pointer to an [OH_Pasteboard](#oh_pasteboard) instance. |
421| data | Pointer to an **OH_UdmfData** instance. |
422
423**Returns**
424
425Returns an error code. For details, see [PASTEBOARD_ErrCode](#pasteboard_errcode).<br>Returns **ERR_OK** if the operation is successful.<br>Returns **ERR_INVALID_PARAMETER** if an invalid parameter is passed in.
426
427**See**
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**Description**
442
443Subscribes to the pasteboard observer.
444
445**Since**: 13
446
447**Parameters**
448
449| Name| Description|
450| -------- | -------- |
451| pasteboard | Pointer to an [OH_Pasteboard](#oh_pasteboard) instance. |
452| type | Subscribed data change type of the pasteboard. For details, see [Pasteboard_NotifyType](#pasteboard_notifytype). |
453| observer | Pointer to an [OH_PasteboardObserver](#oh_pasteboardobserver) instance. It specifies the callback to be invoked when the pasteboard data changes. For details, see [OH_PasteboardObserver](#oh_pasteboardobserver). |
454
455**Returns**
456
457Returns an error code. For details, see [PASTEBOARD_ErrCode](#pasteboard_errcode).<br>Returns **ERR_OK** if the operation is successful.<br>Returns **ERR_INVALID_PARAMETER** if an invalid parameter is passed in.
458
459**See**
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**Description**
476
477Unsubscribes from the pasteboard observer.
478
479**Since**: 13
480
481**Parameters**
482
483| Name| Description|
484| -------- | -------- |
485| pasteboard | Pointer to an [OH_Pasteboard](#oh_pasteboard) instance. |
486| type | Subscribed data change type of the pasteboard. For details, see [Pasteboard_NotifyType](#pasteboard_notifytype). |
487| observer | Pointer to an [OH_PasteboardObserver](#oh_pasteboardobserver) instance. It specifies the callback to be invoked when the pasteboard data changes. For details, see [OH_PasteboardObserver](#oh_pasteboardobserver). |
488
489**Returns**
490
491Returns an error code. For details, see [PASTEBOARD_ErrCode](#pasteboard_errcode).<br>Returns **ERR_OK** if the operation is successful.<br>Returns **ERR_INVALID_PARAMETER** if an invalid parameter is passed in.
492
493**See**
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**Description**
510
511Creates an [OH_PasteboardObserver](#oh_pasteboardobserver) instance and a pointer to it.
512
513**Since**: 13
514
515**Returns**
516
517Returns a pointer to the [OH_PasteboardObserver](#oh_pasteboardobserver) instance created if the operation is successful; returns **nullptr** otherwise. If this pointer is no longer required, use [OH_PasteboardObserver_Destroy](#oh_pasteboardobserver_destroy) to destroy it. Otherwise, memory leaks may occur.
518
519**See**
520
521[OH_PasteboardObserver](#oh_pasteboardobserver)
522
523
524### OH_PasteboardObserver_Destroy()
525
526```
527int OH_PasteboardObserver_Destroy (OH_PasteboardObserver * observer)
528```
529**Description**
530
531Destroys an [OH_PasteboardObserver](_pasteboard.md#oh_pasteboardobserver) instance.
532
533**Since**: 13
534
535**Parameters**
536
537| Name| Description|
538| -------- | -------- |
539| observer | Pointer to an [OH_PasteboardObserver](#oh_pasteboardobserver) instance. |
540
541**Returns**
542
543Returns an error code. For details, see [PASTEBOARD_ErrCode](#pasteboard_errcode).<br>Returns **ERR_OK** if the operation is successful.<br>Returns **ERR_INVALID_PARAMETER** if an invalid parameter is passed in.
544
545**See**
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**Description**
558
559Sets a callback for the pasteboard observer.
560
561**Since**: 13
562
563**Parameters**
564
565| Name| Description|
566| -------- | -------- |
567| observer | Pointer to an [OH_PasteboardObserver](#oh_pasteboardobserver) instance. |
568| context | Pointer to the context data, which is passed to [Pasteboard_Notify](#pasteboard_notify) as the first parameter. |
569| callback | Callback to be invoked when the data changes. For details, see [Pasteboard_Notify](#pasteboard_notify). |
570| finalize | Optional callback, which can be used to release context data when the pasteboard observer is destroyed. For details, see [Pasteboard_Finalize](#pasteboard_finalize). |
571
572**Returns**
573
574Returns an error code. For details, see [PASTEBOARD_ErrCode](#pasteboard_errcode).<br>Returns **ERR_OK** if the operation is successful.<br>Returns **ERR_INVALID_PARAMETER** if an invalid parameter is passed in.
575
576**See**
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**Description**
590
591Obtains the MIME type from the pasteboard.
592
593**Since**: 14
594
595**Parameters**
596
597| Name| Description|
598| -------- | -------- |
599| pasteboard | Pointer to an [OH_Pasteboard](#oh_pasteboard) instance.  |
600| count | Pointer to the number of uniform data types obtained.  |
601
602**Returns**
603
604Returns the MIME type obtained if the operation is successful; returns **nullptr** otherwise.
605
606The lifecycle of the object returned by this API is managed by the input parameter object **pasteboard**. When the application calls [OH_Pasteboard_Destroy](#oh_pasteboard_destroy) to destroy **pasteboard**, the result returned by this API is released synchronously.
607
608The **pasteboard** object saves only the latest result and the historical results obtained by the API become invalid.
609
610**See**
611
612[OH_Pasteboard](#oh_pasteboard)
613