From 7fa2c233377f1ff62f0ecef32c6051993e989ef5 Mon Sep 17 00:00:00 2001 From: MangTsang Date: Sat, 8 Oct 2022 12:38:55 +0800 Subject: [PATCH] update error code for preferences Signed-off-by: MangTsang --- api/@ohos.data.preferences.d.ts | 223 +++++++++++++++++++++++++------- 1 file changed, 175 insertions(+), 48 deletions(-) diff --git a/api/@ohos.data.preferences.d.ts b/api/@ohos.data.preferences.d.ts index 7355e75a0d..3129833c98 100644 --- a/api/@ohos.data.preferences.d.ts +++ b/api/@ohos.data.preferences.d.ts @@ -12,7 +12,7 @@ * See the License for the specific language governing permissions and * limitations under the License. */ -import { AsyncCallback, Callback } from './basic'; +import {AsyncCallback, Callback} from './basic'; import Context from "./application/Context"; /** @@ -30,13 +30,27 @@ declare namespace preferences { *

The {@link references} instance loads all data of the preferences file and * resides in the memory. You can use removePreferencesFromCache to remove the instance from the memory. * - * @param context Indicates the context of application or capability. - * @param name Indicates the preferences file name. - * @return Returns the {@link Preferences} instance matching the specified preferences file name. - * @throws BusinessError if invoked failed - * @since 9 + * @param {Context} context - Indicates the context of application or capability. + * @param {string} name - Indicates the preferences file name. + * @param {AsyncCallback} callback - the {@link Preferences} instance matching the specified + * preferences file name. + * @throws {BusinessError} 401 - if the parameter type is incorrect. + * @since 9 */ function getPreferences(context: Context, name: string, callback: AsyncCallback): void; + + /** + * Obtains a {@link Preferences} instance matching a specified preferences file name. + * + *

The {@link references} instance loads all data of the preferences file and + * resides in the memory. You can use removePreferencesFromCache to remove the instance from the memory. + * + * @param {Context} context - Indicates the context of application or capability. + * @param {string} name - Indicates the preferences file name. + * @returns {Promise} the {@link Preferences} instance matching the specified preferences file name. + * @throws {BusinessError} 401 - if the parameter type is incorrect. + * @since 9 + */ function getPreferences(context: Context, name: string): Promise; /** @@ -48,12 +62,31 @@ declare namespace preferences { * of the instance. In addition, do not use the instance to perform data operations. Otherwise, data inconsistency * will occur. * - * @param context Indicates the context of application or capability. - * @param name Indicates the preferences file name. - * @throws BusinessError if invoked failed + * @param {Context} context - Indicates the context of application or capability. + * @param {string} name - Indicates the preferences file name. + * @param {AsyncCallback} callback - Indicates the callback function. + * @throws {BusinessError} 401 - if the parameter type is incorrect. + * @throws {BusinessError} 15500010 - if failed to delete preferences file. * @since 9 */ function deletePreferences(context: Context, name: string, callback: AsyncCallback): void; + + /** + * Deletes a {@link Preferences} instance matching a specified preferences file name + * from the cache which is performed by removePreferencesFromCache and deletes the + * preferences file. + * + *

When deleting the {@link Preferences} instance, you must release all references + * of the instance. In addition, do not use the instance to perform data operations. Otherwise, data inconsistency + * will occur. + * + * @param {Context} context - Indicates the context of application or capability. + * @param {string} name - Indicates the preferences file name. + * @returns {Promise} a promise object. + * @throws {BusinessError} 401 - if the parameter type is incorrect. + * @throws {BusinessError} 15500010 - if failed to delete preferences file. + * @since 9 + */ function deletePreferences(context: Context, name: string): Promise; /** @@ -64,12 +97,28 @@ declare namespace preferences { * of the instance. In addition, do not use the instance to perform data operations. Otherwise, data inconsistency * will occur. * - * @param context Indicates the context of application or capability. - * @param name Indicates the preferences file name. - * @throws BusinessError if invoked failed + * @param {Context} context - Indicates the context of application or capability. + * @param {string} name - Indicates the preferences file name. + * @param {AsyncCallback} callback - Indicates the callback function. + * @throws {BusinessError} 401 - if the parameter type is incorrect. * @since 9 */ function removePreferencesFromCache(context: Context, name: string, callback: AsyncCallback): void; + + /** + * Deletes a {@link Preferences} instance matching a specified preferences file name + * from the cache. + * + *

When deleting the {@link Preferences} instance, you must release all references + * of the instance. In addition, do not use the instance to perform data operations. Otherwise, data inconsistency + * will occur. + * + * @param {Context} context - Indicates the context of application or capability. + * @param {string} name - Indicates the preferences file name. + * @returns {Promise} a promise object. + * @throws {BusinessError} 401 - if the parameter type is incorrect. + * @since 9 + */ function removePreferencesFromCache(context: Context, name: string): Promise; /** @@ -77,7 +126,7 @@ declare namespace preferences { * *

The preferences data is stored in a file, which matches only one {@link Preferences} instance in the memory. * You can use getPreferences to obtain the {@link Preferences} instance matching - * the file that stores preferences data, and use emovePreferencesFromCache + * the file that stores preferences data, and use movePreferencesFromCache * to remove the {@link Preferences} instance from the memory. * * @syscap SystemCapability.DistributedDataManager.Preferences.Core @@ -86,39 +135,71 @@ declare namespace preferences { */ interface Preferences { /** - * Obtains the value of a preferences in the int format. - * - *

If the value is {@code null} or not in the int format, the default value is returned. - * - * @param key Indicates the key of the preferences. It cannot be {@code null} or empty. - * @param defValue Indicates the default value to return. - * @return Returns the value matching the specified key if it is found; returns the default value otherwise. - * @throws BusinessError if invoked failed - * @since 9 - */ + * Obtains the value of a preferences in the int format. + * + *

If the value is {@code null} or not in the int format, the default value is returned. + * + * @param {string} key - Indicates the key of the preferences. It cannot be {@code null} or empty. + * @param {ValueType} defValue - Indicates the default value to return. + * @param {AsyncCallback} callback - the value matching the specified key if it is found; + * returns the default value otherwise. + * @throws {BusinessError} 401 - if the parameter type is incorrect. + * @since 9 + */ get(key: string, defValue: ValueType, callback: AsyncCallback): void; + + /** + * Obtains the value of a preferences in the int format. + * + *

If the value is {@code null} or not in the int format, the default value is returned. + * + * @param {string} key - Indicates the key of the preferences. It cannot be {@code null} or empty. + * @param {ValueType} defValue - Indicates the default value to return. + * @returns {Promise} the value matching the specified key if it is found; + * returns the default value otherwise. + * @throws {BusinessError} 401 - if the parameter type is incorrect. + * @since 9 + */ get(key: string, defValue: ValueType): Promise; /** - * Obtains all the keys and values of a preferences in an object. - * - * @return Returns the values and keys in an object. - * @throws BusinessError if invoked failed - * @since 9 - */ + * Obtains all the keys and values of a preferences in an object. + * + * @param {AsyncCallback} callback - the values and keys in an object. + * @throws {BusinessError} 401 - if the parameter type is incorrect. + * @since 9 + */ getAll(callback: AsyncCallback): void; + + /** + * Obtains all the keys and values of a preferences in an object. + * + * @returns {Promise} the values and keys in an object. + * @throws {BusinessError} 401 - if the parameter type is incorrect. + * @since 9 + */ getAll(): Promise; /** * Checks whether the {@link Preferences} object contains a preferences matching a specified key. * - * @param key Indicates the key of the preferences to check for. - * @return Returns {@code true} if the {@link Preferences} object contains a preferences with the specified key; - * returns {@code false} otherwise. - * @throws BusinessError if invoked failed + * @param {string} key - Indicates the key of the preferences to modify. It cannot be {@code null} or empty. + * @param {AsyncCallback} callback - {@code true} if the {@link Preferences} object contains a preferences + * with the specified key;returns {@code false} otherwise. + * @throws {BusinessError} 401 - if the parameter type is incorrect. * @since 9 */ has(key: string, callback: AsyncCallback): void; + + /** + * Checks whether the {@link Preferences} object contains a preferences matching a specified key. + * + * @param {string} key - Indicates the key of the preferences to modify. It cannot be {@code null} or empty. + * @returns {Promise} {@code true} if the {@link Preferences} object contains + * a preferences with the specified key; returns {@code false} otherwise. + * @throws {BusinessError} 401 - if the parameter type is incorrect. + * @since 9 + */ has(key: string): Promise; /** @@ -127,13 +208,28 @@ declare namespace preferences { *

You can call the {@link #flush} method to save the {@link Preferences} object to the * file. * - * @param key Indicates the key of the preferences to modify. It cannot be {@code null} or empty. - * @param value Indicates the value of the preferences. - * MAX_KEY_LENGTH. - * @throws BusinessError if invoked failed + * @param {string} key - Indicates the key of the preferences to modify. It cannot be {@code null} or empty. + * @param {ValueType} value - Indicates the value of the preferences. + * MAX_KEY_LENGTH. + * @param {AsyncCallback} callback - Indicates the callback function. + * @throws {BusinessError} 401 - if the parameter type is incorrect. * @since 9 */ put(key: string, value: ValueType, callback: AsyncCallback): void; + + /** + * Sets an int value for the key in the {@link Preferences} object. + * + *

You can call the {@link #flush} method to save the {@link Preferences} object to the + * file. + * + * @param {string} key - Indicates the key of the preferences to modify. It cannot be {@code null} or empty. + * @param {ValueType} value - Indicates the value of the preferences. + * MAX_KEY_LENGTH. + * @returns {Promise} a promise object. + * @throws {BusinessError} 401 - if the parameter type is incorrect. + * @since 9 + */ put(key: string, value: ValueType): Promise; /** @@ -142,40 +238,70 @@ declare namespace preferences { *

You can call the {@link #flush} method to save the {@link Preferences} object to the * file. * - * @param key Indicates the key of the preferences to delete. It cannot be {@code null} or empty. - * MAX_KEY_LENGTH. - * @throws BusinessError if invoked failed + * @param {string} key - Indicates the key of the preferences to delete. It cannot be {@code null} or empty. + * MAX_KEY_LENGTH. + * @param {AsyncCallback} callback - Indicates the callback function. + * @throws {BusinessError} 401 - if the parameter type is incorrect. * @since 9 */ delete(key: string, callback: AsyncCallback): void; - delete(key: string): Promise; /** - * Clears all preferences from the {@link Preferences} object. + * Deletes the preferences with a specified key from the {@link Preferences} object. * *

You can call the {@link #flush} method to save the {@link Preferences} object to the * file. * - * @throws BusinessError if invoked failed + * @param {string} key - Indicates the key of the preferences to delete. It cannot be {@code null} or empty. + * MAX_KEY_LENGTH. + * @returns {Promise} a promise object. + * @throws {BusinessError} 401 - if the parameter type is incorrect. + * @since 9 + */ + delete(key: string): Promise; + + /** + * Clears all preferences from the {@link Preferences} object. + * + *

You can call the {@link #flush} method to save the {@link Preferences} object to the file. + * + * @param {AsyncCallback} callback - Indicates the callback function. * @since 9 */ clear(callback: AsyncCallback): void; + + /** + * Clears all preferences from the {@link Preferences} object. + * + *

You can call the {@link #flush} method to save the {@link Preferences} object to the file. + * + * @returns {Promise} a promise object. + * @since 9 + */ clear(): Promise; /** * Asynchronously saves the {@link Preferences} object to the file. * - * @throws BusinessError if invoked failed + * @param {AsyncCallback} callback - Indicates the callback function. * @since 9 */ flush(callback: AsyncCallback): void; + + /** + * Asynchronously saves the {@link Preferences} object to the file. + * + * @returns {Promise} a promise object. + * @since 9 + */ flush(): Promise; /** * Registers an observer to listen for the change of a {@link Preferences} object. * - * @param callback Indicates the callback when preferences changes. - * @throws BusinessError if invoked failed + * @param {Callback} callback - indicates the callback when preferences changes. + * @param {Callback<{key: string}>} callback - Indicates the callback function. + * @throws {BusinessError} 401 - if the parameter type is incorrect. * @since 9 */ on(type: 'change', callback: Callback<{ key: string }>): void; @@ -183,8 +309,9 @@ declare namespace preferences { /** * Unregisters an existing observer. * - * @param callback Indicates the registered callback. - * @throws BusinessError if invoked failed + * @param {Callback} callback - indicates the callback when preferences changes. + * @param {Callback<{key: string}>} callback - Indicates the callback function. + * @throws {BusinessError} 401 - if the parameter type is incorrect. * @since 9 */ off(type: 'change', callback?: Callback<{ key: string }>): void; -- Gitee