Home2L - C/C++ API v1.4-0-g38cc (2024-05-25)
Smart Tools for a Private Home
Macros
System

Description

Accessing system-specific functionalities and hardware.

Collaboration diagram for System:

Macros

#define WALLCLOCK_NAME   "WallClock"
 Written name of the WallClock application ...
 

System mode ...

To save power, a set of system modes is defined (see ESystemMode ).

In Android, the system modes are implemented as follows:

  • smBackground: Activity is in the background (i.e. not visible)
  • smOff: very low brightness (50% of brightnessStandbyMin), 'FLAG_KEEP_SCREEN_ON' is unset (Android can put device in sleep mode)
  • smStandby: low brightness, 'FLAG_KEEP_SCREEN_ON' set
  • smActive: normal brightness, 'FLAG_KEEP_SCREEN_ON' set

In all modes including 'smOff', touching the screen/keyboard or triggering a light change causes a switch to mode 'smActive'.

If the device is put in sleep mode from outside (e.g. power button), this does not have an effect on the internal system mode. In consequence, the device must manually be activated again. This, however, may be helpful, e.g. to clean the display.

In passive behaviour mode, the following simplified scheme is used: smBackground: Activity is not visible (paused) smStandby: 'FLAG_KEEP_SCREEN_ON' not set smActive: 'FLAG_KEEP_SCREEN_ON' set

The app being paused does not imply 'smBackground', but any of the other states may also apply (depending on the reason for pausing). The brightness is never controlled actively, and the mechanism to fetch the app to the foreground automatically after some time is also disabled.

enum  ESystemMode {
  smNone = -1 , smBackground = 0 , smOff , smStandby ,
  smActive
}
 System mode. More...
 
ESystemMode SystemGetMode ()
 Get the current system mode.
 
void SystemWakeupActive ()
 Wakeup into active mode (e.g. due to user interaction); Reset the standby & off timers.
 
void SystemWakeupStandby ()
 Wakeup into standby mode; Reset the off timer.
 
static void SystemWakeup ()
 Unspecific wakeup (redirects to SystemWakeupActive() ).
 
void SystemActiveLock (const char *reqName, bool withWakeup=true)
 Lock the device in active mode, e.g. during a phone call. More...
 
void SystemActiveUnlock (const char *reqName, bool withWakeup=true)
 Remove the specified active lock. More...
 
void SystemStandbyLock (const char *reqName, bool withWakeup=true)
 Lock the device in standby mode to prevent the screen to be switched off completely, e.g. during alarm clock wakeup. More...
 
void SystemStandbyUnlock (const char *reqName, bool withWakeup=true)
 Remove the specified standby lock. More...
 

General ...

static void SystemPreInit ()
 
void SystemInit ()
 
void SystemDone ()
 

Enter or return from background...

void SystemGoBackground (const char *appStr=NULL)
 Move the WallClock (Android) app into the background. More...
 
void SystemGoForeground ()
 Move the WallClock (Android) app into the foreground again.
 
static void SystemLaunchApp (const char *appStr)
 Launch an (Android) app.
 
void SystemReportUiVisibility (bool foreNotBack)
 Report background/foreground state from UI system (for 'ui_base.C').
 

Muting ...

The "mute" flag demands all "medium-priority" audio to be muted (e.g. during phone calls) and presently affects the music player. The bit has no effect on the phone, phone or door bell ringing or the alarm clock.

CResourceSystemGetMuteRc ()
 Get the "mute" resource.
 
void SystemMute (const char *reqName)
 Mute.
 
void SystemUnmute (const char *reqName)
 Unmute. More...
 
bool SystemIsMuted ()
 Query the mute state in a polling fashion.
 

Audio ...

Deprecated: The following functions are deprecated and can be removed if all phone audio is directed via SDL.

void SystemSetAudioNormal ()
 
void SystemSetAudioPhone ()
 

Bluetooth

CResourceSystemGetBluetoothRc ()
 Get readable/writable resource to indicate if bluetooth is generally on.
 
CResourceSystemGetBluetoothAudioRc ()
 Get read-only resource to indicate if BT audio (output) is available.
 
bool SystemBluetoothGetState (bool *retBusy=NULL, bool *retAudio=NULL)
 Return 'true' iff BT is currently on or switching on. More...
 
void SystemBluetoothSet (bool enable)
 Generally enable or disable Bluetooth.
 
static void SystemBluetoothToggle ()
 Toggle the Bluetooth enable status.
 

Phone State

CResourceSystemGetPhoneStateRc ()
 Get readable resource indicating the reported phone state (may be NULL, if not present).
 
void SystemReportPhoneState (ERctPhoneState _phoneState)
 Report phone state to the phone state resource.
 

Enumeration Type Documentation

◆ ESystemMode

System mode.

Enumerator
smNone 

Uninitialized; Value must not be used after initialization.

smBackground 

Application is in background (e.g. other application in focus).

smOff 

Screen is off.

smStandby 

Screen is in standby mode (not bright, but visible).

smActive 

Screen is in active mode (bright, e.g. during user interaction)

Definition at line 108 of file system.H.

Function Documentation

◆ SystemActiveLock()

void SystemActiveLock ( const char *  reqName,
bool  withWakeup = true 
)

Lock the device in active mode, e.g. during a phone call.

Parameters
reqNameis the ID of the request as visible in the resource(s).
withWakeupissues a new wakeup event to avoid a switch back to standby or "off" mode too quickly; here, the same value as for the corresponding SystemActiveUnlock() call should be passed.

◆ SystemActiveUnlock()

void SystemActiveUnlock ( const char *  reqName,
bool  withWakeup = true 
)

Remove the specified active lock.

Parameters
reqNameis the ID of the request as previously passed to SystemActiveLock().
withWakeupissues a new wakeup event to avoid a switch back to standby or "off" mode too quickly; here, the same value as for the corresponding SystemActiveUnlock() call should be passed. Examples: For an the auto-stop situation after a playlist of the music player, this should be 'true' (the default). For floorplan view on a weather alert, this should be 'false'.

◆ SystemStandbyLock()

void SystemStandbyLock ( const char *  reqName,
bool  withWakeup = true 
)

Lock the device in standby mode to prevent the screen to be switched off completely, e.g. during alarm clock wakeup.

Parameters
reqNameis the ID of the request as visible in the resource(s).
withWakeupensures the UI to stay in standby mode for some time after removing the lock; the same value as for the corresponding SystemStandbyUnlock() call should be passed here.

◆ SystemStandbyUnlock()

void SystemStandbyUnlock ( const char *  reqName,
bool  withWakeup = true 
)

Remove the specified standby lock.

Parameters
reqNameis the ID of the request as previously passed to SystemActiveLock().
withWakeupensures the UI to stay in standby mode for some time after removing the lock.

◆ SystemGoBackground()

void SystemGoBackground ( const char *  appStr = NULL)

Move the WallClock (Android) app into the background.

Parameters
appStris the other Android app to be launched. By default, the home screen is activated.

◆ SystemUnmute()

void SystemUnmute ( const char *  reqName)

Unmute.

Parameters
reqNameis the name of the request as visible in the resource(s).

◆ SystemBluetoothGetState()

bool SystemBluetoothGetState ( bool *  retBusy = NULL,
bool *  retAudio = NULL 
)

Return 'true' iff BT is currently on or switching on.

Parameters
*retBusyindicates whether BT is currently switching state.
*retAudiois true, iff an audio device is coupled ("a2dp" or "headset" profile).