The Platform API is about target states and services. More...

Files
file	sol-platform-linux-micro.h
	These routines are used for Soletta platform Linux micro interaction.

file	sol-platform-linux.h
	These routines are used for Soletta platform Linux interaction.

Macros
#define	SOL_PLATFORM_TARGET_DEFAULT "default"
	Default target string. More...

#define	SOL_PLATFORM_TARGET_EMERGENCY "emergency"
	Emergency target string. More...

#define	SOL_PLATFORM_TARGET_POWER_OFF "poweroff"
	Power-off target string. More...

#define	SOL_PLATFORM_TARGET_REBOOT "reboot"
	Reboot target string. More...

#define	SOL_PLATFORM_TARGET_RESCUE "rescue"
	Rescue target string. More...

#define	SOL_PLATFORM_TARGET_SUSPEND "suspend"
	Suspend target string. More...

Enumerations
enum	sol_platform_locale_category { SOL_PLATFORM_LOCALE_LANGUAGE, SOL_PLATFORM_LOCALE_ADDRESS, SOL_PLATFORM_LOCALE_COLLATE, SOL_PLATFORM_LOCALE_CTYPE, SOL_PLATFORM_LOCALE_IDENTIFICATION, SOL_PLATFORM_LOCALE_MEASUREMENT, SOL_PLATFORM_LOCALE_MESSAGES, SOL_PLATFORM_LOCALE_MONETARY, SOL_PLATFORM_LOCALE_NAME, SOL_PLATFORM_LOCALE_NUMERIC, SOL_PLATFORM_LOCALE_PAPER, SOL_PLATFORM_LOCALE_TELEPHONE, SOL_PLATFORM_LOCALE_TIME, SOL_PLATFORM_LOCALE_UNKNOWN = -1 }
	A locale category. More...

enum	sol_platform_service_state { SOL_PLATFORM_SERVICE_STATE_ACTIVE, SOL_PLATFORM_SERVICE_STATE_RELOADING, SOL_PLATFORM_SERVICE_STATE_INACTIVE, SOL_PLATFORM_SERVICE_STATE_FAILED, SOL_PLATFORM_SERVICE_STATE_ACTIVATING, SOL_PLATFORM_SERVICE_STATE_DEACTIVATING, SOL_PLATFORM_SERVICE_STATE_UNKNOWN = -1 }
	List of service states. More...

enum	sol_platform_state { SOL_PLATFORM_STATE_INITIALIZING, SOL_PLATFORM_STATE_RUNNING, SOL_PLATFORM_STATE_DEGRADED, SOL_PLATFORM_STATE_MAINTENANCE, SOL_PLATFORM_STATE_STOPPING, SOL_PLATFORM_STATE_UNKNOWN = -1 }
	List of platform states. More...

Functions
int	sol_platform_add_hostname_monitor (void(cb)(void data, const char hostname), const void data)
	Adds a hostname monitor. More...

int	sol_platform_add_locale_monitor (void(cb)(void data, enum sol_platform_locale_category category, const char locale), const void data)
	Add a locale monitor. More...

int	sol_platform_add_service_monitor (void(cb)(void data, const char service, enum sol_platform_service_state state), const char service, const void *data)
	Adds a service monitor. More...

int	sol_platform_add_state_monitor (void(cb)(void data, enum sol_platform_state state), const void *data)
	Adds a state monitor. More...

int	sol_platform_add_system_clock_monitor (void(cb)(void data, int64_t timestamp), const void *data)
	Add a callback to monitor system clock changes. More...

int	sol_platform_add_timezone_monitor (void(cb)(void data, const char timezone), const void data)
	Add a timezone monitor. More...

int	sol_platform_apply_locale (enum sol_platform_locale_category category)
	Apply the locale category to the process. More...

int	sol_platform_del_hostname_monitor (void(cb)(void data, const char hostname), const void data)
	Remove a hostname monitor. More...

int	sol_platform_del_locale_monitor (void(cb)(void data, enum sol_platform_locale_category category, const char locale), const void data)
	Remove a locale monitor. More...

int	sol_platform_del_service_monitor (void(cb)(void data, const char service, enum sol_platform_service_state state), const char service, const void *data)
	Removes a service monitor. More...

int	sol_platform_del_state_monitor (void(cb)(void data, enum sol_platform_state state), const void *data)
	Removes a state monitor. More...

int	sol_platform_del_system_clock_monitor (void(cb)(void data, int64_t timestamp), const void *data)
	Delete a register system_clock monitor. More...

int	sol_platform_del_timezone_monitor (void(cb)(void data, const char timezone), const void data)
	Remove a timezone monitor. More...

struct sol_str_slice	sol_platform_get_appname (void)
	Get current app name. More...

const char *	sol_platform_get_board_name (void)
	Retrieves the name of the board on which Soletta is running. More...

const char *	sol_platform_get_hostname (void)
	Gets the hostname. More...

const char *	sol_platform_get_locale (enum sol_platform_locale_category category)
	Get the current locale of a given category. More...

const char *	sol_platform_get_machine_id (void)
	Retrieves the machine-id present in the file system as a string. More...

const uint8_t *	sol_platform_get_machine_id_as_bytes (void)
	Retrieves the machine-id present in the file system as a byte array. More...

int	sol_platform_get_mount_points (struct sol_ptr_vector *vector)
	List mount points mounted by us on hotplug events. More...

const char *	sol_platform_get_os_version (void)
	Retrieves the operating system's version that Soletta is running on top of. More...

const char *	sol_platform_get_serial_number (void)
	Retrieves, in number, the platform's main board serial number/identifier. More...

enum sol_platform_service_state	sol_platform_get_service_state (const char *service)
	Retrieves the state of a given service. More...

int	sol_platform_get_state (void)
	Retrieves the current platform state. More...

const char *	sol_platform_get_sw_version (void)
	Retrieves the version of Soletta that is running. More...

int64_t	sol_platform_get_system_clock (void)
	Get the current system time. More...

const char *	sol_platform_get_timezone (void)
	Get the current timezone. More...

int	sol_platform_restart_service (const char *service)
	Restarts a given service. More...

int	sol_platform_set_hostname (const char *name)
	Changes the hostname to `name`. More...

int	sol_platform_set_locale (enum sol_platform_locale_category category, const char *locale)
	Set locale for a category. More...

int	sol_platform_set_system_clock (int64_t timestamp)
	Set the system wide time. More...

int	sol_platform_set_target (const char *target)
	Set the platform target. More...

int	sol_platform_set_timezone (const char *tzone)
	Set the system timezone. More...

int	sol_platform_start_service (const char *service)
	Starts a given service. More...

int	sol_platform_stop_service (const char *service)
	Stops a given service. More...

int	sol_platform_unmount (const char mpoint, void(cb)(void data, const char mpoint, int error), const void *data)
	Umount a `mpoint`. More...

Detailed Description

The Platform API is about target states and services.

It is specially useful when Soletta is used in a PID 1 process.

Macro Definition Documentation

#define SOL_PLATFORM_TARGET_DEFAULT "default"

Default target string.

#define SOL_PLATFORM_TARGET_EMERGENCY "emergency"

Emergency target string.

#define SOL_PLATFORM_TARGET_POWER_OFF "poweroff"

Power-off target string.

#define SOL_PLATFORM_TARGET_REBOOT "reboot"

Reboot target string.

#define SOL_PLATFORM_TARGET_RESCUE "rescue"

Rescue target string.

#define SOL_PLATFORM_TARGET_SUSPEND "suspend"

Suspend target string.

Enumeration Type Documentation

enum sol_platform_locale_category

A locale category.

Enumerator
SOL_PLATFORM_LOCALE_LANGUAGE
SOL_PLATFORM_LOCALE_ADDRESS
SOL_PLATFORM_LOCALE_COLLATE
SOL_PLATFORM_LOCALE_CTYPE
SOL_PLATFORM_LOCALE_IDENTIFICATION
SOL_PLATFORM_LOCALE_MEASUREMENT
SOL_PLATFORM_LOCALE_MESSAGES
SOL_PLATFORM_LOCALE_MONETARY
SOL_PLATFORM_LOCALE_NAME
SOL_PLATFORM_LOCALE_NUMERIC
SOL_PLATFORM_LOCALE_PAPER
SOL_PLATFORM_LOCALE_TELEPHONE
SOL_PLATFORM_LOCALE_TIME
SOL_PLATFORM_LOCALE_UNKNOWN

enum sol_platform_service_state

List of service states.

Enumerator
SOL_PLATFORM_SERVICE_STATE_ACTIVE	Active.
SOL_PLATFORM_SERVICE_STATE_RELOADING	Reloading.
SOL_PLATFORM_SERVICE_STATE_INACTIVE	Inactive.
SOL_PLATFORM_SERVICE_STATE_FAILED	Failed.
SOL_PLATFORM_SERVICE_STATE_ACTIVATING	Activating.
SOL_PLATFORM_SERVICE_STATE_DEACTIVATING	Deactivating.
SOL_PLATFORM_SERVICE_STATE_UNKNOWN	Unknown.

enum sol_platform_state

List of platform states.

Enumerator
SOL_PLATFORM_STATE_INITIALIZING	Initializing.
SOL_PLATFORM_STATE_RUNNING	Running.
SOL_PLATFORM_STATE_DEGRADED	Degraded.
SOL_PLATFORM_STATE_MAINTENANCE	Maintenance.
SOL_PLATFORM_STATE_STOPPING	Stopping.
SOL_PLATFORM_STATE_UNKNOWN	Unknown.

Function Documentation

int sol_platform_add_hostname_monitor	(	void()(void data, const char *hostname)	cb,
		const void *	data
	)

Adds a hostname monitor.

If the hostname changes cb will be called.

Parameters

cb	The callback that will inform the new hostname.
data	The data to the callback.

Returns: 0 on success, negative errno otherwise.

See Also: sol_platform_del_hostname_monitor()

int sol_platform_add_locale_monitor	(	void()(void data, enum sol_platform_locale_category category, const char *locale)	cb,
		const void *	data
	)

Add a locale monitor.

Parameters

cb	A callback to be called when the locale changes
data	The data to `cb`

Returns: 0 on success, negative errno otherwise.

Note: If an error happens while the locale is being monitored the cb will be called and category will be set to SOL_PLATFORM_SERVICE_STATE_UNKNOWN and locale to NULL.

int sol_platform_add_service_monitor	(	void()(void data, const char *service, enum sol_platform_service_state state)	cb,
		const char *	service,
		const void *	data
	)

Adds a service monitor.

service will be monitored and whenever it's state changes, cb will be called receiving the new state and the provided data.

Parameters

cb	Callback
service	Service name
data	Callback data

Returns: 0 on success, error code (always negative) otherwise.

Examples:: /src/samples/common/linux-micro-init.c, and /src/samples/common/platform-simple.c.

Referenced by on_timeout_cmd(), and startup().

int sol_platform_add_state_monitor	(	void()(void data, enum sol_platform_state state)	cb,
		const void *	data
	)

Adds a state monitor.

Whenever the platform state changes, cb is called receiving the new state and data.

Parameters

cb	Callback
data	Callback data

Returns: 0 on success, error code (always negative) otherwise.

Examples:: /src/samples/common/linux-micro-init.c, and /src/samples/common/platform-simple.c.

Referenced by main(), and startup().

int sol_platform_add_system_clock_monitor	(	void()(void data, int64_t timestamp)	cb,
		const void *	data
	)

Add a callback to monitor system clock changes.

Parameters

cb	A callback to be called when the system clock changes
data	The data to `cb`

Returns: 0 on success, negative errno otherwise

Note: The registered callback will not be called every second (a.k.a: this is not a timer!), it will only be called if the system clock is adjusted. If one needs a timer use sol_timeout_add()

See Also: sol_platform_del_system_clock_monitor()

int sol_platform_add_timezone_monitor	(	void()(void data, const char *timezone)	cb,
		const void *	data
	)

Add a timezone monitor.

Parameters

cb	A callback to be called when the timezone changes
data	The data to `cb`

Returns: 0 on success, negative errno otherwise

int sol_platform_apply_locale ( enum sol_platform_locale_category category )

Apply the locale category to the process.

This function sets the current locale of the given category to the process, in order to set a new locale value to a category use sol_platform_set_locale().

Parameters

category The category to set the process locale

Returns: 0 on success, negative errno otherwise

See Also: sol_platform_set_locale()

int sol_platform_del_hostname_monitor	(	void()(void data, const char *hostname)	cb,
		const void *	data
	)

Remove a hostname monitor.

Parameters

cb	The registered callback.
data	The data to the callback.

Returns: 0 on success, negative errno otherwise.

See Also: sol_platform_add_hostname_monitor()

int sol_platform_del_locale_monitor	(	void()(void data, enum sol_platform_locale_category category, const char *locale)	cb,
		const void *	data
	)

Remove a locale monitor.

Parameters

cb	The previous registered callback
data	The data to `cb`

Returns: 0 on success, negative errno otherwise

int sol_platform_del_service_monitor	(	void()(void data, const char *service, enum sol_platform_service_state state)	cb,
		const char *	service,
		const void *	data
	)

Removes a service monitor.

Parameters

cb	Callback to be removed
service	Service name from which `cb` should be removed
data	Callback data

Returns: 0 on success, error code (always negative) otherwise.

Examples:: /src/samples/common/linux-micro-init.c, and /src/samples/common/platform-simple.c.

Referenced by on_timeout_cmd(), and shutdown().

int sol_platform_del_state_monitor	(	void()(void data, enum sol_platform_state state)	cb,
		const void *	data
	)

Removes a state monitor.

Parameters

cb	Callback to be removed
data	Callback data

Returns: 0 on success, error code (always negative) otherwise.

Examples:: /src/samples/common/linux-micro-init.c, and /src/samples/common/platform-simple.c.

Referenced by main(), and shutdown().

int sol_platform_del_system_clock_monitor	(	void()(void data, int64_t timestamp)	cb,
		const void *	data
	)

Delete a register system_clock monitor.

Parameters

cb	The previous registered callback
data	The data to `cb`

Returns: 0 on success, negative errno otherwise

See Also: sol_platform_add_system_clock_monitor()

int sol_platform_del_timezone_monitor	(	void()(void data, const char *timezone)	cb,
		const void *	data
	)

Remove a timezone monitor.

Parameters

cb	The previous registered callback
data	The data to `cb`

Returns: 0 on success, negative errno otherwise

struct sol_str_slice sol_platform_get_appname ( void )

Get current app name.

Generate current app name from sol_argv[0]. If argv is not set, app name will be soletta.

Returns: The current app name.

const char* sol_platform_get_board_name ( void )

Retrieves the name of the board on which Soletta is running.

Returns: String containing the board name on success, NULL otherwise.

Note: : Check the Board Detection documentation for more information about how the name is found.

const char* sol_platform_get_hostname ( void )

Gets the hostname.

Returns: The hostname or NULL on error.

See Also: sol_platform_set_hostname()

const char* sol_platform_get_locale ( enum sol_platform_locale_category category )

Get the current locale of a given category.

Parameters

category The category which one wants to know the locale

Returns: The locale value on success, NULL otherwise

See Also: sol_platform_set_locale()

const char* sol_platform_get_machine_id ( void )

Retrieves the machine-id present in the file system as a string.

The returned string is assured to be a valid null terminated string with the 16 bytes-long (128 bits) UUID encoded as hexadecimal ASCII characters.

Note: : If the environment variable SOL_MACHINE_ID is set and is properly formatted as a UUID string, its value is returned by this call.

Returns: On success, it returns the machine id string, that must not be modified. On error, it returns NULL.

const uint8_t* sol_platform_get_machine_id_as_bytes ( void )

Retrieves the machine-id present in the file system as a byte array.

The returned byte array is assured to be a 16 bytes-long (128 bits) array with the machine UUID.

Note: : If the environment variable SOL_MACHINE_ID is set and is properly formatted as a UUID byte array, its value is returned by this call.

Returns: On success, it returns the machine id as a byte array, that must not be modified. On error, it returns NULL.

int sol_platform_get_mount_points ( struct sol_ptr_vector * vector )

List mount points mounted by us on hotplug events.

Parameters

vector Initialized sol_vector used to store the resulting list

Returns: 0 on success, negative errno otherwise

const char* sol_platform_get_os_version ( void )

Retrieves the operating system's version that Soletta is running on top of.

Returns: On success, it returns the version string. This string should not be freed after usage. On error, it returns NULL.

const char* sol_platform_get_serial_number ( void )

Retrieves, in number, the platform's main board serial number/identifier.

Note: : If the environment variable SOL_SERIAL_NUMBER is set, its value is returned by this call.

Returns: On success, it returns the serial number string, that must not be modified. On error, it returns NULL.

enum sol_platform_service_state sol_platform_get_service_state ( const char * service )

Retrieves the state of a given service.

Parameters

service Service to be queried

Returns: Service state

See Also: enum sol_platform_service_state

Examples:: /src/samples/common/linux-micro-init.c.

Referenced by startup().

int sol_platform_get_state ( void )

Retrieves the current platform state.

Returns: Platform current state

See Also: enum sol_platform_state

Examples:: /src/samples/common/linux-micro-init.c, and /src/samples/common/platform-simple.c.

Referenced by main(), and startup().

const char* sol_platform_get_sw_version ( void )

Retrieves the version of Soletta that is running.

Returns: On success, it returns the version string, that must not be modified. On error, it returns NULL.

int64_t sol_platform_get_system_clock ( void )

Get the current system time.

Returns: the system time on success, negative errno on error

Note: The returned value is the number of seconds since 1970-01-01 00:00:00 +0000 (UTC)

See Also: sol_platform_set_system_clock()

const char* sol_platform_get_timezone ( void )

Get the current timezone.

Returns: The timezone or NULL on error

See Also: sol_platform_set_timezone()

int sol_platform_restart_service ( const char * service )

Restarts a given service.

Parameters

service Service name

Returns: 0 on success, error code (always negative) otherwise.

Examples:: /src/samples/common/platform-simple.c.

Referenced by on_timeout_cmd().

int sol_platform_set_hostname ( const char * name )

Changes the hostname to name.

Parameters

name	The new hostname.

Returns: 0 on success, negative errno otherwise.

See Also: sol_platform_get_hostname()

int sol_platform_set_locale	(	enum sol_platform_locale_category	category,
		const char *	locale
	)

Set locale for a category.

This function will change the system wide locale for a given category. The already running proceses might not be aware that the locale has changed.

Parameters

category	The category to set the new locale
locale	The locale string (Example: en_US.UTF-8)

Returns: 0 on success, negative errno on error

Note: This function only saves the new locale category in the disk, in order to use it in the current process, one must call sol_platform_apply_locale() after using sol_platform_set_locale()