<?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>