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