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

See also

Light API