Debian Codegraph @

liblomiri-app-launch/lomiri-app-launch.h

raw
1 /*
2 * Copyright 2013 Canonical Ltd.
3 *
4 * This program is free software: you can redistribute it and/or modify it
5 * under the terms of the GNU General Public License version 3, as published
6 * by the Free Software Foundation.
7 *
8 * This program is distributed in the hope that it will be useful, but
9 * WITHOUT ANY WARRANTY; without even the implied warranties of
10 * MERCHANTABILITY, SATISFACTORY QUALITY, or FITNESS FOR A PARTICULAR
11 * PURPOSE. See the GNU General Public License for more details.
12 *
13 * You should have received a copy of the GNU General Public License along
14 * with this program. If not, see <http://www.gnu.org/licenses/>.
15 *
16 * Authors:
17 * Ted Gould <[email protected]>
18 */
19
20 #include <glib.h>
21
22 #include "config.h"
23
24 #ifdef LAL_USE_MIRCLIENT
25 #include <mir_toolkit/mir_prompt_session.h>
26 #endif
27
28 #ifndef __LOMIRI_APP_LAUNCH_H__
29 #define __LOMIRI_APP_LAUNCH_H__ 1
30
31 #pragma GCC visibility push(default)
32
33 #ifdef __cplusplus
34 extern "C" {
35 #endif
36
37 /**
38 * LomiriAppLaunchAppFailed:
39 *
40 * Types of failure that we report.
41 */
42 typedef enum { /*< prefix=LOMIRI_APP_LAUNCH_APP_FAILED */
43 LOMIRI_APP_LAUNCH_APP_FAILED_CRASH, /*< nick=crash */
44 LOMIRI_APP_LAUNCH_APP_FAILED_START_FAILURE /*< nick=start-failure */
45 } LomiriAppLaunchAppFailed;
46
47 /**
48 * LomiriAppLaunchAppObserver:
49 *
50 * Function prototype for application observers.
51 */
52 typedef void (*LomiriAppLaunchAppObserver) (const gchar * appid, gpointer user_data);
53
54 /**
55 * LomiriAppLaunchAppFailedObserver:
56 *
57 * Function prototype for application failed observers.
58 */
59 typedef void (*LomiriAppLaunchAppFailedObserver) (const gchar * appid, LomiriAppLaunchAppFailed failure_type, gpointer user_data);
60
61 /**
62 * LomiriAppLaunchAppPausedResumedObserver:
63 * @appid: App ID of the application being paused
64 * @pids: Zero terminated array of PIDs
65 *
66 * Function prototype for application paused and resumed observers.
67 */
68 typedef void (*LomiriAppLaunchAppPausedResumedObserver) (const gchar * appid, GPid * pids, gpointer user_data);
69
70 /**
71 * LomiriAppLaunchHelperObserver:
72 *
73 * Function to watch for helpers that are starting and stopping
74 */
75 typedef void (*LomiriAppLaunchHelperObserver) (const gchar * appid, const gchar * instanceid, const gchar * helpertype, gpointer user_data);
76
77 /**
78 * lomiri_app_launch_start_application:
79 * @appid: ID of the application to launch
80 * @uris: (allow-none) (array zero-terminated=1) (element-type utf8) (transfer none): A NULL terminated list of URIs to send to the application
81 *
82 * Asks upstart to launch an application.
83 *
84 * Return value: Whether the launch succeeded (may fail later, but upstart
85 * will report the error in that case.
86 */
87 gboolean lomiri_app_launch_start_application (const gchar * appid,
88 const gchar * const * uris);
89
90 /**
91 * lomiri_app_launch_start_application_test:
92 * @appid: ID of the application to launch
93 * @uris: (allow-none) (array zero-terminated=1) (element-type utf8) (transfer none): A NULL terminated list of URIs to send to the application
94 *
95 * Asks upstart to launch an application with environment variables set
96 * to enable testing. Should only be used in testing.
97 *
98 * Return value: Whether the launch succeeded (may fail later, but upstart
99 * will report the error in that case.
100 */
101 gboolean lomiri_app_launch_start_application_test (const gchar * appid,
102 const gchar * const * uris);
103
104 /**
105 * lomiri_app_launch_stop_application:
106 * @appid: ID of the application to launch
107 *
108 * Asks upstart to stop an application.
109 *
110 * Return value: Whether we were able to ask Lomiri to stop the process,
111 * used lomiri_app_launch_observer_add_app_stop() to know when it is
112 * finally stopped.
113 */
114 gboolean lomiri_app_launch_stop_application (const gchar * appid);
115
116 /**
117 * lomiri_app_launch_pause_application:
118 * @appid: ID of the application to pause
119 *
120 * Sends SIGSTOP to all processes related to the application
121 *
122 * Return value: Whether we were able to send SIGSTOP to all processes.
123 */
124 gboolean lomiri_app_launch_pause_application (const gchar * appid);
125
126 /**
127 * lomiri_app_launch_resume_application:
128 * @appid: ID of the application to pause
129 *
130 * Sends SIGCONT to all processes related to the application
131 *
132 * Return value: Whether we were able to send SIGCONT to all processes.
133 */
134 gboolean lomiri_app_launch_resume_application (const gchar * appid);
135
136 /**
137 * lomiri_app_launch_application_info:
138 * @appid: ID of the application
139 * @appdir: (allow-none) (transfer full): Directory for the application
140 * @appdesktop: (allow-none) (transfer full): Relative path to desktop file
141 *
142 * Finds a location for information on an application and the relative
143 * directory that it was found in. So this should be used to find icons
144 * relating to that desktop file.
145 *
146 * Return value: Whether @appid could be found
147 */
148 gboolean lomiri_app_launch_application_info (const gchar * appid,
149 gchar ** appdir,
150 gchar ** appdesktop);
151
152 /**
153 * lomiri_app_launch_observer_add_app_starting:
154 * @observer: (scope notified): Callback when an application is about to start
155 * @user_data: (closure) (allow-none): Data to pass to the observer
156 *
157 * Sets up a callback to get called each time an application
158 * is about to start. The application will not start until the
159 * function returns.
160 *
161 * Return value: Whether adding the observer was successful.
162 */
163 gboolean lomiri_app_launch_observer_add_app_starting (LomiriAppLaunchAppObserver observer,
164 gpointer user_data);
165 /**
166 * lomiri_app_launch_observer_add_app_started:
167 * @observer: (scope notified): Callback when an application started
168 * @user_data: (closure) (allow-none): Data to pass to the observer
169 *
170 * Sets up a callback to get called each time an application
171 * has been started.
172 *
173 * Return value: Whether adding the observer was successful.
174 */
175 gboolean lomiri_app_launch_observer_add_app_started (LomiriAppLaunchAppObserver observer,
176 gpointer user_data);
177 /**
178 * lomiri_app_launch_observer_add_app_stop:
179 * @observer: (scope notified): Callback when an application stops
180 * @user_data: (closure) (allow-none): Data to pass to the observer
181 *
182 * Sets up a callback to get called each time an application
183 * stops.
184 *
185 * Return value: Whether adding the observer was successful.
186 */
187 gboolean lomiri_app_launch_observer_add_app_stop (LomiriAppLaunchAppObserver observer,
188 gpointer user_data);
189
190 /**
191 * lomiri_app_launch_observer_add_app_focus:
192 * @observer: (scope notified): Callback when an application is started for the second time
193 * @user_data: (closure) (allow-none): Data to pass to the observer
194 *
195 * Sets up a callback to get called each time an app gets called
196 * that is already running, so we request it to be focused again.
197 *
198 * Return value: Whether adding the observer was successful.
199 */
200 gboolean lomiri_app_launch_observer_add_app_focus (LomiriAppLaunchAppObserver observer,
201 gpointer user_data);
202
203 /**
204 * lomiri_app_launch_observer_add_app_resume:
205 * @observer: (scope notified): Callback when an application is started and possibly asleep
206 * @user_data: (closure) (allow-none): Data to pass to the observer
207 *
208 * Sets up a callback to get called each time an app gets called
209 * that is already running, so we request it to be given CPU time.
210 * At the end of the observer running the app as assumed to be active.
211 *
212 * Return value: Whether adding the observer was successful.
213 */
214 gboolean lomiri_app_launch_observer_add_app_resume (LomiriAppLaunchAppObserver observer,
215 gpointer user_data);
216
217 /**
218 * lomiri_app_launch_observer_add_app_failed:
219 * @observer: (scope notified): Callback when an application fails
220 * @user_data: (allow-none) (closure): Data to pass to the observer
221 *
222 * Sets up a callback to get called each time an application
223 * stops via failure.
224 *
225 * Return value: Whether adding the observer was successful.
226 */
227 gboolean lomiri_app_launch_observer_add_app_failed (LomiriAppLaunchAppFailedObserver observer,
228 gpointer user_data);
229
230 /**
231 * lomiri_app_launch_observer_add_app_paused:
232 * @observer: (scope notified): Callback when an application is paused
233 * @user_data: (allow-none) (closure): Data to pass to the observer
234 *
235 * Sets up a callback to get called each time an application
236 * is paused.
237 *
238 * Return value: Whether adding the observer was successful.
239 */
240 gboolean lomiri_app_launch_observer_add_app_paused (LomiriAppLaunchAppPausedResumedObserver observer,
241 gpointer user_data);
242
243 /**
244 * lomiri_app_launch_observer_add_app_resumed:
245 * @observer: (scope notified): Callback when an application is resumed
246 * @user_data: (allow-none) (closure): Data to pass to the observer
247 *
248 * Sets up a callback to get called each time an application
249 * is resumed. Which is after the SIGCONT has been sent to the pids.
250 *
251 * Return value: Whether adding the observer was successful.
252 */
253 gboolean lomiri_app_launch_observer_add_app_resumed (LomiriAppLaunchAppPausedResumedObserver observer,
254 gpointer user_data);
255
256 /**
257 * lomiri_app_launch_observer_delete_app_starting:
258 * @observer: (scope notified): Callback to remove
259 * @user_data: (closure) (allow-none): Data that was passed to the observer
260 *
261 * Removes a previously registered callback to ensure it no longer
262 * gets signaled.
263 *
264 * Do not call this method from a different thread than the one the observer
265 * was added.
266 *
267 * Return value: Whether deleting the observer was successful.
268 */
269 gboolean lomiri_app_launch_observer_delete_app_starting (LomiriAppLaunchAppObserver observer,
270 gpointer user_data);
271
272 /**
273 * lomiri_app_launch_observer_delete_app_started:
274 * @observer: (scope notified): Callback to remove
275 * @user_data: (closure) (allow-none): Data that was passed to the observer
276 *
277 * Removes a previously registered callback to ensure it no longer
278 * gets signaled.
279 *
280 * Return value: Whether deleting the observer was successful.
281 */
282 gboolean lomiri_app_launch_observer_delete_app_started (LomiriAppLaunchAppObserver observer,
283 gpointer user_data);
284 /**
285 * lomiri_app_launch_observer_delete_app_stop:
286 * @observer: (scope notified): Callback to remove
287 * @user_data: (closure) (allow-none): Data that was passed to the observer
288 *
289 * Removes a previously registered callback to ensure it no longer
290 * gets signaled.
291 *
292 * Return value: Whether deleting the observer was successful.
293 */
294 gboolean lomiri_app_launch_observer_delete_app_stop (LomiriAppLaunchAppObserver observer,
295 gpointer user_data);
296
297 /**
298 * lomiri_app_launch_observer_delete_app_focus:
299 * @observer: (scope notified): Callback to remove
300 * @user_data: (closure) (allow-none): Data that was passed to the observer
301 *
302 * Removes a previously registered callback to ensure it no longer
303 * gets signaled.
304 *
305 * Do not call this method from a different thread than the one the observer
306 * was added.
307 *
308 * Return value: Whether deleting the observer was successful.
309 */
310 gboolean lomiri_app_launch_observer_delete_app_focus (LomiriAppLaunchAppObserver observer,
311 gpointer user_data);
312
313 /**
314 * lomiri_app_launch_observer_delete_app_resume:
315 * @observer: (scope notified): Callback to remove
316 * @user_data: (closure) (allow-none): Data that was passed to the observer
317 *
318 * Removes a previously registered callback to ensure it no longer
319 * gets signaled.
320 *
321 * Do not call this method from a different thread than the one the observer
322 * was added.
323 *
324 * Return value: Whether deleting the observer was successful.
325 */
326 gboolean lomiri_app_launch_observer_delete_app_resume (LomiriAppLaunchAppObserver observer,
327 gpointer user_data);
328
329 /**
330 * lomiri_app_launch_observer_delete_app_failed:
331 * @observer: (scope notified): Callback to remove
332 * @user_data: (closure) (allow-none): Data to pass to the observer
333 *
334 * Removes a previously registered callback to ensure it no longer
335 * gets signaled.
336 *
337 * Return value: Whether deleting the observer was successful.
338 */
339 gboolean lomiri_app_launch_observer_delete_app_failed (LomiriAppLaunchAppFailedObserver observer,
340 gpointer user_data);
341
342 /**
343 * lomiri_app_launch_observer_delete_app_paused:
344 * @observer: (scope notified): Callback to remove
345 * @user_data: (closure) (allow-none): Data to pass to the observer
346 *
347 * Removes a previously registered callback to ensure it no longer
348 * gets signaled.
349 *
350 * Return value: Whether deleting the observer was successful.
351 */
352 gboolean lomiri_app_launch_observer_delete_app_paused (LomiriAppLaunchAppPausedResumedObserver observer,
353 gpointer user_data);
354
355 /**
356 * lomiri_app_launch_observer_delete_app_resumed:
357 * @observer: (scope notified): Callback to remove
358 * @user_data: (closure) (allow-none): Data to pass to the observer
359 *
360 * Removes a previously registered callback to ensure it no longer
361 * gets signaled.
362 *
363 * Return value: Whether deleting the observer was successful.
364 */
365 gboolean lomiri_app_launch_observer_delete_app_resumed (LomiriAppLaunchAppPausedResumedObserver observer,
366 gpointer user_data);
367
368 /**
369 * lomiri_app_launch_list_running_apps:
370 *
371 * Gets the Application IDs of all the running applications
372 * in the system.
373 *
374 * Return value: (transfer full): A NULL terminated list of
375 * application IDs. Should be free'd with g_strfreev().
376 */
377 gchar ** lomiri_app_launch_list_running_apps (void);
378
379 /**
380 * lomiri_app_launch_get_primary_pid:
381 * @appid: ID of the application to look for
382 *
383 * Checks to see if an application is running and returns its
384 * main PID if so.
385 *
386 * Return Value: Either the PID of the application or 0 if it
387 * is not running.
388 */
389 GPid lomiri_app_launch_get_primary_pid (const gchar * appid);
390
391 /**
392 * lomiri_app_launch_get_pids:
393 * @appid: ID of the application to look for
394 *
395 * Checks to see if an application is running and returns
396 * the PIDs associated with it.
397 *
398 * Return Value: (transfer full) (element-type GLib.Pid): A list
399 * of PIDs associated with @appid, empty if not running.
400 */
401 GList * lomiri_app_launch_get_pids (const gchar * appid);
402
403 /**
404 * lomiri_app_launch_pid_in_app_id:
405 * @pid: Process ID to check on
406 * @appid: ID of the application to look in
407 *
408 * Checks to see if a PID is associated with the current application ID.
409 *
410 * Currently the implementation just calls lomiri_app_launch_get_primary_pid()
411 * and checks to see if they're the same. But in the future this will check
412 * any PID created in the cgroup to see if it is associated.
413 *
414 * Return Value: Whether @pid is associated with the @appid
415 */
416 gboolean lomiri_app_launch_pid_in_app_id (GPid pid,
417 const gchar * appid);
418
419 /**
420 * lomiri_app_launch_triplet_to_app_id:
421 * @pkg: Click package name
422 * @app: (allow-none): Application name, see description
423 * @version: (allow-none): Specific version or wildcard, see description
424 *
425 * Constructs an appid from pkg, app, version triple. Wildcards are allowed
426 * for the @app and @version parameters.
427 *
428 * For the @app parameter the wildcards * "first-listed-app", "last-listed-app"
429 * and "only-listed-app" can be used. A NULL value will default to the
430 * first listed app.
431 *
432 * For the @version parameter only one wildcard is allowed, "current-user-version".
433 * If NULL is passed that is the default.
434 *
435 * Return Value: Either the properly constructed @appid or NULL if it failed
436 * to construct it.
437 */
438 gchar * lomiri_app_launch_triplet_to_app_id (const gchar * pkg,
439 const gchar * app,
440 const gchar * version);
441
442 /**
443 * lomiri_app_launch_app_id_parse:
444 * @appid: Application ID to parse
445 * @package: (out) (transfer full) (allow-none): Package section of @appid
446 * @application: (out) (transfer full) (allow-none): Application section of @appid
447 * @version: (out) (transfer full) (allow-none): Version section of @appid
448 *
449 * Takes an application ID @appid and breaks it into its component parts. Each
450 * of them can be NULL if those parts aren't desired. If all are NULL it will
451 * still parse to generate a proper return value check if @appid is valid.
452 *
453 * Return value: Whether @appid is valid
454 */
455 gboolean lomiri_app_launch_app_id_parse (const gchar * appid,
456 gchar ** package,
457 gchar ** application,
458 gchar ** version);
459
460 /**
461 * lomiri_app_launch_start_helper:
462 * @type: Type of helper
463 * @appid: App ID of the helper
464 * @uris: (allow-none) (array zero-terminated=1) (element-type utf8) (transfer none): A NULL terminated list of URIs to send to the helper
465 *
466 * Start an untrusted helper for a specific @type on a given
467 * @appid. We don't know how that is done specifically, as Upstart
468 * will call a helper for that type. And then execute it under the
469 * AppArmor profile for the helper as defined in its manifest.
470 *
471 * Return value: Whether the helper was able to be started
472 */
473 gboolean lomiri_app_launch_start_helper (const gchar * type,
474 const gchar * appid,
475 const gchar * const * uris);
476
477 /**
478 * lomiri_app_launch_start_multiple_helper:
479 * @type: Type of helper
480 * @appid: App ID of the helper
481 * @uris: (allow-none) (array zero-terminated=1) (element-type utf8) (transfer none): A NULL terminated list of URIs to send to the helper
482 *
483 * Start an untrusted helper for a specific @type of a given
484 * @appid. We don't know how that is done specifically, as Upstart
485 * will call a helper for that type. And then execute it under the
486 * Apparmor profile for that helper type. This function is different
487 * from @lomiri_app_launch_start_helper in that it works for helpers
488 * that aren't single instance and the manager will be managing the
489 * instances as well.
490 *
491 * Return value: The generated instance ID or NULL on failure
492 */
493 gchar * lomiri_app_launch_start_multiple_helper (const gchar * type,
494 const gchar * appid,
495 const gchar * const * uris);
496
497 #ifdef LAL_USE_MIRCLIENT
498 /**
499 * lomiri_app_launch_start_session_helper:
500 * @type: Type of helper
501 * @session: Mir Trusted Prompt Session to run the helper under
502 * @appid: App ID of the helper
503 * @uris: (allow-none) (array zero-terminated=1) (element-type utf8) (transfer none): A NULL terminated list of URIs to send to the helper
504 *
505 * Start an untrusted helper for a specific @type of a given
506 * @appid running under a Mir Trusted Prompt Session @session. The
507 * helper's MIR_SOCKET environment variable will be set appropriately
508 * so that the helper will draw on the correct surfaces. Otherwise this
509 * is the same as #lomiri_app_launch_start_multiple_helper.
510 *
511 * It is important that all exec tools for @type call the function
512 * #lomiri_app_launch_helper_set_exec to set the exec line.
513 *
514 * Return value: The generated instance ID or NULL on failure
515 */
516 gchar * lomiri_app_launch_start_session_helper (const gchar * type,
517 MirPromptSession * session,
518 const gchar * appid,
519 const gchar * const * uris);
520 #endif
521
522 /**
523 * lomiri_app_launch_stop_helper:
524 * @type: Type of helper
525 * @appid: App ID of the helper
526 *
527 * Asks Upstart to kill a helper. In general, this should be a last resort
528 * as we should ask the helper a better way probably with an in-band protocol
529 * of use.
530 *
531 * Return value: Whether the helper is stopped
532 */
533 gboolean lomiri_app_launch_stop_helper (const gchar * type,
534 const gchar * appid);
535
536 /**
537 * lomiri_app_launch_stop_multiple_helper:
538 * @type: Type of helper
539 * @appid: App ID of the helper
540 * @instanceid: The instance ID returned when starting the helper
541 *
542 * Asks Upstart to kill a helper. In general, this should be a last resort
543 * as we should ask the helper a better way probably with an in-band protocol
544 * of use.
545 *
546 * Return value: Whether the helper is stopped
547 */
548 gboolean lomiri_app_launch_stop_multiple_helper (const gchar * type,
549 const gchar * appid,
550 const gchar * instanceid);
551
552 /**
553 * lomiri_app_launch_list_helpers:
554 * @type: Type of helper
555 *
556 * List all App IDs of helpers of a given @type.
557 *
558 * Return value: (transfer full): List of application IDs
559 */
560 gchar ** lomiri_app_launch_list_helpers (const gchar * type);
561
562 /**
563 * lomiri_app_launch_list_helper_instances:
564 * @type: Type of helper
565 * @appid: AppID of helper
566 *
567 * List all the instances for a particular AppID
568 *
569 * Return value: (transfer full): List of instance IDs
570 */
571 gchar ** lomiri_app_launch_list_helper_instances (const gchar * type,
572 const gchar * appid);
573
574
575 /**
576 * lomiri_app_launch_observer_add_helper_started:
577 * @observer: (scope notified): Callback when a helper started
578 * @helper_type: (closure) (allow-none): Type of helpers to look for
579 * @user_data: (allow-none): Data to pass to the observer
580 *
581 * Sets up a callback to get called each time a helper of
582 * @helper_type has been started.
583 *
584 * Return value: Whether adding the observer was successful.
585 */
586 gboolean lomiri_app_launch_observer_add_helper_started (LomiriAppLaunchHelperObserver observer,
587 const gchar * helper_type,
588 gpointer user_data);
589 /**
590 * lomiri_app_launch_observer_add_helper_stop:
591 * @observer: (scope notified): Callback when a helper stops
592 * @helper_type: (closure) (allow-none): Type of helpers to look for
593 * @user_data: (allow-none): Data to pass to the observer
594 *
595 * Sets up a callback to get called each time a helper of
596 * @helper_type stops.
597 *
598 * Return value: Whether adding the observer was successful.
599 */
600 gboolean lomiri_app_launch_observer_add_helper_stop (LomiriAppLaunchHelperObserver observer,
601 const gchar * helper_type,
602 gpointer user_data);
603 /**
604 * lomiri_app_launch_observer_delete_helper_started:
605 * @observer: (scope notified): Callback to remove
606 * @helper_type: (closure) (allow-none): Type of helpers it looked for
607 * @user_data: (allow-none): Data that was passed to the observer
608 *
609 * Removes a previously registered callback to ensure it no longer
610 * gets signaled.
611 *
612 * Return value: Whether deleting the observer was successful.
613 */
614 gboolean lomiri_app_launch_observer_delete_helper_started (LomiriAppLaunchHelperObserver observer,
615 const gchar * helper_type,
616 gpointer user_data);
617 /**
618 * lomiri_app_launch_observer_delete_helper_stop:
619 * @observer: (scope notified): Callback to remove
620 * @helper_type: (closure) (allow-none): Type of helpers it looked for
621 * @user_data: (allow-none): Data that was passed to the observer
622 *
623 * Removes a previously registered callback to ensure it no longer
624 * gets signaled.
625 *
626 * Return value: Whether deleting the observer was successful.
627 */
628 gboolean lomiri_app_launch_observer_delete_helper_stop (LomiriAppLaunchHelperObserver observer,
629 const gchar * helper_type,
630 gpointer user_data);
631
632 /**
633 * lomiri_app_launch_helper_set_exec:
634 * @execline: Exec line to be executed, in Desktop file format
635 * @directory: (allow-none): The directory that the exec line should
636 * be executed in.
637 *
638 * A function to be called by an untrusted helper exec
639 * tool to set the exec line. The exec tool should determine
640 * what should be executed from some sort of configuration
641 * based on its type (usually a configuration file from a click
642 * package). Once it determines the exec line it can set it
643 * with this function and exit.
644 *
645 * Return Value: Whether we were able to set the exec line
646 */
647 gboolean lomiri_app_launch_helper_set_exec (const gchar * execline,
648 const gchar * directory);
649
650 #ifdef __cplusplus
651 }
652 #endif
653
654 #pragma GCC visibility pop
655
656 #endif /* __LOMIRI_APP_LAUNCH_H__ */