<?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 id="GUID-D4E06508-4346-5294-995A-64B403467EC5" xml:lang="en"><title>Light
API Tutorial</title><shortdesc>This tutorial describes how to use the Light API of HWRM. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<section id="GUID-275E5AC3-0D51-5783-8E3F-DCEE6B37970B"><title>Introduction</title> <p>To
use the Light API, the client must first create an instance of <xref href="GUID-3B241B7B-C5D3-33AE-9D51-3F3B78530F60.dita"><apiname>CHWRMLight</apiname></xref> class. <xref href="GUID-3B241B7B-C5D3-33AE-9D51-3F3B78530F60.dita"><apiname>CHWRMLight</apiname></xref> can be used in two modes: </p> <ul>
<li id="GUID-BB6B2D97-C797-5C5C-9CB4-0DA5F7682814"><p>With notify handling. </p> </li>
<li id="GUID-A22F084E-2204-5589-B664-053EC50DEE0C"><p>Without notify handling. </p> </li>
</ul> <p>An instance with notify handling is created if the client requires
up-to-date status information. Else, an instance without a callback pointer
is created. After an instance is created, lights can be directly controlled
through the provided class methods. </p> <p>There are three light control
methods, each with several overloads: </p> <ul>
<li id="GUID-FE777756-F97C-5B4E-8334-C061FFCC0EBB"><p> <xref href="GUID-3B241B7B-C5D3-33AE-9D51-3F3B78530F60.dita"><apiname>LightOnL()</apiname></xref> to
turn ON the lights. </p> </li>
<li id="GUID-FC98BD11-09E2-574D-9A05-5C48B39A6C7E"><p> <xref href="GUID-3B241B7B-C5D3-33AE-9D51-3F3B78530F60.dita"><apiname>LightBlinkL()</apiname></xref> to
make lights blink. </p> </li>
<li id="GUID-EA1C4E36-1B59-57AC-B282-91FACF32A3E3"><p> <xref href="GUID-3B241B7B-C5D3-33AE-9D51-3F3B78530F60.dita"><apiname>LightOffL()</apiname></xref> to
turn OFF the lights. </p> </li>
</ul> <p>Light intensity can be optionally controlled by the <xref href="GUID-3B241B7B-C5D3-33AE-9D51-3F3B78530F60.dita"><apiname>LightOnL()</apiname></xref> and <xref href="GUID-3B241B7B-C5D3-33AE-9D51-3F3B78530F60.dita"><apiname>LightBlinkL()</apiname></xref> methods. Intensity is controlled
as a percentage. <xref href="GUID-3B241B7B-C5D3-33AE-9D51-3F3B78530F60.dita"><apiname>KHWRMDefaultIntensity</apiname></xref> can
use default intensity or ambient light sensor controlled intensity, depending
on general settings. </p> <p>Light fade can be optionally controlled by the <xref href="GUID-3B241B7B-C5D3-33AE-9D51-3F3B78530F60.dita"><apiname>LightOnL()</apiname></xref> and <xref href="GUID-3B241B7B-C5D3-33AE-9D51-3F3B78530F60.dita"><apiname>LightOffL()</apiname></xref> methods.
Fade simply means that lights are turned ON or OFF over a short period of
time with multiple gradual intensity changes instead of single instant change. </p> <p> <b>Note</b>:
All devices do not support this functionality. The current status of any light
target can be obtained with the <xref href="GUID-3B241B7B-C5D3-33AE-9D51-3F3B78530F60.dita"><apiname>LightStatus()</apiname></xref> method. </p> <p>All
control methods require at least a target mask as a parameter. Devices can
have multiple independent lights, called targets, such as device primary display
light or keyboard light. All devices do not support all possible light targets.
Supported targets may be queried with the <xref href="GUID-3B241B7B-C5D3-33AE-9D51-3F3B78530F60.dita"><apiname>SupportedTargets()</apiname></xref> method. </p> <p>All
control methods accept optional duration parameter also. Any infinite duration
call sets session base light state for targets it affects. This base state
is what the target is set to when any duration timer affecting it expires.
If there are no infinite duration calls for a target session, any timer expiry
for that target sets the target to the default state (which is either ON or
OFF), depending on the device inactivity time and the inactivity time-limit
defined by general settings. </p> <p>Each target can have only one duration
timer. Hence, if a target with ongoing timer is issued with new orders, the
ongoing timer is cancelled and a new one is set. </p><p>Using Light API, you
can perform any of the tasks listed in the Procedure section.</p> </section>
<section><title>Procedure</title> <ul id="GUID-95D4E107-AA25-51F0-B081-6889586420F8">
<li id="GUID-25998A3D-1DE9-52FA-8CC7-26657DF8724C"><p><xref href="GUID-CD87FAF6-A11D-4260-9472-CABA18BF86B1.dita">Creating
a light instance</xref>  </p> </li>
<li id="GUID-8567BEBC-4992-5F8F-B9E2-EE1D20C120A8"><p><xref href="GUID-4860A4E6-1641-47D9-8243-C03779276C6D.dita">Retrieving
the supported light targets of a device</xref>  </p> </li>
<li id="GUID-4A985353-C4E0-5ABA-AB97-49E24B99B924"><p><xref href="GUID-D21191CC-965A-4F92-9792-4B34D54114DA.dita">Retrieving
the current light status</xref>  </p> </li>
<li id="GUID-A22870FD-1722-5DCA-BA29-19C66792F148"><p><xref href="GUID-6DA81F01-FBD7-4167-B722-832888DEC0AD.dita">Reserving
light targets</xref>  </p> </li>
<li id="GUID-C136D460-E987-5A04-B6BE-0AB25115623E"><p><xref href="GUID-4FE4B515-EE2B-47DB-BECE-E390E4EB2C3E.dita">Switching
ON the lights</xref>  </p> </li>
<li id="GUID-125018AA-1FAC-5EB2-A6A9-F0A7E01A2484"><p><xref href="GUID-056736E0-3DF0-49FE-A44D-1A8E47FE45A0.dita">Switching
OFF the lights</xref>  </p> </li>
<li id="GUID-B68A413F-892D-5F5A-8EF9-58C9549050A8"><p><xref href="GUID-3715E8EE-FF0A-4344-90F1-1609D54C166B.dita">Blinking
lights</xref>  </p> </li>
<li id="GUID-125ED39B-08F1-5AE6-8664-93EFC03E6016"><p><xref href="GUID-CF6C76A5-AC87-4EBD-AECF-35B456219B94.dita">Releasing
the reserved lights</xref>  </p> </li>
<li id="GUID-3F750C8E-6668-52A5-A7C5-DDD960DECD6E"><p><xref href="GUID-2382F758-35CF-4378-A5D5-183121E3BF6A.dita">Releasing
the instance</xref>  </p> </li>
</ul> </section>
<section><title>See also</title> <p><xref href="GUID-1969956D-CDA0-5DA0-ACF8-69AFBBEC1408.dita">Light
API</xref>  </p> </section>
</conbody></concept>