Functions¶

	`app_id_parse` (appid)
	`application_info` (appid, appdir, appdesktop)
	`get_pids` (appid)
	`get_primary_pid` (appid)
	`helper_set_exec` (execline, directory)
	`list_helper_instances` (type, appid)
	`list_helpers` (type)
	`list_running_apps` ()
	`observer_add_app_failed` (observer, *user_data)
	`observer_add_app_focus` (observer, *user_data)
	`observer_add_app_paused` (observer, *user_data)
	`observer_add_app_resume` (observer, *user_data)
	`observer_add_app_resumed` (observer, *user_data)
	`observer_add_app_started` (observer, *user_data)
	`observer_add_app_starting` (observer, *user_data)
	`observer_add_app_stop` (observer, *user_data)
	`observer_add_helper_started` (observer, helper_type, *user_data)
	`observer_add_helper_stop` (observer, helper_type, *user_data)
	`observer_delete_app_failed` (observer, *user_data)
	`observer_delete_app_focus` (observer, *user_data)
	`observer_delete_app_paused` (observer, *user_data)
	`observer_delete_app_resume` (observer, *user_data)
	`observer_delete_app_resumed` (observer, *user_data)
	`observer_delete_app_started` (observer, *user_data)
	`observer_delete_app_starting` (observer, *user_data)
	`observer_delete_app_stop` (observer, *user_data)
	`observer_delete_helper_started` (observer, helper_type, *user_data)
	`observer_delete_helper_stop` (observer, helper_type, *user_data)
	`pause_application` (appid)
	`pid_in_app_id` (pid, appid)
	`resume_application` (appid)
	`start_application` (appid, uris)
	`start_application_test` (appid, uris)
	`start_helper` (type, appid, uris)
	`start_multiple_helper` (type, appid, uris)
	`stop_application` (appid)
	`stop_helper` (type, appid)
	`stop_multiple_helper` (type, appid, instanceid)
	`triplet_to_app_id` (pkg, app, version)

Details¶

LomiriAppLaunch.app_id_parse(appid)¶

Parameters:

appid (str) – Application ID to parse

Returns:

Whether appid is valid

package:: Package section of appid
application:: Application section of appid
version:: Version section of appid

Return type:

(bool, package: str, application: str, version: str)

Takes an application ID appid and breaks it into its component parts. Each of them can be None if those parts aren’t desired. If all are None it will still parse to generate a proper return value check if appid is valid.

LomiriAppLaunch.application_info(appid, appdir, appdesktop)¶

Parameters:

appid (str) – ID of the application
appdir (str or None) – Directory for the application
appdesktop (str or None) – Relative path to desktop file

Returns:

Whether appid could be found

Return type:

bool

Finds a location for information on an application and the relative directory that it was found in. So this should be used to find icons relating to that desktop file.

LomiriAppLaunch.get_pids(appid)¶

Parameters:: appid (str) – ID of the application to look for
Returns:: A list of PIDs associated with appid, empty if not running.
Return type:: [int]

Checks to see if an application is running and returns the PIDs associated with it.

LomiriAppLaunch.get_primary_pid(appid)¶

Parameters:: appid (str) – ID of the application to look for
Returns:: Either the PID of the application or 0 if it is not running.
Return type:: int

Checks to see if an application is running and returns its main PID if so.

LomiriAppLaunch.helper_set_exec(execline, directory)¶

Parameters:

execline (str) – Exec line to be executed, in Desktop file format
directory (str or None) – The directory that the exec line should be executed in.

Returns:

Whether we were able to set the exec line

Return type:

bool

A function to be called by an untrusted helper exec tool to set the exec line. The exec tool should determine what should be executed from some sort of configuration based on its type (usually a configuration file from a click package). Once it determines the exec line it can set it with this function and exit.

LomiriAppLaunch.list_helper_instances(type, appid)¶

Parameters:

type (str) – Type of helper
appid (str) – AppID of helper

Returns:

List of instance IDs

Return type:

[str]

List all the instances for a particular AppID

LomiriAppLaunch.list_helpers(type)¶

Parameters:: type (str) – Type of helper
Returns:: List of application IDs
Return type:: [str]

List all App IDs of helpers of a given type.

LomiriAppLaunch.list_running_apps()¶

Returns:: A None terminated list of application IDs. Should be free’d with GLib.strfreev().
Return type:: [str]

Gets the Application IDs of all the running applications in the system.

LomiriAppLaunch.observer_add_app_failed(observer, *user_data)¶

Parameters:

observer (LomiriAppLaunch.AppFailedObserver) – Callback when an application fails
user_data (object or None) – Data to pass to the observer

Returns:

Whether adding the observer was successful.

Return type:

bool

Sets up a callback to get called each time an application stops via failure.

LomiriAppLaunch.observer_add_app_focus(observer, *user_data)¶

Parameters:

observer (LomiriAppLaunch.AppObserver) – Callback when an application is started for the second time
user_data (object or None) – Data to pass to the observer

Returns:

Whether adding the observer was successful.

Return type:

bool

Sets up a callback to get called each time an app gets called that is already running, so we request it to be focused again.

LomiriAppLaunch.observer_add_app_paused(observer, *user_data)¶

Parameters:

observer (LomiriAppLaunch.AppPausedResumedObserver) – Callback when an application is paused
user_data (object or None) – Data to pass to the observer

Returns:

Whether adding the observer was successful.

Return type:

bool

Sets up a callback to get called each time an application is paused.

LomiriAppLaunch.observer_add_app_resume(observer, *user_data)¶

Parameters:

observer (LomiriAppLaunch.AppObserver) – Callback when an application is started and possibly asleep
user_data (object or None) – Data to pass to the observer

Returns:

Whether adding the observer was successful.

Return type:

bool

Sets up a callback to get called each time an app gets called that is already running, so we request it to be given CPU time. At the end of the observer running the app as assumed to be active.

LomiriAppLaunch.observer_add_app_resumed(observer, *user_data)¶

Parameters:

observer (LomiriAppLaunch.AppPausedResumedObserver) – Callback when an application is resumed
user_data (object or None) – Data to pass to the observer

Returns:

Whether adding the observer was successful.

Return type:

bool

Sets up a callback to get called each time an application is resumed. Which is after the SIGCONT has been sent to the pids.

LomiriAppLaunch.observer_add_app_started(observer, *user_data)¶

Parameters:

observer (LomiriAppLaunch.AppObserver) – Callback when an application started
user_data (object or None) – Data to pass to the observer

Returns:

Whether adding the observer was successful.

Return type:

bool

Sets up a callback to get called each time an application has been started.

LomiriAppLaunch.observer_add_app_starting(observer, *user_data)¶

Parameters:

observer (LomiriAppLaunch.AppObserver) – Callback when an application is about to start
user_data (object or None) – Data to pass to the observer

Returns:

Whether adding the observer was successful.

Return type:

bool

Sets up a callback to get called each time an application is about to start. The application will not start until the function returns.

LomiriAppLaunch.observer_add_app_stop(observer, *user_data)¶

Parameters:

observer (LomiriAppLaunch.AppObserver) – Callback when an application stops
user_data (object or None) – Data to pass to the observer

Returns:

Whether adding the observer was successful.

Return type:

bool

Sets up a callback to get called each time an application stops.

LomiriAppLaunch.observer_add_helper_started(observer, helper_type, *user_data)¶

Parameters:

observer (LomiriAppLaunch.HelperObserver) – Callback when a helper started
helper_type (str or None) – Type of helpers to look for
user_data (object or None) – Data to pass to the observer

Returns:

Whether adding the observer was successful.

Return type:

bool

Sets up a callback to get called each time a helper of helper_type has been started.

LomiriAppLaunch.observer_add_helper_stop(observer, helper_type, *user_data)¶

Parameters:

observer (LomiriAppLaunch.HelperObserver) – Callback when a helper stops
helper_type (str or None) – Type of helpers to look for
user_data (object or None) – Data to pass to the observer

Returns:

Whether adding the observer was successful.

Return type:

bool

Sets up a callback to get called each time a helper of helper_type stops.

LomiriAppLaunch.observer_delete_app_failed(observer, *user_data)¶

Parameters:

observer (LomiriAppLaunch.AppFailedObserver) – Callback to remove
user_data (object or None) – Data to pass to the observer

Returns:

Whether deleting the observer was successful.

Return type:

bool

Removes a previously registered callback to ensure it no longer gets signaled.

LomiriAppLaunch.observer_delete_app_focus(observer, *user_data)¶

Parameters:

observer (LomiriAppLaunch.AppObserver) – Callback to remove
user_data (object or None) – Data that was passed to the observer

Returns:

Whether deleting the observer was successful.

Return type:

bool

Removes a previously registered callback to ensure it no longer gets signaled.

Do not call this method from a different thread than the one the observer was added.

LomiriAppLaunch.observer_delete_app_paused(observer, *user_data)¶

Parameters:

observer (LomiriAppLaunch.AppPausedResumedObserver) – Callback to remove
user_data (object or None) – Data to pass to the observer

Returns:

Whether deleting the observer was successful.

Return type:

bool

Removes a previously registered callback to ensure it no longer gets signaled.

LomiriAppLaunch.observer_delete_app_resume(observer, *user_data)¶

Parameters:

observer (LomiriAppLaunch.AppObserver) – Callback to remove
user_data (object or None) – Data that was passed to the observer

Returns:

Whether deleting the observer was successful.

Return type:

bool

Removes a previously registered callback to ensure it no longer gets signaled.

Do not call this method from a different thread than the one the observer was added.

LomiriAppLaunch.observer_delete_app_resumed(observer, *user_data)¶

Parameters:

observer (LomiriAppLaunch.AppPausedResumedObserver) – Callback to remove
user_data (object or None) – Data to pass to the observer

Returns:

Whether deleting the observer was successful.

Return type:

bool

Removes a previously registered callback to ensure it no longer gets signaled.

LomiriAppLaunch.observer_delete_app_started(observer, *user_data)¶

Parameters:

observer (LomiriAppLaunch.AppObserver) – Callback to remove
user_data (object or None) – Data that was passed to the observer

Returns:

Whether deleting the observer was successful.

Return type:

bool

Removes a previously registered callback to ensure it no longer gets signaled.

LomiriAppLaunch.observer_delete_app_starting(observer, *user_data)¶

Parameters:

observer (LomiriAppLaunch.AppObserver) – Callback to remove
user_data (object or None) – Data that was passed to the observer

Returns:

Whether deleting the observer was successful.

Return type:

bool

Removes a previously registered callback to ensure it no longer gets signaled.

Do not call this method from a different thread than the one the observer was added.

LomiriAppLaunch.observer_delete_app_stop(observer, *user_data)¶

Parameters:

observer (LomiriAppLaunch.AppObserver) – Callback to remove
user_data (object or None) – Data that was passed to the observer

Returns:

Whether deleting the observer was successful.

Return type:

bool

Removes a previously registered callback to ensure it no longer gets signaled.

LomiriAppLaunch.observer_delete_helper_started(observer, helper_type, *user_data)¶

Parameters:

observer (LomiriAppLaunch.HelperObserver) – Callback to remove
helper_type (str or None) – Type of helpers it looked for
user_data (object or None) – Data that was passed to the observer

Returns:

Whether deleting the observer was successful.

Return type:

bool

Removes a previously registered callback to ensure it no longer gets signaled.

LomiriAppLaunch.observer_delete_helper_stop(observer, helper_type, *user_data)¶

Parameters:

observer (LomiriAppLaunch.HelperObserver) – Callback to remove
helper_type (str or None) – Type of helpers it looked for
user_data (object or None) – Data that was passed to the observer

Returns:

Whether deleting the observer was successful.

Return type:

bool

Removes a previously registered callback to ensure it no longer gets signaled.

LomiriAppLaunch.pause_application(appid)¶

Parameters:: appid (str) – ID of the application to pause
Returns:: Whether we were able to send SIGSTOP to all processes.
Return type:: bool

Sends SIGSTOP to all processes related to the application

LomiriAppLaunch.pid_in_app_id(pid, appid)¶

Parameters:

pid (int) – Process ID to check on
appid (str) – ID of the application to look in

Returns:

Whether pid is associated with the appid

Return type:

bool

Checks to see if a PID is associated with the current application ID.

Currently the implementation just calls LomiriAppLaunch.get_primary_pid() and checks to see if they’re the same. But in the future this will check any PID created in the cgroup to see if it is associated.

LomiriAppLaunch.resume_application(appid)¶

Parameters:: appid (str) – ID of the application to pause
Returns:: Whether we were able to send SIGCONT to all processes.
Return type:: bool

Sends SIGCONT to all processes related to the application

LomiriAppLaunch.start_application(appid, uris)¶

Parameters:

appid (str) – ID of the application to launch
uris ([str] or None) – A None terminated list of URIs to send to the application

Returns:

Whether the launch succeeded (may fail later, but upstart will report the error in that case.

Return type:

bool

Asks upstart to launch an application.

LomiriAppLaunch.start_application_test(appid, uris)¶

Parameters:

appid (str) – ID of the application to launch
uris ([str] or None) – A None terminated list of URIs to send to the application

Returns:

Whether the launch succeeded (may fail later, but upstart will report the error in that case.

Return type:

bool

Asks upstart to launch an application with environment variables set to enable testing. Should only be used in testing.

LomiriAppLaunch.start_helper(type, appid, uris)¶

Parameters:

type (str) – Type of helper
appid (str) – App ID of the helper
uris ([str] or None) – A None terminated list of URIs to send to the helper

Returns:

Whether the helper was able to be started

Return type:

bool

Start an untrusted helper for a specific type on a given appid. We don’t know how that is done specifically, as Upstart will call a helper for that type. And then execute it under the AppArmor profile for the helper as defined in its manifest.

LomiriAppLaunch.start_multiple_helper(type, appid, uris)¶

Parameters:

type (str) – Type of helper
appid (str) – App ID of the helper
uris ([str] or None) – A None terminated list of URIs to send to the helper

Returns:

The generated instance ID or None on failure

Return type:

str

Start an untrusted helper for a specific type of a given appid. We don’t know how that is done specifically, as Upstart will call a helper for that type. And then execute it under the Apparmor profile for that helper type. This function is different from lomiri_app_launch_start_helper in that it works for helpers that aren’t single instance and the manager will be managing the instances as well.

LomiriAppLaunch.stop_application(appid)¶

Parameters:: appid (str) – ID of the application to launch
Returns:: Whether we were able to ask Lomiri to stop the process, used LomiriAppLaunch.observer_add_app_stop() to know when it is finally stopped.
Return type:: bool

Asks upstart to stop an application.

LomiriAppLaunch.stop_helper(type, appid)¶

Parameters:

type (str) – Type of helper
appid (str) – App ID of the helper

Returns:

Whether the helper is stopped

Return type:

bool

Asks Upstart to kill a helper. In general, this should be a last resort as we should ask the helper a better way probably with an in-band protocol of use.

LomiriAppLaunch.stop_multiple_helper(type, appid, instanceid)¶

Parameters:

type (str) – Type of helper
appid (str) – App ID of the helper
instanceid (str) – The instance ID returned when starting the helper

Returns:

Whether the helper is stopped

Return type:

bool

Asks Upstart to kill a helper. In general, this should be a last resort as we should ask the helper a better way probably with an in-band protocol of use.

LomiriAppLaunch.triplet_to_app_id(pkg, app, version)¶

Parameters:

pkg (str) – Click package name
app (str or None) – Application name, see description
version (str or None) – Specific version or wildcard, see description

Returns:

Either the properly constructed appid or None if it failed to construct it.

Return type:

str

Constructs an appid from pkg, app, version triple. Wildcards are allowed for the app and version parameters.

For the app parameter the wildcards * “first-listed-app”, “last-listed-app” and “only-listed-app” can be used. A None value will default to the first listed app.

For the version parameter only one wildcard is allowed, “current-user-version”. If None is passed that is the default.