diff --git a/api/@ohos.security.asset.d.ts b/api/@ohos.security.asset.d.ts index 59c0ac4bb4c87994fd36322869402d36b7b7955b..ab174122639ad7831f9469a980b85acd9a5bf2e3 100644 --- a/api/@ohos.security.asset.d.ts +++ b/api/@ohos.security.asset.d.ts @@ -65,9 +65,8 @@ declare namespace asset { * @since 11 */ /** - * Add an Asset. - * Permission ohos.permission.STORE_PERSISTENT_DATA is required when the Asset needs to be stored persistently - * by setting {@link Tag.IS_PERSISTENT} tag. + * Add an asset. This API uses a promise to return the result. + * To set {@link Tag.IS_PERSISTENT}, the application must have the ohos.permission.STORE_PERSISTENT_DATA permission. * * @param { AssetMap } attributes - a map object containing attributes of the Asset to be added. * @returns { Promise } the promise object returned by the function. @@ -96,9 +95,8 @@ declare namespace asset { function add(attributes: AssetMap): Promise; /** - * Add an Asset to a specific user space. - * Permission ohos.permission.STORE_PERSISTENT_DATA is required when the Asset needs to be stored persistently - * by setting {@link Tag.IS_PERSISTENT} tag. + * Adds an asset to the specified user space. This API uses a promise to return the result. + * To set {@link Tag.IS_PERSISTENT}, the application must have the ohos.permission.STORE_PERSISTENT_DATA permission. * * @permission ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS * @param { number } userId - the user identifier to add an Asset. The user identifier cannot be lower than 100. @@ -157,9 +155,8 @@ declare namespace asset { * @since 12 */ /** - * Add an Asset. - * Permission ohos.permission.STORE_PERSISTENT_DATA is required when the Asset needs to be stored persistently - * by setting {@link Tag.IS_PERSISTENT} tag. + * Add an asset. This API returns the result synchronously. + * To set {@link Tag.IS_PERSISTENT}, the application must have the ohos.permission.STORE_PERSISTENT_DATA permission. * * @param { AssetMap } attributes - a map object containing attributes of the Asset to be added. * @throws { BusinessError } 201 - The caller doesn't have the permission. @@ -208,7 +205,7 @@ declare namespace asset { * @since 11 */ /** - * Remove one or more Assets that match a search query. + * Removes one or more assets. This API uses a promise to return the result. * * @param { AssetMap } query - a map object containing attributes of the Asset to be removed. * @returns { Promise } the promise object returned by the function. @@ -232,7 +229,7 @@ declare namespace asset { function remove(query: AssetMap): Promise; /** - * Remove one or more Assets that match a search query from a specific user space. + * Removes one or more assets from the specified user space. This API uses a promise to return the result. * * @permission ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS * @param { number } userId - the user identifier to remove one or more Assets. The user identifier cannot be lower @@ -281,7 +278,7 @@ declare namespace asset { * @since 12 */ /** - * Remove one or more Assets that match a search query. + * Removes one or more assets. This API returns the result synchronously. * * @param { AssetMap } query - a map object containing attributes of the Asset to be removed. * @throws { BusinessError } 401 - Parameter error. Possible causes: @@ -329,7 +326,7 @@ declare namespace asset { * @since 11 */ /** - * Update an Asset that matches a search query. + * Updates an asset. This API uses a promise to return the result. * * @param { AssetMap } query - a map object containing attributes of the Asset to be updated. * @param { AssetMap } attributesToUpdate - a map object containing attributes with new values. @@ -357,7 +354,7 @@ declare namespace asset { function update(query: AssetMap, attributesToUpdate: AssetMap): Promise; /** - * Update an Asset that matches a search query in a specific user space. + * Updates an asset in the specified user space. This API uses a promise to return the result. * * @permission ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS * @param { number } userId - the user identifier to update an Asset. The user identifier cannot be lower than 100. @@ -413,7 +410,7 @@ declare namespace asset { * @since 12 */ /** - * Update an Asset that matches a search query. + * Updates an asset. This API returns the result synchronously. * * @param { AssetMap } query - a map object containing attributes of the Asset to be updated. * @param { AssetMap } attributesToUpdate - a map object containing attributes with new values. @@ -464,7 +461,9 @@ declare namespace asset { * @since 11 */ /** - * Preprocessing (e.g. get challenge) for querying one or more Assets that require user authentication. + * Performs preprocessing for the asset query. This API is used when user authentication is required for the + * access to the asset. After the user authentication is successful, call {@link asset.query} and + * {@link asset.postQuery}. This API uses a promise to return the result. * * @param { AssetMap } query - a map object containing attributes of the Asset to be queried. * @returns { Promise } the promise object returned by the function. @@ -548,7 +547,9 @@ declare namespace asset { * @since 12 */ /** - * Preprocessing (e.g. get challenge) for querying one or more Assets that require user authentication. + * Performs preprocessing for the asset query. This API is used when user authentication is required for the + * access to the asset. After the user authentication is successful, call {@link asset.querySync} and + * {@link asset.postQuerySync}. This API returns the result synchronously. * * @param { AssetMap } query - a map object containing attributes of the Asset to be queried. * @returns { Uint8Array } the challenge value to be used when {@link querySync} is called. @@ -599,7 +600,10 @@ declare namespace asset { * @since 11 */ /** - * Query one or more Assets that match a search query. + * Queries one or more assets. If user authentication is required for the access to the asset, + * call {@link asset.preQuery} before this API and call {@link asset.postQuery} after this API. + * For details about the development procedure, see Querying an Asset with User Authentication. + * This API uses a promise to return the result. * * @param { AssetMap } query - a map object containing attributes of the Asset to be queried. * @returns { Promise> } the promise object returned by the function. @@ -682,7 +686,10 @@ declare namespace asset { * @since 12 */ /** - * Query one or more Assets that match a search query. + * Queries one or more assets. If user authentication is required for the access to the asset, + * call {@link asset.preQuerySync} before this API and call {@link asset.postQuerySync} after this API. + * For details about the development procedure, see Querying an Asset with User Authentication. + * This API returns the result synchronously. * * @param { AssetMap } query - a map object containing attributes of the Asset to be queried. * @returns { Array } the query result. @@ -727,7 +734,9 @@ declare namespace asset { * @since 11 */ /** - * Post-processing (e.g. release cached resource) for querying multiple Assets that require user authentication. + * Performs postprocessing for the asset query. This API is used when user authentication is required for + * the access to the asset. This API must be used with {@link asset.preQuery} together. + * This API uses a promise to return the result. * * @param { AssetMap } handle - a map object containing the handle returned by {@link preQuery}. * @returns { Promise } the promise object returned by the function. @@ -792,7 +801,9 @@ declare namespace asset { * @since 12 */ /** - * Post-processing (e.g. release cached resource) for querying multiple Assets that require user authentication. + * Performs postprocessing for the asset query. This API is used when user authentication is required for + * the access to the asset. This API must be used with {@link asset.preQuerySync} together. + * This API returns the result synchronously. * * @param { AssetMap } handle - a map object containing the handle returned by {@link preQuerySync}. * @throws { BusinessError } 401 - Parameter error. Possible causes: @@ -838,7 +849,7 @@ declare namespace asset { * @since 11 */ /** - * A Map type containing tag-value pairs that describe the attributes of an Asset. + * Represents a set of asset attributes in the form of KV pairs. * * @typedef { Map } * @syscap SystemCapability.Security.Asset @@ -855,7 +866,7 @@ declare namespace asset { * @since 11 */ /** - * A type that indicates the secret or attribute value of an Asset tag. + * Represents the value of each attribute in {@link AssetMap}. * * @typedef { boolean | number | Uint8Array } * @syscap SystemCapability.Security.Asset @@ -872,7 +883,7 @@ declare namespace asset { * @since 11 */ /** - * An enum type indicates when the Asset is accessible. + * Enumerates the types of access control based on the lock screen status. * * @enum { number } * @syscap SystemCapability.Security.Asset @@ -887,7 +898,7 @@ declare namespace asset { * @since 11 */ /** - * The secret value in the Asset can only be accessed after the device is powered on. + * The asset can be accessed after the device is powered on. * * @syscap SystemCapability.Security.Asset * @atomicservice @@ -901,7 +912,10 @@ declare namespace asset { * @since 11 */ /** - * The secret value in the Asset can only be accessed after the device is first unlocked. + * The asset can be accessed only after the device is unlocked for the first time. + *

NOTE: + * If no lock screen password is set, this option is equivalent to DEVICE_POWERED_ON. + *

* * @syscap SystemCapability.Security.Asset * @atomicservice @@ -915,7 +929,10 @@ declare namespace asset { * @since 11 */ /** - * The secret value in the Asset can only be accessed while the device is unlocked. + * The asset can be accessed only when the device is unlocked. + *

NOTE: + * If no lock screen password is set, this option is equivalent to DEVICE_POWERED_ON. + *

* * @syscap SystemCapability.Security.Asset * @atomicservice @@ -932,7 +949,7 @@ declare namespace asset { * @since 11 */ /** - * An enum type indicates the user authentication type for Asset access control. + * Enumerates the types of user authentication supported by an asset. * * @enum { number } * @syscap SystemCapability.Security.Asset @@ -947,7 +964,7 @@ declare namespace asset { * @since 11 */ /** - * The access to an Asset doesn't require user authentication. + * No user authentication is required before the asset is accessed. * * @syscap SystemCapability.Security.Asset * @atomicservice @@ -961,7 +978,8 @@ declare namespace asset { * @since 11 */ /** - * The access to an Asset requires user authentication using either PIN/pattern/password or biometric traits. + * The asset can be accessed if any user authentication (such as PIN, facial, or fingerprint authentication) + * is successful. * * @syscap SystemCapability.Security.Asset * @atomicservice @@ -978,7 +996,10 @@ declare namespace asset { * @since 11 */ /** - * An enum type indicates the type of Asset synchronization. + * Enumerates the sync types supported by an asset. + *

NOTE: + * This field is an embedded parameter. Currently, asset sync is not supported. + *

* * @enum { number } * @syscap SystemCapability.Security.Asset @@ -993,7 +1014,7 @@ declare namespace asset { * @since 11 */ /** - * An Asset with this attribute value is never allowed to be transferred out. + * Asset sync is not allowed. * * @syscap SystemCapability.Security.Asset * @atomicservice @@ -1007,7 +1028,7 @@ declare namespace asset { * @since 11 */ /** - * An Asset with this attribute value can only be restored to the device from which it was transferred out. + * Asset sync is allowed only on the local device, for example, in data restore on the local device. * * @syscap SystemCapability.Security.Asset * @atomicservice @@ -1021,7 +1042,7 @@ declare namespace asset { * @since 11 */ /** - * An Asset with this attribute value can only be transferred out to a trusted device (user authorized). + * Asset sync is allowed only between trusted devices, for example, in the case of cloning. * * @syscap SystemCapability.Security.Asset * @atomicservice @@ -1035,7 +1056,8 @@ declare namespace asset { * @since 12 */ /** - * An Asset with this attribute value can only be transferred out to devices logged in with trusted accounts. + * Asset sync is allowed only between the devices that are logged in with trusted accounts, for example, + * in cloud sync scenarios. * * @syscap SystemCapability.Security.Asset * @atomicservice @@ -1076,7 +1098,7 @@ declare namespace asset { * @since 11 */ /** - * An enum type indicates the strategy for conflict resolution when handling duplicated Asset alias. + * Enumerates the policies for resolving conflicts (for example, a duplicate alias) when an asset is added. * * @enum { number } * @syscap SystemCapability.Security.Asset @@ -1091,7 +1113,7 @@ declare namespace asset { * @since 11 */ /** - * Directly overwrite an Asset with duplicated alias when a conflict is detected. + * Overwrite the original asset. * * @syscap SystemCapability.Security.Asset * @atomicservice @@ -1105,7 +1127,7 @@ declare namespace asset { * @since 11 */ /** - * Throw an error so that the caller can take measures when a conflict is detected. + * Throw an exception for the service to perform subsequent processing. * * @syscap SystemCapability.Security.Asset * @atomicservice @@ -1122,7 +1144,7 @@ declare namespace asset { * @since 11 */ /** - * An enum type indicates the return type of the queried Asset. + * Enumerates the type of information returned by an asset query operation. * * @enum { number } * @syscap SystemCapability.Security.Asset @@ -1137,7 +1159,10 @@ declare namespace asset { * @since 11 */ /** - * Specify that the return data should contain both secret value and attributes. + * The query result contains the asset plaintext and its attributes. + *

NOTE: + * Use this option when you need to query the plaintext of a single asset. + *

* * @syscap SystemCapability.Security.Asset * @atomicservice @@ -1151,7 +1176,10 @@ declare namespace asset { * @since 11 */ /** - * Specify that the return data contains only attributes. + * The query result contains only the asset attributes. + *

NOTE: + * Use this option when you need to query attributes of multiple assets. + *

* * @syscap SystemCapability.Security.Asset * @atomicservice @@ -1161,7 +1189,7 @@ declare namespace asset { } /** - * An enum type indicates the additional action to be performed during operation. + * Enumerates the types of additional operation to perform. * * @enum { number } * @syscap SystemCapability.Security.Asset @@ -1169,14 +1197,14 @@ declare namespace asset { */ enum OperationType { /** - * Synchronization is required during operation. + * Sync. * * @syscap SystemCapability.Security.Asset * @since 12 */ NEED_SYNC = 0, /** - * Logout is required during operation. + * Logout. * * @syscap SystemCapability.Security.Asset * @since 12 @@ -1304,7 +1332,7 @@ declare namespace asset { * @since 11 */ /** - * A tag whose value is a byte array indicating the sensitive user data such as passwords and tokens. + * Asset plaintext. * * @syscap SystemCapability.Security.Asset * @atomicservice @@ -1318,7 +1346,7 @@ declare namespace asset { * @since 11 */ /** - * A tag whose value is a byte array identifying an Asset. + * Asset alias, which uniquely identifies an asset. * * @syscap SystemCapability.Security.Asset * @atomicservice @@ -1332,7 +1360,7 @@ declare namespace asset { * @since 11 */ /** - * A tag whose value is a 32-bit unsigned integer indicating when the Asset can be accessed. + * Access control based on the lock screen status. * * @syscap SystemCapability.Security.Asset * @atomicservice @@ -1346,7 +1374,7 @@ declare namespace asset { * @since 11 */ /** - * A tag whose value is a bool indicating whether a screen lock password is required for the device. + * Whether the asset is accessible only when a lock screen password is set. * * @syscap SystemCapability.Security.Asset * @atomicservice @@ -1360,7 +1388,7 @@ declare namespace asset { * @since 11 */ /** - * A tag whose value is a 32-bit unsigned integer indicating the user authentication type for Asset access control. + * Type of user authentication required for accessing the asset. * * @syscap SystemCapability.Security.Asset * @atomicservice @@ -1374,7 +1402,7 @@ declare namespace asset { * @since 11 */ /** - * A tag whose value is a 32-bit unsigned integer indicating the validity period in seconds of user authentication. + * Validity period of the user authentication. * * @syscap SystemCapability.Security.Asset * @atomicservice @@ -1388,7 +1416,7 @@ declare namespace asset { * @since 11 */ /** - * A tag whose value is a byte array indicating the authentication challenge for anti-replay protection. + * Challenge for the user authentication. * * @syscap SystemCapability.Security.Asset * @atomicservice @@ -1402,7 +1430,7 @@ declare namespace asset { * @since 11 */ /** - * A tag whose value is a byte array indicating the authentication token after a user is verified. + * Authorization token obtained after the user authentication is successful. * * @syscap SystemCapability.Security.Asset * @atomicservice @@ -1416,7 +1444,7 @@ declare namespace asset { * @since 11 */ /** - * A tag whose value is a 32-bit unsigned integer indicating the type of Asset synchronization. + * Asset sync type. * * @syscap SystemCapability.Security.Asset * @atomicservice @@ -1424,7 +1452,7 @@ declare namespace asset { */ SYNC_TYPE = TagType.NUMBER | 0x10, /** - * A tag whose value is a bool indicating whether Asset is stored persistently. + * Whether to retain the asset when the application is uninstalled. * * @syscap SystemCapability.Security.Asset * @since 11 @@ -1437,7 +1465,7 @@ declare namespace asset { * @since 11 */ /** - * A tag whose value is a byte array indicating the first user-defined Asset data label (not allow to update). + * Additional asset data customized by the service with integrity protection. * * @syscap SystemCapability.Security.Asset * @atomicservice @@ -1451,7 +1479,7 @@ declare namespace asset { * @since 11 */ /** - * A tag whose value is a byte array indicating the second user-defined Asset data label (not allow to update). + * Additional asset data customized by the service with integrity protection. * * @syscap SystemCapability.Security.Asset * @atomicservice @@ -1465,7 +1493,7 @@ declare namespace asset { * @since 11 */ /** - * A tag whose value is a byte array indicating the third user-defined Asset data label (not allow to update). + * Additional asset data customized by the service with integrity protection. * * @syscap SystemCapability.Security.Asset * @atomicservice @@ -1479,7 +1507,7 @@ declare namespace asset { * @since 11 */ /** - * A tag whose value is a byte array indicating the fourth user-defined Asset data label (not allow to update). + * Additional asset data customized by the service with integrity protection. * * @syscap SystemCapability.Security.Asset * @atomicservice @@ -1493,7 +1521,7 @@ declare namespace asset { * @since 11 */ /** - * A tag whose value is a byte array indicating the first user-defined Asset data label (allow to update). + * Additional asset data customized by the service without integrity protection. * * @syscap SystemCapability.Security.Asset * @atomicservice @@ -1507,7 +1535,7 @@ declare namespace asset { * @since 11 */ /** - * A tag whose value is a byte array indicating the second user-defined Asset data label (allow to update). + * Additional asset data customized by the service without integrity protection. * * @syscap SystemCapability.Security.Asset * @atomicservice @@ -1521,7 +1549,7 @@ declare namespace asset { * @since 11 */ /** - * A tag whose value is a byte array indicating the third user-defined Asset data label (allow to update). + * Additional asset data customized by the service without integrity protection. * * @syscap SystemCapability.Security.Asset * @atomicservice @@ -1535,7 +1563,7 @@ declare namespace asset { * @since 11 */ /** - * A tag whose value is a byte array indicating the fourth user-defined Asset data label (allow to update). + * Additional asset data customized by the service without integrity protection. * * @syscap SystemCapability.Security.Asset * @atomicservice @@ -1550,8 +1578,8 @@ declare namespace asset { * @since 12 */ /** - * A local tag whose value is a byte array indicating the first user-defined Asset data label (allow to update). - * The information of a local tag will not be synchronized. + * Local information about the asset. The value is assigned by the service without integrity protection and + * will not be synced. * * @syscap SystemCapability.Security.Asset * @atomicservice @@ -1566,8 +1594,8 @@ declare namespace asset { * @since 12 */ /** - * A local tag whose value is a byte array indicating the second user-defined Asset data label (allow to update). - * The information of a local tag will not be synchronized. + * Local information about the asset. The value is assigned by the service without integrity protection and + * will not be synced. * * @syscap SystemCapability.Security.Asset * @atomicservice @@ -1582,8 +1610,8 @@ declare namespace asset { * @since 12 */ /** - * A local tag whose value is a byte array indicating the third user-defined Asset data label (allow to update). - * The information of a local tag will not be synchronized. + * Local information about the asset. The value is assigned by the service without integrity protection and + * will not be synced. * * @syscap SystemCapability.Security.Asset * @atomicservice @@ -1598,8 +1626,8 @@ declare namespace asset { * @since 12 */ /** - * A local tag whose value is a byte array indicating the fourth user-defined Asset data label (allow to update). - * The information of a local tag will not be synchronized. + * Local information about the asset. The value is assigned by the service without integrity protection and + * will not be synced. * * @syscap SystemCapability.Security.Asset * @atomicservice @@ -1613,7 +1641,7 @@ declare namespace asset { * @since 11 */ /** - * A tag whose value is a 32-bit unsigned integer indicating the return type of the queried Asset. + * Type of the asset query result to return. * * @syscap SystemCapability.Security.Asset * @atomicservice @@ -1627,7 +1655,7 @@ declare namespace asset { * @since 11 */ /** - * A tag whose value is a 32-bit unsigned integer indicating the maximum number of returned Assets in one query. + * Maximum number of asset records to return. * * @syscap SystemCapability.Security.Asset * @atomicservice @@ -1641,7 +1669,10 @@ declare namespace asset { * @since 11 */ /** - * A tag whose value is a 32-bit unsigned integer indicating the offset of return data in batch query. + * Offset of the asset query result. + *

NOTE: + * This parameter specifies the starting asset record to return in batch asset query. + *

* * @syscap SystemCapability.Security.Asset * @atomicservice @@ -1655,7 +1686,11 @@ declare namespace asset { * @since 11 */ /** - * A tag whose value is a 32-bit unsigned integer indicating how the query results are sorted. + * Sorting order of the query results. Currently, the results can be sorted only by + * ASSET_TAG_DATA_LABEL. + *

NOTE: + * By default, assets are returned in the order in which they are added. + *

* * @syscap SystemCapability.Security.Asset * @atomicservice @@ -1669,7 +1704,7 @@ declare namespace asset { * @since 11 */ /** - * A tag whose value is a 32-bit unsigned integer indicating the strategy for resolving Asset conflicts. + * Policy for resolving the conflict (for example, a duplicate alias). * * @syscap SystemCapability.Security.Asset * @atomicservice @@ -1683,7 +1718,7 @@ declare namespace asset { * @since 12 */ /** - * A tag whose value is a byte array indicating the update time of an Asset. + * Data update time, in timestamp. * * @syscap SystemCapability.Security.Asset * @atomicservice @@ -1691,14 +1726,14 @@ declare namespace asset { */ UPDATE_TIME = TagType.BYTES | 0x45, /** - * A tag whose value is a 32-bit unsigned integer indicating the additional action to be performed during operation. + * Additional operation type. * * @syscap SystemCapability.Security.Asset * @since 12 */ OPERATION_TYPE = TagType.NUMBER | 0x46, /** - * A tag whose value is a bool indicating whether the attributes of an asset are required to be encrypted. + * Whether to encrypt the additional asset information customized by the service. * * @syscap SystemCapability.Security.Asset * @atomicservice @@ -1706,7 +1741,7 @@ declare namespace asset { */ REQUIRE_ATTR_ENCRYPTED = TagType.BOOL | 0x47, /** - * A tag whose value is a byte array indicating the group id an asset belongs to. + * Group to which the asset belongs. * * @syscap SystemCapability.Security.Asset * @since 18