harmony 鸿蒙oh_pasteboard.h

2025-06-15
浏览 (2)

oh_pasteboard.h

概述

提供访问系统剪贴板的接口、数据结构、枚举类型。引用文件：

库： libpasteboard.so

系统能力： SystemCapability.MiscServices.Pasteboard

起始版本： 13

相关模块： Pasteboard

汇总

结构体

枚举

函数

枚举类型说明

Pasteboard_NotifyType

enum Pasteboard_NotifyType

描述：

剪贴板的数据变更类型。

起始版本： 13

|枚举项|描述| |–|–| |NOTIFY_LOCAL_DATA_CHANGE = 1|本地设备剪贴板数据变更。| |NOTIFY_REMOTE_DATA_CHANGE = 2|组网内的非本地设备剪贴板数据变更。|

Pasteboard_FileConflictOptions

enum Pasteboard_FileConflictOptions

描述：

定义文件拷贝冲突时的选项。

起始版本： 15

|枚举项|描述| |–|–| |PASTEBOARD_OVERWRITE = 0|目标路径存在同文件名时覆盖。| |PASTEBOARD_SKIP = 1|目标路径存在同文件名时跳过。|

Pasteboard_ProgressIndicator

enum Pasteboard_ProgressIndicator

描述：

定义进度条指示选项，可选择是否采用系统默认进度显示。

起始版本： 15

|枚举项|描述| |–|–| |PASTEBOARD_NONE = 0|不采用系统默认进度显示。| |PASTEBOARD_DEFAULT = 1|采用系统默认进度显示。|

函数说明

OH_Pasteboard_ProgressListener()

typedef void (*OH_Pasteboard_ProgressListener)(Pasteboard_ProgressInfo* progressInfo)

描述：

用于在不使用系统默认进度显示时，通知应用拷贝粘贴任务进度。

起始版本： 15

参数：

|参数项|描述| |–|–| |Pasteboard_ProgressInfo* progressInfo|定义进度上报的数据结构，且仅当进度指示选项Pasteboard_ProgressInfo设置为NONE时才会上报此信息。|

Pasteboard_Notify()

typedef void (*Pasteboard_Notify)(void* context, Pasteboard_NotifyType type)

描述：

定义剪贴板内容变更时触发的回调函数。

起始版本： 13

参数：

|参数项|描述| |–|–| |void* context|上下文信息，由函数OH_PasteboardObserver_SetData传入。| |Pasteboard_NotifyType type|数据变更的类型。详见：Pasteboard_NotifyType。|

Pasteboard_Finalize()

typedef void (*Pasteboard_Finalize)(void* context)

描述：

定义用于释放上下文的回调函数，剪贴板数据变更观察者对象销毁时触发。

起始版本： 13

参数：

|参数项|描述| |–|–| |void* context|要释放的上下文指针。|

OH_PasteboardObserver_Create()

OH_PasteboardObserver* OH_PasteboardObserver_Create()

描述：

创建一个剪贴板数据变更观察者OH_PasteboardObserver指针及实例对象。

起始版本： 13

返回：

|类型|说明| |–|–| |OH_PasteboardObserver*|执行成功时返回一个指向剪贴板数据变更观察者OH_PasteboardObserver实例对象的指针，否则返回空指针。
当不再需要使用指针时，请使用OH_PasteboardObserver_Destroy销毁实例对象，否则会导致内存泄漏。|

OH_PasteboardObserver_Destroy()

int OH_PasteboardObserver_Destroy(OH_PasteboardObserver* observer)

描述：

销毁剪贴板数据变更观察者OH_PasteboardObserver指针指向的实例对象。

起始版本： 13

参数：

|参数项|描述| |–|–| |OH_PasteboardObserver* observer|表示指向剪贴板数据变更观察者OH_PasteboardObserver实例的指针。|

返回：

|类型|说明 | |–|————————————————————————————————————————————————————————————————————————————-| |int|返回执行的错误码。错误码定义详见PASTEBOARD_ErrCode。
若返回ERR_OK，表示指向成功。
若返回ERR_INVALID_PARAMETER，表示传入了无效参数。|

OH_PasteboardObserver_SetData()

int OH_PasteboardObserver_SetData(OH_PasteboardObserver* observer, void* context,const Pasteboard_Notify callback, const Pasteboard_Finalize finalize)

描述：

向剪贴板数据变更观察者设置回调函数。

起始版本： 13

参数：

返回：

|类型|说明| |–|–| |int|返回执行的错误码。错误码定义详见PASTEBOARD_ErrCode。
若返回ERR_OK，表示指向成功。
若返回ERR_INVALID_PARAMETER，表示传入了无效参数。|

OH_Pasteboard_Create()

OH_Pasteboard* OH_Pasteboard_Create()

描述：

创建剪贴板OH_Pasteboard指针及实例对象。

起始版本： 13

返回：

|类型|说明| |–|–| |OH_Pasteboard*|执行成功则返回一个指向剪贴板OH_Pasteboard实例对象的指针，否则返回nulllptr。|

OH_Pasteboard_Destroy()

void OH_Pasteboard_Destroy(OH_Pasteboard* pasteboard)

描述：

销毁剪贴板OH_Pasteboard实例对象。

起始版本： 13

参数：

|参数项|描述| |–|–| |OH_Pasteboard* pasteboard|表示指向剪贴板OH_Pasteboard实例的指针。|

OH_Pasteboard_Subscribe()

int OH_Pasteboard_Subscribe(OH_Pasteboard* pasteboard, int type, const OH_PasteboardObserver* observer)

描述：

订阅剪贴板的数据变更事件。

起始版本： 13

参数：

返回：

OH_Pasteboard_Unsubscribe()

int OH_Pasteboard_Unsubscribe(OH_Pasteboard* pasteboard, int type, const OH_PasteboardObserver* observer)

描述：

取消对剪贴板数据变更事件的订阅。

起始版本： 13

参数：

返回：

OH_Pasteboard_IsRemoteData()

bool OH_Pasteboard_IsRemoteData(OH_Pasteboard* pasteboard)

描述：

判断剪贴板中的数据是否来自远端设备。

起始版本： 13

参数：

|参数项|描述| |–|–| |OH_Pasteboard* pasteboard|表示指向剪贴板OH_Pasteboard实例的指针。|

返回：

|类型|说明| |–|–| |bool|返回剪贴板中的数据是否来自远端设备。返回true表示剪贴板中的数据来自远端设备，返回false表示剪贴板中数据来自本端设备。|

OH_Pasteboard_GetDataSource()

int OH_Pasteboard_GetDataSource(OH_Pasteboard* pasteboard, char* source, unsigned int len)

描述：

获取剪贴板中数据的数据源。

起始版本： 13

参数：

返回：

OH_Pasteboard_HasType()

bool OH_Pasteboard_HasType(OH_Pasteboard* pasteboard, const char* type)

描述：

判断剪贴板中是否有指定类型的数据。

起始版本： 13

参数：

|参数项|描述| |–|–| |OH_Pasteboard* pasteboard|表示指向剪贴板OH_Pasteboard实例的指针。| |const char* type|表示要检查的数据类型。包含剪贴板基础数据类型与自定义数据类型，其中剪贴板基础数据类型有：”text/plain”、”text/html”、”text/uri”、”text/want”和”pixelMap”。|

返回：

|类型|说明| |–|–| |bool|返回剪贴板中是否有指定类型的数据。返回true表示剪贴板中包含指定类型的数据，返回false表示剪贴板中没有指定类型的数据。|

OH_Pasteboard_HasData()

bool OH_Pasteboard_HasData(OH_Pasteboard* pasteboard)

描述：

判断剪贴板中是否有数据。

起始版本： 13

参数：

|参数项|描述| |–|–| |OH_Pasteboard* pasteboard|表示指向剪贴板OH_Pasteboard实例的指针。|

返回：

|类型|说明| |–|–| |bool|返回剪贴板中是否有数据。返回true表示剪贴板中有数据，返回false表示剪贴板中没有数据。|

OH_Pasteboard_GetData()

OH_UdmfData* OH_Pasteboard_GetData(OH_Pasteboard* pasteboard, int* status)

描述：

获取剪贴板中的数据。

起始版本： 13

参数：

|参数项|描述| |–|–| |OH_Pasteboard* pasteboard|表示指向剪贴板OH_Pasteboard实例的指针。| |int* status|该参数是输出参数，表示执行的错误码。错误码定义详见PASTEBOARD_ErrCode。|

返回：

|类型|说明| |–|–| |OH_UdmfData*|执行成功时返回统一数据对象OH_UdmfData实例的指针。否则返回空指针。|

OH_Pasteboard_SetData()

int OH_Pasteboard_SetData(OH_Pasteboard* pasteboard, OH_UdmfData* data)

描述：

将统一数据对象数据写入剪贴板。

起始版本： 13

参数：

|参数项|描述| |–|–| |OH_Pasteboard* pasteboard|表示指向剪贴板OH_Pasteboard实例的指针。| |OH_UdmfData* data|表示指向统一数据对象OH_UdmfData实例的指针。|

返回：

OH_Pasteboard_ClearData()

int OH_Pasteboard_ClearData(OH_Pasteboard* pasteboard)

描述：

清空剪贴板中的数据。

起始版本： 13

参数：

|参数项|描述| |–|–| |OH_Pasteboard* pasteboard|表示指向剪贴板OH_Pasteboard实例的指针。|

返回：

OH_Pasteboard_GetMimeTypes()

char **OH_Pasteboard_GetMimeTypes(OH_Pasteboard *pasteboard, unsigned int *count)

描述：

获取剪贴板中的MIME类型。

起始版本： 14

参数：

|参数项|描述| |–|–| |OH_Pasteboard *pasteboard|表示指向剪贴板OH_Pasteboard实例的指针。| |unsigned int *count|该参数是输出参数，结果集中的类型数量会写入该变量。|

返回：

|类型|说明| |–|–| |char|执行成功时返回剪贴板所有内容的MIME类型，否则返回nullptr。|

OH_Pasteboard_GetDataParams_Create()

Pasteboard_GetDataParams *OH_Pasteboard_GetDataParams_Create(void)

描述：

创建剪贴板Pasteboard_GetDataParams指针及实例对象。

起始版本： 15

返回：

|类型|说明| |–|–| |Pasteboard_GetDataParams|执行成功时返回一个指向剪贴板Pasteboard_GetDataParams实例对象的指针，否则返回空指针。当不再需要使用指针时，
请使用OH_Pasteboard_GetDataParams_Destroy销毁实例对象，否则会导致内存泄漏。|

OH_Pasteboard_GetDataParams_Destroy()

void OH_Pasteboard_GetDataParams_Destroy(Pasteboard_GetDataParams* params)

描述：

销毁剪贴板Pasteboard_GetDataParams指针指向的实例对象。

起始版本： 15

参数：

|参数项|描述| |–|–| |Pasteboard_GetDataParams* params|表示指向剪贴板OH_Pasteboard_GetDataParams的指针。|

OH_Pasteboard_GetDataParams_SetProgressIndicator()

void OH_Pasteboard_GetDataParams_SetProgressIndicator(Pasteboard_GetDataParams* params,Pasteboard_ProgressIndicator progressIndicator)

描述：

向剪贴板Pasteboard_GetDataParams设置进度条指示选项，可选择是否采用系统默认进度显示。

起始版本： 15

参数：

|参数项|描述| |–|–| |Pasteboard_GetDataParams* params|表示指向剪贴板OH_Pasteboard_GetDataParams的指针。| |Pasteboard_ProgressIndicator progressIndicator|定义进度条指示选项。|

OH_Pasteboard_GetDataParams_SetDestUri()

void OH_Pasteboard_GetDataParams_SetDestUri(Pasteboard_GetDataParams* params, const char* destUri, uint32_t destUriLen)

描述：

设置拷贝文件时目标路径。若不支持文件处理，则不需要设置此参数；若应用涉及复杂文件处理策略或需要区分文件多路径存储，建议不设置此参数，由应用自行完成文件copy处理。

起始版本： 15

参数：

OH_Pasteboard_GetDataParams_SetFileConflictOptions()

void OH_Pasteboard_GetDataParams_SetFileConflictOptions(Pasteboard_GetDataParams* params,Pasteboard_FileConflictOptions option)

描述：

向剪贴板Pasteboard_GetDataParams设置文件冲突选项。

起始版本： 15

参数：

|参数项|描述| |–|–| |Pasteboard_GetDataParams* params|表示指向剪贴板OH_Pasteboard_GetDataParams的指针。| |Pasteboard_FileConflictOptions option|定义文件拷贝冲突时的选项，默认为PASTEBOARD_OVERWRITE。|

OH_Pasteboard_GetDataParams_SetProgressListener()

void OH_Pasteboard_GetDataParams_SetProgressListener(Pasteboard_GetDataParams* params,const OH_Pasteboard_ProgressListener listener)

描述：

向剪贴板Pasteboard_GetDataParams设置进度上报回调函数。

起始版本： 15

参数：

|参数项 |描述| |———————————————————————————-|–| |Pasteboard_GetDataParams* params |表示指向剪贴板OH_Pasteboard_GetDataParams的指针。| |const OH_Pasteboard_ProgressListener listener|表示进度上报回调函数。|

OH_Pasteboard_ProgressInfo_GetProgress()

int OH_Pasteboard_ProgressInfo_GetProgress(Pasteboard_ProgressInfo* progressInfo)

描述：

从Pasteboard_ProgressInfo获取粘贴进度。

起始版本： 15

参数：

|参数项|描述| |–|–| |Pasteboard_ProgressInfo* progressInfo|表示指向剪贴板Pasteboard_ProgressInfo的指针。|

返回：

|类型|说明| |–|–| |int|返回粘贴进度百分比。|

OH_Pasteboard_ProgressCancel()

void OH_Pasteboard_ProgressCancel(Pasteboard_GetDataParams* params)

描述：

定义取消函数，用于在获取粘贴数据时取消正在进行的粘贴动作。

起始版本： 15

参数：

|参数项|描述| |–|–| |Pasteboard_GetDataParams* params|表示指向剪贴板OH_Pasteboard_GetDataParams的指针。|

OH_Pasteboard_GetDataWithProgress()

OH_UdmfData* OH_Pasteboard_GetDataWithProgress(OH_Pasteboard* pasteboard, Pasteboard_GetDataParams* params,int* status)

描述：

获取剪贴板的数据以及粘贴进度，不支持对文件夹的拷贝。

起始版本： 15

参数：

返回：

|类型|说明| |–|–| |OH_UdmfData*|执行成功时返回统一数据对象OH_PasteData实例的指针。否则返回空指针。|

OH_Pasteboard_GetChangeCount()

uint32_t OH_Pasteboard_GetChangeCount(OH_Pasteboard *pasteboard)

描述：

获取剪贴板内容的变化次数。

起始版本： 18

参数：

|参数项|描述| |–|–| |OH_Pasteboard *pasteboard|表示指向剪贴板OH_Pasteboard实例的指针。|

返回：

|类型|说明| |–|–| |uint32_t|执行成功时返回剪贴板内容的变化次数，否则返回0。
当剪贴板内容过期或调用OH_Pasteboard_ClearData等接口导致剪贴板内容为空时，内容变化次数不会因此改变。
系统重启或剪贴板服务异常重启时，剪贴板内容变化次数重新从0开始计数。对同一内容连续多次复制会被视作多次更改，每次复制均会导致内容变化次数增加。|