1# Interface (Session) 2<!--Kit: Camera Kit--> 3<!--Subsystem: Multimedia--> 4<!--Owner: @qano--> 5<!--SE: @leo_ysl--> 6<!--TSE: @xchaosioda--> 7 8> **NOTE** 9> 10> - The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version. 11> - The initial APIs of this interface are supported since API version 11. 12 13Session implements a session, which saves all [CameraInput](arkts-apis-camera-CameraInput.md) and [CameraOutput](arkts-apis-camera-CameraOutput.md) instances required to run the camera and requests the camera to take a photo or record a video. 14 15## Modules to Import 16 17```ts 18import { camera } from '@kit.CameraKit'; 19``` 20 21## beginConfig<sup>11+</sup> 22 23beginConfig(): void 24 25Starts configuration for the session. 26 27**Atomic service API**: This API can be used in atomic services since API version 19. 28 29**System capability**: SystemCapability.Multimedia.Camera.Core 30 31**Error codes** 32 33For details about the error codes, see [Camera Error Codes](errorcode-camera.md). 34 35| ID | Error Message | 36| --------------- | --------------- | 37| 7400105 | Session config locked. | 38| 7400201 | Camera service fatal error. | 39 40**Example** 41 42```ts 43import { BusinessError } from '@kit.BasicServicesKit'; 44 45function beginConfig(session: camera.Session): void { 46 try { 47 session.beginConfig(); 48 } catch (error) { 49 // If the operation fails, error.code is returned and processed. 50 let err = error as BusinessError; 51 console.error(`The beginConfig call failed. error code: ${err.code}`); 52 } 53} 54``` 55 56## commitConfig<sup>11+</sup> 57 58commitConfig(callback: AsyncCallback\<void\>): void 59 60Commits the configuration for this session. This API uses an asynchronous callback to return the result. 61 62**Atomic service API**: This API can be used in atomic services since API version 19. 63 64**System capability**: SystemCapability.Multimedia.Camera.Core 65 66**Parameters** 67 68| Name | Type | Mandatory| Description | 69| -------- | -------------------- | ---- | -------------------- | 70| callback | AsyncCallback\<void\> | Yes | Callback used to return the result. If the operation fails, an error code defined in [CameraErrorCode](arkts-apis-camera-e.md#cameraerrorcode) is returned. For example, if the aspect ratio of the preview stream is different from that of the video output stream, error code 7400201 is returned.| 71 72**Error codes** 73 74For details about the error codes, see [Camera Error Codes](errorcode-camera.md). 75 76| ID | Error Message | 77| --------------- | --------------- | 78| 7400102 | Operation not allowed. | 79| 7400201 | Camera service fatal error. | 80 81**Example** 82 83```ts 84import { BusinessError } from '@kit.BasicServicesKit'; 85 86function commitConfig(session: camera.Session): void { 87 session.commitConfig((err: BusinessError) => { 88 if (err) { 89 console.error(`The commitConfig call failed. error code: ${err.code}`); 90 return; 91 } 92 console.info('Callback invoked to indicate the commit config success.'); 93 }); 94} 95``` 96 97## commitConfig<sup>11+</sup> 98 99commitConfig(): Promise\<void\> 100 101Commits the configuration for this session. This API uses a promise to return the result. 102 103**Atomic service API**: This API can be used in atomic services since API version 19. 104 105**System capability**: SystemCapability.Multimedia.Camera.Core 106 107**Return value** 108 109| Type | Description | 110| -------------- | ------------------------ | 111| Promise\<void\> | Promise that returns no value.| 112 113**Error codes** 114 115For details about the error codes, see [Camera Error Codes](errorcode-camera.md). 116 117| ID | Error Message | 118| --------------- | --------------- | 119| 7400102 | Operation not allowed. | 120| 7400201 | Camera service fatal error. | 121 122**Example** 123 124```ts 125import { BusinessError } from '@kit.BasicServicesKit'; 126 127function commitConfig(session: camera.Session): void { 128 session.commitConfig().then(() => { 129 console.info('Promise returned to indicate the commit config success.'); 130 }).catch((error: BusinessError) => { 131 // If the operation fails, error.code is returned and processed. 132 console.error(`The commitConfig call failed. error code: ${error.code}`); 133 }); 134} 135``` 136 137## canAddInput<sup>11+</sup> 138 139canAddInput(cameraInput: CameraInput): boolean 140 141Checks whether a CameraInput instance can be added to this session. This API must be called after [beginConfig](#beginconfig11) and before [commitConfig](#commitconfig11-1). 142 143**Atomic service API**: This API can be used in atomic services since API version 19. 144 145**System capability**: SystemCapability.Multimedia.Camera.Core 146 147**Parameters** 148 149| Name | Type | Mandatory| Description | 150| ----------- | --------------------------- | ---- | ------------------------ | 151| cameraInput | [CameraInput](arkts-apis-camera-CameraInput.md) | Yes | CameraInput instance to add. The API does not take effect if the input parameter is invalid (for example, the value is out of range, null, or undefined).| 152 153**Return value** 154 155| Type | Description | 156| -------------- | ------------------------ | 157| boolean | Check result for adding the CameraInput instance. **true** if it can be added, **false** otherwise.| 158 159**Example** 160 161```ts 162import { BusinessError } from '@kit.BasicServicesKit'; 163 164function canAddInput(session: camera.Session, cameraInput: camera.CameraInput): void { 165 let canAdd: boolean = session.canAddInput(cameraInput); 166 console.info(`The input canAddInput: ${canAdd}`); 167} 168``` 169 170## addInput<sup>11+</sup> 171 172addInput(cameraInput: CameraInput): void 173 174Adds a [CameraInput](arkts-apis-camera-CameraInput.md) instance to this session. 175 176**Atomic service API**: This API can be used in atomic services since API version 19. 177 178**System capability**: SystemCapability.Multimedia.Camera.Core 179 180**Parameters** 181 182| Name | Type | Mandatory| Description | 183| ----------- | --------------------------- | ---- | ------------------------ | 184| cameraInput | [CameraInput](arkts-apis-camera-CameraInput.md) | Yes | CameraInput instance to add.| 185 186**Error codes** 187 188For details about the error codes, see [Camera Error Codes](errorcode-camera.md). 189 190| ID | Error Message | 191| --------------- | --------------- | 192| 7400101 | Parameter missing or parameter type incorrect. | 193| 7400102 | Operation not allowed. | 194| 7400201 | Camera service fatal error. | 195 196**Example** 197 198```ts 199import { BusinessError } from '@kit.BasicServicesKit'; 200 201function addInput(session: camera.Session, cameraInput: camera.CameraInput): void { 202 try { 203 session.addInput(cameraInput); 204 } catch (error) { 205 // If the operation fails, error.code is returned and processed. 206 let err = error as BusinessError; 207 console.error(`The addInput call failed. error code: ${err.code}`); 208 } 209} 210``` 211 212## removeInput<sup>11+</sup> 213 214removeInput(cameraInput: CameraInput): void 215 216Removes a [CameraInput](arkts-apis-camera-CameraInput.md) instance from this session. This API must be called after [beginConfig](#beginconfig11) and before [commitConfig](#commitconfig11-1). 217 218**Atomic service API**: This API can be used in atomic services since API version 19. 219 220**System capability**: SystemCapability.Multimedia.Camera.Core 221 222**Parameters** 223 224| Name | Type | Mandatory| Description | 225| ----------- | --------------------------- | ---- | ------------------------ | 226| cameraInput | [CameraInput](arkts-apis-camera-CameraInput.md) | Yes | CameraInput instance to remove.| 227 228**Error codes** 229 230For details about the error codes, see [Camera Error Codes](errorcode-camera.md). 231 232| ID | Error Message | 233| --------------- | --------------- | 234| 7400101 | Parameter missing or parameter type incorrect. | 235| 7400102 | Operation not allowed. | 236| 7400201 | Camera service fatal error. | 237 238**Example** 239 240```ts 241import { BusinessError } from '@kit.BasicServicesKit'; 242 243function removeInput(session: camera.Session, cameraInput: camera.CameraInput): void { 244 try { 245 session.removeInput(cameraInput); 246 } catch (error) { 247 // If the operation fails, error.code is returned and processed. 248 let err = error as BusinessError; 249 console.error(`The removeInput call failed. error code: ${err.code}`); 250 } 251} 252``` 253 254## canAddOutput<sup>11+</sup> 255 256canAddOutput(cameraOutput: CameraOutput): boolean 257 258Determines whether a CameraOutput instance can be added to this session. This API must be called after [addInput](#addinput11) and before [commitConfig](#commitconfig11-1). 259 260**Atomic service API**: This API can be used in atomic services since API version 19. 261 262**System capability**: SystemCapability.Multimedia.Camera.Core 263 264**Parameters** 265 266| Name | Type | Mandatory| Description | 267| ----------- | --------------------------- | ---- | ------------------------ | 268| cameraOutput | [CameraOutput](arkts-apis-camera-CameraOutput.md) | Yes | CameraOutput instance to add. The API does not take effect if the input parameter is invalid (for example, the value is out of range, null, or undefined).| 269 270**Return value** 271 272| Type | Description | 273| -------------- | ------------------------ | 274| boolean | Check result for adding the CameraOutput instance. **true** if it can be added, **false** otherwise.| 275 276**Example** 277 278```ts 279import { BusinessError } from '@kit.BasicServicesKit'; 280 281function canAddOutput(session: camera.Session, cameraOutput: camera.CameraOutput): void { 282 let canAdd: boolean = session.canAddOutput(cameraOutput); 283 console.info(`This addOutput can add: ${canAdd}`); 284} 285``` 286 287## addOutput<sup>11+</sup> 288 289addOutput(cameraOutput: CameraOutput): void 290 291Adds a [CameraOutput](arkts-apis-camera-CameraOutput.md) instance to this session. 292 293**Atomic service API**: This API can be used in atomic services since API version 19. 294 295**System capability**: SystemCapability.Multimedia.Camera.Core 296 297**Parameters** 298 299| Name | Type | Mandatory| Description | 300| ------------- | ------------------------------- | ---- | ------------------------ | 301| cameraOutput | [CameraOutput](arkts-apis-camera-CameraOutput.md) | Yes | CameraOutput instance to add.| 302 303**Error codes** 304 305For details about the error codes, see [Camera Error Codes](errorcode-camera.md). 306 307| ID | Error Message | 308| --------------- | --------------- | 309| 7400101 | Parameter missing or parameter type incorrect. | 310| 7400102 | Operation not allowed. | 311| 7400201 | Camera service fatal error. | 312 313**Example** 314 315```ts 316import { BusinessError } from '@kit.BasicServicesKit'; 317 318function addOutput(session: camera.Session, cameraOutput: camera.CameraOutput): void { 319 try { 320 session.addOutput(cameraOutput); 321 } catch (error) { 322 // If the operation fails, error.code is returned and processed. 323 let err = error as BusinessError; 324 console.error(`The addOutput call failed. error code: ${err.code}`); 325 } 326} 327``` 328 329## removeOutput<sup>11+</sup> 330 331removeOutput(cameraOutput: CameraOutput): void 332 333Removes a [CameraOutput](arkts-apis-camera-CameraOutput.md) instance from this session. 334 335**Atomic service API**: This API can be used in atomic services since API version 19. 336 337**System capability**: SystemCapability.Multimedia.Camera.Core 338 339**Parameters** 340 341| Name | Type | Mandatory| Description | 342| ------------- | ------------------------------- | ---- | ------------------------ | 343| cameraOutput | [CameraOutput](arkts-apis-camera-CameraOutput.md) | Yes | CameraOutput instance to remove.| 344 345**Error codes** 346 347For details about the error codes, see [Camera Error Codes](errorcode-camera.md). 348 349| ID | Error Message | 350| --------------- | --------------- | 351| 7400101 | Parameter missing or parameter type incorrect. | 352| 7400102 | Operation not allowed. | 353| 7400201 | Camera service fatal error. | 354 355**Example** 356 357```ts 358import { BusinessError } from '@kit.BasicServicesKit'; 359 360function removeOutput(session: camera.Session, previewOutput: camera.PreviewOutput): void { 361 try { 362 session.removeOutput(previewOutput); 363 } catch (error) { 364 // If the operation fails, error.code is returned and processed. 365 let err = error as BusinessError; 366 console.error(`The removeOutput call failed. error code: ${err.code}`); 367 } 368} 369``` 370 371## start<sup>11+</sup> 372 373start(callback: AsyncCallback\<void\>): void 374 375Starts this session. This API uses an asynchronous callback to return the result. 376 377**Atomic service API**: This API can be used in atomic services since API version 19. 378 379**System capability**: SystemCapability.Multimedia.Camera.Core 380 381**Parameters** 382 383| Name | Type | Mandatory| Description | 384| -------- | -------------------- | ---- | -------------------- | 385| callback | AsyncCallback\<void\> | Yes | Callback used to return the result. If the operation fails, an error code defined in [CameraErrorCode](arkts-apis-camera-e.md#cameraerrorcode) is returned.| 386 387**Error codes** 388 389For details about the error codes, see [Camera Error Codes](errorcode-camera.md). 390 391| ID | Error Message | 392| --------------- | --------------- | 393| 7400102 | Operation not allowed. | 394| 7400103 | Session not config. | 395| 7400201 | Camera service fatal error. | 396 397**Example** 398 399```ts 400import { BusinessError } from '@kit.BasicServicesKit'; 401 402function startCaptureSession(session: camera.Session): void { 403 session.start((err: BusinessError) => { 404 if (err) { 405 console.error(`Failed to start the session, error code: ${err.code}.`); 406 return; 407 } 408 console.info('Callback invoked to indicate the session start success.'); 409 }); 410} 411``` 412 413## start<sup>11+</sup> 414 415start(): Promise\<void\> 416 417Starts this session. This API uses a promise to return the result. 418 419**Atomic service API**: This API can be used in atomic services since API version 19. 420 421**System capability**: SystemCapability.Multimedia.Camera.Core 422 423**Return value** 424 425| Type | Description | 426| -------------- | ------------------------ | 427| Promise\<void\> | Promise that returns no value.| 428 429**Error codes** 430 431For details about the error codes, see [Camera Error Codes](errorcode-camera.md). 432 433| ID | Error Message | 434| --------------- | --------------- | 435| 7400102 | Operation not allowed. | 436| 7400103 | Session not config. | 437| 7400201 | Camera service fatal error. | 438 439**Example** 440 441```ts 442import { BusinessError } from '@kit.BasicServicesKit'; 443 444function startCaptureSession(session: camera.Session): void { 445 session.start().then(() => { 446 console.info('Promise returned to indicate the session start success.'); 447 }).catch((error: BusinessError) => { 448 console.error(`Failed to start the session, error code: ${error.code}.`); 449 }); 450} 451``` 452 453## stop<sup>11+</sup> 454 455stop(callback: AsyncCallback\<void\>): void 456 457Stops this session. This API uses an asynchronous callback to return the result. 458 459**Atomic service API**: This API can be used in atomic services since API version 19. 460 461**System capability**: SystemCapability.Multimedia.Camera.Core 462 463**Parameters** 464 465| Name | Type | Mandatory| Description | 466| -------- | -------------------- | ---- | ------------------- | 467| callback | AsyncCallback\<void\> | Yes | Callback used to return the result. If the operation fails, an error code defined in [CameraErrorCode](arkts-apis-camera-e.md#cameraerrorcode) is returned.| 468 469**Error codes** 470 471For details about the error codes, see [Camera Error Codes](errorcode-camera.md). 472 473| ID | Error Message | 474| --------------- | --------------- | 475| 7400201 | Camera service fatal error. | 476 477**Example** 478 479```ts 480import { BusinessError } from '@kit.BasicServicesKit'; 481 482function stopCaptureSession(session: camera.Session): void { 483 session.stop((err: BusinessError) => { 484 if (err) { 485 console.error(`Failed to stop the session, error code: ${err.code}.`); 486 return; 487 } 488 console.info('Callback invoked to indicate the session stop success.'); 489 }); 490} 491``` 492 493## stop<sup>11+</sup> 494 495stop(): Promise\<void\> 496 497Stops this session. This API uses a promise to return the result. 498 499**Atomic service API**: This API can be used in atomic services since API version 19. 500 501**System capability**: SystemCapability.Multimedia.Camera.Core 502 503**Return value** 504 505| Type | Description | 506| -------------- |-------------------| 507| Promise\<void\> | Promise that returns no value. | 508 509**Error codes** 510 511For details about the error codes, see [Camera Error Codes](errorcode-camera.md). 512 513| ID | Error Message | 514| --------------- | --------------- | 515| 7400201 | Camera service fatal error. | 516 517**Example** 518 519```ts 520import { BusinessError } from '@kit.BasicServicesKit'; 521 522function stopCaptureSession(session: camera.Session): void { 523 session.stop().then(() => { 524 console.info('Promise returned to indicate the session stop success.'); 525 }).catch((error: BusinessError) => { 526 console.error(`Failed to stop the session, error code: ${error.code}.`); 527 }); 528} 529``` 530 531## release<sup>11+</sup> 532 533release(callback: AsyncCallback\<void\>): void 534 535Releases this session. This API uses an asynchronous callback to return the result. 536 537**Atomic service API**: This API can be used in atomic services since API version 19. 538 539**System capability**: SystemCapability.Multimedia.Camera.Core 540 541**Parameters** 542 543| Name | Type | Mandatory| Description | 544| -------- | -------------------- | ---- | -------------------- | 545| callback | AsyncCallback\<void\> | Yes | Callback used to return the result. If the operation fails, an error code defined in [CameraErrorCode](arkts-apis-camera-e.md#cameraerrorcode) is returned.| 546 547**Error codes** 548 549For details about the error codes, see [Camera Error Codes](errorcode-camera.md). 550 551| ID | Error Message | 552| --------------- | --------------- | 553| 7400201 | Camera service fatal error. | 554 555**Example** 556 557```ts 558import { BusinessError } from '@kit.BasicServicesKit'; 559 560function releaseCaptureSession(session: camera.Session): void { 561 session.release((err: BusinessError) => { 562 if (err) { 563 console.error(`Failed to release the session instance, error code: ${err.code}.`); 564 return; 565 } 566 console.info('Callback invoked to indicate that the session instance is released successfully.'); 567 }); 568} 569``` 570 571## release<sup>11+</sup> 572 573release(): Promise\<void\> 574 575Releases this session. This API uses a promise to return the result. 576 577**Atomic service API**: This API can be used in atomic services since API version 19. 578 579**System capability**: SystemCapability.Multimedia.Camera.Core 580 581**Return value** 582 583| Type | Description | 584| -------------- | ------------------------ | 585| Promise\<void\> | Promise that returns no value.| 586 587**Error codes** 588 589For details about the error codes, see [Camera Error Codes](errorcode-camera.md). 590 591| ID | Error Message | 592| --------------- | --------------- | 593| 7400201 | Camera service fatal error. | 594 595**Example** 596 597```ts 598import { BusinessError } from '@kit.BasicServicesKit'; 599 600function releaseCaptureSession(session: camera.Session): void { 601 session.release().then(() => { 602 console.info('Promise returned to indicate that the session instance is released successfully.'); 603 }).catch((error: BusinessError) => { 604 console.error(`Failed to release the session instance, error code: ${error.code}.`); 605 }); 606} 607``` 608