1# @ohos.account.distributedAccount (Distributed Account Management) 2 3The **distributedAccount** module provides APIs for managing distributed accounts, including querying and updating account login states. 4 5> **NOTE** 6> 7> 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. 8 9## Modules to Import 10 11```js 12import account_distributedAccount from '@ohos.account.distributedAccount'; 13``` 14 15## account_distributedAccount.getDistributedAccountAbility 16 17getDistributedAccountAbility(): DistributedAccountAbility 18 19Obtains a **DistributedAccountAbility** instance. 20 21**System capability**: SystemCapability.Account.OsAccount 22 23**Return value** 24 25 | Type| Description| 26 | -------- | -------- | 27 | [DistributedAccountAbility](#distributedaccountability) | **DistributedAccountAbility** instance obtained. This instance provides APIs for querying and updating the login state of a distributed account.| 28 29**Example** 30 ```js 31 const accountAbility = account_distributedAccount.getDistributedAccountAbility(); 32 ``` 33 34## DistributedAccountAbility 35 36Provides APIs for querying and updating the login state of a distributed account. You must obtain a **DistributedAccountAbility** instance first. 37 38### getOsAccountDistributedInfo<sup>9+</sup> 39 40getOsAccountDistributedInfo(callback: AsyncCallback<DistributedInfo>): void 41 42Obtains distributed account information. This API uses an asynchronous callback to return the result. 43 44**System capability**: SystemCapability.Account.OsAccount 45 46**Required permissions**: ohos.permission.MANAGE_DISTRIBUTED_ACCOUNTS, ohos.permission.GET_DISTRIBUTED_ACCOUNTS, or ohos.permission.DISTRIBUTED_DATASYNC 47 48**Parameters** 49 50 | Name| Type| Mandatory| Description| 51 | -------- | -------- | -------- | -------- | 52 | callback | AsyncCallback<[DistributedInfo](#distributedinfo)> | Yes| Callback invoked 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.| 53 54**Error codes** 55 56| ID| Error Message| 57| -------- | ------------------- | 58| 12300001 | System service exception. | 59 60**Example** 61 ```js 62 const accountAbility = account_distributedAccount.getDistributedAccountAbility(); 63 try { 64 accountAbility.getOsAccountDistributedInfo((err, data) => { 65 console.log("getOsAccountDistributedInfo err: " + JSON.stringify(err)); 66 console.log('Query account info name: ' + data.name); 67 console.log('Query account info id: ' + data.id); 68 }); 69 } catch (e) { 70 console.log("getOsAccountDistributedInfo exception: " + JSON.stringify(e)); 71 } 72 ``` 73 74### getOsAccountDistributedInfo<sup>9+</sup> 75 76getOsAccountDistributedInfo(): Promise<DistributedInfo> 77 78Obtains distributed account information. This API uses a promise to return the result. 79 80**System capability**: SystemCapability.Account.OsAccount 81 82**Required permissions**: ohos.permission.MANAGE_DISTRIBUTED_ACCOUNTS, ohos.permission.GET_DISTRIBUTED_ACCOUNTS, or ohos.permission.DISTRIBUTED_DATASYNC 83 84**Return value** 85 86 | Type| Description| 87 | -------- | -------- | 88 | Promise<[DistributedInfo](#distributedinfo)> | Promise used to return the distributed account information obtained.| 89 90**Error codes** 91 92| ID| Error Message| 93| -------- | ------------------- | 94| 12300001 | System service exception. | 95 96**Example** 97 ```js 98 const accountAbility = account_distributedAccount.getDistributedAccountAbility(); 99 try { 100 accountAbility.getOsAccountDistributedInfo().then((data) => { 101 console.log('Query account info name: ' + data.name); 102 console.log('Query account info id: ' + data.id); 103 }).catch((err) => { 104 console.log("getOsAccountDistributedInfo err: " + JSON.stringify(err)); 105 }); 106 } catch (e) { 107 console.log("getOsAccountDistributedInfo exception: " + JSON.stringify(e)); 108 } 109 ``` 110### queryOsAccountDistributedInfo<sup>(deprecated)</sup> 111 112queryOsAccountDistributedInfo(callback: AsyncCallback<DistributedInfo>): void 113 114Obtains distributed account information. This API uses an asynchronous callback to return the result. 115> **NOTE** 116> 117> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [getOsAccountDistributedInfo](#getosaccountdistributedinfo9). 118 119**System capability**: SystemCapability.Account.OsAccount 120 121**Required permissions**: ohos.permission.MANAGE_LOCAL_ACCOUNTS or ohos.permission.DISTRIBUTED_DATASYNC 122 123**Parameters** 124 125 | Name| Type| Mandatory| Description| 126 | -------- | -------- | -------- | -------- | 127 | callback | AsyncCallback<[DistributedInfo](#distributedinfo)> | Yes| Callback invoked 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.| 128 129**Example** 130 ```js 131 const accountAbility = account_distributedAccount.getDistributedAccountAbility(); 132 accountAbility.queryOsAccountDistributedInfo((err, data) => { 133 console.log("queryOsAccountDistributedInfo err: " + JSON.stringify(err)); 134 console.log('Query account info name: ' + data.name); 135 console.log('Query account info id: ' + data.id); 136 }); 137 ``` 138 139### queryOsAccountDistributedInfo<sup>(deprecated)</sup> 140 141queryOsAccountDistributedInfo(): Promise<DistributedInfo> 142 143Obtains distributed account information. This API uses a promise to return the result. 144 145> **NOTE** 146> 147> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [getOsAccountDistributedInfo](#getosaccountdistributedinfo9-1). 148 149**System capability**: SystemCapability.Account.OsAccount 150 151**Required permissions**: ohos.permission.MANAGE_LOCAL_ACCOUNTS or ohos.permission.DISTRIBUTED_DATASYNC 152 153**Return value** 154 155 | Type| Description| 156 | -------- | -------- | 157 | Promise<[DistributedInfo](#distributedinfo)> | Promise used to return the distributed account information obtained.| 158 159**Example** 160 ```js 161 const accountAbility = account_distributedAccount.getDistributedAccountAbility(); 162 accountAbility.queryOsAccountDistributedInfo().then((data) => { 163 console.log('Query account info name: ' + data.name); 164 console.log('Query account info id: ' + data.id); 165 }).catch((err) => { 166 console.log("queryOsAccountDistributedInfoerr: " + JSON.stringify(err)); 167 }); 168 ``` 169 170### setOsAccountDistributedInfo<sup>9+</sup> 171 172setOsAccountDistributedInfo(accountInfo: DistributedInfo, callback: AsyncCallback<void>): void 173 174Sets the distributed account information. This API uses an asynchronous callback to return the result. 175 176**System capability**: SystemCapability.Account.OsAccount 177 178**Required permissions**: ohos.permission.MANAGE_DISTRIBUTED_ACCOUNTS 179 180**Parameters** 181 182 | Name| Type| Mandatory| Description| 183 | -------- | -------- | -------- | -------- | 184 | accountInfo | [DistributedInfo](#distributedinfo) | Yes| Distributed account information to set.| 185 | callback | AsyncCallback<void> | Yes| Callback invoked to return the result. If the distributed account information is set successfully, **err** is **undefined**. Otherwise, **err** is an error object.| 186 187**Error codes** 188 189| ID| Error Message| 190| -------- | ------------------- | 191| 12300001 | System service exception. | 192| 12300002 | Invalid accountInfo. | 193| 12300003 | Account not found. | 194 195**Example** 196 ```js 197 const accountAbility = account_distributedAccount.getDistributedAccountAbility(); 198 let accountInfo = {id: '12345', name: 'ZhangSan', event: 'Ohos.account.event.LOGIN'}; 199 try { 200 accountAbility.setOsAccountDistributedInfo(accountInfo, (err) => { 201 console.log("setOsAccountDistributedInfo err: " + JSON.stringify(err)); 202 }); 203 } catch (e) { 204 console.log("setOsAccountDistributedInfo exception: " + JSON.stringify(e)); 205 } 206 ``` 207 208### setOsAccountDistributedInfo<sup>9+</sup> 209 210setOsAccountDistributedInfo(accountInfo: DistributedInfo): Promise<void> 211 212Sets the distributed account information. This API uses a promise to return the result. 213 214**System capability**: SystemCapability.Account.OsAccount 215 216**Required permissions**: ohos.permission.MANAGE_DISTRIBUTED_ACCOUNTS 217 218**Parameters** 219 220 | Name| Type| Mandatory| Description| 221 | -------- | -------- | -------- | -------- | 222 | accountInfo | [DistributedInfo](#distributedinfo) | Yes| Distributed account information to set.| 223 224**Return value** 225 226 | Type| Description| 227 | -------- | -------- | 228 | Promise<void> | Promise that returns no value.| 229 230**Error codes** 231 232| ID| Error Message| 233| -------- | ------------------- | 234| 12300001 | System service exception. | 235| 12300002 | Invalid accountInfo. | 236 237**Example** 238 ```js 239 const accountAbility = account_distributedAccount.getDistributedAccountAbility(); 240 let accountInfo = {id: '12345', name: 'ZhangSan', event: 'Ohos.account.event.LOGIN'}; 241 try { 242 accountAbility.setOsAccountDistributedInfo(accountInfo).then(() => { 243 console.log('setOsAccountDistributedInfo Success'); 244 }).catch((err) => { 245 console.log("setOsAccountDistributedInfo err: " + JSON.stringify(err)); 246 }); 247 } catch (e) { 248 console.log("setOsAccountDistributedInfo exception: " + JSON.stringify(e)); 249 } 250 ``` 251### updateOsAccountDistributedInfo<sup>(deprecated)</sup> 252 253updateOsAccountDistributedInfo(accountInfo: DistributedInfo, callback: AsyncCallback<void>): void 254 255Updates the distributed account information. This API uses an asynchronous callback to return the result. 256 257> **NOTE** 258> 259> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setOsAccountDistributedInfo](#setosaccountdistributedinfo9). 260 261**System capability**: SystemCapability.Account.OsAccount 262 263**Required permissions**: ohos.permission.MANAGE_LOCAL_ACCOUNTS 264 265**Parameters** 266 267 | Name| Type| Mandatory| Description| 268 | -------- | -------- | -------- | -------- | 269 | accountInfo | [DistributedInfo](#distributedinfo) | Yes| New distributed account information.| 270 | callback | AsyncCallback<void> | Yes| Callback invoked to return the result. If the distributed account information is set successfully, **err** is **undefined**. Otherwise, **err** is an error object.| 271 272**Example** 273 ```js 274 const accountAbility = account_distributedAccount.getDistributedAccountAbility(); 275 let accountInfo = {id: '12345', name: 'ZhangSan', event: 'Ohos.account.event.LOGIN'}; 276 accountAbility.updateOsAccountDistributedInfo(accountInfo, (err) => { 277 console.log("queryOsAccountDistributedInfo err: " + JSON.stringify(err)); 278 }); 279 ``` 280 281### updateOsAccountDistributedInfo<sup>(deprecated)</sup> 282 283updateOsAccountDistributedInfo(accountInfo: DistributedInfo): Promise<void> 284 285Updates the distributed account information. This API uses a promise to return the result. 286> **NOTE** 287> 288> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setOsAccountDistributedInfo](#setosaccountdistributedinfo9-1). 289**System capability**: SystemCapability.Account.OsAccount 290 291**Required permissions**: ohos.permission.MANAGE_LOCAL_ACCOUNTS 292 293**Parameters** 294 295 | Name| Type| Mandatory| Description| 296 | -------- | -------- | -------- | -------- | 297 | accountInfo | [DistributedInfo](#distributedinfo) | Yes| New distributed account information.| 298 299**Return value** 300 301 | Type| Description| 302 | -------- | -------- | 303 | Promise<void> | Promise that returns no value.| 304 305**Example** 306 ```js 307 const accountAbility = account_distributedAccount.getDistributedAccountAbility(); 308 let accountInfo = {id: '12345', name: 'ZhangSan', event: 'Ohos.account.event.LOGIN'}; 309 accountAbility.updateOsAccountDistributedInfo(accountInfo).then(() => { 310 console.log('updateOsAccountDistributedInfo Success'); 311 }).catch((err) => { 312 console.log("updateOsAccountDistributedInfo err: " + JSON.stringify(err)); 313 }); 314 ``` 315## DistributedInfo 316 317Defines distributed OS account information. 318 319**System capability**: SystemCapability.Account.OsAccount 320 321| Name| Type| Mandatory| Description| 322| -------- | -------- | -------- | -------- | 323| name | string | Yes| Name of the distributed account. It must be a non-null string.| 324| id | string | Yes| UID of the distributed account. It must be a non-null string.| 325| 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 | 326| nickname<sup>9+</sup> | string | No| Nickname of the distributed account. It must be a non-null string.| 327| avatar<sup>9+</sup> | string | No| Avatar of the distributed account. It must be a non-null string.| 328| scalableData | object | No| Extended information about the distributed account, passed in key-value (KV) pairs.<br>**NOTE**<br>This parameter is reserved and not used in the setters and getters.| 329