oh_pasteboard.h

概述

提供访问系统剪贴板的接口、数据结构、枚举类型。引用文件：<database/pasteboard/oh_pasteboard.h>

库： libpasteboard.so

系统能力： SystemCapability.MiscServices.Pasteboard

起始版本： 13

相关模块： Pasteboard

汇总

结构体

名称	typedef关键字	描述
Pasteboard_ProgressInfo	Pasteboard_ProgressInfo	定义进度上报的数据结构。
Pasteboard_GetDataParams	Pasteboard_GetDataParams	表示从剪贴板获取粘贴数据和进度时需要写入的参数。
OH_PasteboardObserver	OH_PasteboardObserver	定义剪贴板数据变更观察者。
OH_Pasteboard	OH_Pasteboard	定义剪贴板对象，用以操作系统剪贴板。

枚举

名称	typedef关键字	描述
Pasteboard_NotifyType	Pasteboard_NotifyType	剪贴板的数据变更类型。
Pasteboard_FileConflictOptions	Pasteboard_FileConflictOptions	定义文件拷贝冲突时的选项。
Pasteboard_ProgressIndicator	Pasteboard_ProgressIndicator	定义进度条指示选项，可选择是否采用系统默认进度显示。

函数

名称	typedef关键字	描述
typedef void (*OH_Pasteboard_ProgressListener)(Pasteboard_ProgressInfo* progressInfo)	OH_Pasteboard_ProgressListener	用于在不使用系统默认进度显示时，通知应用拷贝粘贴任务进度。
typedef void (*Pasteboard_Notify)(void* context, Pasteboard_NotifyType type)	Pasteboard_Notify	定义剪贴板内容变更时触发的回调函数。
typedef void (*Pasteboard_Finalize)(void* context)	Pasteboard_Finalize	定义用于释放上下文的回调函数，剪贴板数据变更观察者对象销毁时触发。
OH_PasteboardObserver* OH_PasteboardObserver_Create()	-	创建一个剪贴板数据变更观察者OH_PasteboardObserver指针及实例对象。
int OH_PasteboardObserver_Destroy(OH_PasteboardObserver* observer)	-	销毁剪贴板数据变更观察者OH_PasteboardObserver指针指向的实例对象。
int OH_PasteboardObserver_SetData(OH_PasteboardObserver* observer, void* context,const Pasteboard_Notify callback, const Pasteboard_Finalize finalize)	-	向剪贴板数据变更观察者设置回调函数。
OH_Pasteboard* OH_Pasteboard_Create()	-	创建剪贴板OH_Pasteboard指针及实例对象。
void OH_Pasteboard_Destroy(OH_Pasteboard* pasteboard)	-	销毁剪贴板OH_Pasteboard实例对象。
int OH_Pasteboard_Subscribe(OH_Pasteboard* pasteboard, int type, const OH_PasteboardObserver* observer)	-	订阅剪贴板的数据变更事件。
int OH_Pasteboard_Unsubscribe(OH_Pasteboard* pasteboard, int type, const OH_PasteboardObserver* observer)	-	取消对剪贴板数据变更事件的订阅。
bool OH_Pasteboard_IsRemoteData(OH_Pasteboard* pasteboard)	-	判断剪贴板中的数据是否来自远端设备。
int OH_Pasteboard_GetDataSource(OH_Pasteboard* pasteboard, char* source, unsigned int len)	-	获取剪贴板中数据的数据源。
bool OH_Pasteboard_HasType(OH_Pasteboard* pasteboard, const char* type)	-	判断剪贴板中是否有指定类型的数据。
bool OH_Pasteboard_HasData(OH_Pasteboard* pasteboard)	-	判断剪贴板中是否有数据。
OH_UdmfData* OH_Pasteboard_GetData(OH_Pasteboard* pasteboard, int* status)	-	获取剪贴板中的数据。
int OH_Pasteboard_SetData(OH_Pasteboard* pasteboard, OH_UdmfData* data)	-	将统一数据对象数据写入剪贴板。
int OH_Pasteboard_ClearData(OH_Pasteboard* pasteboard)	-	清空剪贴板中的数据。
char **OH_Pasteboard_GetMimeTypes(OH_Pasteboard *pasteboard, unsigned int *count)	-	获取剪贴板中的MIME类型。
Pasteboard_GetDataParams *OH_Pasteboard_GetDataParams_Create(void)	-	创建剪贴板Pasteboard_GetDataParams指针及实例对象。
void OH_Pasteboard_GetDataParams_Destroy(Pasteboard_GetDataParams* params)	-	销毁剪贴板Pasteboard_GetDataParams指针指向的实例对象。
void OH_Pasteboard_GetDataParams_SetProgressIndicator(Pasteboard_GetDataParams* params,Pasteboard_ProgressIndicator progressIndicator)	-	向剪贴板Pasteboard_GetDataParams设置进度条指示选项，可选择是否采用系统默认进度显示。
void OH_Pasteboard_GetDataParams_SetDestUri(Pasteboard_GetDataParams* params, const char* destUri, uint32_t destUriLen)	-	向剪贴板Pasteboard_GetDataParams设置拷贝文件时目标路径。若不支持文件处理，则不需要设置此参数；若应用涉及复杂文件处理策略或需要区分文件多路径存储，建议不设置此参数，由应用自行完成文件copy处理。
void OH_Pasteboard_GetDataParams_SetFileConflictOptions(Pasteboard_GetDataParams* params,Pasteboard_FileConflictOptions option)	-	向剪贴板Pasteboard_GetDataParams设置文件冲突选项。
void OH_Pasteboard_GetDataParams_SetProgressListener(Pasteboard_GetDataParams* params,const OH_Pasteboard_ProgressListener listener)	-	向剪贴板Pasteboard_GetDataParams设置进度上报回调函数。
int OH_Pasteboard_ProgressInfo_GetProgress(Pasteboard_ProgressInfo* progressInfo)	-	从Pasteboard_ProgressInfo获取粘贴进度。
void OH_Pasteboard_ProgressCancel(Pasteboard_GetDataParams* params)	-	定义取消函数，用于在获取粘贴数据时取消正在进行的粘贴动作。
OH_UdmfData* OH_Pasteboard_GetDataWithProgress(OH_Pasteboard* pasteboard, Pasteboard_GetDataParams* params,int* status)	-	获取剪贴板的数据以及粘贴进度，不支持对文件夹的拷贝。
uint32_t OH_Pasteboard_GetChangeCount(OH_Pasteboard *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

参数：

参数项	描述
OH_PasteboardObserver* observer	表示指向剪贴板数据变更观察者OH_PasteboardObserver实例的指针。
void* context	表示指向上下文数据的指针，将作为第一个参数传入Pasteboard_Notify。
const Pasteboard_Notify callback	表示数据变更回调函数。详见：Pasteboard_Notify。
const Pasteboard_Finalize finalize	表示可选的回调函数，可以用于剪贴板数据变更观察者销毁时释放上下文数据。详见：Pasteboard_Finalize。

返回：

类型	说明
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* pasteboard	表示指向剪贴板OH_Pasteboard实例的指针。
int type	表示订阅的剪贴板数据变更类型，详见：Pasteboard_NotifyType。
const OH_PasteboardObserver* observer	表示指向剪贴板数据变更观察者OH_PasteboardObserver实例的指针。它指定了剪贴板数据变更时触发的回调函数，详见：OH_PasteboardObserver。

返回：

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

OH_Pasteboard_Unsubscribe()

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

描述：

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

起始版本： 13

参数：

参数项	描述
OH_Pasteboard* pasteboard	表示指向剪贴板OH_Pasteboard实例的指针。
int type	表示订阅的剪贴板数据变更类型，详见：Pasteboard_NotifyType。
const OH_PasteboardObserver* observer	表示指向剪贴板数据变更观察者OH_PasteboardObserver实例的指针。它指定了剪贴板数据变更时触发的回调函数，详见：OH_PasteboardObserver。

返回：

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

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* pasteboard	表示指向剪贴板OH_Pasteboard实例的指针。
char* source	表示用于存放剪贴板数据数据源实例的指针，开发者需在调用接口前申请指针指向的内存。
unsigned int len	表示source指针对应的内存长度，当内存长度不足时调用接口会失败，建议长度：128。

返回：

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

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实例的指针。

返回：

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

OH_Pasteboard_ClearData()

int OH_Pasteboard_ClearData(OH_Pasteboard* pasteboard)

描述：

清空剪贴板中的数据。

起始版本： 13

参数：

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

返回：

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

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

参数：

参数项	描述
Pasteboard_GetDataParams* params	表示指向剪贴板OH_Pasteboard_GetDataParams的指针。
const char* destUri	定义拷贝文件目标路径。
uint32_t destUriLen	定义拷贝文件目标路径长度。

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_Pasteboard* pasteboard	表示指向剪贴板OH_Pasteboard实例的指针。
Pasteboard_GetDataParams* params	表示指向剪贴板OH_Pasteboard_GetDataParams的指针。
int* status	该参数是输出参数，表示执行的错误码。错误码定义详见PASTEBOARD_ErrCode。

返回：

类型	说明
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开始计数。对同一内容连续多次复制会被视作多次更改，每次复制均会导致内容变化次数增加。

你可能感兴趣的鸿蒙文章

harmony 鸿蒙Basic Services Kit（基础服务）

harmony 鸿蒙DeviceInfo

harmony 鸿蒙OH_Print

harmony 鸿蒙Print_Margin

harmony 鸿蒙Print_PageSize

harmony 鸿蒙Print_PrintAttributes

harmony 鸿蒙Print_PrintDocCallback

harmony 鸿蒙Print_Range

harmony 鸿蒙TimeService

harmony 鸿蒙ohscan.h