1/* 2 * Copyright (c) 2021-2022 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16import {AsyncCallback, Callback} from "./basic"; 17import {Want} from "./ability/want"; 18 19/** 20 * This module provides the capability to manage application accounts. 21 * 22 * @since 7 23 * @syscap SystemCapability.Account.AppAccount 24 */ 25declare namespace appAccount { 26 /** 27 * Obtains the AppAccountManager instance. 28 * @since 7 29 * @syscap SystemCapability.Account.AppAccount 30 * @return Returns the instance of the AppAccountManager. 31 */ 32 function createAppAccountManager(): AppAccountManager; 33 34 /** 35 * Provides methods for managing application accounts. 36 * @name AppAccountManager 37 * @since 7 38 * @syscap SystemCapability.Account.AppAccount 39 */ 40 interface AppAccountManager { 41 /** 42 * Adds the account name and extra information of this application to the account management service. 43 * <p> 44 * Only the owner of the application account has the permission to call this method. 45 * 46 * @since 7 47 * @param name Indicates the name of the application account to add. 48 * @param extraInfo Indicates the extra information of the application account to add. 49 * The extra information cannot be sensitive information of the application account. 50 * @return void. 51 */ 52 addAccount(name: string, callback: AsyncCallback<void>): void; 53 addAccount(name: string, extraInfo: string, callback: AsyncCallback<void>): void; 54 addAccount(name: string, extraInfo?: string): Promise<void>; 55 56 /** 57 * Adds an application account of a specified owner implicitly. 58 * 59 * @since 8 60 * @param owner Indicates the account owner of your application or third-party applications. 61 * @param authType Indicates the authentication type. 62 * @param options Indicates the authenticator-specific options for the request. 63 * @param callback Indicates the authenticator callback. 64 * @return void. 65 */ 66 addAccountImplicitly(owner: string, authType: string, options: {[key: string]: any}, callback: AuthenticatorCallback): void; 67 68 /** 69 * Deletes an application account from the account management service. 70 * <p> 71 * Only the owner of the application account has the permission to call this method. 72 * 73 * @since 7 74 * @param name Indicates the name of the application account to delete. 75 * @return void. 76 */ 77 deleteAccount(name: string, callback: AsyncCallback<void>): void; 78 deleteAccount(name: string): Promise<void>; 79 80 /** 81 * Disables a third-party application with the specified bundle name from 82 * accessing the given application account. 83 * 84 * @since 7 85 * @param name Indicates the name of the application account to disable access from 86 * the third-party application. 87 * @param bundleName Indicates the bundle name of the third-party application. 88 * @return void. 89 */ 90 disableAppAccess(name: string, bundleName: string, callback: AsyncCallback<void>): void; 91 disableAppAccess(name: string, bundleName: string): Promise<void>; 92 93 /** 94 * Enables a third-party application with the specified bundle name to access the given application 95 * account for data query and listening. 96 * 97 * @since 7 98 * @param name Indicates the name of the application account. 99 * @param bundleName Indicates the bundle name of the third-party application. 100 * @return void. 101 */ 102 enableAppAccess(name: string, bundleName: string, callback: AsyncCallback<void>): void; 103 enableAppAccess(name: string, bundleName: string): Promise<void>; 104 105 /** 106 * Checks whether a specified application account allows application data synchronization. 107 * <p> 108 * If the same OHOS account has logged in to multiple devices, these devices constitute a super device 109 * through the distributed networking. On the networked devices, you can call this method to check 110 * whether application data can be synchronized. 111 * <p> 112 * 113 * @since 7 114 * @param name Indicates the name of the application account. 115 * @return Returns {@code true} if application data synchronization is allowed; returns {@code false} otherwise. 116 * @permission ohos.permission.DISTRIBUTED_DATASYNC. 117 */ 118 checkAppAccountSyncEnable(name: string, callback: AsyncCallback<boolean>): void; 119 checkAppAccountSyncEnable(name: string): Promise<boolean>; 120 121 /** 122 * Sets the credential for this application account. 123 * 124 * @since 7 125 * @param name Indicates the name of the application account. 126 * @param credentialType Indicates the type of the credential to set. 127 * @param credential Indicates the credential to set. 128 * @return void. 129 */ 130 setAccountCredential(name: string, credentialType: string, credential: string, 131 callback: AsyncCallback<void>): void; 132 setAccountCredential(name: string, credentialType: string, credential: string): Promise<void>; 133 134 /** 135 * Sets extra information for this application account. 136 * <p> 137 * You can call this method when you forget the extra information of your application account or 138 * need to modify the extra information. 139 * 140 * @since 7 141 * @param name Indicates the name of the application account. 142 * @param extraInfo Indicates the extra information to set. 143 * @return void. 144 */ 145 setAccountExtraInfo(name: string, extraInfo: string, callback: AsyncCallback<void>): void; 146 setAccountExtraInfo(name: string, extraInfo: string): Promise<void>; 147 148 /** 149 * Sets whether a specified application account allows application data synchronization. 150 * <p> 151 * If the same OHOS account has logged in to multiple devices, these devices constitute a super device 152 * through the distributed networking. On the networked devices, you can call this method to set whether to 153 * allow cross-device data synchronization. If synchronization is allowed, application data can be synchronized 154 * among these devices in the event of any changes related to the application account. 155 * If synchronization is not allowed, the application data is stored only on the local device. 156 * <p> 157 * <b>Application account-related changes</b>: adding or deleting an application account, setting extra 158 * information (such as updating a token), and setting data associated with this application account 159 * <p> 160 * <b>Application data that can be synchronized</b>: application account name, token, 161 * and data associated with this application account 162 * <p> 163 * 164 * @since 7 165 * @param name Indicates the name of the application account. 166 * @param isEnable Specifies whether to allow application data synchronization. 167 * @return void. 168 * @permission ohos.permission.DISTRIBUTED_DATASYNC. 169 */ 170 setAppAccountSyncEnable(name: string, isEnable: boolean, callback: AsyncCallback<void>): void; 171 setAppAccountSyncEnable(name: string, isEnable: boolean): Promise<void>; 172 173 /** 174 * Sets data associated with this application account. 175 * 176 * @since 7 177 * @param name Indicates the name of the application account. 178 * @param key Indicates the key of the data to set. The key can be customized. 179 * @param value Indicates the value of the data to set. 180 * @return void. 181 */ 182 setAssociatedData(name: string, key: string, value: string, callback: AsyncCallback<void>): void; 183 setAssociatedData(name: string, key: string, value: string): Promise<void>; 184 185 /** 186 * Obtains information about all accessible accounts. 187 * <p> 188 * This method applies to the following accounts: 189 * <ul> 190 * <li>Accounts of this application.</li> 191 * <li>Accounts of third-party applications. To obtain such information, 192 * your application must have gained authorization from the third-party applications.</li> 193 * </ul> 194 * 195 * @since 7 196 * @return Returns a list of application accounts. 197 * @permission ohos.permission.GET_ALL_APP_ACCOUNTS. 198 */ 199 getAllAccessibleAccounts(callback: AsyncCallback<Array<AppAccountInfo>>): void; 200 getAllAccessibleAccounts(): Promise<Array<AppAccountInfo>>; 201 202 /** 203 * Obtains information about all accounts of a specified account owner. 204 * <p> 205 * This method applies to the following accounts: 206 * <ul> 207 * <li>Accounts of this application.</li> 208 * <li>Accounts of third-party applications. To obtain such information, 209 * your application must have gained authorization from the third-party applications.</li> 210 * </ul> 211 * 212 * @since 7 213 * @param owner Indicates the account owner of your application or third-party applications. 214 * @return Returns a list of application accounts. 215 * @permission ohos.permission.GET_ALL_APP_ACCOUNTS. 216 */ 217 getAllAccounts(owner: string, callback: AsyncCallback<Array<AppAccountInfo>>): void; 218 getAllAccounts(owner: string): Promise<Array<AppAccountInfo>>; 219 220 /** 221 * Obtains the credential of this application account. 222 * 223 * @since 7 224 * @param name Indicates the name of the application account. 225 * @param credentialType Indicates the type of the credential to obtain. 226 * @return Returns the credential of the application account. 227 */ 228 getAccountCredential(name: string, credentialType: string, callback: AsyncCallback<string>): void; 229 getAccountCredential(name: string, credentialType: string): Promise<string>; 230 231 /** 232 * Obtains extra information of this application account. 233 * 234 * @since 7 235 * @param name Indicates the name of the application account. 236 * @return Returns the extra information of the account; returns {@code null} in other scenarios, 237 * for example, if the account does not exist. 238 */ 239 getAccountExtraInfo(name: string, callback: AsyncCallback<string>): void; 240 getAccountExtraInfo(name: string): Promise<string>; 241 242 /** 243 * Obtains data associated with this application account. 244 * 245 * @since 7 246 * @param name Indicates the name of the application account. 247 * @param key Indicates the key of the data to obtain. 248 * @return Returns the associated data of the application account. 249 */ 250 getAssociatedData(name: string, key: string, callback: AsyncCallback<string>): void; 251 getAssociatedData(name: string, key: string): Promise<string>; 252 253 /** 254 * Subscribes to the change events of accounts of the specified owners. 255 * <p> 256 * When the account owner updates the account, the subscriber will receive a notification 257 * about the account change event. 258 * 259 * @since 7 260 * @param owners Indicates the account owners, which are specified 261 * by {@link AppAccount#AppAccount(String name, String owner)}. 262 * @return void 263 */ 264 on(type: 'change', owners: Array<string>, callback: Callback<Array<AppAccountInfo>>): void; 265 266 /** 267 * Unsubscribes from account events. 268 * 269 * @since 7 270 * @return void 271 */ 272 off(type: 'change', callback?: Callback<Array<AppAccountInfo>>): void; 273 274 /** 275 * Authenticates an application account to get an oauth token. 276 * 277 * @since 8 278 * @param name Indicates the account name of your application or third-party applications. 279 * @param owner Indicates the account owner of your application or third-party applications. 280 * @param authType Indicates the authentication type. 281 * @param options Indicates the authenticator-specific options for the request. 282 * @param callback Indicates the authenticator callback. 283 * @return void. 284 */ 285 authenticate(name: string, owner: string, authType: string, options: {[key: string]: any}, callback: AuthenticatorCallback): void; 286 287 /** 288 * Gets an oauth token with the specified authentication type from a particular application account. 289 * 290 * @since 8 291 * @param name Indicates the account name of your application or third-party applications. 292 * @param owner Indicates the account owner of your application or third-party applications. 293 * @param authType Indicates the authentication type. 294 * @return Returns an oauth token. 295 */ 296 getOAuthToken(name: string, owner: string, authType: string, callback: AsyncCallback<string>): void; 297 getOAuthToken(name: string, owner: string, authType: string): Promise<string>; 298 299 /** 300 * Sets an oauth token with the specified authentication type for a particular account. 301 * <p> 302 * Only the owner of the application account has the permission to call this method. 303 * 304 * @since 8 305 * @param name Indicates the account name of your application. 306 * @param authType Indicates the authentication type. 307 * @param token Indicates the oauth token. 308 * @return void. 309 */ 310 setOAuthToken(name: string, authType: string, token: string, callback: AsyncCallback<void>): void; 311 setOAuthToken(name: string, authType: string, token: string): Promise<void>; 312 313 /** 314 * Deletes an oauth token for the specified application account. 315 * <p> 316 * Only tokens visible to the caller application can be deleted. 317 * 318 * @since 8 319 * @param name Indicates the account name of your application or third-party applications. 320 * @param owner Indicates the account owner of your application or third-party applications. 321 * @param authType Indicates the authentication type. 322 * @param token Indicates the oauth token. 323 * @return void. 324 */ 325 deleteOAuthToken(name: string, owner: string, authType: string, token: string, callback: AsyncCallback<void>): void; 326 deleteOAuthToken(name: string, owner: string, authType: string, token: string): Promise<void>; 327 328 /** 329 * Sets the oauth token visibility of the specified authentication type to a third-party application. 330 * <p> 331 * Only the owner of the application account has the permission to call this method. 332 * 333 * @since 8 334 * @param name Indicates the account name of your application. 335 * @param authType Indicates the authentication type. 336 * @param bundleName Indicates the bundle name of the third-party application. 337 * @param isVisible Indicates the bool value of visibility. 338 * @return void. 339 */ 340 setOAuthTokenVisibility(name: string, authType: string, bundleName: string, isVisible: boolean, callback: AsyncCallback<void>): void; 341 setOAuthTokenVisibility(name: string, authType: string, bundleName: string, isVisible: boolean): Promise<void>; 342 343 /** 344 * Checks the oauth token visibility of the specified authentication type for a third-party application. 345 * <p> 346 * Only the owner of the application account has the permission to call this method. 347 * 348 * @since 8 349 * @param name Indicates the account name of your application or third-party applications. 350 * @param authType Indicates the authentication type. 351 * @param bundleName Indicates the bundle name of the third-party application. 352 * @return Returns the bool value of visibility. 353 */ 354 checkOAuthTokenVisibility(name: string, authType: string, bundleName: string, callback: AsyncCallback<boolean>): void; 355 checkOAuthTokenVisibility(name: string, authType: string, bundleName: string): Promise<boolean>; 356 357 /** 358 * Gets all oauth tokens visible to the caller application. 359 * 360 * @since 8 361 * @param name Indicates the account name of your application or third-party applications. 362 * @param owner Indicates the account owner of your application or third-party applications. 363 * @return Returns a list of oauth tokens visible to the caller application. 364 */ 365 getAllOAuthTokens(name: string, owner: string, callback: AsyncCallback<Array<OAuthTokenInfo>>): void; 366 getAllOAuthTokens(name: string, owner: string): Promise<Array<OAuthTokenInfo>>; 367 368 /** 369 * Gets the open authorization list with a specified authentication type for a paticular application account. 370 * <p> 371 * Only the owner of the application account has the permission to call this method. 372 * 373 * @since 8 374 * @param name Indicates the account name of your application. 375 * @param authType Indicates the authentication type. 376 * @return Returns the open authorization list of the specified authentication type. 377 */ 378 getOAuthList(name: string, authType: string, callback: AsyncCallback<Array<string>>): void; 379 getOAuthList(name: string, authType: string): Promise<Array<string>>; 380 381 /** 382 * Gets the authenticator callback with the specified session id. 383 * <p> 384 * Only the owner of the authenticator has the permission to call this method. 385 * 386 * @since 8 387 * @param sessionId Indicates the id of a authentication session. 388 * @return Returns the authenticator callback related to the session id. 389 */ 390 getAuthenticatorCallback(sessionId: string, callback: AsyncCallback<AuthenticatorCallback>): void; 391 getAuthenticatorCallback(sessionId: string): Promise<AuthenticatorCallback>; 392 393 /** 394 * Gets the authenticator information of an application account. 395 * 396 * @since 8 397 * @param owner Indicates the account owner of your application or third-party applications. 398 * @return Returns the authenticator information of the application account. 399 */ 400 getAuthenticatorInfo(owner: string, callback: AsyncCallback<AuthenticatorInfo>): void; 401 getAuthenticatorInfo(owner: string): Promise<AuthenticatorInfo>; 402 } 403 404 /** 405 * Provides basic information of an application account, including the account owner and name. 406 * @name AppAccountInfo 407 * @since 7 408 * @syscap SystemCapability.Account.AppAccount 409 */ 410 interface AppAccountInfo { 411 /** 412 * The owner an application account. 413 */ 414 owner: string; 415 416 /** 417 * The name an application account. 418 */ 419 name: string; 420 } 421 422 /** 423 * Provides basic information of an oauth token, including the authentication type and token value. 424 * @name OAuthTokenInfo 425 * @since 8 426 * @syscap SystemCapability.Account.AppAccount 427 */ 428 interface OAuthTokenInfo { 429 /** 430 * The authentication type. 431 */ 432 authType: string; 433 434 /** 435 * The token value. 436 */ 437 token: string; 438 } 439 440 /** 441 * Provides basic information of an authenticator, including the authenticator owner, icon id and label id. 442 * @name AuthenticatorInfo 443 * @since 8 444 * @syscap SystemCapability.Account.AppAccount 445 */ 446 interface AuthenticatorInfo { 447 /** 448 * The owner of an authenticator. 449 */ 450 owner: string; 451 452 /** 453 * The icon id of an authenticator. 454 */ 455 iconId: number; 456 457 /** 458 * The label id of an authenticator. 459 */ 460 labelId: number; 461 } 462 463 /** 464 * Provides constants definition. 465 * @name Constants 466 * @since 8 467 * @syscap SystemCapability.Account.AppAccount 468 */ 469 enum Constants { 470 ACTION_ADD_ACCOUNT_IMPLICITLY = "addAccountImplicitly", 471 ACTION_AUTHENTICATE = "authenticate", 472 KEY_NAME = "name", 473 KEY_OWNER = "owner", 474 KEY_TOKEN = "token", 475 KEY_ACTION = "action", 476 KEY_AUTH_TYPE = "authType", 477 KEY_SESSION_ID = "sessionId", 478 KEY_CALLER_PID = "callerPid", 479 KEY_CALLER_UID = "callerUid", 480 KEY_CALLER_BUNDLE_NAME = "callerBundleName", 481 } 482 483 /** 484 * Provides result code definition. 485 * @name ResultCode 486 * @since 8 487 * @syscap SystemCapability.Account.AppAccount 488 */ 489 enum ResultCode { 490 SUCCESS = 0, 491 ERROR_ACCOUNT_NOT_EXIST = 10001, 492 ERROR_APP_ACCOUNT_SERVICE_EXCEPTION = 10002, 493 ERROR_INVALID_PASSWORD = 10003, 494 ERROR_INVALID_REQUEST = 10004, 495 ERROR_INVALID_RESPONSE = 10005, 496 ERROR_NETWORK_EXCEPTION = 10006, 497 ERROR_OAUTH_AUTHENTICATOR_NOT_EXIST = 10007, 498 ERROR_OAUTH_CANCELED = 10008, 499 ERROR_OAUTH_LIST_TOO_LARGE = 10009, 500 ERROR_OAUTH_SERVICE_BUSY = 10010, 501 ERROR_OAUTH_SERVICE_EXCEPTION = 10011, 502 ERROR_OAUTH_SESSION_NOT_EXIST = 10012, 503 ERROR_OAUTH_TIMEOUT = 10013, 504 ERROR_OAUTH_TOKEN_NOT_EXIST = 10014, 505 ERROR_OAUTH_TOKEN_TOO_MANY = 10015, 506 ERROR_OAUTH_UNSUPPORT_ACTION = 10016, 507 ERROR_OAUTH_UNSUPPORT_AUTH_TYPE = 10017, 508 ERROR_PERMISSION_DENIED = 10018 509 } 510 511 /** 512 * Provides methods for authenticator callback. 513 * @name AuthenticatorCallback 514 * @since 8 515 * @syscap SystemCapability.Account.AppAccount 516 */ 517 interface AuthenticatorCallback { 518 /** 519 * Notifies the client of the authentication result. 520 * 521 * @since 8 522 * @param code Indicates the result code. 523 * @param result Indicates the authentication result. 524 * @return void. 525 */ 526 onResult: (code: number, result: {[key: string]: any}) => void; 527 528 /** 529 * Notifies the client that the authentication request need to be redirected. 530 * 531 * @since 8 532 * @param request Indicates the request information to be redirected. 533 * @return void. 534 */ 535 onRequestRedirected: (request: Want) => void; 536 } 537 538 /** 539 * Provides methods for authenticator. 540 * @name Authenticator 541 * @since 8 542 * @syscap SystemCapability.Account.AppAccount 543 */ 544 class Authenticator { 545 /** 546 * Adds an application account of a specified owner implicitly. 547 * 548 * @since 8 549 * @param authType Indicates the authentication type. 550 * @param callerBundleName Indicates the caller bundle name. 551 * @param options Indicates the authenticator-specific options for the request. 552 * @param callback Indicates the authenticator callback. 553 * @return void. 554 */ 555 addAccountImplicitly(authType: string, callerBundleName: string, options: {[key: string]: any}, callback: AuthenticatorCallback): void; 556 557 /** 558 * Authenticates an application account to get an oauth token. 559 * 560 * @since 8 561 * @param name Indicates the account name. 562 * @param authType Indicates the authentication type. 563 * @param callerBundleName Indicates the caller bundle name. 564 * @param options Indicates the authenticator-specific options for the request. 565 * @param callback Indicates the authenticator callback. 566 * @return void. 567 */ 568 authenticate(name: string, authType: string, callerBundleName: string, options: {[key: string]: any}, callback: AuthenticatorCallback): void; 569 } 570} 571 572export default appAccount;