1# @ohos.account.distributedAccount (Distributed Account Management) 2 3<!--Kit: Basic Services Kit--> 4<!--Subsystem: Account--> 5<!--Owner: @steven-q--> 6<!--Designer: @JiDong-CS1--> 7<!--Tester: @zhaimengchao--> 8<!--Adviser: @zengyawen--> 9 10The **distributedAccount** module provides APIs for managing distributed accounts, including querying and updating account login states. 11 12> **NOTE** 13> 14> The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. 15 16## Modules to Import 17 18```ts 19import { distributedAccount } from '@kit.BasicServicesKit'; 20``` 21 22## distributedAccount.getDistributedAccountAbility 23 24getDistributedAccountAbility(): DistributedAccountAbility 25 26Obtains a **DistributedAccountAbility** instance. 27 28**System capability**: SystemCapability.Account.OsAccount 29 30**Return value** 31 32 | Type| Description| 33 | -------- | -------- | 34 | [DistributedAccountAbility](#distributedaccountability) | **DistributedAccountAbility** instance obtained. This instance provides APIs for querying and updating the login state of a distributed account.|| 35 36**Example** 37 ```ts 38 const accountAbility: distributedAccount.DistributedAccountAbility = distributedAccount.getDistributedAccountAbility(); 39 ``` 40 41## DistributedAccountAbility 42 43Provides APIs for querying and updating the login state of a distributed account. You must obtain a **DistributedAccountAbility** instance first. 44 45### getOsAccountDistributedInfo<sup>9+</sup> 46 47getOsAccountDistributedInfo(callback: AsyncCallback<DistributedInfo>): void 48 49Obtains distributed account information. This API uses an asynchronous callback to return the result. 50 51**System capability**: SystemCapability.Account.OsAccount 52 53**Required permissions**: ohos.permission.MANAGE_DISTRIBUTED_ACCOUNTS (for system applications only), ohos.permission.GET_DISTRIBUTED_ACCOUNTS (for system applications only), or ohos.permission.DISTRIBUTED_DATASYNC 54 55**Parameters** 56 57 | Name| Type| Mandatory| Description| 58 | -------- | -------- | -------- | -------- | 59 | callback | AsyncCallback<[DistributedInfo](#distributedinfo)> | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the distributed account information obtained. Otherwise, **err** is an error object.| 60 61**Error codes** 62 63For details about the error codes, see [Account Management Error Codes](errorcode-account.md) and [Universal Error Codes](../errorcode-universal.md). 64 65| ID| Error Message| 66| -------- | ------------------- | 67| 201 | Permission denied.| 68| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 69| 12300001 | System service exception. | 70 71**Example** 72 ```ts 73 import { BusinessError } from '@kit.BasicServicesKit'; 74 75 const accountAbility: distributedAccount.DistributedAccountAbility = distributedAccount.getDistributedAccountAbility(); 76 try { 77 accountAbility.getOsAccountDistributedInfo( 78 (err: BusinessError, data: distributedAccount.DistributedInfo) => { 79 if (err) { 80 console.error('getOsAccountDistributedInfo exception: ' + JSON.stringify(err)); 81 } else { 82 console.log('distributed information: ' + JSON.stringify(data)); 83 } 84 }); 85 } catch (err) { 86 console.error('getOsAccountDistributedInfo exception: ' + JSON.stringify(err)); 87 } 88 ``` 89 90### getOsAccountDistributedInfo<sup>9+</sup> 91 92getOsAccountDistributedInfo(): Promise<DistributedInfo> 93 94Obtains distributed account information. This API uses a promise to return the result. 95 96**System capability**: SystemCapability.Account.OsAccount 97 98**Required permissions**: ohos.permission.MANAGE_DISTRIBUTED_ACCOUNTS (for system applications only), ohos.permission.GET_DISTRIBUTED_ACCOUNTS (for system applications only), or ohos.permission.DISTRIBUTED_DATASYNC 99 100**Return value** 101 102 | Type| Description| 103 | -------- | -------- | 104 | Promise<[DistributedInfo](#distributedinfo)> | Promise used to return the distributed account information obtained.| 105 106**Error codes** 107 108For details about the error codes, see [Account Management Error Codes](errorcode-account.md) and [Universal Error Codes](../errorcode-universal.md). 109 110| ID| Error Message| 111| -------- | ------------------- | 112| 201 | Permission denied.| 113| 12300001 | System service exception. | 114 115**Example** 116 ```ts 117 import { BusinessError } from '@kit.BasicServicesKit'; 118 119 const accountAbility: distributedAccount.DistributedAccountAbility = distributedAccount.getDistributedAccountAbility(); 120 try { 121 accountAbility.getOsAccountDistributedInfo().then((data: distributedAccount.DistributedInfo) => { 122 console.log('distributed information: ' + JSON.stringify(data)); 123 }).catch((err: BusinessError) => { 124 console.error('getOsAccountDistributedInfo exception: ' + JSON.stringify(err)); 125 }); 126 } catch (err) { 127 console.error('getOsAccountDistributedInfo exception: ' + JSON.stringify(err)); 128 } 129 ``` 130 131### queryOsAccountDistributedInfo<sup>(deprecated)</sup> 132 133queryOsAccountDistributedInfo(callback: AsyncCallback<DistributedInfo>): void 134 135Queries distributed account information. This API uses an asynchronous callback to return the result. 136> **NOTE** 137> 138> This API is supported since API version 7 and deprecated since API version 9. Use [getOsAccountDistributedInfo](#getosaccountdistributedinfo9) instead. 139 140**System capability**: SystemCapability.Account.OsAccount 141 142**Required permissions**: ohos.permission.MANAGE_LOCAL_ACCOUNTS (for system applications only) or ohos.permission.DISTRIBUTED_DATASYNC 143 144**Parameters** 145 146 | Name| Type| Mandatory| Description| 147 | -------- | -------- | -------- | -------- | 148 | callback | AsyncCallback<[DistributedInfo](#distributedinfo)> | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the distributed account information obtained. Otherwise, **err** is an error object.| 149 150**Example** 151 ```ts 152 import { BusinessError } from '@kit.BasicServicesKit'; 153 154 const accountAbility: distributedAccount.DistributedAccountAbility = distributedAccount.getDistributedAccountAbility(); 155 accountAbility.queryOsAccountDistributedInfo( 156 (err: BusinessError, data: distributedAccount.DistributedInfo) => { 157 if (err) { 158 console.error('queryOsAccountDistributedInfo exception: ' + JSON.stringify(err)); 159 } else { 160 console.log('distributed information: ' + JSON.stringify(data)); 161 } 162 }); 163 ``` 164 165### queryOsAccountDistributedInfo<sup>(deprecated)</sup> 166 167queryOsAccountDistributedInfo(): Promise<DistributedInfo> 168 169Queries distributed account information. This API uses a promise to return the result. 170 171> **NOTE** 172> 173> This API is supported since API version 7 and deprecated since API version 9. Use [getOsAccountDistributedInfo](#getosaccountdistributedinfo9-1) instead. 174 175**System capability**: SystemCapability.Account.OsAccount 176 177**Required permissions**: ohos.permission.MANAGE_LOCAL_ACCOUNTS (for system applications only) or ohos.permission.DISTRIBUTED_DATASYNC 178 179**Return value** 180 181 | Type| Description| 182 | -------- | -------- | 183 | Promise<[DistributedInfo](#distributedinfo)> | Promise used to return the distributed account information obtained.| 184 185**Example** 186 ```ts 187 import { BusinessError } from '@kit.BasicServicesKit'; 188 189 const accountAbility: distributedAccount.DistributedAccountAbility = distributedAccount.getDistributedAccountAbility(); 190 accountAbility.queryOsAccountDistributedInfo().then((data: distributedAccount.DistributedInfo) => { 191 console.log('distributed information: ' + JSON.stringify(data)); 192 }).catch((err: BusinessError) => { 193 console.error('queryOsAccountDistributedInfo exception: ' + JSON.stringify(err)); 194 }); 195 ``` 196 197### setOsAccountDistributedInfo<sup>9+</sup> 198 199setOsAccountDistributedInfo(accountInfo: DistributedInfo, callback: AsyncCallback<void>): void 200 201Sets the distributed account information. This API uses an asynchronous callback to return the result. 202 203**System capability**: SystemCapability.Account.OsAccount 204 205**Required permissions**: ohos.permission.MANAGE_DISTRIBUTED_ACCOUNTS (available only for system applications) 206 207**Parameters** 208 209 | Name| Type| Mandatory| Description| 210 | -------- | -------- | -------- | -------- | 211 | accountInfo | [DistributedInfo](#distributedinfo) | Yes| Distributed account information to set.| 212 | callback | AsyncCallback<void> | Yes| Callback used to return the result. If the distributed account information is set successfully, **err** is **undefined**. Otherwise, **err** is an error object.| 213 214**Error codes** 215 216For details about the error codes, see [Account Management Error Codes](errorcode-account.md) and [Universal Error Codes](../errorcode-universal.md). 217 218| ID| Error Message| 219| -------- | ------------------- | 220| 201 | Permission denied.| 221| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 222| 12300001 | System service exception. | 223| 12300002 | Invalid accountInfo. | 224| 12300003 | Account not found. | 225 226**Example** 227 ```ts 228 import { BusinessError } from '@kit.BasicServicesKit'; 229 230 const accountAbility: distributedAccount.DistributedAccountAbility = distributedAccount.getDistributedAccountAbility(); 231 let accountInfo: distributedAccount.DistributedInfo = 232 {id: '12345', name: 'ZhangSan', event: 'Ohos.account.event.LOGIN'}; 233 try { 234 accountAbility.setOsAccountDistributedInfo(accountInfo, (err: BusinessError) => { 235 if (err) { 236 console.error('setOsAccountDistributedInfo exception: ' + JSON.stringify(err)); 237 } else { 238 console.log('setOsAccountDistributedInfo successfully'); 239 } 240 }); 241 } catch (err) { 242 console.error('setOsAccountDistributedInfo exception: ' + JSON.stringify(err)); 243 } 244 ``` 245 246### setOsAccountDistributedInfo<sup>9+</sup> 247 248setOsAccountDistributedInfo(accountInfo: DistributedInfo): Promise<void> 249 250Sets the distributed account information. This API uses a promise to return the result. 251 252**System capability**: SystemCapability.Account.OsAccount 253 254**Required permissions**: ohos.permission.MANAGE_DISTRIBUTED_ACCOUNTS (available only for system applications) 255 256**Parameters** 257 258 | Name| Type| Mandatory| Description| 259 | -------- | -------- | -------- | -------- | 260 | accountInfo | [DistributedInfo](#distributedinfo) | Yes| Distributed account information to set.| 261 262**Return value** 263 264 | Type| Description| 265 | -------- | -------- | 266 | Promise<void> | Promise that returns no value.| 267 268**Error codes** 269 270For details about the error codes, see [Account Management Error Codes](errorcode-account.md) and [Universal Error Codes](../errorcode-universal.md). 271 272| ID| Error Message| 273| -------- | ------------------- | 274| 201 | Permission denied.| 275| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 276| 12300001 | System service exception. | 277| 12300002 | Invalid accountInfo. | 278| 12300003 | Account not found. | 279 280**Example** 281 ```ts 282 import { BusinessError } from '@kit.BasicServicesKit'; 283 284 const accountAbility: distributedAccount.DistributedAccountAbility = distributedAccount.getDistributedAccountAbility(); 285 let accountInfo: distributedAccount.DistributedInfo = 286 {id: '12345', name: 'ZhangSan', event: 'Ohos.account.event.LOGIN'}; 287 try { 288 accountAbility.setOsAccountDistributedInfo(accountInfo).then(() => { 289 console.log('setOsAccountDistributedInfo successfully'); 290 }).catch((err: BusinessError) => { 291 console.error('setOsAccountDistributedInfo exception: ' + JSON.stringify(err)); 292 }); 293 } catch (err) { 294 console.error('setOsAccountDistributedInfo exception: ' + JSON.stringify(err)); 295 } 296 ``` 297 298### updateOsAccountDistributedInfo<sup>(deprecated)</sup> 299 300updateOsAccountDistributedInfo(accountInfo: DistributedInfo, callback: AsyncCallback<void>): void 301 302Updates the distributed account information. This API uses an asynchronous callback to return the result. 303 304> **NOTE** 305> 306> This API is supported since API version 7 and deprecated since API version 9. Use [setOsAccountDistributedInfo](#setosaccountdistributedinfo9) instead. 307 308**System capability**: SystemCapability.Account.OsAccount 309 310**Required permissions**: ohos.permission.MANAGE_LOCAL_ACCOUNTS (available only for system applications) 311 312**Parameters** 313 314 | Name| Type| Mandatory| Description| 315 | -------- | -------- | -------- | -------- | 316 | accountInfo | [DistributedInfo](#distributedinfo) | Yes| Distributed account information to update.| 317 | callback | AsyncCallback<void> | Yes| Callback used to return the result. If the distributed account information is updated successfully, **err** is **undefined**. Otherwise, **err** is an error object.| 318 319**Example** 320 ```ts 321 import { BusinessError } from '@kit.BasicServicesKit'; 322 323 const accountAbility: distributedAccount.DistributedAccountAbility = distributedAccount.getDistributedAccountAbility(); 324 let accountInfo: distributedAccount.DistributedInfo = 325 {id: '12345', name: 'ZhangSan', event: 'Ohos.account.event.LOGIN'}; 326 accountAbility.updateOsAccountDistributedInfo(accountInfo, (err: BusinessError) => { 327 if (err) { 328 console.error(`updateOsAccountDistributedInfo exception: code is ${err.code}, message is ${err.message}`); 329 } else { 330 console.info('updateOsAccountDistributedInfo successfully'); 331 } 332 }); 333 ``` 334 335### updateOsAccountDistributedInfo<sup>(deprecated)</sup> 336 337updateOsAccountDistributedInfo(accountInfo: DistributedInfo): Promise<void> 338 339Updates the distributed account information. This API uses a promise to return the result. 340> **NOTE** 341> 342> This API is supported since API version 7 and deprecated since API version 9. Use [setOsAccountDistributedInfo](#setosaccountdistributedinfo9-1) instead. 343 344**System capability**: SystemCapability.Account.OsAccount 345 346**Required permissions**: ohos.permission.MANAGE_LOCAL_ACCOUNTS (available only for system applications) 347 348**Parameters** 349 350 | Name| Type| Mandatory| Description| 351 | -------- | -------- | -------- | -------- | 352 | accountInfo | [DistributedInfo](#distributedinfo) | Yes| Distributed account information to update.| 353 354**Return value** 355 356 | Type| Description| 357 | -------- | -------- | 358 | Promise<void> | Promise that returns no value.| 359 360**Example** 361 ```ts 362 import { BusinessError } from '@kit.BasicServicesKit'; 363 364 const accountAbility: distributedAccount.DistributedAccountAbility = distributedAccount.getDistributedAccountAbility(); 365 let accountInfo: distributedAccount.DistributedInfo = 366 {id: '12345', name: 'ZhangSan', event: 'Ohos.account.event.LOGIN'}; 367 accountAbility.updateOsAccountDistributedInfo(accountInfo).then(() => { 368 console.log('updateOsAccountDistributedInfo successfully'); 369 }).catch((err: BusinessError) => { 370 console.error('updateOsAccountDistributedInfo exception: ' + JSON.stringify(err)); 371 }); 372 ``` 373 374## DistributedInfo 375 376Represents the distributed information about a system account. 377 378**System capability**: SystemCapability.Account.OsAccount 379 380| Name| Type| Mandatory| Description| 381| -------- | -------- | -------- | -------- | 382| name | string |Yes| Name of the distributed account. It must be a non-null string.| 383| id | string |Yes| UID of the distributed account. It must be a non-null string.| 384| event | string |Yes| Login state of the distributed account. The state can be login, logout, token invalid, or logoff, which correspond to the following strings respectively:<br>- Ohos.account.event.LOGIN<br>- Ohos.account.event.LOGOUT<br>- Ohos.account.event.TOKEN_INVALID<br>- Ohos.account.event.LOGOFF | 385| nickname<sup>9+</sup> | string |No| Nickname of the distributed account. By default, no value is passed in.| 386| avatar<sup>9+</sup> | string |No| Avatar of the distributed account. By default, no value is passed in.| 387| status<sup>10+</sup> | [DistributedAccountStatus](#distributedaccountstatus10) |No| Status of the distributed account. The value is of the enumerated type. The default status is unlogged.| 388| scalableData<sup>8+</sup> | object |No| Additional information about the distributed account, in the form of KV pairs. This parameter is left empty by default.| 389 390## DistributedAccountStatus<sup>10+</sup> 391 392Enumerates the statuses of a distributed account. 393 394**System capability**: SystemCapability.Account.OsAccount 395 396| Name | Value| Description | 397| ---- | ------ | ----------- | 398| NOT_LOGGED_IN | 0 | The account has not logged in.| 399| LOGGED_IN | 1 | The account has logged in.| 400