1 # @ohos.app.ability.sendableContextManager (sendableContextManager)
2 
3 The sendableContextManager module provides APIs for converting between Context and [SendableContext](js-apis-inner-application-sendableContext.md) objects.
4 
5 > **NOTE**
6 >
7 > - The initial APIs of this module are supported since API version 12. Newly added APIs will be marked with a superscript to indicate their earliest API version.
8 > - The APIs of this module can be used only in the stage model.
9 
10 ## When to Use
11 
12 This module is used to transfer data between concurrent ArkTS instances (including the main thread and the worker thread of TaskPool or Worker).
13 
14 For example, when transferring sendable data from the main thread to a child thread, the following conversion steps are involved to ensure efficient data transfer:
15 - Conversion from Context to SendableContext for the main thread to transfer sendable data to the child thread.
16 - Conversion from SendableContext to Context for the child thread to use the sendable data.
17 
18 The Context here is different from that created by [createModuleContext](./js-apis-app-ability-application.md#applicationcreatemodulecontext12). The differences are as follows:
19 - Context involved in the conversion: ArkTS concurrent instances hold different application-side Context instances that correspond to the same underlying Context object. When the Context properties and methods in an instance are modified, the Context properties and methods in the related instances are modified accordingly. The eventHub attribute in the Context instance is special. The eventHub objects in different instances are independent from each other and cannot be used across ArkTS instances.
20 - Context created using [createModuleContext](./js-apis-app-ability-application.md#applicationcreatemodulecontext12): ArkTS concurrent instances hold different application-side Context objects that correspond to different underlying Context objects.
21 
22 ## Constraints
23 
24 The Context types used in the conversion must be the same. Currently, the following types of Context support conversion: [Context](js-apis-inner-application-context.md), [ApplicationContext](js-apis-inner-application-applicationContext.md), [AbilityStageContext](js-apis-inner-application-abilityStageContext.md), and [UIAbilityContext](js-apis-inner-application-uiAbilityContext.md).
25 
26 ## Modules to Import
27 
28 ```ts
29 import { sendableContextManager } from '@kit.AbilityKit';
30 ```
31 
32 ## Properties
33 
34 **System capability**: SystemCapability.Ability.AbilityRuntime.Core
35 
36 **Atomic service API**: This API can be used in atomic services since API version 12.
37 
38 | Name| Type| Mandatory| Description|
39 | ------- | ------- | ------- | ------- |
40 | SendableContext | [SendableContext](js-apis-inner-application-sendableContext.md) | Yes| Level-2 module **SendableContext**.|
41 
42 **Example**
43 
44 ```ts
45 import { sendableContextManager } from '@kit.AbilityKit';
46 
47 let sendableContext: sendableContextManager.SendableContext;
48 ```
49 
50 ## sendableContextManager.convertFromContext
51 
52 convertFromContext(context: common.Context): SendableContext;
53 
54 Converts a **Context** object to a **SendableContext** object.
55 
56 **System capability**: SystemCapability.Ability.AbilityRuntime.Core
57 
58 **Atomic service API**: This API can be used in atomic services since API version 12.
59 
60 **Parameters**
61 
62 | Name| Type| Mandatory| Description|
63 | ------- | ------- | ------- | ------- |
64 | context | common.Context | Yes| **Context** object, which supports the base class **Context** and the child classes **ApplicationContext**, **AbilityStageContext**, and **UIAbilityContext**.|
65 
66 **Error codes**
67 
68 For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
69 
70 | ID| Error Message|
71 | ------- | ------- |
72 | 401     | If the input parameter invalid. Possible causes: 1.Incorrect parameter types; 2.Parameter verification failed. |
73 
74 **Example**
75 
76 ```ts
77 import { AbilityConstant, UIAbility, Want, sendableContextManager } from '@kit.AbilityKit';
78 import { hilog } from '@kit.PerformanceAnalysisKit';
79 import { worker } from '@kit.ArkTS';
80 
81 @Sendable
82 export class SendableObject {
83   constructor(sendableContext: sendableContextManager.SendableContext) {
84     this.sendableContext = sendableContext;
85   }
86 
87   sendableContext: sendableContextManager.SendableContext;
88   // other sendable object
89 }
90 
91 export default class EntryAbility extends UIAbility {
92   worker: worker.ThreadWorker = new worker.ThreadWorker('entry/ets/workers/Worker.ets');
93 
94   onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
95     hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onCreate');
96 
97     // convert and post
98     try {
99       let sendableContext: sendableContextManager.SendableContext = sendableContextManager.convertFromContext(this.context);
100       let object: SendableObject = new SendableObject(sendableContext);
101       hilog.info(0x0000, 'testTag', '%{public}s', 'Ability post message');
102       this.worker.postMessageWithSharedSendable(object);
103     } catch (error) {
104       hilog.error(0x0000, 'testTag', 'convertFromContext failed %{public}s', JSON.stringify(error));
105     }
106   }
107 }
108 ```
109 
110 ## sendableContextManager.convertToContext
111 
112 convertToContext(sendableContext: SendableContext): common.Context
113 
114 Converts a **SendableContext** object to a **Context** object.
115 
116 **System capability**: SystemCapability.Ability.AbilityRuntime.Core
117 
118 **Atomic service API**: This API can be used in atomic services since API version 12.
119 
120 **Parameters**
121 
122 | Name| Type| Mandatory| Description|
123 | ------- | ------- | ------- | ------- |
124 | sendableContext | [SendableContext](js-apis-inner-application-sendableContext.md) | Yes| **SendableContext** object.|
125 
126 **Error codes**
127 
128 For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
129 
130 | ID| Error Message|
131 | ------- | ------- |
132 | 401     | If the input parameter invalid. Possible causes: 1.Incorrect parameter types; 2.Parameter verification failed. |
133 
134 **Example**
135 
136 Context passed by the main thread:
137 ```ts
138 import { AbilityConstant, UIAbility, Want, common, sendableContextManager } from '@kit.AbilityKit';
139 import { hilog } from '@kit.PerformanceAnalysisKit';
140 import { worker } from '@kit.ArkTS';
141 
142 @Sendable
143 export class SendableObject {
144   constructor(sendableContext: sendableContextManager.SendableContext, contextName: string) {
145     this.sendableContext = sendableContext;
146     this.contextName = contextName;
147   }
148 
149   sendableContext: sendableContextManager.SendableContext;
150   contextName: string;
151 }
152 
153 export default class EntryAbility extends UIAbility {
154   worker: worker.ThreadWorker = new worker.ThreadWorker('entry/ets/workers/Worker.ets');
155 
156   onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
157     hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onCreate');
158 
159     // convert and post
160     try {
161       let context: common.Context = this.context as common.Context;
162       let sendableContext: sendableContextManager.SendableContext = sendableContextManager.convertFromContext(context);
163       let object: SendableObject = new SendableObject(sendableContext, 'BaseContext');
164       hilog.info(0x0000, 'testTag', '%{public}s', 'Ability post message');
165       this.worker.postMessageWithSharedSendable(object);
166     } catch (error) {
167       hilog.error(0x0000, 'testTag', 'convertFromContext failed %{public}s', JSON.stringify(error));
168     }
169   }
170 }
171 ```
172 
173 Context received by the Worker thread:
174 ```ts
175 import { ErrorEvent, MessageEvents, ThreadWorkerGlobalScope, worker } from '@kit.ArkTS';
176 import { common, sendableContextManager } from '@kit.AbilityKit';
177 import { hilog } from '@kit.PerformanceAnalysisKit';
178 
179 @Sendable
180 export class SendableObject {
181   constructor(sendableContext: sendableContextManager.SendableContext, contextName: string) {
182     this.sendableContext = sendableContext;
183     this.contextName = contextName;
184   }
185 
186   sendableContext: sendableContextManager.SendableContext;
187   contextName: string;
188 }
189 
190 const workerPort: ThreadWorkerGlobalScope = worker.workerPort;
191 
192 workerPort.onmessage = (e: MessageEvents) => {
193   let object: SendableObject = e.data;
194   let sendableContext: sendableContextManager.SendableContext = object.sendableContext;
195   if (object.contextName == 'BaseContext') {
196     hilog.info(0x0000, 'testTag', '%{public}s', 'convert to context.');
197     try {
198       let context: common.Context = sendableContextManager.convertToContext(sendableContext);
199       // Obtain the sandbox path after obtaining the Context object.
200       hilog.info(0x0000, 'testTag', 'worker context.databaseDir: %{public}s', context.databaseDir);
201     } catch (error) {
202       hilog.error(0x0000, 'testTag', 'convertToContext failed %{public}s', JSON.stringify(error));
203     }
204   }
205 }
206 
207 workerPort.onmessageerror = (e: MessageEvents) => {
208   hilog.info(0x0000, 'testTag', '%{public}s', 'onmessageerror');
209 }
210 
211 workerPort.onerror = (e: ErrorEvent) => {
212   hilog.info(0x0000, 'testTag', '%{public}s', 'onerror');
213 }
214 ```
215 
216 ## sendableContextManager.convertToApplicationContext
217 
218 convertToApplicationContext(sendableContext: SendableContext): common.ApplicationContext
219 
220 Converts a **SendableContext** object to an **ApplicationContext** object.
221 
222 **System capability**: SystemCapability.Ability.AbilityRuntime.Core
223 
224 **Atomic service API**: This API can be used in atomic services since API version 12.
225 
226 **Parameters**
227 
228 | Name| Type| Mandatory| Description|
229 | ------- | ------- | ------- | ------- |
230 | sendableContext | [SendableContext](js-apis-inner-application-sendableContext.md) | Yes| **SendableContext** object.|
231 
232 **Error codes**
233 
234 For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
235 
236 | ID| Error Message|
237 | ------- | ------- |
238 | 401     | If the input parameter invalid. Possible causes: 1.Incorrect parameter types; 2.Parameter verification failed. |
239 
240 **Example**
241 
242 Context passed by the main thread:
243 ```ts
244 import { AbilityConstant, UIAbility, Want, common, sendableContextManager } from '@kit.AbilityKit';
245 import { hilog } from '@kit.PerformanceAnalysisKit';
246 import { worker } from '@kit.ArkTS';
247 
248 @Sendable
249 export class SendableObject {
250   constructor(sendableContext: sendableContextManager.SendableContext, contextName: string) {
251     this.sendableContext = sendableContext;
252     this.contextName = contextName;
253   }
254 
255   sendableContext: sendableContextManager.SendableContext;
256   contextName: string;
257 }
258 
259 export default class EntryAbility extends UIAbility {
260   worker: worker.ThreadWorker = new worker.ThreadWorker('entry/ets/workers/Worker.ets');
261 
262   onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
263     hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onCreate');
264 
265     // convert and post
266     try {
267       let context: common.Context = this.context as common.Context;
268       let applicationContext = context.getApplicationContext();
269       let sendableContext: sendableContextManager.SendableContext = sendableContextManager.convertFromContext(applicationContext);
270       let object: SendableObject = new SendableObject(sendableContext, 'ApplicationContext');
271       hilog.info(0x0000, 'testTag', '%{public}s', 'Ability post message');
272       this.worker.postMessageWithSharedSendable(object);
273     } catch (error) {
274       hilog.error(0x0000, 'testTag', 'convertFromContext failed %{public}s', JSON.stringify(error));
275     }
276   }
277 }
278 ```
279 
280 Context received by the Worker thread:
281 ```ts
282 import { ErrorEvent, MessageEvents, ThreadWorkerGlobalScope, worker } from '@kit.ArkTS';
283 import { common, sendableContextManager } from '@kit.AbilityKit';
284 import { hilog } from '@kit.PerformanceAnalysisKit';
285 
286 @Sendable
287 export class SendableObject {
288   constructor(sendableContext: sendableContextManager.SendableContext, contextName: string) {
289     this.sendableContext = sendableContext;
290     this.contextName = contextName;
291   }
292 
293   sendableContext: sendableContextManager.SendableContext;
294   contextName: string;
295 }
296 
297 const workerPort: ThreadWorkerGlobalScope = worker.workerPort;
298 
299 workerPort.onmessage = (e: MessageEvents) => {
300   let object: SendableObject = e.data;
301   let sendableContext: sendableContextManager.SendableContext = object.sendableContext;
302   if (object.contextName == 'ApplicationContext') {
303     hilog.info(0x0000, 'testTag', '%{public}s', 'convert to application context.');
304     try {
305       let context: common.ApplicationContext = sendableContextManager.convertToApplicationContext(sendableContext);
306       // Obtain the sandbox path after obtaining the Context object.
307       hilog.info(0x0000, 'testTag', 'worker context.databaseDir: %{public}s', context.databaseDir);
308     } catch (error) {
309       hilog.error(0x0000, 'testTag', 'convertToApplicationContext failed %{public}s', JSON.stringify(error));
310     }
311   }
312 }
313 
314 workerPort.onmessageerror = (e: MessageEvents) => {
315   hilog.info(0x0000, 'testTag', '%{public}s', 'onmessageerror');
316 }
317 
318 workerPort.onerror = (e: ErrorEvent) => {
319   hilog.info(0x0000, 'testTag', '%{public}s', 'onerror');
320 }
321 ```
322 
323 ## sendableContextManager.convertToAbilityStageContext
324 
325 convertToAbilityStageContext(sendableContext: SendableContext): common.AbilityStageContext
326 
327 Converts a **SendableContext** object to an **AbilityStageContext** object.
328 
329 **System capability**: SystemCapability.Ability.AbilityRuntime.Core
330 
331 **Atomic service API**: This API can be used in atomic services since API version 12.
332 
333 **Parameters**
334 
335 | Name| Type| Mandatory| Description|
336 | ------- | ------- | ------- | ------- |
337 | sendableContext | [SendableContext](js-apis-inner-application-sendableContext.md) | Yes| **SendableContext** object.|
338 
339 **Error codes**
340 
341 For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
342 
343 | ID| Error Message|
344 | ------- | ------- |
345 | 401     | If the input parameter invalid. Possible causes: 1.Incorrect parameter types; 2.Parameter verification failed. |
346 
347 **Example**
348 
349 Context passed by the main thread:
350 ```ts
351 import { UIAbility, sendableContextManager } from '@kit.AbilityKit';
352 import { hilog } from '@kit.PerformanceAnalysisKit';
353 import { worker } from '@kit.ArkTS';
354 
355 @Sendable
356 export class SendableObject {
357   constructor(sendableContext: sendableContextManager.SendableContext, contextName: string) {
358     this.sendableContext = sendableContext;
359     this.contextName = contextName;
360   }
361 
362   sendableContext: sendableContextManager.SendableContext;
363   contextName: string;
364 }
365 
366 export default class EntryAbility extends UIAbility {
367   worker: worker.ThreadWorker = new worker.ThreadWorker('entry/ets/workers/Worker.ets');
368 
369   onCreate(): void {
370     hilog.info(0x0000, 'testTag', '%{public}s', 'AbilityStage onCreate');
371 
372     // convert and post
373     try {
374       let sendableContext: sendableContextManager.SendableContext = sendableContextManager.convertFromContext(this.context);
375       let object: SendableObject = new SendableObject(sendableContext, 'AbilityStageContext');
376       hilog.info(0x0000, 'testTag', '%{public}s', 'AbilityStage post message');
377       this.worker.postMessageWithSharedSendable(object);
378     } catch (error) {
379       hilog.error(0x0000, 'testTag', 'convertFromContext failed %{public}s', JSON.stringify(error));
380     }
381   }
382 }
383 ```
384 
385 Context received by the Worker thread:
386 ```ts
387 import { ErrorEvent, MessageEvents, ThreadWorkerGlobalScope, worker } from '@kit.ArkTS';
388 import { common, sendableContextManager } from '@kit.AbilityKit';
389 import { hilog } from '@kit.PerformanceAnalysisKit';
390 
391 @Sendable
392 export class SendableObject {
393   constructor(sendableContext: sendableContextManager.SendableContext, contextName: string) {
394     this.sendableContext = sendableContext;
395     this.contextName = contextName;
396   }
397 
398   sendableContext: sendableContextManager.SendableContext;
399   contextName: string;
400 }
401 
402 const workerPort: ThreadWorkerGlobalScope = worker.workerPort;
403 
404 workerPort.onmessage = (e: MessageEvents) => {
405   let object: SendableObject = e.data;
406   let sendableContext: sendableContextManager.SendableContext = object.sendableContext;
407   if (object.contextName == 'AbilityStageContext') {
408     hilog.info(0x0000, 'testTag', '%{public}s', 'convert to abilitystage context.');
409     try {
410       let context: common.AbilityStageContext = sendableContextManager.convertToAbilityStageContext(sendableContext);
411       // Obtain the sandbox path after obtaining the Context object.
412       hilog.info(0x0000, 'testTag', 'worker context.databaseDir: %{public}s', context.databaseDir);
413     } catch (error) {
414       hilog.error(0x0000, 'testTag', 'convertToAbilityStageContext failed %{public}s', JSON.stringify(error));
415     }
416   }
417 }
418 
419 workerPort.onmessageerror = (e: MessageEvents) => {
420   hilog.info(0x0000, 'testTag', '%{public}s', 'onmessageerror');
421 }
422 
423 workerPort.onerror = (e: ErrorEvent) => {
424   hilog.info(0x0000, 'testTag', '%{public}s', 'onerror');
425 }
426 ```
427 
428 ## sendableContextManager.convertToUIAbilityContext
429 
430 convertToUIAbilityContext(sendableContext: SendableContext): common.UIAbilityContext
431 
432 Converts a **SendableContext** object to a **UIAbilityContext** object.
433 
434 **System capability**: SystemCapability.Ability.AbilityRuntime.Core
435 
436 **Atomic service API**: This API can be used in atomic services since API version 12.
437 
438 **Parameters**
439 
440 | Name| Type| Mandatory| Description|
441 | ------- | ------- | ------- | ------- |
442 | sendableContext | [SendableContext](js-apis-inner-application-sendableContext.md) | Yes| **SendableContext** object.|
443 
444 **Error codes**
445 
446 For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
447 
448 | ID| Error Message|
449 | ------- | ------- |
450 | 401     | If the input parameter invalid. Possible causes: 1.Incorrect parameter types; 2.Parameter verification failed. |
451 
452 **Example**
453 
454 Context passed by the main thread:
455 ```ts
456 import { AbilityConstant, UIAbility, Want, common, sendableContextManager } from '@kit.AbilityKit';
457 import { hilog } from '@kit.PerformanceAnalysisKit';
458 import { worker } from '@kit.ArkTS';
459 
460 @Sendable
461 export class SendableObject {
462   constructor(sendableContext: sendableContextManager.SendableContext, contextName: string) {
463     this.sendableContext = sendableContext;
464     this.contextName = contextName;
465   }
466 
467   sendableContext: sendableContextManager.SendableContext;
468   contextName: string;
469 }
470 
471 export default class EntryAbility extends UIAbility {
472   worker: worker.ThreadWorker = new worker.ThreadWorker('entry/ets/workers/Worker.ets');
473 
474   onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
475     hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onCreate');
476 
477     // convert and post
478     try {
479       let sendableContext: sendableContextManager.SendableContext = sendableContextManager.convertFromContext(this.context);
480       let object: SendableObject = new SendableObject(sendableContext, 'EntryAbilityContext');
481       hilog.info(0x0000, 'testTag', '%{public}s', 'Ability post message');
482       this.worker.postMessageWithSharedSendable(object);
483     } catch (error) {
484       hilog.error(0x0000, 'testTag', 'convertFromContext failed %{public}s', JSON.stringify(error));
485     }
486   }
487 }
488 ```
489 
490 Context received by the Worker thread:
491 ```ts
492 import { ErrorEvent, MessageEvents, ThreadWorkerGlobalScope, worker } from '@kit.ArkTS';
493 import { common, sendableContextManager } from '@kit.AbilityKit';
494 import { hilog } from '@kit.PerformanceAnalysisKit';
495 
496 @Sendable
497 export class SendableObject {
498   constructor(sendableContext: sendableContextManager.SendableContext, contextName: string) {
499     this.sendableContext = sendableContext;
500     this.contextName = contextName;
501   }
502 
503   sendableContext: sendableContextManager.SendableContext;
504   contextName: string;
505 }
506 
507 const workerPort: ThreadWorkerGlobalScope = worker.workerPort;
508 
509 workerPort.onmessage = (e: MessageEvents) => {
510   let object: SendableObject = e.data;
511   let sendableContext: sendableContextManager.SendableContext = object.sendableContext;
512   if (object.contextName == 'EntryAbilityContext') {
513     hilog.info(0x0000, 'testTag', '%{public}s', 'convert to uiability context.');
514     try {
515       let context: common.UIAbilityContext = sendableContextManager.convertToUIAbilityContext(sendableContext);
516       // Obtain the sandbox path after obtaining the Context object.
517       hilog.info(0x0000, 'testTag', 'worker context.databaseDir: %{public}s', context.databaseDir);
518     } catch (error) {
519       hilog.error(0x0000, 'testTag', 'convertToUIAbilityContext failed %{public}s', JSON.stringify(error));
520     }
521   }
522 }
523 
524 workerPort.onmessageerror = (e: MessageEvents) => {
525   hilog.info(0x0000, 'testTag', '%{public}s', 'onmessageerror');
526 }
527 
528 workerPort.onerror = (e: ErrorEvent) => {
529   hilog.info(0x0000, 'testTag', '%{public}s', 'onerror');
530 }
531 ```
532