Interface (Session)

Session implements a session, which saves all CameraInput and CameraOutput instances required to run the camera and requests the camera to take a photo or record a video.

NOTE

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.

The initial APIs of this interface are supported since API version 11.

Modules to Import

import { camera } from '@kit.CameraKit';

beginConfig¹¹⁺

beginConfig(): void

Starts configuration for the session.

Atomic service API: This API can be used in atomic services since API version 19.

System capability: SystemCapability.Multimedia.Camera.Core

Error codes

For details about the error codes, see Camera Error Codes.

ID	Error Message
7400105	Session config locked.
7400201	Camera service fatal error.

Example

import { BusinessError } from '@kit.BasicServicesKit';

function beginConfig(session: camera.Session): void {
  try {
    session.beginConfig();
  } catch (error) {
    // If the operation fails, error.code is returned and processed.
    let err = error as BusinessError;
    console.error(`The beginConfig call failed. error code: ${err.code}`);
  }
}

commitConfig¹¹⁺

commitConfig(callback: AsyncCallback<void>): void

Commits the configuration for this session. This API uses an asynchronous callback to return the result.

Atomic service API: This API can be used in atomic services since API version 19.

System capability: SystemCapability.Multimedia.Camera.Core

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the configuration is successfully committed, err is undefined; otherwise, err is an error object with an error code defined in CameraErrorCode. For example, if the aspect ratio of the preview stream is different from that of the video output stream, error code 7400201 is returned.

Error codes

For details about the error codes, see Camera Error Codes.

ID	Error Message
7400102	Operation not allowed.
7400201	Camera service fatal error.

Example

import { BusinessError } from '@kit.BasicServicesKit';

function commitConfig(session: camera.Session): void {
  session.commitConfig((err: BusinessError) => {
    if (err) {
      console.error(`The commitConfig call failed. error code: ${err.code}`);
      return;
    }
    console.info('Callback invoked to indicate the commit config success.');
  });
}

commitConfig¹¹⁺

commitConfig(): Promise<void>

Commits the configuration for this session. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 19.

System capability: SystemCapability.Multimedia.Camera.Core

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Camera Error Codes.

ID	Error Message
7400102	Operation not allowed.
7400201	Camera service fatal error.

Example

import { BusinessError } from '@kit.BasicServicesKit';

function commitConfig(session: camera.Session): void {
  session.commitConfig().then(() => {
    console.info('Promise returned to indicate the commit config success.');
  }).catch((error: BusinessError) => {
    // If the operation fails, error.code is returned and processed.
    console.error(`The commitConfig call failed. error code: ${error.code}`);
  });
}

canAddInput¹¹⁺

canAddInput(cameraInput: CameraInput): boolean

Checks whether a CameraInput instance can be added to this session. This API must be called after beginConfig and before commitConfig.

Atomic service API: This API can be used in atomic services since API version 19.

System capability: SystemCapability.Multimedia.Camera.Core

Parameters

Name	Type	Mandatory	Description
cameraInput	CameraInput	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).

Return value

Type	Description
boolean	Check result for adding the CameraInput instance. true if it can be added, false otherwise.

Example

function canAddInput(session: camera.Session, cameraInput: camera.CameraInput): void {
  let canAdd: boolean = session.canAddInput(cameraInput);
  console.info(`The input canAddInput: ${canAdd}`);
}

addInput¹¹⁺

addInput(cameraInput: CameraInput): void

Adds a CameraInput instance to this session.

Atomic service API: This API can be used in atomic services since API version 19.

System capability: SystemCapability.Multimedia.Camera.Core

Parameters

Name	Type	Mandatory	Description
cameraInput	CameraInput	Yes	CameraInput instance to add.

Error codes

For details about the error codes, see Camera Error Codes.

ID	Error Message
7400101	Parameter missing or parameter type incorrect.
7400102	Operation not allowed.
7400201	Camera service fatal error.

Example

import { BusinessError } from '@kit.BasicServicesKit';

function addInput(session: camera.Session, cameraInput: camera.CameraInput): void {
  try {
    session.addInput(cameraInput);
  } catch (error) {
    // If the operation fails, error.code is returned and processed.
    let err = error as BusinessError;
    console.error(`The addInput call failed. error code: ${err.code}`);
  }
}

removeInput¹¹⁺

removeInput(cameraInput: CameraInput): void

Removes a CameraInput instance from this session. This API must be called after beginConfig and before commitConfig.

Atomic service API: This API can be used in atomic services since API version 19.

System capability: SystemCapability.Multimedia.Camera.Core

Parameters

Name	Type	Mandatory	Description
cameraInput	CameraInput	Yes	CameraInput instance to remove.

Error codes

For details about the error codes, see Camera Error Codes.

ID	Error Message
7400101	Parameter missing or parameter type incorrect.
7400102	Operation not allowed.
7400201	Camera service fatal error.

Example

import { BusinessError } from '@kit.BasicServicesKit';

function removeInput(session: camera.Session, cameraInput: camera.CameraInput): void {
  try {
    session.removeInput(cameraInput);
  } catch (error) {
    // If the operation fails, error.code is returned and processed.
    let err = error as BusinessError;
    console.error(`The removeInput call failed. error code: ${err.code}`);
  }
}

canAddOutput¹¹⁺

canAddOutput(cameraOutput: CameraOutput): boolean

Determines whether a CameraOutput instance can be added to this session. This API must be called after addInput and before commitConfig.

Atomic service API: This API can be used in atomic services since API version 19.

System capability: SystemCapability.Multimedia.Camera.Core

Parameters

Name	Type	Mandatory	Description
cameraOutput	CameraOutput	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).

Return value

Type	Description
boolean	Check result for adding the CameraOutput instance. true if it can be added, false otherwise.

Example

function canAddOutput(session: camera.Session, cameraOutput: camera.CameraOutput): void {
  let canAdd: boolean = session.canAddOutput(cameraOutput);
  console.info(`This addOutput can add: ${canAdd}`);
}

addOutput¹¹⁺

addOutput(cameraOutput: CameraOutput): void

Adds a CameraOutput instance to this session.

Atomic service API: This API can be used in atomic services since API version 19.

System capability: SystemCapability.Multimedia.Camera.Core

Parameters

Name	Type	Mandatory	Description
cameraOutput	CameraOutput	Yes	CameraOutput instance to add.

Error codes

For details about the error codes, see Camera Error Codes.

ID	Error Message
7400101	Parameter missing or parameter type incorrect.
7400102	Operation not allowed.
7400201	Camera service fatal error.

Example

import { BusinessError } from '@kit.BasicServicesKit';

function addOutput(session: camera.Session, cameraOutput: camera.CameraOutput): void {
  try {
    session.addOutput(cameraOutput);
  } catch (error) {
    // If the operation fails, error.code is returned and processed.
    let err = error as BusinessError;
    console.error(`The addOutput call failed. error code: ${err.code}`);
  }
}

removeOutput¹¹⁺

removeOutput(cameraOutput: CameraOutput): void

Removes a CameraOutput instance from this session.

Atomic service API: This API can be used in atomic services since API version 19.

System capability: SystemCapability.Multimedia.Camera.Core

Parameters

Name	Type	Mandatory	Description
cameraOutput	CameraOutput	Yes	CameraOutput instance to remove.

Error codes

For details about the error codes, see Camera Error Codes.

ID	Error Message
7400101	Parameter missing or parameter type incorrect.
7400102	Operation not allowed.
7400201	Camera service fatal error.

Example

import { BusinessError } from '@kit.BasicServicesKit';

function removeOutput(session: camera.Session, previewOutput: camera.PreviewOutput): void {
  try {
    session.removeOutput(previewOutput);
  } catch (error) {
    // If the operation fails, error.code is returned and processed.
    let err = error as BusinessError;
    console.error(`The removeOutput call failed. error code: ${err.code}`);
  }
}

start¹¹⁺

start(callback: AsyncCallback<void>): void

Starts this session. This API uses an asynchronous callback to return the result.

Atomic service API: This API can be used in atomic services since API version 19.

System capability: SystemCapability.Multimedia.Camera.Core

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the session starts successfully, err is undefined; otherwise, err is an error object with an error code defined in CameraErrorCode.

Error codes

For details about the error codes, see Camera Error Codes.

ID	Error Message
7400102	Operation not allowed.
7400103	Session not config.
7400201	Camera service fatal error.

Example

import { BusinessError } from '@kit.BasicServicesKit';

function startCaptureSession(session: camera.Session): void {
  session.start((err: BusinessError) => {
    if (err) {
      console.error(`Failed to start the session, error code: ${err.code}.`);
      return;
    }
    console.info('Callback invoked to indicate the session start success.');
  });
}

start¹¹⁺

start(): Promise<void>

Starts this session. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 19.

System capability: SystemCapability.Multimedia.Camera.Core

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Camera Error Codes.

ID	Error Message
7400102	Operation not allowed.
7400103	Session not config.
7400201	Camera service fatal error.

Example

import { BusinessError } from '@kit.BasicServicesKit';

function startCaptureSession(session: camera.Session): void {
  session.start().then(() => {
    console.info('Promise returned to indicate the session start success.');
  }).catch((error: BusinessError) => {
    console.error(`Failed to start the session, error code: ${error.code}.`);
  });
}

stop¹¹⁺

stop(callback: AsyncCallback<void>): void

Stops this session. This API uses an asynchronous callback to return the result.

Atomic service API: This API can be used in atomic services since API version 19.

System capability: SystemCapability.Multimedia.Camera.Core

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the session stops successfully, err is undefined; otherwise, err is an error object with an error code defined in CameraErrorCode.

Error codes

For details about the error codes, see Camera Error Codes.

ID	Error Message
7400201	Camera service fatal error.

Example

import { BusinessError } from '@kit.BasicServicesKit';

function stopCaptureSession(session: camera.Session): void {
  session.stop((err: BusinessError) => {
    if (err) {
      console.error(`Failed to stop the session, error code: ${err.code}.`);
      return;
    }
    console.info('Callback invoked to indicate the session stop success.');
  });
}

stop¹¹⁺

stop(): Promise<void>

Stops this session. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 19.

System capability: SystemCapability.Multimedia.Camera.Core

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Camera Error Codes.

ID	Error Message
7400201	Camera service fatal error.

Example

import { BusinessError } from '@kit.BasicServicesKit';

function stopCaptureSession(session: camera.Session): void {
  session.stop().then(() => {
    console.info('Promise returned to indicate the session stop success.');
  }).catch((error: BusinessError) => {
    console.error(`Failed to stop the session, error code: ${error.code}.`);
  });
}

release¹¹⁺

release(callback: AsyncCallback<void>): void

Releases this session. This API uses an asynchronous callback to return the result.

Atomic service API: This API can be used in atomic services since API version 19.

System capability: SystemCapability.Multimedia.Camera.Core

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the session is released successfully, err is undefined; otherwise, err is an error object with an error code defined in CameraErrorCode.

Error codes

For details about the error codes, see Camera Error Codes.

ID	Error Message
7400201	Camera service fatal error.

Example

import { BusinessError } from '@kit.BasicServicesKit';

function releaseCaptureSession(session: camera.Session): void {
  session.release((err: BusinessError) => {
    if (err) {
      console.error(`Failed to release the session instance, error code: ${err.code}.`);
      return;
    }
    console.info('Callback invoked to indicate that the session instance is released successfully.');
  });
}

release¹¹⁺

release(): Promise<void>

Releases this session. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 19.

System capability: SystemCapability.Multimedia.Camera.Core

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Camera Error Codes.

ID	Error Message
7400201	Camera service fatal error.

Example

import { BusinessError } from '@kit.BasicServicesKit';

function releaseCaptureSession(session: camera.Session): void {
  session.release().then(() => {
    console.info('Promise returned to indicate that the session instance is released successfully.');
  }).catch((error: BusinessError) => {
    console.error(`Failed to release the session instance, error code: ${error.code}.`);
  });
}

Interface (Session)

Modules to Import

beginConfig11+

commitConfig11+

commitConfig11+

canAddInput11+

addInput11+

removeInput11+

canAddOutput11+

addOutput11+

removeOutput11+

start11+

start11+

stop11+

stop11+

release11+

release11+

beginConfig¹¹⁺

commitConfig¹¹⁺

commitConfig¹¹⁺

canAddInput¹¹⁺

addInput¹¹⁺

removeInput¹¹⁺

canAddOutput¹¹⁺

addOutput¹¹⁺

removeOutput¹¹⁺

start¹¹⁺

start¹¹⁺

stop¹¹⁺

stop¹¹⁺

release¹¹⁺

release¹¹⁺