<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept xml:lang="en" id="GUID-9014ED9B-B0A0-5C95-9C5B-7D2F658C757F"><title>Accessing and Power Control of Camera</title><shortdesc>This tutorial describes how to access camera and control its power settings using Ecam APIs: </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody><section><title>Purpose</title> <p>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. </p> <p><b>Required Background</b> </p> <p>The <xref href="GUID-80EC80E2-E197-50F7-B1FD-720A00AC3B4D.dita">Onboard Camera Overview</xref> introduces the camera utilities. </p> <p>Camera is implemented as Ecom plug-ins, the Ecom plug-in implements <xref href="GUID-021C509B-C821-3401-B2F4-DE7F52BB16D4.dita"><apiname>CCamera</apiname></xref> interface defined in <filepath>ECam.h</filepath>. When you need to create a new camera object, the Ecam library requests a camera plug-in from the ECOM framework. </p> <p><b>Introduction</b> </p> <p>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. </p> </section> <section><title>Using Camera </title> <p>The following tasks will be covered in this tutorial: </p> <ul><li id="GUID-1CE9E3AF-96C6-59E6-8242-798055D4FAFE"><p><xref href="GUID-9014ED9B-B0A0-5C95-9C5B-7D2F658C757F.dita#GUID-9014ED9B-B0A0-5C95-9C5B-7D2F658C757F/GUID-4000B2F3-A948-5C35-AE2A-804CEF1EAA8E">Accessing the Camera</xref>  </p> <p> </p> </li> <li id="GUID-8A0C2A5D-AD79-55B3-AFEF-8EB20A6E10FF"><p><xref href="GUID-9014ED9B-B0A0-5C95-9C5B-7D2F658C757F.dita#GUID-9014ED9B-B0A0-5C95-9C5B-7D2F658C757F/GUID-8A587F65-EDFB-5609-BE96-4869047F3E71">Power Control</xref>  </p> </li> </ul> <p id="GUID-4000B2F3-A948-5C35-AE2A-804CEF1EAA8E"><b>Accessing the Camera</b> </p> <p>The high level steps to access specific camera connected to the device are shown here: </p> <ol id="GUID-087EC84C-8EAC-5BF1-B5D7-00CDA28941B3"><li id="GUID-8FF5D72F-1719-5D2C-B301-69E547CBB391"><p>Make sure that you configure the initial settings and use <xref href="GUID-021C509B-C821-3401-B2F4-DE7F52BB16D4.dita#GUID-021C509B-C821-3401-B2F4-DE7F52BB16D4/GUID-AE298F30-D55B-3812-95A8-8BAE319C2FB6"><apiname>CCamera::CamerasAvailable()</apiname></xref> method to get the number of cameras available for usage. </p> <codeblock id="GUID-2C77F771-E42B-5E94-B6BB-C46DA34F4671" xml:space="preserve">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;

</codeblock> </li> <li id="GUID-6BB8429D-3580-53A6-BD6B-797CF7F63BB1"><p>Create a new camera object using <xref href="GUID-021C509B-C821-3401-B2F4-DE7F52BB16D4.dita#GUID-021C509B-C821-3401-B2F4-DE7F52BB16D4/GUID-9EAAE04E-9C9B-357A-B73E-55574E7CA02D"><apiname>CCamera::New2L()</apiname></xref> API. </p> <codeblock id="GUID-4B290B75-289E-58F6-BCB9-D6C618C417D4" xml:space="preserve">CCamera* camera = NULL;

MCameraObserver2* observer2L; //exists beforehand

camera = CCamera::New2L(*observer2, 0, 0);

</codeblock> </li> <li id="GUID-CBF8CF4A-A558-5D81-B4A3-9FA55A22B52C"><p>Use <xref href="GUID-4E8A5141-5E4A-322A-9892-8DC49D04986E.dita#GUID-4E8A5141-5E4A-322A-9892-8DC49D04986E/GUID-069D6532-4D43-3547-94BF-D0E5E6CDD78B"><apiname>Ccamera::NewDuplicate2L</apiname></xref>, if collaborative clients wants to share the same camera device. This makes sure that the client can receive unrecognised enum, UIDs and so on. </p> <p> <b>Note</b>: This is true if <xref href="GUID-94C66CB9-328A-3275-B5A9-198EC6D0DD30.dita"><apiname>New2L</apiname></xref> method instead of <xref href="GUID-E6F013A6-6413-3691-A70D-0289916ACD8A.dita"><apiname>NewL</apiname></xref> and <xref href="GUID-14200C39-1435-31B0-9768-363BD3D4331E.dita"><apiname>NewDuplicate2L</apiname></xref> method is instead of over <xref href="GUID-0DB8D81E-AEC1-364B-B404-996B35B449FD.dita"><apiname>NewDuplicateL</apiname></xref> method. </p> <codeblock id="GUID-A3E2D65F-B3A6-59DD-812E-5C940391CE1B" xml:space="preserve">CCamera* sharingCamera = NULL;

sharingCamera = CCamera::NewDuplicate2L(*observer2, 0);</codeblock> </li> <li id="GUID-53C83699-8ACC-5F75-8F26-D6F21241DB7F"><p>Use <xref href="GUID-021C509B-C821-3401-B2F4-DE7F52BB16D4.dita#GUID-021C509B-C821-3401-B2F4-DE7F52BB16D4/GUID-2B806D39-5C5C-357E-A4CC-240CE0C4D786"><apiname>CCamera::Reserve</apiname></xref>, an asynchronous method to gain exclusive access to a particular camera. </p> <p>Even if a camera object is created successfully based on specified camera index, the client cannot use it, if it is not reserved. </p> <ul><li id="GUID-E6677D62-D0C5-52A9-8A08-1DE41C79EA35"><p>The <xref href="GUID-021C509B-C821-3401-B2F4-DE7F52BB16D4.dita#GUID-021C509B-C821-3401-B2F4-DE7F52BB16D4/GUID-2B806D39-5C5C-357E-A4CC-240CE0C4D786"><apiname>CCamera::Reserve</apiname></xref> call will be unsuccessful if a higher priority client is already using the camera and <xref href="GUID-09C6DDB6-A208-3C81-9F54-697D4865D99F.dita#GUID-09C6DDB6-A208-3C81-9F54-697D4865D99F/GUID-1E3D825C-1924-3A1E-9B0F-1359504633E7"><apiname>MCameraObserver2::HandleEvent</apiname></xref> call back will return an error. </p> </li> <li id="GUID-C008313B-9AD6-5EFB-B01C-21D6ABF9EAB4"><p>Event UID <xref href="GUID-3D4AC57E-B975-3F91-A1FC-13AC526AD4A6.dita"><apiname>KUidECamEventCameraNoLongerReserved</apiname></xref> notifies that a high priority client has gained control over another client. </p> </li> </ul> </li> <li id="GUID-F8BE95D3-27CE-5323-9177-86B54F836C13"><p>Use <xref href="GUID-54A053B1-2B90-3A69-A6DD-B0A7A4B46BBA.dita"><apiname>HandleEvent()</apiname></xref> 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 <xref href="GUID-C318ACF6-1959-3BF4-9698-B7F0E228528E.dita"><apiname>Reserve()</apiname></xref>, a call to <xref href="GUID-97444FAF-67EB-3648-B4AA-22AFE912F68A.dita"><apiname>PowerOn()</apiname></xref> or a notification that the client has lost control of the camera. </p> <p>This provides a reference to a <xref href="GUID-2773C25B-19DF-38B0-84F7-CABC89F43DD2.dita"><apiname>TECAMEvent</apiname></xref> with uid <xref href="GUID-81136EE6-71EF-3D84-AD1A-B74BD3DE674E.dita"><apiname>KUidECamEventReserveComplete</apiname></xref> and error as <xref href="GUID-6CA4F1ED-7947-3087-B618-D35858FAA3BC.dita"><apiname>KErrNone</apiname></xref>. </p> <codeblock id="GUID-9A58EC65-5065-51FF-BFFA-2C32B6208545" xml:space="preserve">    void HandleEvent(const TECAMEvent&amp; aEvent); 

void TDummyObserver::HandleEvent(const TECAMEvent& /*aEvent*/)

    {

    return;

    }</codeblock> </li> <li id="GUID-2E45D548-C1B0-51C7-9AF1-6113DBD5307F"><p>Use <xref href="GUID-021C509B-C821-3401-B2F4-DE7F52BB16D4.dita#GUID-021C509B-C821-3401-B2F4-DE7F52BB16D4/GUID-635500E6-055A-36A0-8993-21BF2584A35C"><apiname>CCamera::Release()</apiname></xref> method to de-initialize and withdraw the client's access to the camera such that other clients might use it. </p> </li> </ol> <p> <b>Note</b>: Clients should not use the legacy call-back interface <xref href="GUID-F2DC0AB8-A896-3F7A-BBED-848A3F463853.dita"><apiname>MCameraObserver</apiname></xref> which is still supported. </p> <p id="GUID-8A587F65-EDFB-5609-BE96-4869047F3E71"><b>Power Control</b> </p> <p>The high level steps to control the power settings of the camera are shown here: </p> <ol id="GUID-45695F99-1C19-5D58-806C-1BF11DDDE704"><li id="GUID-33CA1CE5-72BE-58A4-AEDA-82570F448EB9"><p>Use <xref href="GUID-97444FAF-67EB-3648-B4AA-22AFE912F68A.dita"><apiname>PowerOn()</apiname></xref>, an asynchronous method, to switch on the camera, when the client gains exclusive access for the given camera. </p> <p>When power on is complete, client receives notification through <xref href="GUID-09C6DDB6-A208-3C81-9F54-697D4865D99F.dita#GUID-09C6DDB6-A208-3C81-9F54-697D4865D99F/GUID-1E3D825C-1924-3A1E-9B0F-1359504633E7"><apiname>MCameraObserver2::HandleEvent</apiname></xref> callback with uid <xref href="GUID-0683BF83-B8F7-3582-99D8-1448B8CEA92C.dita"><apiname>KUidECamEventPowerOnComplete</apiname></xref> and the appropriate error code. If the camera is not successfully reserved, <xref href="GUID-B6FDA0AB-750D-321C-BC7E-BEDE099006EB.dita"><apiname>PowerOn</apiname></xref> will fail. </p> </li> <li id="GUID-3FEDAA32-C41C-5201-80A1-32B41CC7ACA0"><p>The callback interface is notified when power on is complete via MCameraObserver2::HandleEvent() notification. The event used is KUidECamEventPowerOnComplete. </p> <codeblock id="GUID-7EF4B115-6C98-59AC-A280-683ED4FDAF23" xml:space="preserve">void CCamMyPlugin::PowerOn()

    {

    }</codeblock> </li> <li id="GUID-A669B86A-8878-5634-98BF-53B80E781833"><p>Once the processing is complete, use <xref href="GUID-816450E5-A395-3220-BEA0-1C1571CACD3F.dita"><apiname>PowerOff()</apiname></xref>, a synchronous method to switch off the camera power. </p> <codeblock id="GUID-9A062705-A90E-5B09-BC1F-07B49DC7F663" xml:space="preserve">void CCamMyPlugin::PowerOff()

    {