Accessing and Power Control of Camera

Purpose

The purpose of the tutorial is to explain you how to use Ecam APIs to access and control power settings of a camera on a phone.

Required Background

The Onboard Camera Overview introduces the camera utilities.

Camera is implemented as Ecom plug-ins, the Ecom plug-in implements CCamera interface defined in ECam.h. When you need to create a new camera object, the Ecam library requests a camera plug-in from the ECOM framework.

Introduction

Ecam is a component of the Symbian platform Multimedia subsystem that represents the Onboard Camera API. Licensees may provide customised implementation for snapshots, histogram and image processing depending on the camera mode in which it is operated.

Using Camera

The following tasks will be covered in this tutorial:

• Accessing the Camera

• Power Control

Accessing the Camera

The high level steps to access specific camera connected to the device are shown here:

1. Make sure that you configure the initial settings and use CCamera::CamerasAvailable() method to get the number of cameras available for usage.

   TInt numCameras = CCamera::CamerasAvailable();
   if (numCameras <= 0)
       {
       INFO_PRINTF2(_L("Error %d returned"), numCameras);
       return EFail;
       }
   INFO_PRINTF2(_L("Available cameras  %d returned"), numCameras);
   return EPass;
   

2. Create a new camera object using CCamera::New2L() API.

   CCamera* camera = NULL;
   MCameraObserver2* observer2L; //exists beforehand
   
   camera = CCamera::New2L(*observer2, 0, 0);
   

3. Use Ccamera::NewDuplicate2L, if collaborative clients wants to share the same camera device. This makes sure that the client can receive unrecognised enum, UIDs and so on.

   Note: This is true if New2L method instead of NewL and NewDuplicate2L method is instead of over NewDuplicateL method.

   CCamera* sharingCamera = NULL;
   sharingCamera = CCamera::NewDuplicate2L(*observer2, 0);

4. Use CCamera::Reserve, an asynchronous method to gain exclusive access to a particular camera.

   Even if a camera object is created successfully based on specified camera index, the client cannot use it, if it is not reserved.

   • The CCamera::Reserve call will be unsuccessful if a higher priority client is already using the camera and MCameraObserver2::HandleEvent call back will return an error.

   • Event UID KUidECamEventCameraNoLongerReserved notifies that a high priority client has gained control over another client.

5. Use HandleEvent() method to notify the client that the call is unsuccessful and the camera is not available. This can be due to completion of a call to Reserve(), a call to PowerOn() or a notification that the client has lost control of the camera.

   This provides a reference to a TECAMEvent with uid KUidECamEventReserveComplete and error as KErrNone.

       void HandleEvent(const TECAMEvent& aEvent); 
   void TDummyObserver::HandleEvent(const TECAMEvent& /*aEvent*/)
       {
       return;
       }

6. Use CCamera::Release() method to de-initialize and withdraw the client's access to the camera such that other clients might use it.

Note: Clients should not use the legacy call-back interface MCameraObserver which is still supported.

Power Control

The high level steps to control the power settings of the camera are shown here:

1. Use PowerOn(), an asynchronous method, to switch on the camera, when the client gains exclusive access for the given camera.

   When power on is complete, client receives notification through MCameraObserver2::HandleEvent callback with uid KUidECamEventPowerOnComplete and the appropriate error code. If the camera is not successfully reserved, PowerOn will fail.

2. The callback interface is notified when power on is complete via MCameraObserver2::HandleEvent() notification. The event used is KUidECamEventPowerOnComplete.

   void CCamMyPlugin::PowerOn()
       {
       }

3. Once the processing is complete, use PowerOff(), a synchronous method to switch off the camera power.

   void CCamMyPlugin::PowerOff()
       {
       }

Miscellaneous

This section details miscellaneous camera access and control APIsl.

Reserve Status Retrieval

Licensees need to implement MSecureIdPlugin (ecaminfoplugin.h) to retrieve the secure ID of the process where serialized part of the ECam implementation runs, such as Ecam server.

Clients can retrieve the reservation status of a particular camera prior to creating an instance of the Ccamera class. This saves time, if the client is denied control to reserve the camera after creating an instance of theCcamera class. Client needs to subscribe for receiving the reserve status by calling static method TreservedInfo::SubscribeReserveInfoL() and this provides a reference to CcameraStatusWatch.

Symbian must provide implementation of CCameraStatusWatch class. Clients can use this to asynchronously receive the reserve status of a camera index through MReserveObserver. Client must implement MReserveObserver to handle the notifications of Reserve status and take appropriate steps accordingly. Note: If the client needs to unsubscribe, it must make sure to delete the CcameraStatusWatch object.

Get the reserve status of the camera using ReserveStatus API. This can be used, when a low priority client interrupts a high priority client in a phone supporting multiple cameras.