Interface (PhotoSession)

PhotoSession inherits from Session, Flash, AutoExposure, WhiteBalance, Focus, Zoom, ColorManagement, AutoDeviceSwitch, Macro, ManualExposure, ManualFocus, ManualIso, OIS, and Aperture.

It implements a photo session, which provides operations on the flash, exposure, white balance, focus, zoom, color space, macro mode, manual exposure, manual focus, manual ISO setting, optical image stabilization (OIS), and aperture.

PhotoSession is provided for the default photo mode. It is used to take standard photos. It supports multiple photo formats and resolutions, which are suitable for most daily photo capture scenarios.

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';

canPreconfig¹²⁺

canPreconfig(preconfigType: PreconfigType, preconfigRatio?: PreconfigRatio): boolean

Checks whether this session supports a preconfigured resolution.

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
preconfigType	PreconfigType	Yes	Resolution type.
preconfigRatio	PreconfigRatio	No	Aspect ratio. The default value is 4:3.

Return value

Type	Description
boolean	Whether a preconfigured resolution is supported. true if supported, false otherwise.

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 testCanPreconfig(photoSession: camera.PhotoSession, preconfigType: camera.PreconfigType,
  preconfigRatio: camera.PreconfigRatio): void {
  try {
    let result = photoSession.canPreconfig(preconfigType, preconfigRatio);
    console.info(`canPreconfig ${preconfigType} ${preconfigRatio} result is : ${result}`);
  } catch (error) {
    let err = error as BusinessError;
    console.error(`The canPreconfig call failed. error code: ${err.code}`);
  }
}

preconfig¹²⁺

preconfig(preconfigType: PreconfigType, preconfigRatio?: PreconfigRatio): void

Preconfigures 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
preconfigType	PreconfigType	Yes	Resolution type.
preconfigRatio	PreconfigRatio	No	Aspect ratio. The default value is 4:3.

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 testPreconfig(photoSession: camera.PhotoSession, preconfigType: camera.PreconfigType,
  preconfigRatio: camera.PreconfigRatio): void {
  try {
    photoSession.preconfig(preconfigType, preconfigRatio);
    console.info(`preconfig success preconfigType: ${preconfigType}, preconfigRatio: ${preconfigRatio}`);
  } catch (error) {
    let err = error as BusinessError;
    console.error(`The preconfig call failed. error code: ${err.code}`);
  }
}

on('error')¹¹⁺

on(type: 'error', callback: ErrorCallback): void

Subscribes to PhotoSession error events. This API uses an asynchronous callback to return the result.

NOTE

Currently, you cannot use off() to unregister the callback in the callback method of on().

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
type	string	Yes	Event type. The value is fixed at 'error'. The event can be listened for when a session is created. This event is triggered and the error message is returned when an error occurs during the calling of a session-related API such as beginConfig, commitConfig, and addInput.
callback	ErrorCallback	Yes	Callback used to return an error code defined in CameraErrorCode.

Example

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

function callback(err: BusinessError): void {
  console.error(`Photo session error code: ${err.code}`);
}

function registerSessionError(photoSession: camera.PhotoSession): void {
  photoSession.on('error', callback);
}

off('error')¹¹⁺

off(type: 'error', callback?: ErrorCallback): void

Unsubscribes from PhotoSession error events. This API uses a 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
type	string	Yes	Event type. The value is fixed at 'error'. The event can be listened for when a session is created.
callback	ErrorCallback	No	Callback used to return the result. If this parameter is specified, the subscription to the specified event with the specified callback is canceled. (The callback object cannot be an anonymous function.) Otherwise, the subscriptions to the specified event with all the callbacks are canceled.

Example

function unregisterSessionError(photoSession: camera.PhotoSession): void {
  photoSession.off('error');
}

on('focusStateChange')¹¹⁺

on(type: 'focusStateChange', callback: AsyncCallback<FocusState>): void

Subscribes to focus state change events. This API uses an asynchronous callback to return the result.

NOTE

Currently, you cannot use off() to unregister the callback in the callback method of on().

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
type	string	Yes	Event type. The value is fixed at 'focusStateChange'. The event can be listened for when a session is created. This event is triggered only when the camera focus state changes in autofocus mode.
callback	AsyncCallback<FocusState>	Yes	Callback used to return the focus state change.

Example

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

function callback(err: BusinessError, focusState: camera.FocusState): void {
  if (err !== undefined && err.code !== 0) {
    console.error(`Callback Error, errorCode: ${err.code}`);
    return;
  }
  console.info(`Focus state: ${focusState}`);
}

function registerFocusStateChange(photoSession: camera.PhotoSession): void {
  photoSession.on('focusStateChange', callback);
}

off('focusStateChange')¹¹⁺

off(type: 'focusStateChange', callback?: AsyncCallback<FocusState>): void

Unsubscribes from focus state change events.

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
type	string	Yes	Event type. The value is fixed at 'focusStateChange'. The event can be listened for when a session is created.
callback	AsyncCallback<FocusState>	No	Callback used to return the result. If this parameter is specified, the subscription to the specified event with the specified callback is canceled. (The callback object cannot be an anonymous function.) Otherwise, the subscriptions to the specified event with all the callbacks are canceled.

Example

function unregisterFocusStateChange(photoSession: camera.PhotoSession): void {
  photoSession.off('focusStateChange');
}

on('smoothZoomInfoAvailable')¹¹⁺

on(type: 'smoothZoomInfoAvailable', callback: AsyncCallback<SmoothZoomInfo>): void

Subscribes to smooth zoom state change events. This API uses an asynchronous callback to return the result.

NOTE

Currently, you cannot use off() to unregister the callback in the callback method of on().

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
type	string	Yes	Event type. The value is fixed at 'smoothZoomInfoAvailable'. The event can be listened for when a session is created.
callback	AsyncCallback<SmoothZoomInfo>	Yes	Callback used to return the smooth zoom state change.

Example

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

function callback(err: BusinessError, smoothZoomInfo: camera.SmoothZoomInfo): void {
  if (err !== undefined && err.code !== 0) {
    console.error(`Callback Error, errorCode: ${err.code}`);
    return;
  }
  console.info(`The duration of smooth zoom: ${smoothZoomInfo.duration}`);
}

function registerSmoothZoomInfo(photoSession: camera.PhotoSession): void {
  photoSession.on('smoothZoomInfoAvailable', callback);
}

off('smoothZoomInfoAvailable')¹¹⁺

off(type: 'smoothZoomInfoAvailable', callback?: AsyncCallback<SmoothZoomInfo>): void

Unsubscribes from smooth zoom state change events.

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
type	string	Yes	Event type. The value is fixed at 'smoothZoomInfoAvailable'. The event can be listened for when a session is created.
callback	AsyncCallback<SmoothZoomInfo>	No	Callback used to return the result. If this parameter is specified, the subscription to the specified event with the specified callback is canceled. (The callback object cannot be an anonymous function.) Otherwise, the subscriptions to the specified event with all the callbacks are canceled.

Example

function unregisterSmoothZoomInfo(photoSession: camera.PhotoSession): void {
  photoSession.off('smoothZoomInfoAvailable');
}

on('autoDeviceSwitchStatusChange')¹³⁺

on(type: 'autoDeviceSwitchStatusChange', callback: AsyncCallback<AutoDeviceSwitchStatus>): void

Subscribes to automatic camera switch status change events. This API uses an asynchronous callback to return the result.

NOTE

Currently, you cannot use off() to unregister the callback in the callback method of on().

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
type	string	Yes	Event type. The value is fixed at 'autoDeviceSwitchStatusChange'. The event can be listened for when a session is created.
callback	AsyncCallback<AutoDeviceSwitchStatus>	Yes	Callback function, which is used to obtain the status of automatic camera switch.

Example

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

function callback(err: BusinessError, autoDeviceSwitchStatus: camera.AutoDeviceSwitchStatus): void {
  if (err !== undefined && err.code !== 0) {
    console.error(`Callback Error, errorCode: ${err.code}`);
    return;
  }
  console.info(`isDeviceSwitched: ${autoDeviceSwitchStatus.isDeviceSwitched}, isDeviceCapabilityChanged: ${autoDeviceSwitchStatus.isDeviceCapabilityChanged}`);
}

function registerAutoDeviceSwitchStatus(photoSession: camera.PhotoSession): void {
  photoSession.on('autoDeviceSwitchStatusChange', callback);
}

off('autoDeviceSwitchStatusChange')¹³⁺

off(type: 'autoDeviceSwitchStatusChange', callback?: AsyncCallback<AutoDeviceSwitchStatus>): void

Unsubscribes from automatic camera switch status change events.

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
type	string	Yes	Event type. The value is fixed at 'autoDeviceSwitchStatusChange'. The event can be listened for when a session is created.
callback	AsyncCallback<AutoDeviceSwitchStatus>	No	Callback used to return the result. If this parameter is specified, the subscription to the specified event with the specified callback is canceled. (The callback object cannot be an anonymous function.) Otherwise, the subscriptions to the specified event with all the callbacks are canceled.

Example

function unregisterSmoothZoomInfo(photoSession: camera.PhotoSession): void {
  photoSession.off('autoDeviceSwitchStatusChange');
}

on('systemPressureLevelChange')²⁰⁺

on(type: 'systemPressureLevelChange', callback: AsyncCallback<SystemPressureLevel>): void

Subscribes to system pressure level change events. This API uses an asynchronous callback to return the result.

NOTE

Currently, you cannot use off() to unregister the callback in the callback method of on().

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

System capability: SystemCapability.Multimedia.Camera.Core

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. The value is fixed at 'systemPressureLevelChange'. The event can be listened for when a session is created.
callback	AsyncCallback<SystemPressureLevel>	Yes	Callback used to return the current system pressure level.

Example

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

function callback(err: BusinessError, systemPressureLevel: camera.SystemPressureLevel): void {
  if (err !== undefined && err.code !== 0) {
    console.error(`Callback Error, errorCode: ${err.code}`);
    return;
  }
  console.info(`systemPressureLevel: ${systemPressureLevel}`);
}

function registerSystemPressureLevelChangeCallback(photoSession: camera.PhotoSession): void {
    photoSession.on('systemPressureLevelChange', callback);
}

off('systemPressureLevelChange')²⁰⁺

off(type: 'systemPressureLevelChange', callback?: AsyncCallback<SystemPressureLevel>): void

Unsubscribes from system pressure level change events.

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

System capability: SystemCapability.Multimedia.Camera.Core

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. The value is fixed at 'systemPressureLevelChange'. The event can be listened for when a session is created.
callback	AsyncCallback<SystemPressureLevel>	No	Callback used to return the result. If this parameter is specified, the subscription to the specified event with the specified callback is canceled. (The callback object cannot be an anonymous function.) Otherwise, the subscriptions to the specified event with all the callbacks are canceled.

Example

function unregisterSystemPressureLevelChangeCallback(photoSession: camera.PhotoSession): void {
  photoSession.off('systemPressureLevelChange');
}

on('macroStatusChanged')²⁰⁺

on(type: 'macroStatusChanged', callback: AsyncCallback<boolean>): void

Subscribes to macro state change events. This API uses an asynchronous callback to return the result.

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

System capability: SystemCapability.Multimedia.Camera.Core

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. The value is fixed at 'macroStatusChanged'. The event can be listened for when a session is created.
callback	AsyncCallback<boolean>	Yes	Callback used to return the macro state. true if enabled, false otherwise.

Example

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

function callback(err: BusinessError, macroStatus: boolean): void {
  if (err !== undefined && err.code !== 0) {
    console.error(`Callback Error, errorCode: ${err.code}`);
    return;
  }
  console.info(`Macro state: ${macroStatus}`);
}

function registerMacroStatusChanged(photoSession: camera.PhotoSession): void {
  photoSession.on('macroStatusChanged', callback);
}

off('macroStatusChanged')²⁰⁺

off(type: 'macroStatusChanged', callback?: AsyncCallback<boolean>): void

Unsubscribes from macro state change events.

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

System capability: SystemCapability.Multimedia.Camera.Core

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. The value is fixed at 'macroStatusChanged'. The event can be listened for when a session is created.
callback	AsyncCallback<boolean>	No	Callback used to return the result. If this parameter is specified, the subscription to the specified event with the specified callback is canceled. (The callback object cannot be an anonymous function.) Otherwise, the subscriptions to the specified event with all the callbacks are canceled.

Example

function unregisterMacroStatusChanged(photoSession: camera.PhotoSession): void {
  photoSession.off('macroStatusChanged');
}

onIsoInfoChange²⁴⁺

onIsoInfoChange(callback: Callback<IsoInfo>): void

Subscribes to ISO information change events.

Model restriction: This API can be used only in the stage model.

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

System capability: SystemCapability.Multimedia.Camera.Core

Parameters

Name	Type	Mandatory	Description
callback	Callback<IsoInfo>	Yes	Callback used to obtain the ISO information.

Example

function onIsoInfoChange(photoSession: camera.PhotoSession): void {
  photoSession.onIsoInfoChange((isoInfo: camera.IsoInfo) => {
    console.info(`ISO info changed, iso: ${isoInfo.iso}`);
  });
}

offIsoInfoChange²⁴⁺

offIsoInfoChange(callback?: Callback<IsoInfo>): void

Unsubscribes from ISO information change events.

Model restriction: This API can be used only in the stage model.

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

System capability: SystemCapability.Multimedia.Camera.Core

Parameters

Name	Type	Mandatory	Description
callback	Callback<IsoInfo>	No	Callback used to return the result. If this parameter is specified, the subscription to the specified event with the specified callback is canceled. (The callback object cannot be an anonymous function.) Otherwise, the subscriptions to the specified event with all the callbacks are canceled.

Example

function offIsoInfoChange(photoSession: camera.PhotoSession): void {
  photoSession.offIsoInfoChange();
}

Interface (PhotoSession)

Modules to Import

canPreconfig12+

preconfig12+

on('error')11+

off('error')11+

on('focusStateChange')11+

off('focusStateChange')11+

on('smoothZoomInfoAvailable')11+

off('smoothZoomInfoAvailable')11+

on('autoDeviceSwitchStatusChange')13+

off('autoDeviceSwitchStatusChange')13+

on('systemPressureLevelChange')20+

off('systemPressureLevelChange')20+

on('macroStatusChanged')20+

off('macroStatusChanged')20+

onIsoInfoChange24+

offIsoInfoChange24+

canPreconfig¹²⁺

preconfig¹²⁺

on('error')¹¹⁺

off('error')¹¹⁺

on('focusStateChange')¹¹⁺

off('focusStateChange')¹¹⁺

on('smoothZoomInfoAvailable')¹¹⁺

off('smoothZoomInfoAvailable')¹¹⁺

on('autoDeviceSwitchStatusChange')¹³⁺

off('autoDeviceSwitchStatusChange')¹³⁺

on('systemPressureLevelChange')²⁰⁺

off('systemPressureLevelChange')²⁰⁺

on('macroStatusChanged')²⁰⁺

off('macroStatusChanged')²⁰⁺

onIsoInfoChange²⁴⁺

offIsoInfoChange²⁴⁺