Reserving light targets

The ReserveLightL() call reserves the light target(s) exclusively for this client. Multiple lights can be specified by using bitwise-or.

A higher priority client can cause lower priority client reservation to be temporarily suspended. Commands can still be issued in suspended state, but they are not acted upon unless suspension is lifted within a specified duration. The suspended client does not receive any notification about the suspension. If the light target is already reserved by a higher or an equal priority application, reserving still succeeds but gets suspended immediately. In such case, only the virtual state of the lights is remembered by the session; actual lights are not controlled. When suspended reservation is activated, the actual lights state is restored to the same as the virtual state.

The following code snippet demonstrates how to reserve multiple light targets:

//aRestoreState = ETrue means that any previously frozen state will be restored.
// aForceNoCCoeEnv = EFalse means that the CCoeEnv background/foreground status
// is always used to control further reservations.
iLight->ReserveLightL( ( CHWRMLight::EPrimaryDisplay | CHWRMLight::EPrimaryKeyboard ), ETrue, EFalse );

Calling the ReserveLightL() method without second and third parameters is equal to calling ReserveLightL( aTarget, EFalse, EFalse ), that is, any previously frozen state is not restored and the CCoeEnv background/foreground status is always used to control further reservations.

Note: Light can be controlled without a reservation, if there is no other client with a reservation.