--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/PDK/Source/GUID-9014ED9B-B0A0-5C95-9C5B-7D2F658C757F.dita	Fri Jan 22 18:26:19 2010 +0000
@@ -0,0 +1,33 @@
+<?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 &lt;= 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&amp; /*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()
+    {
+    }</codeblock> </li> </ol> </section> <section><title>Miscellaneous</title> <p>This section details miscellaneous camera access and control APIsl. </p> <p><b> Reserve Status Retrieval</b> </p> <p>Licensees need to implement <xref href="GUID-36BA124F-A7BE-3449-9C00-C2F2D4F15293.dita"><apiname>MSecureIdPlugin</apiname></xref> (<filepath>ecaminfoplugin.h)</filepath> to retrieve the secure ID of the process where serialized part of the ECam implementation runs, such as Ecam server. </p> <p>Clients can retrieve the reservation status of a particular camera prior to creating an instance of the <xref href="GUID-4E8A5141-5E4A-322A-9892-8DC49D04986E.dita"><apiname>Ccamera</apiname></xref> class. This saves time, if the client is denied control to reserve the camera after creating an instance of the<xref href="GUID-4E8A5141-5E4A-322A-9892-8DC49D04986E.dita"><apiname>Ccamera</apiname></xref> class. Client needs to subscribe for receiving the reserve status by calling static method <xref href="GUID-AE32A954-5A26-367B-8F3F-99A19F93430A.dita#GUID-AE32A954-5A26-367B-8F3F-99A19F93430A/GUID-A56B25A1-B2F1-306E-952F-1FD0BA43B833"><apiname>TreservedInfo::SubscribeReserveInfoL()</apiname></xref> and this provides a reference to <xref href="GUID-104B8CDA-8F7E-3E41-BDE9-6EC5A9D7AA9C.dita"><apiname>CcameraStatusWatch</apiname></xref>. </p> <p>Symbian must provide implementation of <xref href="GUID-6C0DAE0A-F64C-3AE0-9F53-63E767E79E9B.dita"><apiname>CCameraStatusWatch</apiname></xref> class. Clients can use this to asynchronously receive the reserve status of a camera index through <xref href="GUID-FFC680A5-8BE5-355C-816E-F3B0625AC5CF.dita"><apiname>MReserveObserver</apiname></xref>. Client must implement <xref href="GUID-FFC680A5-8BE5-355C-816E-F3B0625AC5CF.dita"><apiname>MReserveObserver</apiname></xref> to handle the notifications of Reserve status and take appropriate steps accordingly. <b>Note</b>: If the client needs to unsubscribe, it must make sure to delete the <xref href="GUID-104B8CDA-8F7E-3E41-BDE9-6EC5A9D7AA9C.dita"><apiname>CcameraStatusWatch</apiname></xref> object. </p> <p>Get the reserve status of the camera using <xref href="GUID-0F901FF4-4F24-317B-9B0A-4733E0612AAF.dita"><apiname>ReserveStatus</apiname></xref> API. This can be used, when a low priority client interrupts a high priority client in a phone supporting multiple cameras. </p> </section> </conbody><related-links><link href="GUID-FAB548CF-24EB-52D1-A7A1-9446BA67C7A5.dita"><linktext>Camera Preset Support</linktext> </link> <link href="GUID-DA26D246-D74A-529F-9F81-11B45669103F.dita"><linktext> Capturing Image</linktext> </link> <link href="GUID-F690DAC8-688B-5BD7-88DF-0CB3D4ACDCFF.dita"><linktext>Capturing Video</linktext> </link> </related-links></concept>
\ No newline at end of file