/*
* Copyright 2013 Canonical Ltd.
*
* This program is free software: you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 3, as published
* by the Free Software Foundation.
*
* This program is distributed in the hope that it will be useful, but
* WITHOUT ANY WARRANTY; without even the implied warranties of
* MERCHANTABILITY, SATISFACTORY QUALITY, or FITNESS FOR A PARTICULAR
* PURPOSE. See the GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License along
* with this program. If not, see .
*
* Authors:
* Ted Gould
*/
#include
#include "config.h"
#ifdef LAL_USE_MIRCLIENT
#include
#endif
#ifndef __LOMIRI_APP_LAUNCH_H__
#define __LOMIRI_APP_LAUNCH_H__ 1
#pragma GCC visibility push(default)
#ifdef __cplusplus
extern "C" {
#endif
/**
* LomiriAppLaunchAppFailed:
*
* Types of failure that we report.
*/
typedef enum { /*< prefix=LOMIRI_APP_LAUNCH_APP_FAILED */
LOMIRI_APP_LAUNCH_APP_FAILED_CRASH, /*< nick=crash */
LOMIRI_APP_LAUNCH_APP_FAILED_START_FAILURE /*< nick=start-failure */
} LomiriAppLaunchAppFailed;
/**
* LomiriAppLaunchAppObserver:
*
* Function prototype for application observers.
*/
typedef void (*LomiriAppLaunchAppObserver) (const gchar * appid, gpointer user_data);
/**
* LomiriAppLaunchAppFailedObserver:
*
* Function prototype for application failed observers.
*/
typedef void (*LomiriAppLaunchAppFailedObserver) (const gchar * appid, LomiriAppLaunchAppFailed failure_type, gpointer user_data);
/**
* LomiriAppLaunchAppPausedResumedObserver:
* @appid: App ID of the application being paused
* @pids: Zero terminated array of PIDs
*
* Function prototype for application paused and resumed observers.
*/
typedef void (*LomiriAppLaunchAppPausedResumedObserver) (const gchar * appid, GPid * pids, gpointer user_data);
/**
* LomiriAppLaunchHelperObserver:
*
* Function to watch for helpers that are starting and stopping
*/
typedef void (*LomiriAppLaunchHelperObserver) (const gchar * appid, const gchar * instanceid, const gchar * helpertype, gpointer user_data);
/**
* lomiri_app_launch_start_application:
* @appid: ID of the application to launch
* @uris: (allow-none) (array zero-terminated=1) (element-type utf8) (transfer none): A NULL terminated list of URIs to send to the application
*
* Asks upstart to launch an application.
*
* Return value: Whether the launch succeeded (may fail later, but upstart
* will report the error in that case.
*/
gboolean lomiri_app_launch_start_application (const gchar * appid,
const gchar * const * uris);
/**
* lomiri_app_launch_start_application_test:
* @appid: ID of the application to launch
* @uris: (allow-none) (array zero-terminated=1) (element-type utf8) (transfer none): A NULL terminated list of URIs to send to the application
*
* Asks upstart to launch an application with environment variables set
* to enable testing. Should only be used in testing.
*
* Return value: Whether the launch succeeded (may fail later, but upstart
* will report the error in that case.
*/
gboolean lomiri_app_launch_start_application_test (const gchar * appid,
const gchar * const * uris);
/**
* lomiri_app_launch_stop_application:
* @appid: ID of the application to launch
*
* Asks upstart to stop an application.
*
* Return value: Whether we were able to ask Lomiri to stop the process,
* used lomiri_app_launch_observer_add_app_stop() to know when it is
* finally stopped.
*/
gboolean lomiri_app_launch_stop_application (const gchar * appid);
/**
* lomiri_app_launch_pause_application:
* @appid: ID of the application to pause
*
* Sends SIGSTOP to all processes related to the application
*
* Return value: Whether we were able to send SIGSTOP to all processes.
*/
gboolean lomiri_app_launch_pause_application (const gchar * appid);
/**
* lomiri_app_launch_resume_application:
* @appid: ID of the application to pause
*
* Sends SIGCONT to all processes related to the application
*
* Return value: Whether we were able to send SIGCONT to all processes.
*/
gboolean lomiri_app_launch_resume_application (const gchar * appid);
/**
* lomiri_app_launch_application_info:
* @appid: ID of the application
* @appdir: (allow-none) (transfer full): Directory for the application
* @appdesktop: (allow-none) (transfer full): Relative path to desktop file
*
* 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.
*
* Return value: Whether @appid could be found
*/
gboolean lomiri_app_launch_application_info (const gchar * appid,
gchar ** appdir,
gchar ** appdesktop);
/**
* lomiri_app_launch_observer_add_app_starting:
* @observer: (scope notified): Callback when an application is about to start
* @user_data: (closure) (allow-none): Data to pass to the observer
*
* Sets up a callback to get called each time an application
* is about to start. The application will not start until the
* function returns.
*
* Return value: Whether adding the observer was successful.
*/
gboolean lomiri_app_launch_observer_add_app_starting (LomiriAppLaunchAppObserver observer,
gpointer user_data);
/**
* lomiri_app_launch_observer_add_app_started:
* @observer: (scope notified): Callback when an application started
* @user_data: (closure) (allow-none): Data to pass to the observer
*
* Sets up a callback to get called each time an application
* has been started.
*
* Return value: Whether adding the observer was successful.
*/
gboolean lomiri_app_launch_observer_add_app_started (LomiriAppLaunchAppObserver observer,
gpointer user_data);
/**
* lomiri_app_launch_observer_add_app_stop:
* @observer: (scope notified): Callback when an application stops
* @user_data: (closure) (allow-none): Data to pass to the observer
*
* Sets up a callback to get called each time an application
* stops.
*
* Return value: Whether adding the observer was successful.
*/
gboolean lomiri_app_launch_observer_add_app_stop (LomiriAppLaunchAppObserver observer,
gpointer user_data);
/**
* lomiri_app_launch_observer_add_app_focus:
* @observer: (scope notified): Callback when an application is started for the second time
* @user_data: (closure) (allow-none): Data to pass to the observer
*
* 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.
*
* Return value: Whether adding the observer was successful.
*/
gboolean lomiri_app_launch_observer_add_app_focus (LomiriAppLaunchAppObserver observer,
gpointer user_data);
/**
* lomiri_app_launch_observer_add_app_resume:
* @observer: (scope notified): Callback when an application is started and possibly asleep
* @user_data: (closure) (allow-none): Data to pass to the observer
*
* 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.
*
* Return value: Whether adding the observer was successful.
*/
gboolean lomiri_app_launch_observer_add_app_resume (LomiriAppLaunchAppObserver observer,
gpointer user_data);
/**
* lomiri_app_launch_observer_add_app_failed:
* @observer: (scope notified): Callback when an application fails
* @user_data: (allow-none) (closure): Data to pass to the observer
*
* Sets up a callback to get called each time an application
* stops via failure.
*
* Return value: Whether adding the observer was successful.
*/
gboolean lomiri_app_launch_observer_add_app_failed (LomiriAppLaunchAppFailedObserver observer,
gpointer user_data);
/**
* lomiri_app_launch_observer_add_app_paused:
* @observer: (scope notified): Callback when an application is paused
* @user_data: (allow-none) (closure): Data to pass to the observer
*
* Sets up a callback to get called each time an application
* is paused.
*
* Return value: Whether adding the observer was successful.
*/
gboolean lomiri_app_launch_observer_add_app_paused (LomiriAppLaunchAppPausedResumedObserver observer,
gpointer user_data);
/**
* lomiri_app_launch_observer_add_app_resumed:
* @observer: (scope notified): Callback when an application is resumed
* @user_data: (allow-none) (closure): Data to pass to the observer
*
* Sets up a callback to get called each time an application
* is resumed. Which is after the SIGCONT has been sent to the pids.
*
* Return value: Whether adding the observer was successful.
*/
gboolean lomiri_app_launch_observer_add_app_resumed (LomiriAppLaunchAppPausedResumedObserver observer,
gpointer user_data);
/**
* lomiri_app_launch_observer_delete_app_starting:
* @observer: (scope notified): Callback to remove
* @user_data: (closure) (allow-none): Data that was passed to the observer
*
* 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.
*
* Return value: Whether deleting the observer was successful.
*/
gboolean lomiri_app_launch_observer_delete_app_starting (LomiriAppLaunchAppObserver observer,
gpointer user_data);
/**
* lomiri_app_launch_observer_delete_app_started:
* @observer: (scope notified): Callback to remove
* @user_data: (closure) (allow-none): Data that was passed to the observer
*
* Removes a previously registered callback to ensure it no longer
* gets signaled.
*
* Return value: Whether deleting the observer was successful.
*/
gboolean lomiri_app_launch_observer_delete_app_started (LomiriAppLaunchAppObserver observer,
gpointer user_data);
/**
* lomiri_app_launch_observer_delete_app_stop:
* @observer: (scope notified): Callback to remove
* @user_data: (closure) (allow-none): Data that was passed to the observer
*
* Removes a previously registered callback to ensure it no longer
* gets signaled.
*
* Return value: Whether deleting the observer was successful.
*/
gboolean lomiri_app_launch_observer_delete_app_stop (LomiriAppLaunchAppObserver observer,
gpointer user_data);
/**
* lomiri_app_launch_observer_delete_app_focus:
* @observer: (scope notified): Callback to remove
* @user_data: (closure) (allow-none): Data that was passed to the observer
*
* 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.
*
* Return value: Whether deleting the observer was successful.
*/
gboolean lomiri_app_launch_observer_delete_app_focus (LomiriAppLaunchAppObserver observer,
gpointer user_data);
/**
* lomiri_app_launch_observer_delete_app_resume:
* @observer: (scope notified): Callback to remove
* @user_data: (closure) (allow-none): Data that was passed to the observer
*
* 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.
*
* Return value: Whether deleting the observer was successful.
*/
gboolean lomiri_app_launch_observer_delete_app_resume (LomiriAppLaunchAppObserver observer,
gpointer user_data);
/**
* lomiri_app_launch_observer_delete_app_failed:
* @observer: (scope notified): Callback to remove
* @user_data: (closure) (allow-none): Data to pass to the observer
*
* Removes a previously registered callback to ensure it no longer
* gets signaled.
*
* Return value: Whether deleting the observer was successful.
*/
gboolean lomiri_app_launch_observer_delete_app_failed (LomiriAppLaunchAppFailedObserver observer,
gpointer user_data);
/**
* lomiri_app_launch_observer_delete_app_paused:
* @observer: (scope notified): Callback to remove
* @user_data: (closure) (allow-none): Data to pass to the observer
*
* Removes a previously registered callback to ensure it no longer
* gets signaled.
*
* Return value: Whether deleting the observer was successful.
*/
gboolean lomiri_app_launch_observer_delete_app_paused (LomiriAppLaunchAppPausedResumedObserver observer,
gpointer user_data);
/**
* lomiri_app_launch_observer_delete_app_resumed:
* @observer: (scope notified): Callback to remove
* @user_data: (closure) (allow-none): Data to pass to the observer
*
* Removes a previously registered callback to ensure it no longer
* gets signaled.
*
* Return value: Whether deleting the observer was successful.
*/
gboolean lomiri_app_launch_observer_delete_app_resumed (LomiriAppLaunchAppPausedResumedObserver observer,
gpointer user_data);
/**
* lomiri_app_launch_list_running_apps:
*
* Gets the Application IDs of all the running applications
* in the system.
*
* Return value: (transfer full): A NULL terminated list of
* application IDs. Should be free'd with g_strfreev().
*/
gchar ** lomiri_app_launch_list_running_apps (void);
/**
* lomiri_app_launch_get_primary_pid:
* @appid: ID of the application to look for
*
* Checks to see if an application is running and returns its
* main PID if so.
*
* Return Value: Either the PID of the application or 0 if it
* is not running.
*/
GPid lomiri_app_launch_get_primary_pid (const gchar * appid);
/**
* lomiri_app_launch_get_pids:
* @appid: ID of the application to look for
*
* Checks to see if an application is running and returns
* the PIDs associated with it.
*
* Return Value: (transfer full) (element-type GLib.Pid): A list
* of PIDs associated with @appid, empty if not running.
*/
GList * lomiri_app_launch_get_pids (const gchar * appid);
/**
* lomiri_app_launch_pid_in_app_id:
* @pid: Process ID to check on
* @appid: ID of the application to look in
*
* Checks to see if a PID is associated with the current application ID.
*
* Currently the implementation just calls lomiri_app_launch_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.
*
* Return Value: Whether @pid is associated with the @appid
*/
gboolean lomiri_app_launch_pid_in_app_id (GPid pid,
const gchar * appid);
/**
* lomiri_app_launch_triplet_to_app_id:
* @pkg: Click package name
* @app: (allow-none): Application name, see description
* @version: (allow-none): Specific version or wildcard, see description
*
* 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 NULL value will default to the
* first listed app.
*
* For the @version parameter only one wildcard is allowed, "current-user-version".
* If NULL is passed that is the default.
*
* Return Value: Either the properly constructed @appid or NULL if it failed
* to construct it.
*/
gchar * lomiri_app_launch_triplet_to_app_id (const gchar * pkg,
const gchar * app,
const gchar * version);
/**
* lomiri_app_launch_app_id_parse:
* @appid: Application ID to parse
* @package: (out) (transfer full) (allow-none): Package section of @appid
* @application: (out) (transfer full) (allow-none): Application section of @appid
* @version: (out) (transfer full) (allow-none): Version section of @appid
*
* Takes an application ID @appid and breaks it into its component parts. Each
* of them can be NULL if those parts aren't desired. If all are NULL it will
* still parse to generate a proper return value check if @appid is valid.
*
* Return value: Whether @appid is valid
*/
gboolean lomiri_app_launch_app_id_parse (const gchar * appid,
gchar ** package,
gchar ** application,
gchar ** version);
/**
* lomiri_app_launch_start_helper:
* @type: Type of helper
* @appid: App ID of the helper
* @uris: (allow-none) (array zero-terminated=1) (element-type utf8) (transfer none): A NULL terminated list of URIs to send to the helper
*
* 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.
*
* Return value: Whether the helper was able to be started
*/
gboolean lomiri_app_launch_start_helper (const gchar * type,
const gchar * appid,
const gchar * const * uris);
/**
* lomiri_app_launch_start_multiple_helper:
* @type: Type of helper
* @appid: App ID of the helper
* @uris: (allow-none) (array zero-terminated=1) (element-type utf8) (transfer none): A NULL terminated list of URIs to send to the helper
*
* 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.
*
* Return value: The generated instance ID or NULL on failure
*/
gchar * lomiri_app_launch_start_multiple_helper (const gchar * type,
const gchar * appid,
const gchar * const * uris);
#ifdef LAL_USE_MIRCLIENT
/**
* lomiri_app_launch_start_session_helper:
* @type: Type of helper
* @session: Mir Trusted Prompt Session to run the helper under
* @appid: App ID of the helper
* @uris: (allow-none) (array zero-terminated=1) (element-type utf8) (transfer none): A NULL terminated list of URIs to send to the helper
*
* Start an untrusted helper for a specific @type of a given
* @appid running under a Mir Trusted Prompt Session @session. The
* helper's MIR_SOCKET environment variable will be set appropriately
* so that the helper will draw on the correct surfaces. Otherwise this
* is the same as #lomiri_app_launch_start_multiple_helper.
*
* It is important that all exec tools for @type call the function
* #lomiri_app_launch_helper_set_exec to set the exec line.
*
* Return value: The generated instance ID or NULL on failure
*/
gchar * lomiri_app_launch_start_session_helper (const gchar * type,
MirPromptSession * session,
const gchar * appid,
const gchar * const * uris);
#endif
/**
* lomiri_app_launch_stop_helper:
* @type: Type of helper
* @appid: App ID of the helper
*
* 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.
*
* Return value: Whether the helper is stopped
*/
gboolean lomiri_app_launch_stop_helper (const gchar * type,
const gchar * appid);
/**
* lomiri_app_launch_stop_multiple_helper:
* @type: Type of helper
* @appid: App ID of the helper
* @instanceid: The instance ID returned when starting the helper
*
* 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.
*
* Return value: Whether the helper is stopped
*/
gboolean lomiri_app_launch_stop_multiple_helper (const gchar * type,
const gchar * appid,
const gchar * instanceid);
/**
* lomiri_app_launch_list_helpers:
* @type: Type of helper
*
* List all App IDs of helpers of a given @type.
*
* Return value: (transfer full): List of application IDs
*/
gchar ** lomiri_app_launch_list_helpers (const gchar * type);
/**
* lomiri_app_launch_list_helper_instances:
* @type: Type of helper
* @appid: AppID of helper
*
* List all the instances for a particular AppID
*
* Return value: (transfer full): List of instance IDs
*/
gchar ** lomiri_app_launch_list_helper_instances (const gchar * type,
const gchar * appid);
/**
* lomiri_app_launch_observer_add_helper_started:
* @observer: (scope notified): Callback when a helper started
* @helper_type: (closure) (allow-none): Type of helpers to look for
* @user_data: (allow-none): Data to pass to the observer
*
* Sets up a callback to get called each time a helper of
* @helper_type has been started.
*
* Return value: Whether adding the observer was successful.
*/
gboolean lomiri_app_launch_observer_add_helper_started (LomiriAppLaunchHelperObserver observer,
const gchar * helper_type,
gpointer user_data);
/**
* lomiri_app_launch_observer_add_helper_stop:
* @observer: (scope notified): Callback when a helper stops
* @helper_type: (closure) (allow-none): Type of helpers to look for
* @user_data: (allow-none): Data to pass to the observer
*
* Sets up a callback to get called each time a helper of
* @helper_type stops.
*
* Return value: Whether adding the observer was successful.
*/
gboolean lomiri_app_launch_observer_add_helper_stop (LomiriAppLaunchHelperObserver observer,
const gchar * helper_type,
gpointer user_data);
/**
* lomiri_app_launch_observer_delete_helper_started:
* @observer: (scope notified): Callback to remove
* @helper_type: (closure) (allow-none): Type of helpers it looked for
* @user_data: (allow-none): Data that was passed to the observer
*
* Removes a previously registered callback to ensure it no longer
* gets signaled.
*
* Return value: Whether deleting the observer was successful.
*/
gboolean lomiri_app_launch_observer_delete_helper_started (LomiriAppLaunchHelperObserver observer,
const gchar * helper_type,
gpointer user_data);
/**
* lomiri_app_launch_observer_delete_helper_stop:
* @observer: (scope notified): Callback to remove
* @helper_type: (closure) (allow-none): Type of helpers it looked for
* @user_data: (allow-none): Data that was passed to the observer
*
* Removes a previously registered callback to ensure it no longer
* gets signaled.
*
* Return value: Whether deleting the observer was successful.
*/
gboolean lomiri_app_launch_observer_delete_helper_stop (LomiriAppLaunchHelperObserver observer,
const gchar * helper_type,
gpointer user_data);
/**
* lomiri_app_launch_helper_set_exec:
* @execline: Exec line to be executed, in Desktop file format
* @directory: (allow-none): The directory that the exec line should
* be executed in.
*
* 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.
*
* Return Value: Whether we were able to set the exec line
*/
gboolean lomiri_app_launch_helper_set_exec (const gchar * execline,
const gchar * directory);
#ifdef __cplusplus
}
#endif
#pragma GCC visibility pop
#endif /* __LOMIRI_APP_LAUNCH_H__ */