鸿蒙OS Ability DataAbilityHelper

帮助应用程序访问数据。

DataAbilityHelper是用于数据操作的帮助程序类。它使用IDataAbilityObserver注册一个观察器以监视数据。您可以在不指定Uri的情况下调用 creator（ohos.app.Context）创建一个 DataAbilityHelper实例，或调用creator（ohos.app.Context，ohos.utils.net.Uri，boolean）创建一个具有给定 Uri的实例。

也可以看看：

IDataAbilityObserver，Context，Uri

方法总结

修饰符和类型	方法	描述
整型	batchInsert（Uri uri，ValuesBucket []值）	将多个数据记录插入数据库。
PacMap	call（Uri uri，String 方法，String arg，PacMap extras）	调用“数据”功能定义的方法。
静态DataAbilityHelper	creator（Context context）	创建一个 DataAbilityHelper  实例，而不基于给定的 Context 指定 Uri。
静态DataAbilityHelper	creator（Context context，Uri uri）	根据给定的 Context 创建一个具有指定 Uri 的 DataAbilityHelper 实例。
静态DataAbilityHelper	creator（Context context，Uri uri，boolean tryBind）	创建一个 DataAbilityHelper 实例。
整型	delete（Uri uri，DataAbilityPredicates 谓词）	从数据库中删除一个或多个数据记录。
Uri	denormalizeUri（Uri uri）	将 normalizeUri（ohos.utils.net.Uri）生成的给定归一化 uri 转为非归一化的uri 。
DataAbilityResult []  executeBatch（Uri uri，ArrayList < DataAbilityOperation >操作）	在数据库上执行批处理操作。
String	getFileTypes（Uri uri，String mimeTypeFilter）	获取支持的文件的 MIME 类型。
String	getType（Uri uri）	获取给定 URI 指定的日期的 MIME 类型。
整型	update（Uri uri，ValuesBucket值）	将单个数据记录插入数据库。
Uri	normalizeUri（Uri uri）	将引用数据能力的给定 uri 转换为规范化的 Uri。
void	notifyChange（Uri uri）	通知注册观察者 Uri指定的数据资源已更改。
FileDescriptor	openFile（Uri uri，String模式）	在指定的远程路径中打开文件。
RawFileDescriptor	openRawFile（Uri uri，String模式）	这就像 openFile（ohos.utils.net.Uri，java.lang.String）一样，打开一个文件，该文件需要能够返回文件的子部分，通常是其 .hap 中的资产。
ResultSet	query（Uri uri，String []列，DataAbilityPredicates谓词）	查询数据库中的数据。
void	registerObserver（Uri uri，IDataAbilityObserver dataObserver）	注册观察者以观察给定 Uri 指定的数据。
布尔值	release（）	释放数据能力的客户资源。
void	unregisterObserver（Uri uri，IDataAbilityObserver dataObserver）	注销用于监视给定 Uri 指定的数据的观察者。
整型	update（Uri uri，ValuesBucket 值，DataAbilityPredicates 谓词）	更新数据库中的数据记录。

从类 java.lang 继承的方法。object
clone，equals，finalize，getClass，hashCode，notify，notifyAll，toString，wait，wait，wait

方法细节

创作者

公共静态 DataAbilityHelper creator（Contextcontext）

创建一个 DataAbilityHelper 实例，而不基于给定的 Context指定Uri。

参数：

参数名称	参数说明
语境	指示 HarmonyOS 上的 Context 对象。

返回值：

返回创建的 DataAbilityHelper 实例，其中未指定 Uri。

创作者

公共静态 DataAbilityHelper creator（Contextcontext，Uriuri）

根据给定的Context创建一个具有指定Uri的 DataAbilityHelper 实例 。

参数：

参数名称	参数说明
语境	指示 HarmonyOS 上的 Context 对象。
乌里	表示要操作的数据库表或磁盘文件。

返回值：

返回具有指定Uri 的创建的 DataAbilityHelper 实例。

创作者

公共静态 DataAbilityHelper creator（Contextcontext，Uri uri，布尔 tryBind）

创建一个 DataAbilityHelper 实例。

您可以使用此方法指定要操作的数据的Uri，并设置使用数据模板的能力（简称 Data 能力）与 DataAbilityHelper 实例中关联的客户端进程之间的绑定关系。

参数：

参数名称	参数说明
语境	指示 HarmonyOS 上的 Context 对象。
uri	指示要操作的数据库表。
tryBind	指定相应数据能力流程的退出是否导致客户流程的退出。

返回值：

返回创建的 DataAbilityHelper 实例。

释放

公共布尔发布（）

释放数据能力的客户资源。

数据操作完成后，应调用此方法释放客户端资源。

返回值：

如果资源已成功释放，则返回 true；否则，返回 false。否则返回 false。

注册观察者

公共无效 registerObserver（Uriuri，IDataAbilityObserverdataObserver）ThrowsIllegalArgumentException

注册观察者以观察给定Uri 指定的数据 。

参数：

参数名称	参数说明
uri	指示要操作的数据的路径。
数据观察者	指示 IDataAbilityObserver 对象。

Throws：

Throws名称	Throws说明
IllegalArgumentException	如果参数值无效，则Throws此异常。
NullPointerException	如果 uri 为 null，则Throws此异常。

通知变更

公共无效 notifyChange（（Uriuri）引发IllegalArgumentException

通知注册观察者Uri 指定的数据资源已更改 。

参数：

参数名称	参数说明
uri	指示要操作的数据的路径。

Throws：

Throws名称	Throws说明
IllegalArgumentException	如果参数值无效，则Throws此异常。
NullPointerException	如果 uri 为 null，则Throws此异常。

注销观察者

公共无效 unregisterObserver（Uriuri，IDataAbilityObserverdataObserver）ThrowsIllegalArgumentException

注销用于监视给定Uri 指定的数据的观察者 。

参数：

参数名称	参数说明
uri	指示要操作的数据的路径。
数据观察者	指示 IDataAbilityObserver 对象。

Throws：

Throws名称	Throws说明
IllegalArgumentException	如果参数值无效，则Throws此异常。
NullPointerException	如果 uri 为 null，则Throws此异常。

插

public int insert（Uriuri，ValuesBucketvalue）ThrowsDataAbilityRemoteException

将单个数据记录插入数据库。

参数：

参数名称	参数说明
uri	指示要操作的数据的路径。
值	指示要插入的数据记录。如果此参数为 null，将插入空白行。

返回值：

返回插入的数据记录的索引。

Throws：

Throws名称	Throws说明
DataAbilityRemoteException	如果发生远程进程异常，则Throws此异常。
IllegalStateException	如果 dataAbility 不存在，则Throws此异常。
NullPointerException	如果 uri 为 null，则Throws此异常。

batchInsert

public int batchInsert（Uriuri，ValuesBucket [] values）Throws DataAbilityRemoteException

将多个数据记录插入数据库。

参数：

参数名称	参数说明
uri	指示要操作的数据的路径。
价值观	指示要插入的数据记录。

返回值：

返回插入的数据记录数。

Throws：

Throws名称	Throws说明
DataAbilityRemoteException	如果发生远程进程异常，则Throws此异常。
IllegalStateException	如果 dataAbility 不存在，则Throws此异常。
IllegalArgumentException	如果参数值无效，则Throws此异常。
NullPointerException	如果 uri 为 null，则Throws此异常。

删除

public int delete（Uriuri，DataAbilityPredicates谓词）引发DataAbilityRemoteException

从数据库中删除一个或多个数据记录。

参数：

参数名称	参数说明
乌里	指示要操作的数据的路径。
谓词	表示过滤条件。当此参数为 null 时，您应该定义处理逻辑。

返回值：

返回已删除的数据记录数。

Throws：

Throws名称	Throws说明
DataAbilityRemoteException	如果发生远程进程异常，则Throws此异常。
IllegalStateException	如果 dataAbility 不存在，则Throws此异常。
NullPointerException	如果 uri 为 null，则Throws此异常。

更新

public int update（Uriuri，ValuesBucketvalue，DataAbilityPredicates谓词）ThrowsDataAbilityRemoteException

更新数据库中的数据记录。

参数：

参数名称	参数说明
uri	指示要更新的数据路径。
值	指示要更新的数据。此参数可以为空。
谓词	表示过滤条件。当此参数为null时，您应该定义处理逻辑。

返回值：

返回更新的数据记录数。

Throws：

Throws名称	Throws说明
DataAbilityRemoteException	如果发生远程进程异常，则Throws此异常。
IllegalStateException	如果 dataAbility 不存在，则Throws此异常。
NullPointerException	如果 uri 为 null，则Throws此异常。

询问

公共ResultSet查询（Uriuri，String [ ]列，DataAbilityPredicates谓词）ThrowsDataAbilityRemoteException

查询数据库中的数据。

参数：

参数名称	参数说明
uri	指示要查询的数据路径。
列	指示要查询的列。如果此参数为 null，则查询所有列。
谓词	表示过滤条件。当此参数为 null 时，您应该定义处理逻辑。

返回值：

返回查询结果。

Throws：

Throws名称	Throws说明
DataAbilityRemoteException	如果发生远程进程异常，则Throws此异常。
IllegalStateException	如果 dataAbility 不存在，则Throws此异常。
NullPointerException	如果 uri 为 null，则Throws此异常。

执行批处理

publicDataAbilityResult [] executeBatch（Uriuri，ArrayList<DataAbilityOperation>操作）ThrowsDataAbilityRemoteException，OperationExecuteException

在数据库上执行批处理操作。

参数：

参数名称	参数说明
uri	指示要操作的数据路径。
运作	指示数据库上数据库操作的列表。

返回值：

以数组形式返回每个操作的结果。

Throws：

Throws名称	Throws说明
DataAbilityRemoteException	如果发生远程进程异常，则Throws此异常。
OperationExecuteException	如果发生操作异常，则Throws此异常。
IllegalStateException	如果 dataAbility 不存在，则Throws此异常。
IllegalArgumentException	如果参数值无效，则Throws此异常。
NullPointerException	如果 uri 为 null，则Throws此异常。

打开文件

publicFileDescriptoropenFile（Uriuri，String模式）ThrowsDataAbilityRemoteException，FileNotFoundException

在指定的远程路径中打开文件。

参数：

参数名称	参数说明
uri	指示要打开的文件的路径。
模式	表示文件打开模式，对于只读访问可以为“ r”，对于只读访问可以为“ w”（擦除文件中当前的任何数据），对于截断任何现有文件的写访问可以为“ wt”，“ “ wa”表示只写访问权限，以追加到任何现有数据；“ rw”表示对任何现有数据的读写访问；“ rwt”表示对截断任何现有文件的读写访问。

返回值：

返回文件描述符。

Throws：

Throws名称	Throws说明
FileNotFoundException	如果找不到该文件，则Throws此异常。
DataAbilityRemoteException	如果发生远程进程异常，则Throws此异常。
IllegalStateException	如果 dataAbility 不存在，则Throws此异常。
NullPointerException	如果 uri 或 mode 为 null，则Throws此异常。

打开原始文件

publicRawFileDescriptoropenRawFile（Uriuri，String模式）ThrowsDataAbilityRemoteException，FileNotFoundException

这就像 openFile（ohos.utils.net.Uri，java.lang.String）一样，打开一个文件，该文件需要能够返回文件的子部分，通常是其 .hap 中的资产。

参数：

参数名称	参数说明
uri	指示要打开的文件的路径。
模式	表示文件打开模式，对于只读访问可以为“ r”，对于只读访问可以为“ w”（擦除文件中当前的任何数据），对于截断任何现有文件的写访问可以为“ wt”，“ “ wa”表示只写访问权限，以追加到任何现有数据；“ rw”表示对任何现有数据的读写访问；“ rwt”表示对截断任何现有文件的读写访问。

返回值：

返回包含文件描述符的RawFileDescriptor对象。

Throws：

Throws名称	Throws说明
FileNotFoundException	如果找不到该文件，则Throws此异常。
DataAbilityRemoteException	如果发生远程进程异常，则Throws此异常。
IllegalStateException	如果 dataAbility 不存在，则Throws此异常。
NullPointerException	如果 uri 或 mode 为 null，则Throws此异常。

获取文件类型

publicString [] getFileTypes（（Uriuri，StringmimeTypeFilter）ThrowsDataAbilityRemoteException

获取支持的文件的MIME类型。

参数：

参数名称	参数说明
uri	指示要获取的文件的路径。
mimeTypeFilter	表示要获取的文件的 MIME 类型。此参数不能为空。<br />1.“  / ”：获得数据功能支持的所有类型。<br />2.“ image / ”：获取主要类型为任何子类型的图像的文件。<br />3.“  / jpg”：获取其子类型为任何主要类型的 JPG 的文件。

返回值：

返回匹配的 MIME 类型。如果没有匹配项，则返回 null。

Throws：

Throws名称	Throws说明
DataAbilityRemoteException	如果发生远程进程异常，则Throws此异常。
NullPointerException	如果 uri 或  mimeTypeFilter 为 null，则Throws此异常。

呼叫

公共PacMap调用（Uriuri，String方法，Stringarg，PacMap附加功能）ThrowsDataAbilityRemoteException

调用“数据”功能定义的方法。

参数：

参数名称	参数说明
uri	指示数据处理能力。
方法	指示方法名称。
arg	指示字符串类型的参数。
extras	表示 PacMap 类型的参数。

返回值：

返回被调用方法返回的值。

Throws：

Throws名称	Throws说明
DataAbilityRemoteException	如果发生远程进程异常，则Throws此异常。
NullPointerException	如果 uri 或 method  为 null，则Throws此异常。

获取类型

publicStringgetType（（Uriuri）ThrowsDataAbilityRemoteException

获取给定URI指定的日期的MIME类型。

参数：

参数名称	参数说明
uri	指示要操作的数据的路径。

返回值：

返回与 uri 指定的数据匹配的 MIME 类型。

Throws：

Throws名称	Throws说明
DataAbilityRemoteException	如果发生远程进程异常，则Throws此异常。
NullPointerException	如果 uri 为 null，则Throws此异常。

规范化

公共UrinormalizeUri（Uriuri）引发DataAbilityRemoteException

将引用数据能力的给定 uri 转换为规范化的 Uri。标准化的 URI 可以在设备之间使用，持久化，备份和还原。

要将标准化的URI从另一个环境转移到当前环境，您应该再次调用此方法以对当前环境的 URI 进行重新标准化，或调用denormalizeUri（ohos.utils.net.Uri）将其转换为可以仅在当前环境中使用。

参数：

参数名称	参数说明
uri	指示要规范化的 Uri 对象。

返回值：

如果数据功能支持 URI 标准化，则返回标准化的 Uri 对象；否则返回 null。

Throws：

Throws名称	Throws说明
DataAbilityRemoteException	如果远程进程退出，则Throws此异常。
NullPointerException	如果 uri 为 null，则Throws此异常。

也可以看看：

denormalizeUri（ohos.utils.net.Uri）

非规范化

公共UridenormalizeUri（Uriuri）引发DataAbilityRemoteException

将 normalizeUri（ohos.utils.net.Uri）生成的给定归一化 uri 转换为非归一化的 uri 。

参数：

参数名称	参数说明
uri	指示要规范化的 Uri 对象。

返回值：

如果非规范化成功，则返回非规范化的 Uri 对象；如果没有任何关系，则返回传递给此方法的原始 Uri；如果在当前环境中找不到由规范化 Uri 标识的数据，则返回 null。

Throws：

Throws 名称	Throws 说明
DataAbilityRemoteException	如果远程进程退出，则Throws此异常。
NullPointerException	如果 uri 为 null，则Throws此异常。

也可以看看：

normalizeUri（ohos.utils.net.Uri）