harmony 鸿蒙Pasteboard

OH_Pasteboard_Create()

OH_Pasteboard* OH_Pasteboard_Create ()

描述：

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

起始版本： 13

返回：

执行成功则返回一个指向剪贴板OH_Pasteboard实例对象的指针，否则返回nullptr。

参见：

OH_Pasteboard_Destroy()

void OH_Pasteboard_Destroy (OH_Pasteboard * pasteboard)

描述：

销毁剪贴板OH_Pasteboard实例对象。

起始版本： 13

参数:

名称	描述
pasteboard	表示指向剪贴板OH_Pasteboard实例的指针。

参见：

OH_Pasteboard_GetData()

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

描述：

获取剪贴板中的数据。

起始版本： 13

参数:

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

返回：

执行成功时返回统一数据对象OH_UdmfData实例的指针。否则返回空指针。

参见：

OH_UdmfData

OH_Pasteboard_GetDataSource()

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

描述：

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

起始版本： 13

参数:

名称	描述
pasteboard	表示指向剪贴板OH_Pasteboard实例的指针。
source	表示用于存放剪贴板数据数据源实例的指针，开发者需在调用接口前申请指针指向的内存。
len	表示source指针对应的内存长度，当内存长度不足时调用接口会失败，建议长度：128。

返回：

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

参见：

OH_Pasteboard_HasData()

bool OH_Pasteboard_HasData (OH_Pasteboard * pasteboard)

描述：

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

起始版本： 13

参数:

名称	描述
pasteboard	表示指向剪贴板OH_Pasteboard实例的指针。

返回：

返回剪贴板中是否有数据。返回true表示剪贴板中有数据，返回false表示剪贴板中没有数据。

参见：

OH_Pasteboard_HasType()

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

描述：

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

起始版本： 13

参数:

名称	描述
pasteboard	表示指向剪贴板OH_Pasteboard实例的指针。
type	表示要检查的数据类型。包含剪贴板基础数据类型与自定义数据类型，其中剪贴板基础数据类型有：`"text/plain"`、`"text/html"`、`"text/uri"`、`"text/want"`和`"pixelMap"`。

返回：

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

示例：

OH_Pasteboard* pasteboard = OH_Pasteboard_Create();
bool hasType = OH_Pasteboard_HasType(pasteboard, "text/plain");
OH_Pasteboard_Destory(pasteboard);

参见：

OH_Pasteboard_IsRemoteData()

bool OH_Pasteboard_IsRemoteData (OH_Pasteboard * pasteboard)

描述：

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

起始版本： 13

参数:

名称	描述
pasteboard	表示指向剪贴板OH_Pasteboard实例的指针。

返回：

返回剪贴板中的数据是否来自远端设备。返回true表示剪贴板中的数据来自远端设备，返回false表示剪贴板中数据来自本端设备。

参见：

OH_Pasteboard_SetData()

int OH_Pasteboard_SetData (OH_Pasteboard * pasteboard, OH_UdmfData * data )

描述：

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

起始版本： 13

参数:

名称	描述
pasteboard	表示指向剪贴板OH_Pasteboard实例的指针。
data	表示指向统一数据对象OH_UdmfData实例的指针。

返回：

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

参见：

OH_UdmfData

OH_Pasteboard_Subscribe()

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

描述：

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

起始版本： 13

参数:

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

返回：

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

参见：

Pasteboard_NotifyType

OH_Pasteboard_Unsubscribe()

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

描述：

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

起始版本： 13

参数:

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

返回：

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

参见：

Pasteboard_NotifyType

OH_PasteboardObserver_Create()

OH_PasteboardObserver* OH_PasteboardObserver_Create ()

描述：

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

起始版本： 13

返回：

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

参见：

OH_PasteboardObserver_Destroy()

int OH_PasteboardObserver_Destroy (OH_PasteboardObserver * observer)

描述：

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

起始版本： 13

参数:

名称	描述
observer	表示指向剪贴板数据变更观察者OH_PasteboardObserver实例的指针。

返回：

返回执行的错误码。错误码定义详见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

参数:

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

返回：

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

参见：

Pasteboard_Notify

OH_Pasteboard_GetMimeTypes()

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

描述：

获取剪贴板中的MIME类型。

起始版本： 14

参数:

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

返回：

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

本接口返回对象的生命周期由入参对象pasteboard管理，应用调用OH_Pasteboard_Destroy销毁入参对象pasteboard时同步释放本接口返回的结果，不允许应用主动释放。

入参对象pasteboard只保存本接口最新返回的结果，接口历史调用获得的结果将失效。

参见：

OH_Pasteboard_GetDataParams_Create()

Pasteboard_GetDataParams *OH_Pasteboard_GetDataParams_Create(void);

描述：

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

起始版本： 15

返回：

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

参见：

OH_Pasteboard_GetDataParams_Destroy()

void OH_Pasteboard_GetDataParams_Destroy(Pasteboard_GetDataParams* params)

描述：

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

起始版本： 15

参数:

名称	描述
params	表示指向剪贴板Pasteboard_GetDataParams实例的指针。

参见：

OH_Pasteboard_GetDataParams_SetProgressIndicator()

void OH_Pasteboard_GetDataParams_SetProgressIndicator(Pasteboard_GetDataParams* params,
    Pasteboard_ProgressIndicator progressIndicator)

描述：

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

起始版本： 15

参数:

名称	描述
params	表示指向上下文数据的指针。
progressIndicator	表示进度条指示选项，可选择是否采用系统默认进度显示。

参见：

Pasteboard_ProgressIndicator

OH_Pasteboard_GetDataParams_SetDestUri()

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

描述：

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

起始版本： 15

参数:

名称	描述
params	表示指向上下文数据的指针。
destUri	表示拷贝文件时的目标路径。
destUriLen	表示目标路径长度。

参见：

Pasteboard_ProgressIndicator

OH_Pasteboard_GetDataParams_SetFileConflictOptions()

void OH_Pasteboard_GetDataParams_SetFileConflictOptions(Pasteboard_GetDataParams* params,
    Pasteboard_FileConflictOptions option)

描述：

向剪贴板Pasteboard_GetDataParams设置文件拷贝冲突选项，默认为PASTEBOARD_OVERWRITE。

起始版本： 15

参数:

名称	描述
params	表示指向上下文数据的指针。
option	表示文件拷贝冲突时的选项，默认为PASTEBOARD_OVERWRITE。

参见：

Pasteboard_FileConflictOptions

OH_Pasteboard_GetDataParams_SetProgressListener()

void OH_Pasteboard_GetDataParams_SetProgressListener(Pasteboard_GetDataParams* params,
    const OH_Pasteboard_ProgressListener listener)

描述：

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

起始版本： 15

参数:

名称	描述
params	表示指向上下文数据的指针。
listener	表示进度数据变化的订阅函数，当选择不使用系统默认进度显示时，可设置该项获取粘贴过程的进度。

参见：

OH_Pasteboard_ProgressListener

OH_Pasteboard_ProgressInfo_GetProgress()

int OH_Pasteboard_ProgressInfo_GetProgress(Pasteboard_ProgressInfo* progressInfo)

描述：

通过Pasteboard_ProgressInfo获取粘贴进度，且仅当进度指示选项Pasteboard_ProgressIndicator设置为PASTEBOARD_NONE时，才可以获取到此信息。

起始版本： 15

参数:

名称	描述
progressInfo	定义进度上报的数据结构，且仅当进度指示选项Pasteboard_ProgressIndicator设置为PASTEBOARD_NONE时才会上报此信息。

返回：

系统拷贝粘贴任务进度百分比。

参见：

Pasteboard_ProgressInfo

OH_Pasteboard_ProgressCancel()

void OH_Pasteboard_ProgressCancel(Pasteboard_GetDataParams* params);

描述：

通过Pasteboard_GetDataParams取消正在进行的拷贝粘贴任务，且仅当进度指示选项Pasteboard_ProgressIndicator设置为PASTEBOARD_NONE时此参数才有意义。

起始版本： 15

参数:

名称	描述
params	表示指向上下文数据的指针。

参见：

OH_Pasteboard_GetDataWithProgress()

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

描述：

获取剪贴板的内容和进度，不支持对文件夹的拷贝。

起始版本： 15

参数:

名称	描述
pasteboard	表示指向剪贴板OH_Pasteboard实例的指针。
params	应用在使用剪贴板提供的文件拷贝能力的情况下需要的参数。定义详见Pasteboard_GetDataParams。
status	该参数是输出参数，表示执行的错误码。错误码定义详见PASTEBOARD_ErrCode。

返回：

执行成功时返回统一数据对象OH_UdmfData实例的指针。否则返回空指针。

参见：

OH_Pasteboard_GetChangeCount()

uint32_t OH_Pasteboard_GetChangeCount(OH_Pasteboard *pasteboard);

描述：

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

当剪贴板内容过期或调用OH_Pasteboard_ClearData等接口导致剪贴板内容为空时，内容变化次数不会因此改变。

系统重启或剪贴板服务异常重启时，剪贴板内容变化次数重新从0开始计数。对同一内容连续多次复制会被视作多次更改，每次复制均会导致内容变化次数增加。

起始版本： 18

参数:

名称	描述
pasteboard	表示指向剪贴板OH_Pasteboard实例的指针。

返回：

执行成功时返回剪贴板内容的变化次数，否则返回0。

参见：