diff --git a/Modules/app-module/include/app/event.h b/Modules/app-module/include/app/event.h index e8dc3bb16..2cd793a2b 100644 --- a/Modules/app-module/include/app/event.h +++ b/Modules/app-module/include/app/event.h @@ -24,8 +24,8 @@ struct AppResultEventData { uint32_t launch_id; /** The child app instance's own AppMainFn/AppLoaderApi::run() return value. By convention: * 0 = Ok, 1 = Cancelled, 2 = Error. Apps that need to hand back more than this (e.g. picked - * text, a path) expose their own "get last result" getter instead - see e.g. - * tt::app::inputdialog::getLastText(). */ + * text, a path) write it to their own stdout instead, for the caller to read via an + * AppStream bound to it. See e.g. tt::app::inputdialog::start(). */ int32_t result; }; diff --git a/Modules/app-module/include/app/execute.h b/Modules/app-module/include/app/execute.h index c51787e7a..5bcf51be0 100644 --- a/Modules/app-module/include/app/execute.h +++ b/Modules/app-module/include/app/execute.h @@ -17,11 +17,9 @@ extern "C" { /** * Starts an app directly from @a location, without it having to be pre-registered via - * app_manager_add() first. Independent of the id-based app_start*() family - * (app/manager.h): performs no checks of its own beyond what AppLoaderApi::load() itself - * rejects. Not manifest lookup, and not whether @a location should be allowed to run (see - * app_is_executable() below): callers that need a check must run it themselves before calling - * this. + * app_manager_add() first. + * Performs no checks of its own beyond what AppLoaderApi::load() itself rejects. + * @warning It's advised to validate @a location with app_is_executable() first * @param[in] stack stack allocation config for the app's task; all-zero uses the scheduler's * default depth/capability, same as an AppManifest that leaves AppManifest::stack zeroed * @retval ERROR_NOT_FOUND no AppLoaderApi is registered for @a location.type @@ -36,9 +34,8 @@ error_t app_execute( ); /** - * Same as app_execute(), but as a modal child of @a parent_instance_id - see - * app_start_for_result()'s own doc for the result-delivery contract. Still no manifest - * and no check of its own beyond what AppLoaderApi::load() itself rejects. + * Same as app_execute(), but as a modal child of @a parent_instance_id. + * See app_start_for_result()'s own doc for the result-delivery contract. * @retval ERROR_NOT_FOUND no AppLoaderApi is registered for @a location.type * @retval ERROR_NONE on success */ @@ -53,7 +50,7 @@ error_t app_execute_for_result( /** * Same as app_execute(), but installs @a bindings into the new instance's fd table before its - * task begins executing - see app_start_with_streams()'s own doc for stream ownership. + * task begins executing. See app_start_with_streams()'s own doc for stream ownership. * @param[in] bindings see app_start_with_streams() * @retval ERROR_NOT_FOUND no AppLoaderApi is registered for @a location.type * @retval ERROR_OUT_OF_RANGE a binding's producer_fd is out of range @@ -90,9 +87,9 @@ error_t app_execute_for_result_with_streams( ); /** - * Reports whether @a location is runnable on this target - the extension and header a loader - * requires (e.g. an ELF's class/data/type/machine), not whether it lives anywhere in particular: - * any executable app is runnable from any path. Cheap enough to call while listing a directory. + * Reports whether @a location is runnable on this target: the extension and header a loader + * requires (e.g. an ELF's class/data/type/machine), not whether it lives anywhere in particular. + * Any executable app is runnable from any path. Cheap enough to call while listing a directory. * @return false if @a location can't be run, or if no AppLoaderApi is registered for its type */ bool app_is_executable(struct AppLocation location); diff --git a/Modules/app-module/include/app/start.h b/Modules/app-module/include/app/start.h index 3531c2665..6d5cc3b32 100644 --- a/Modules/app-module/include/app/start.h +++ b/Modules/app-module/include/app/start.h @@ -4,7 +4,7 @@ #include /** - * This file contains functions to start and run apps that were registerd to the app manager. + * This file contains functions to start and run apps that were registered to the app manager. * It differs from execute.h which runs executables from a specific path. */ @@ -13,29 +13,27 @@ extern "C" { #endif /** - * Same as app_start(), but also passes @a argc/@a argv to the new instance's own main - * function (see app/loader.h's AppMainFn) - modelled on a C program's main(argc, argv). For - * regular (non-modal) navigations that need to pass data to the target app (e.g. "show details - * for this app id") without expecting a result back. + * Starts @a id, a manifest already registered via app_manager_add(), passing @a argc/@a argv to + * the new instance's own main function (see app/loader.h's AppMainFn), modelled on a C program's + * main(argc, argv). For regular (non-modal) navigations that need to pass data to the target app + * (e.g. "show details for this app id") without expecting a result back. * @param[in] argv @a argc strings; app-module makes its own deep copy before returning, so * @a argv and the strings it points to may be freed/go out of scope immediately after this call * returns (e.g. safe to pass a stack-local array of a caller's own std::string::c_str()s). + * @retval ERROR_NOT_FOUND no manifest with this id is registered, or no AppLoaderApi is registered + * @retval ERROR_NONE on success */ error_t app_start(const char* id, int argc, const char* const argv[], AppInstanceId* out_app_instance_id); /** - * Starts @a id as a modal child of @a parent_instance_id, for the purpose of receiving a - * result. The parent keeps running (window_manager's own multi-window stack handles burying its - * window while the child is shown). + * Starts @a id as a child of @a parent_instance_id, for the purpose of receiving a result. * - * When the child's task exits, an APP_EVENT_RESULT is delivered to @a parent_instance_id - - * result is whatever the child's AppMainFn/AppLoaderApi::run() returned - unless + * When the child's task exits, an APP_EVENT_RESULT is delivered to @a parent_instance_id. + * The result is whatever the child's AppMainFn/AppLoaderApi::run() returned, unless * @a parent_instance_id is 0, in which case no result is delivered (fire-and-forget, for * callers with no app_instance_id of their own). The parent is then responsible for calling - * app_manager_stop() on the child's instance id to fully reap it. Children that need to hand - * back more than an int32_t (e.g. picked text, a path) expose their own "get last result" - * getter for the parent to call after receiving the event - see e.g. - * tt::app::inputdialog::getLastText(). + * app_manager_stop() on the child's instance id to fully reap it. + * * @param[in] argv @a argc strings; app-module makes its own deep copy before returning (same as * app_start()), so @a argv and the strings it points to may be * freed/go out of scope immediately after this call returns. @@ -62,10 +60,8 @@ error_t app_start_with_streams(const char* id, const struct AppStreamBinding* bi * Combines app_start_for_result() and app_start_with_streams(): starts @a id as * a modal child of @a parent_instance_id (see app_start_for_result()'s own doc for the * result-delivery contract) with @a bindings installed into its fd table before its task begins - * executing (see app_start_with_streams()'s own doc for stream ownership). For a child - * that needs to hand back more than an int32_t (e.g. a path) via its own stdout instead of the - * "get last result" getter pattern (see app_start_for_result()) - see e.g. - * tt::app::fileselection::startForExistingFile(). + * executing (see app_start_with_streams()'s own doc for stream ownership). + * For a child that needs to hand back more than an int32_t (e.g. a path) via its own stdout. * @param[in] argv see app_start_for_result(). * @param[in] bindings see app_start_with_streams(). * @retval ERROR_NOT_FOUND no manifest with this id is registered, or no AppLoaderApi is registered