1# @ohos.account.distributedAccount (Distributed Account Management) (System API) 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> - This topic describes only the system APIs provided by the module. For details about its public APIs, see [@ohos.account.distributedAccount (Distributed Account Management)](js-apis-distributed-account.md). 16 17## Modules to Import 18 19```ts 20import { distributedAccount } from '@kit.BasicServicesKit'; 21``` 22 23## DistributedAccountAbility 24 25Provides APIs for querying and updating the login state of a distributed account. You must obtain a **DistributedAccountAbility** instance first. 26 27### getOsAccountDistributedInfoByLocalId<sup>10+</sup> 28 29getOsAccountDistributedInfoByLocalId(localId: number, callback: AsyncCallback<DistributedInfo>): void 30 31Obtains distributed information about a system account. This API uses an asynchronous callback to return the result. 32 33**System API**: This is a system API. 34 35**System capability**: SystemCapability.Account.OsAccount 36 37**Required permissions**: ohos.permission.MANAGE_DISTRIBUTED_ACCOUNTS; or ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS and ohos.permission.GET_DISTRIBUTED_ACCOUNTS 38 39**Parameters** 40 41 | Name| Type| Mandatory| Description| 42 | -------- | -------- | -------- | -------- | 43 | localId | number | Yes| ID of the target system account.| 44 | callback | AsyncCallback<[DistributedInfo](js-apis-distributed-account.md#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.| 45 46**Error codes** 47 48| ID| Error Message| 49| -------- | ------------------- | 50| 201 | Permission denied.| 51| 202 | Not system application.| 52| 12300001 | System service exception. | 53| 12300003 | Account not found. | 54 55**Example** 56 57```ts 58import { BusinessError } from '@kit.BasicServicesKit'; 59 60const accountAbility: distributedAccount.DistributedAccountAbility = distributedAccount.getDistributedAccountAbility(); 61try { 62 accountAbility.getOsAccountDistributedInfoByLocalId(100, 63 (err: BusinessError, data: distributedAccount.DistributedInfo) => { 64 if (err) { 65 console.error('getOsAccountDistributedInfoByLocalId exception: ' + JSON.stringify(err)); 66 } else { 67 console.log('distributed information: ' + JSON.stringify(data)); 68 } 69 }); 70} catch (err) { 71 console.error('getOsAccountDistributedInfoByLocalId exception: ' + JSON.stringify(err)); 72} 73``` 74 75### getOsAccountDistributedInfoByLocalId<sup>10+</sup> 76 77getOsAccountDistributedInfoByLocalId(localId: number): Promise<DistributedInfo> 78 79Obtains distributed information about a system account. This API uses a promise to return the result. 80 81**System API**: This is a system API. 82 83**System capability**: SystemCapability.Account.OsAccount 84 85**Required permissions**: ohos.permission.MANAGE_DISTRIBUTED_ACCOUNTS; or ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS and ohos.permission.GET_DISTRIBUTED_ACCOUNTS 86 87**Parameters** 88 89 | Name| Type| Mandatory| Description| 90 | -------- | -------- | -------- | -------- | 91 | localId | number | Yes| ID of the target system account.| 92 93**Return value** 94 95 | Type| Description| 96 | -------- | -------- | 97 | Promise<[DistributedInfo](js-apis-distributed-account.md#distributedinfo)> | Promise used to return the distributed account information obtained.| 98 99**Error codes** 100 101| ID| Error Message| 102| -------- | ------------------- | 103| 201 | Permission denied.| 104| 202 | Not system application.| 105| 12300001 | System service exception. | 106| 12300003 | Account not found. | 107 108**Example** 109 110```ts 111import { BusinessError } from '@kit.BasicServicesKit'; 112 113const accountAbility: distributedAccount.DistributedAccountAbility = distributedAccount.getDistributedAccountAbility(); 114try { 115 accountAbility.getOsAccountDistributedInfoByLocalId(100).then(( 116 data: distributedAccount.DistributedInfo) => { 117 console.log('distributed information: ' + JSON.stringify(data)); 118 }).catch((err: BusinessError) => { 119 console.error('getOsAccountDistributedInfoByLocalId exception: ' + JSON.stringify(err)); 120 }); 121} catch (err) { 122 console.error('getOsAccountDistributedInfoByLocalId exception: ' + JSON.stringify(err)); 123} 124``` 125 126### setOsAccountDistributedInfoByLocalId<sup>10+</sup> 127 128setOsAccountDistributedInfoByLocalId(localId: number, distributedInfo: DistributedInfo, callback: AsyncCallback<void>): void 129 130Sets the distributed information for a system account. This API uses an asynchronous callback to return the result. 131 132**System API**: This is a system API. 133 134**System capability**: SystemCapability.Account.OsAccount 135 136**Required permissions**: ohos.permission.MANAGE_DISTRIBUTED_ACCOUNTS 137 138**Parameters** 139 140 | Name| Type| Mandatory| Description| 141 | -------- | -------- | -------- | -------- | 142 | localId | number | Yes| ID of the target system account.| 143 | distributedInfo | [DistributedInfo](js-apis-distributed-account.md#distributedinfo) | Yes| Distributed account information to set.| 144 | callback | AsyncCallback<void> | Yes| Callback used to return the result. If the distributed information is set successfully, **err** is **undefined**. Otherwise, **err** is an error object.| 145 146**Error codes** 147 148| ID| Error Message| 149| -------- | ------------------- | 150| 201 | Permission denied.| 151| 202 | Not system application.| 152| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 153| 12300001 | System service exception. | 154| 12300002 | Invalid distributedInfo. | 155| 12300003 | Account identified by localId or by distributedInfo not found. | 156| 12300008 | Restricted OS account. | 157 158**Example** 159 160```ts 161import { BusinessError } from '@kit.BasicServicesKit'; 162 163const accountAbility: distributedAccount.DistributedAccountAbility = distributedAccount.getDistributedAccountAbility(); 164let accountInfo: distributedAccount.DistributedInfo = 165 {id: '12345', name: 'ZhangSan', event: 'Ohos.account.event.LOGIN'}; 166try { 167 accountAbility.setOsAccountDistributedInfoByLocalId(100, accountInfo, (err: BusinessError) => { 168 if (err) { 169 console.error('setOsAccountDistributedInfoByLocalId exception: ' + JSON.stringify(err)); 170 } else { 171 console.log('setOsAccountDistributedInfoByLocalId successfully'); 172 } 173 }); 174} catch (err) { 175 console.error('setOsAccountDistributedInfoByLocalId exception: ' + JSON.stringify(err)); 176} 177``` 178 179### setOsAccountDistributedInfoByLocalId<sup>10+</sup> 180 181setOsAccountDistributedInfoByLocalId(localId: number, distributedInfo: DistributedInfo): Promise<void> 182 183Sets the distributed information for a system account. This API uses a promise to return the result. 184 185**System API**: This is a system API. 186 187**System capability**: SystemCapability.Account.OsAccount 188 189**Required permissions**: ohos.permission.MANAGE_DISTRIBUTED_ACCOUNTS 190 191**Parameters** 192 193 | Name| Type| Mandatory| Description| 194 | -------- | -------- | -------- | -------- | 195 | localId | number | Yes| ID of the target system account.| 196 | distributedInfo | [DistributedInfo](js-apis-distributed-account.md#distributedinfo) | Yes| Distributed account information to set.| 197 198**Return value** 199 200 | Type| Description| 201 | -------- | -------- | 202 | Promise<void> | Promise that returns no value.| 203 204**Error codes** 205 206| ID| Error Message| 207| -------- | ------------------- | 208| 201 | Permission denied.| 209| 202 | Not system application.| 210| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 211| 12300001 | System service exception. | 212| 12300002 | Invalid distributedInfo. | 213| 12300003 | Account identified by localId or by distributedInfo not found. | 214| 12300008 | Restricted OS account. | 215 216**Example** 217 218```ts 219import { BusinessError } from '@kit.BasicServicesKit'; 220 221const accountAbility: distributedAccount.DistributedAccountAbility = distributedAccount.getDistributedAccountAbility(); 222let accountInfo: distributedAccount.DistributedInfo = 223 {id: '12345', name: 'ZhangSan', event: 'Ohos.account.event.LOGIN'}; 224try { 225 accountAbility.setOsAccountDistributedInfoByLocalId(100, accountInfo).then(() => { 226 console.log('setOsAccountDistributedInfoByLocalId successfully'); 227 }).catch((err: BusinessError) => { 228 console.error('setOsAccountDistributedInfoByLocalId exception: ' + JSON.stringify(err)); 229 }); 230} catch (err) { 231 console.error('setOsAccountDistributedInfoByLocalId exception: ' + JSON.stringify(err)); 232} 233``` 234