Light -API Tutorial

Introduction

To -use the Light API, the client must first create an instance of CHWRMLight class. CHWRMLight can be used in two modes:

With notify handling.
Without notify handling.

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.

There are three light control -methods, each with several overloads:

LightOnL() to -turn ON the lights.
LightBlinkL() to -make lights blink.
LightOffL() to -turn OFF the lights.

Light intensity can be optionally controlled by the LightOnL() and LightBlinkL() methods. Intensity is controlled -as a percentage. KHWRMDefaultIntensity can -use default intensity or ambient light sensor controlled intensity, depending -on general settings.

Light fade can be optionally controlled by the LightOnL() and LightOffL() 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.

Note: -All devices do not support this functionality. The current status of any light -target can be obtained with the LightStatus() method.

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 SupportedTargets() method.

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.

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.

Using Light API, you -can perform any of the tasks listed in the Procedure section.

Procedure

Creating -a light instance
Retrieving -the supported light targets of a device
Retrieving -the current light status
Reserving -light targets
Switching -ON the lights
Switching -OFF the lights
Blinking -lights
Releasing -the reserved lights
Releasing -the instance