From: Kazumasa Mitsunari Date: Wed, 13 Jun 2018 02:41:05 +0000 (+0900) Subject: Add description X-Git-Url: https://gerrit.automotivelinux.org/gerrit/gitweb?a=commitdiff_plain;h=6e2872d06857fdb6ecc76064cb80930e9a2635e4;p=apps%2Fagl-service-windowmanager.git Add description Change-Id: I48162088e865aa4ade9e7ca09c0ea01e43addea1 Signed-off-by: Kazumasa Mitsunari --- diff --git a/src/applist.cpp b/src/applist.cpp index 365c485..4e0dc11 100644 --- a/src/applist.cpp +++ b/src/applist.cpp @@ -28,6 +28,14 @@ namespace wm const static int kReserveClientSize = 100; const static int kReserveReqSize = 10; +/** + * AppList Constructor. + * + * Reserve the container size to avoid re-allocating memory. + * + * @note Size should be changed according to the system. + * If the number of applications becomes over the size, re-allocating memory will happen. + */ AppList::AppList() : req_list(), app2client(), @@ -39,14 +47,24 @@ AppList::AppList() AppList::~AppList() {} -void AppList::addClient(const string &appid, const string &role) -{ - std::lock_guard lock(mtx); - shared_ptr client = std::make_shared(appid, role); - this->app2client[appid] = client; - this->clientDump(); -} +// =================== Client Date container API =================== +/** + * Add Client to the list + * + * Add Client to the list. + * The Client means application which has role, layer, surface + * This function should be called once for the app. + * Caller should take care not to be called more than once. + * + * @param string[in] Application id. This will be the key to withdraw the information. + * @param unsigned[in] Layer ID in which the application is + * @param unsigned[in] surface ID which the application has + * @param string[in] Role which means what behavior the application will do. + * @return None + * @attention This function should be called once for the app + * Caller should take care not to be called more than once. + */ void AppList::addClient(const std::string &appid, unsigned layer, unsigned surface, const std::string &role) { std::lock_guard lock(mtx); @@ -55,6 +73,11 @@ void AppList::addClient(const std::string &appid, unsigned layer, unsigned surfa this->clientDump(); } +/** + * Remove WMClient from the list + * + * @param string[in] Application id. This will be the key to withdraw the information. + */ void AppList::removeClient(const string &appid) { std::lock_guard lock(mtx); @@ -62,6 +85,12 @@ void AppList::removeClient(const string &appid) HMI_INFO("wm", "Remove client %s", appid.c_str()); } +/** + * Check this class stores the appid. + * + * @param string[in] Application id. This will be the key to withdraw the information. + * @return true if the class has the requested key(appid) + */ bool AppList::contains(const string &appid) const { auto result = this->app2client.find(appid); @@ -84,26 +113,64 @@ void AppList::removeSurface(unsigned surface_id){ } /** - * @brief get WMClient object. Before call this function, must call "contains" + * Get WMClient object. + * + * After get the WMClient object, caller can call the client method. + * Before call this function, caller must call "contains" * to check the key is contained, otherwise, you have to take care of std::out_of_range. - * @param string[in] application id(key) - * @return WMClient object + * + * @param string[in] application id(key) + * @return WMClient object + * @attention Must call cantains to check appid is stored before this function. */ shared_ptr AppList::lookUpClient(const string &appid) { return this->app2client.at(appid); } +/** + * Count Client. + * + * Returns the number of client stored in the list. + * + * @param string[in] application id(key) + * @return WMClient object + * @attention Must call cantains to check appid is stored before this function. + */ int AppList::countClient() const { return this->app2client.size(); } +// =================== Request Date container API =================== + +/** + * Get current request number + * + * Request number is the numeric ID to designate the request. + * But returned request number from this function doesn't mean the request exists. + * This number is used as key to withdraw the WMRequest object. + * + * @param None + * @return current request number. + * @note request number is more than 0. + */ unsigned AppList::currentRequestNumber() const { return this->current_req; } +/** + * Get request number + * + * Request number is the numeric ID to designate the request. + * But returned request number from this function doesn't mean the request exists. + * This number is used as key to withdraw the WMRequest object. + * + * @param None + * @return request number. + * @attention If returned value is 0, no request exists. + */ unsigned AppList::getRequestNumber(const string &appid) const { for (const auto &x : this->req_list) @@ -117,6 +184,18 @@ unsigned AppList::getRequestNumber(const string &appid) const return 0; } +/** + * Add Request + * + * Request number is the numeric ID to designate the request. + * But returned request number from this function doesn't mean the request exists. + * This number is used as key to withdraw the WMRequest object. + * + * @param WMRequest[in] WMRequest object caller creates + * @return Request number + * @attention If the request number is different with curent request number, + * it means the previous request is not finished. + */ unsigned AppList::addAllocateRequest(WMRequest req) { std::lock_guard lock(mtx); @@ -133,6 +212,19 @@ unsigned AppList::addAllocateRequest(WMRequest req) return req.req_num; } +/** + * Get trigger which the application requests + * + * WMTrigger contains which application requests what role and where to put(area) and task. + * This is used for input event to Window Policy Manager(state machine). + * + * @param unsigned[in] request number + * @param bool[in,out] Check request number of the parameter is valid. + * @return WMTrigger which associates with the request number + * @attention If the request number is not valid, parameter "found" is false + * and return value will be meaningless value. + * Caller can check the request parameter is valid. + */ struct WMTrigger AppList::getRequest(unsigned req_num, bool *found) { *found = false; @@ -148,6 +240,20 @@ struct WMTrigger AppList::getRequest(unsigned req_num, bool *found) return WMTrigger{"", "", "", Task::TASK_INVALID}; } +/** + * Get actions which the application requests + * + * WMAciton contains the information of state transition. + * In other words, it contains actions of Window Manager, + * which role should be put to the area. + * + * @param unsigned[in] request number + * @param bool[in,out] Check request number of the parameter is valid. + * @return WMTrigger which associates with the request number + * @attention If the request number is not valid, parameter "found" is false + * and return value will be no reference pointer. + * Caller must check the request parameter is valid. + */ const vector &AppList::getActions(unsigned req_num, bool* found) { *found = false; @@ -162,6 +268,18 @@ const vector &AppList::getActions(unsigned req_num, bool* found HMI_SEQ_ERROR(req_num, "Couldn't get action with the request : %d", req_num); } +/** + * Set actions to the request. + * + * Add actions to the request. + * This function can be called many times, and actions increase. + * This function is used for decision of actions of Window Manager + * according to the result of Window Policy Manager. + * + * @param unsigned[in] request number + * @param WMAction[in] Action of Window Manager. + * @return WMError If request number is not valid, FAIL will be returned. + */ WMError AppList::setAction(unsigned req_num, const struct WMAction &action) { std::lock_guard lock(mtx); @@ -181,15 +299,32 @@ WMError AppList::setAction(unsigned req_num, const struct WMAction &action) /** * Note: - * This function set action with parameters. - * if visible is true, it means app should be visible, so enddraw_finished parameter should be false. - * otherwise (visible is false) app should be invisible. Then enddraw_finished param is set to true. - * This function doesn't support actions for focus yet. + * @note This function set action with parameters. + * If visible is true, it means app should be visible, so enddraw_finished parameter should be false. + * otherwise (visible is false) app should be invisible. Then enddraw_finished param is set to true. + * This function doesn't support actions for focus yet. + */ +/** + * Set actions to the request. + * + * This function is overload function. + * The feature is same as other one. + * + * @param unsigned[in] request number + * @param string[in] application id + * @param string[in] role + * @param string[in] area + * @param bool[in] the role should be visible or not. + * @return WMError If request number is not valid, FAIL will be returned. + * @attention This function set action with parameters, then caller doesn't need to create WMAction object. + * If visible is true, it means app should be visible, so enddraw_finished parameter will be false. + * otherwise (visible is false) app should be invisible. Then enddraw_finished param is set to true. + * This function doesn't support actions for focus yet. */ WMError AppList::setAction(unsigned req_num, const string &appid, const string &role, const string &area, bool visible) { std::lock_guard lock(mtx); - WMError result = WMError::NOT_REGISTERED; + WMError result = WMError::FAIL; for (auto &x : req_list) { if (req_num != x.req_num) @@ -207,9 +342,17 @@ WMError AppList::setAction(unsigned req_num, const string &appid, const string & } /** + * Set end_draw_finished param is true + * * This function checks - * * req_num is equal to current request number - * * appid and role are equeal to the appid and role stored in action list(sync_draw_req) + * - req_num is equal to current request number + * - appid and role are equeal to the appid and role stored in action list + * If it is valid, set the action is finished. + * + * @param unsigned[in] request number + * @param string[in] application id + * @param string[in] role + * @return If the parameters are not valid in action list, returns false */ bool AppList::setEndDrawFinished(unsigned req_num, const string &appid, const string &role) { @@ -238,8 +381,9 @@ bool AppList::setEndDrawFinished(unsigned req_num, const string &appid, const st } /** - * @brief check all actions of the requested sequence is finished - * @param unsigned request_number + * Check all actions of the requested sequence is finished + * + * @param unsigned[in] request_number * @return true if all action is set. */ bool AppList::endDrawFullfilled(unsigned req_num) @@ -267,6 +411,13 @@ bool AppList::endDrawFullfilled(unsigned req_num) return result; } +/** + * Finish the request, then remove it. + * + * @param unsigned[in] request_number + * @return None + * @note Please call next after this function to receive or process next request. + */ void AppList::removeRequest(unsigned req_num) { std::lock_guard lock(mtx); @@ -276,6 +427,12 @@ void AppList::removeRequest(unsigned req_num) })); } +/** + * Move the current request to next + * + * @param None + * @return None + */ void AppList::next() { std::lock_guard lock(mtx); @@ -286,6 +443,12 @@ void AppList::next() } } +/** + * Check the request exists is in request list + * + * @param None + * @return true if WMRequest exists in the request list + */ bool AppList::haveRequest() const { return !this->req_list.empty(); diff --git a/src/applist.hpp b/src/applist.hpp index c0cc298..59f37ba 100644 --- a/src/applist.hpp +++ b/src/applist.hpp @@ -39,7 +39,9 @@ class AppList AppList(const AppList &obj) = delete; // Client Database Interface - void addClient(const std::string &appid, const std::string &role); + /* TODO: consider, which is better WMClient as parameter? + If the WMClient should be more flexible, I think this param should be WMClient class + */ void addClient(const std::string &appid, unsigned layer, unsigned surface, const std::string &role); void removeClient(const std::string &appid); bool contains(const std::string &appid) const; @@ -51,9 +53,6 @@ class AppList unsigned currentRequestNumber() const; unsigned getRequestNumber(const std::string &appid) const; unsigned addAllocateRequest(WMRequest req); - /* TODO: consider, which is better WMClient or std::string appid? - if appid is key to manage resources, it is better to select std::string - otherwise WMClient is better, IMO */ WMError setAction(unsigned req_num, const struct WMAction &action); WMError setAction(unsigned req_num, const std::string &appid, const std::string &role, const std::string &area, bool visible = true); bool setEndDrawFinished(unsigned req_num, const std::string &appid, const std::string &role);