From 4d7063d9db0075533f6531c89f18c99d62aff49c Mon Sep 17 00:00:00 2001 From: AKalinich-Luxoft Date: Wed, 30 Aug 2017 13:53:20 +0300 Subject: Added/updated description in PolicyManager and UsageStatistics classes for policy external --- .../policy/policy_external/policy/policy_manager.h | 143 ++-- .../policy/usage_statistics/statistics_manager.h | 25 + .../include/policy/policy_manager_impl.h | 792 +++++++++++++++++---- 3 files changed, 773 insertions(+), 187 deletions(-) diff --git a/src/components/include/policy/policy_external/policy/policy_manager.h b/src/components/include/policy/policy_external/policy/policy_manager.h index 335e9e9425..adf195e3a9 100644 --- a/src/components/include/policy/policy_external/policy/policy_manager.h +++ b/src/components/include/policy/policy_external/policy/policy_manager.h @@ -59,12 +59,17 @@ class PolicyManager : public usage_statistics::StatisticsManager { enum NotificationMode { kSilentMode, kNotifyApplicationMode }; virtual ~PolicyManager() {} + /** + * @brief set_listener set new policy listener instance + * @param listener new policy listener + */ virtual void set_listener(PolicyListener* listener) = 0; /** - * Inits Policy Table - * @param file_name Path to preloaded PT file - * @return true if successfully + * @brief Inits Policy Table + * @param file_name path to preloaded PT file + * @param settings pointer to policy init settings + * @return true if init is successful */ virtual bool InitPT(const std::string& file_name, const PolicySettings* settings) = 0; @@ -75,26 +80,30 @@ class PolicyManager : public usage_statistics::StatisticsManager { * sent in snapshot and received Policy Table. * @param file name of file with update policy table * @param pt_content PTU as binary string - * @return bool Success of operation + * @return true if successfully */ virtual bool LoadPT(const std::string& file, const BinaryMessage& pt_content) = 0; /** - * Resets Policy Table + * @brief Resets Policy Table * @param file_name Path to preloaded PT file * @return true if successfully */ virtual bool ResetPT(const std::string& file_name) = 0; + /** + * @brief Gets last URL for sending PTS to from PT itself + * @param service_type Service specifies user of URL + * @return last URL or empty string if endpoint entry is empty + */ virtual std::string GetUpdateUrl(int service_type) = 0; /** - * @brief Gets all URLs for sending PTS to from PT itself. - * @param service_type Service specifies user of URL - * @return vector of urls - */ - + * @brief Gets all URLs for sending PTS to from PT itself. + * @param service_type Service specifies user of URL + * @return vector of urls + */ virtual void GetUpdateUrls(const uint32_t service_type, EndpointUrls& out_end_points) = 0; virtual void GetUpdateUrls(const std::string& service_type, @@ -102,7 +111,6 @@ class PolicyManager : public usage_statistics::StatisticsManager { /** * @brief GetLockScreenIcon allows to obtain lock screen icon url; - * * @return url which point to the resourse where lock screen icon could be *obtained. */ @@ -120,6 +128,7 @@ class PolicyManager : public usage_statistics::StatisticsManager { * @param app_id Id of application provided during registration * @param hmi_level Current HMI Level of application * @param rpc Name of RPC + * @param rpc_params List of RPC params * @param CheckPermissionResult containing flag if HMI Level is allowed * and list of allowed params. */ @@ -142,41 +151,43 @@ class PolicyManager : public usage_statistics::StatisticsManager { virtual std::string GetPolicyTableStatus() const = 0; /** - * Checks is PT exceeded kilometers + * @brief Checks is PT exceeded kilometers * @param kilometers current kilometers at odometer * @return true if exceeded */ virtual void KmsChanged(int kilometers) = 0; /** - * Increments counter of ignition cycles + * @brief Increments counter of ignition cycles */ virtual void IncrementIgnitionCycles() = 0; /** * @brief Exchange by hmi or mobile request + * @return Current status of policy table */ virtual std::string ForcePTExchange() = 0; /** - * @brief ExchangeByUserRequest + * @brief Exchange by user request + * @return Current status of policy table */ virtual std::string ForcePTExchangeAtUserRequest() = 0; /** - * Resets retry sequence + * @brief Resets retry sequence */ virtual void ResetRetrySequence() = 0; /** - * Gets timeout to wait before next retry updating PT + * @brief Gets timeout to wait before next retry updating PT * If timeout is less or equal to zero then the retry sequence is not need. * @return timeout in seconds */ virtual int NextRetryTimeout() = 0; /** - * Gets timeout to wait until receive response + * @brief Gets timeout to wait until receive response * @return timeout in seconds */ virtual uint32_t TimeoutExchangeMSec() = 0; @@ -189,7 +200,7 @@ class PolicyManager : public usage_statistics::StatisticsManager { virtual const std::vector RetrySequenceDelaysSeconds() = 0; /** - * Handler of exceeding timeout of exchanging policy table + * @brief Handler of exceeding timeout of exchanging policy table */ virtual void OnExceededTimeout() = 0; @@ -228,21 +239,24 @@ class PolicyManager : public usage_statistics::StatisticsManager { /** * @brief Update Application Policies as reaction * on User allowing/disallowing device this app is running on. + * @param app_id Unique application id + * @param is_device_allowed true if user allowing device otherwise false + * @return true if operation was successful */ virtual bool ReactOnUserDevConsentForApp(const std::string& app_id, const bool is_device_allowed) = 0; /** - * Sets counter value that passed for receiving PT UPdate. + * @brief Sets counter value that passed for receiving PT UPdate. */ virtual void PTUpdatedAt(Counters counter, int value) = 0; /** * @brief Retrieves data from app_policies about app on its registration: - * @param app_id - id of registered app - * @param app_types Section on HMI where app can appear (Navigation, Phone - * etc) + * @param application_id - id of registered app * @param nicknames Synonyms for application + * @param app_hmi_types Section on HMI where app can appear (Navigation, Phone + * etc) */ virtual bool GetInitialAppData(const std::string& application_id, StringArray* nicknames = NULL, @@ -271,6 +285,7 @@ class PolicyManager : public usage_statistics::StatisticsManager { * The permissions is not const reference because it may contains * valid data as well as invalid. So we will remove all invalid data * from this structure. + * @param mode notification mode */ virtual void SetUserConsentForApp(const PermissionConsent& permissions, const NotificationMode mode) = 0; @@ -298,6 +313,7 @@ class PolicyManager : public usage_statistics::StatisticsManager { * @brief Get user friendly messages for given RPC messages and language * @param message_codes RPC message codes * @param language Language + * @param active_hmi_language Currently active language * @return Array of structs with appropriate message parameters */ virtual std::vector GetUserFriendlyMessages( @@ -306,7 +322,7 @@ class PolicyManager : public usage_statistics::StatisticsManager { const std::string& active_hmi_language) = 0; /** - * Checks if the application is revoked + * @brief Checks if the application is revoked * @param app_id application id * @return true if application is revoked */ @@ -333,11 +349,15 @@ class PolicyManager : public usage_statistics::StatisticsManager { virtual AppPermissions GetAppPermissionsChanges( const std::string& policy_app_id) = 0; + /** + * @brief Removes specific application permissions changes + * @param app_id Unique application id + */ virtual void RemovePendingPermissionChanges(const std::string& app_id) = 0; /** * @brief Return device id, which hosts specific application - * @param Application id, which is required to update device id + * @param policy_app_id Application id, which is required to update device id */ virtual std::string& GetCurrentDeviceId( const std::string& policy_app_id) const = 0; @@ -360,13 +380,13 @@ class PolicyManager : public usage_statistics::StatisticsManager { /** * @brief Send OnPermissionsUpdated for choosen application - * @param application_id + * @param application_id Unique application id */ virtual void SendNotificationOnPermissionsUpdated( const std::string& application_id) = 0; /** - * Marks device as upaired + * @brief Marks device as upaired * @param device_id id device */ virtual void MarkUnpairedDevice(const std::string& device_id) = 0; @@ -374,7 +394,8 @@ class PolicyManager : public usage_statistics::StatisticsManager { /** * @brief Adds, application to the db or update existed one * run PTU if policy update is necessary for application. - * @param Application id assigned by Ford to the application + * @param application_id Unique application id + * @param hmi_types application HMI types * @return function that will notify update manager about new application */ virtual StatusNotifier AddApplication( @@ -383,18 +404,21 @@ class PolicyManager : public usage_statistics::StatisticsManager { /** * @brief Removes unpaired device records and related records from DB - * @param device_ids List of device_id, which should be removed * @return true, if succedeed, otherwise - false */ virtual bool CleanupUnpairedDevices() = 0; /** * @brief Check if app can keep context. + * @param app_id Unique application id + * @return true if app can keep context, otherwise - false */ virtual bool CanAppKeepContext(const std::string& app_id) const = 0; /** * @brief Check if app can steal focus. + * @param app_id Unique application id + * @return true if app can steal focus, otherwise - false */ virtual bool CanAppStealFocus(const std::string& app_id) const = 0; @@ -406,9 +430,9 @@ class PolicyManager : public usage_statistics::StatisticsManager { virtual void OnSystemReady() = 0; /** - * @brief GetNotificationNumber - * @param priority - * @return + * @brief Get number of notification by priority + * @param priority Specified priority + * @return notification number */ virtual uint32_t GetNotificationsNumber( const std::string& priority) const = 0; @@ -427,7 +451,7 @@ class PolicyManager : public usage_statistics::StatisticsManager { virtual bool IsPredataPolicy(const std::string& policy_app_id) const = 0; /** - * Returns heart beat timeout + * @brief Returns heart beat timeout * @param app_id application id * @return if timeout was set then value in milliseconds greater zero * otherwise heart beat for specific application isn't set @@ -435,7 +459,8 @@ class PolicyManager : public usage_statistics::StatisticsManager { virtual uint32_t HeartBeatTimeout(const std::string& app_id) const = 0; /** - * @brief SaveUpdateStatusRequired alows to save update status. + * @brief SaveUpdateStatusRequired allows to save update status. + * @param is_update_needed true if update needed */ virtual void SaveUpdateStatusRequired(bool is_update_needed) = 0; @@ -446,14 +471,14 @@ class PolicyManager : public usage_statistics::StatisticsManager { /** * @brief Handler on applications search completed + * @param trigger_ptu contains true if PTU should be triggered */ virtual void OnAppsSearchCompleted(const bool trigger_ptu) = 0; /** * @brief OnAppRegisteredOnMobile allows to handle event when application were * succesfully registered on mobile device. - * It will send OnAppPermissionSend notification and will try to start PTU. - * + * It will send OnAppPermissionSend notification and will try to start PTU. * * @param application_id registered application. */ virtual void OnAppRegisteredOnMobile(const std::string& application_id) = 0; @@ -461,13 +486,14 @@ class PolicyManager : public usage_statistics::StatisticsManager { /** * @brief Gets request types for application * @param policy_app_id Unique application id - * @return request_types Request types of application + * @return request types of application */ virtual const std::vector GetAppRequestTypes( const std::string policy_app_id) const = 0; /** * @brief Get information about vehicle + * @return vehicle information */ virtual const VehicleInfo GetVehicleInfo() const = 0; @@ -480,7 +506,6 @@ class PolicyManager : public usage_statistics::StatisticsManager { /** * @brief RetrieveCertificate Allows to obtain certificate in order * to start secure connection. - * * @return The certificate in PKCS#7 format. */ virtual std::string RetrieveCertificate() const = 0; @@ -488,7 +513,6 @@ class PolicyManager : public usage_statistics::StatisticsManager { /** * @brief HasCertificate check whether policy table has certificate * int module_config section. - * * @return true in case certificate exists, false otherwise */ virtual bool HasCertificate() const = 0; @@ -499,6 +523,10 @@ class PolicyManager : public usage_statistics::StatisticsManager { */ virtual void SetDecryptedCertificate(const std::string& certificate) = 0; + /** + * @brief Getter for policy settings + * @return policy settings instance + */ virtual const PolicySettings& get_settings() const = 0; /** @@ -510,10 +538,15 @@ class PolicyManager : public usage_statistics::StatisticsManager { virtual AppIdURL GetNextUpdateUrl(const EndpointUrls& urls) = 0; #ifdef SDL_REMOTE_CONTROL + /** + * @brief Assigns new HMI types for specified application + * @param application_id Unique application id + * @param hmi_types new HMI types list + */ virtual void SetDefaultHmiTypes(const std::string& application_id, const std::vector& hmi_types) = 0; /** - * Gets HMI types + * @brief Gets HMI types * @param application_id ID application * @param app_types list to save HMI types * @return true if policy has specific policy for this application @@ -522,15 +555,15 @@ class PolicyManager : public usage_statistics::StatisticsManager { std::vector* app_types) = 0; /** - * Checks if module for application is present in policy table + * @brief Checks if module for application is present in policy table * @param app_id id of application * @param module type * @return true if module is present, otherwise - false */ virtual bool CheckModule(const PTString& app_id, const PTString& module) = 0; - /* - * Send OnPermissionsChange notification to mobile app + /** + * @brief Send OnPermissionsChange notification to mobile app * when it's permissions are changed. * @param device_id Device on which app is running * @param application_id ID of app whose permissions are changed @@ -539,14 +572,18 @@ class PolicyManager : public usage_statistics::StatisticsManager { const std::string& application_id) = 0; /** - * Gets all allowed module types - * @param app_id unique identifier of application - * @param list of allowed module types + * @brief Gets all allowed module types + * @param policy_app_id unique identifier of application + * @param modules list of allowed module types * @return true if application has allowed modules */ virtual bool GetModuleTypes(const std::string& policy_app_id, std::vector* modules) const = 0; + /** + * @brief Setter for access_remote instance + * @param access_remote pointer to new access_remote instance + */ virtual void set_access_remote( utils::SharedPtr access_remote) = 0; #endif // SDL_REMOTE_CONTROL @@ -564,11 +601,11 @@ class PolicyManager : public usage_statistics::StatisticsManager { const EndpointUrls& urls) const = 0; /** - * @brief Checks, if SDL needs to update it's policy table "external consent - * status" section - * @param status ExternalConsent status - * @return true if there's such a need, otherwise - false - */ + * @brief Checks, if SDL needs to update it's policy table section + "external_consent_status" + * @param ExternalConsent status + * @return true if such check is needed, false - if not. + */ virtual bool IsNeedToUpdateExternalConsentStatus( const ExternalConsentStatus& status) const = 0; @@ -582,19 +619,19 @@ class PolicyManager : public usage_statistics::StatisticsManager { /** * @brief Gets customer connectivity settings status - * @return external consent status + * @return ExternalConsent status */ virtual ExternalConsentStatus GetExternalConsentStatus() = 0; protected: /** - * Checks is PT exceeded IgnitionCycles + * @brief Checks is PT exceeded IgnitionCycles * @return true if exceeded */ virtual bool ExceededIgnitionCycles() = 0; /** - * Checks is PT exceeded days + * @brief Checks is PT exceeded days * @return true if exceeded */ virtual bool ExceededDays() = 0; diff --git a/src/components/include/policy/policy_external/policy/usage_statistics/statistics_manager.h b/src/components/include/policy/policy_external/policy/usage_statistics/statistics_manager.h index dac553b547..7186400ff4 100644 --- a/src/components/include/policy/policy_external/policy/usage_statistics/statistics_manager.h +++ b/src/components/include/policy/policy_external/policy/usage_statistics/statistics_manager.h @@ -71,11 +71,36 @@ enum AppCounterId { class StatisticsManager { public: virtual ~StatisticsManager() {} + + /** + * @brief Increments global counter + * @param type counter type + */ virtual void Increment(GlobalCounterId type) = 0; + + /** + * @brief Increments specified application counter + * @param app_id Unique ID of application + * @param type application counter type + */ virtual void Increment(const std::string& app_id, AppCounterId type) = 0; + + /** + * @brief Sets specified application info value + * @param app_id Unique ID of application + * @param type application info type + * @param value new value for counter + */ virtual void Set(const std::string& app_id, AppInfoId type, const std::string& value) = 0; + + /** + * @brief Add seconds for specified application stopwatch + * @param app_id Unique ID of application + * @param type application stopwatch type + * @param timespan_seconds seconds to add + */ virtual void Add(const std::string& app_id, AppStopwatchId type, int32_t timespan_seconds) = 0; diff --git a/src/components/policy/policy_external/include/policy/policy_manager_impl.h b/src/components/policy/policy_external/include/policy/policy_manager_impl.h index 6e8c86103e..00cccb4c24 100644 --- a/src/components/policy/policy_external/include/policy/policy_manager_impl.h +++ b/src/components/policy/policy_external/include/policy/policy_manager_impl.h @@ -57,190 +57,557 @@ class PolicyManagerImpl : public PolicyManager { public: PolicyManagerImpl(); explicit PolicyManagerImpl(bool in_memory); - virtual void set_listener(PolicyListener* listener); + + /** + * @brief set_listener set new policy listener instance + * @param listener new policy listener + */ + void set_listener(PolicyListener* listener) OVERRIDE; + + /** + * @brief listener get current policy listener instance + * @return current policy listener + */ PolicyListener* listener() const { return listener_; } - virtual bool InitPT(const std::string& file_name, - const PolicySettings* settings); - virtual bool LoadPT(const std::string& file, const BinaryMessage& pt_content); - virtual bool ResetPT(const std::string& file_name); - - virtual std::string GetUpdateUrl(int service_type); - virtual void GetUpdateUrls(const uint32_t service_type, - EndpointUrls& out_end_points); - virtual void GetUpdateUrls(const std::string& service_type, - EndpointUrls& out_end_points); - virtual void RequestPTUpdate(); - virtual void CheckPermissions(const PTString& app_id, - const PTString& hmi_level, - const PTString& rpc, - const RPCParams& rpc_params, - CheckPermissionResult& result); - virtual bool ResetUserConsent(); - virtual void KmsChanged(int kilometers); - virtual void IncrementIgnitionCycles(); - virtual std::string ForcePTExchange(); - virtual std::string ForcePTExchangeAtUserRequest(); - virtual std::string GetPolicyTableStatus() const; - virtual void ResetRetrySequence(); - virtual int NextRetryTimeout(); - virtual uint32_t TimeoutExchangeMSec(); - virtual const std::vector RetrySequenceDelaysSeconds(); - virtual void OnExceededTimeout(); - virtual std::string GetLockScreenIconUrl() const OVERRIDE; - virtual void OnUpdateStarted(); - virtual void PTUpdatedAt(Counters counter, int value); - - /** - * Refresh data about retry sequence from policy table + + /** + * @brief Inits Policy Table + * @param file_name path to preloaded PT file + * @param settings pointer to policy init settings + * @return true if init is successful + */ + bool InitPT(const std::string& file_name, + const PolicySettings* settings) OVERRIDE; + + /** + * @brief Updates Policy Table from binary message received from + * mobile device. Saves to Policy Table diff between Policy Table + * sent in snapshot and received Policy Table. + * @param file name of file with update policy table + * @param pt_content PTU as binary string + * @return true if successfully + */ + bool LoadPT(const std::string& file, + const BinaryMessage& pt_content) OVERRIDE; + + /** + * @brief Resets Policy Table + * @param file_name Path to preloaded PT file + * @return true if successfully + */ + bool ResetPT(const std::string& file_name) OVERRIDE; + + /** + * @brief Gets last URL for sending PTS to from PT itself + * @param service_type Service specifies user of URL + * @return last URL or empty string if endpoint entry is empty + */ + std::string GetUpdateUrl(int service_type) OVERRIDE; + + /** + * @brief Gets all URLs for sending PTS to from PT itself. + * @param service_type Service specifies user of URL + * @param out_end_points output vector of urls + */ + void GetUpdateUrls(const uint32_t service_type, + EndpointUrls& out_end_points) OVERRIDE; + void GetUpdateUrls(const std::string& service_type, + EndpointUrls& out_end_points) OVERRIDE; + + /** + * @brief PTU is needed, for this PTS has to be formed and sent. + */ + void RequestPTUpdate() OVERRIDE; + + /** + * @brief Check if specified RPC for specified application + * has permission to be executed in specified HMI Level + * and also its permitted params. + * @param app_id Id of application provided during registration + * @param hmi_level Current HMI Level of application + * @param rpc Name of RPC + * @param rpc_params List of RPC params + * @param result containing flag if HMI Level is allowed + * and list of allowed params. + */ + void CheckPermissions(const PTString& app_id, + const PTString& hmi_level, + const PTString& rpc, + const RPCParams& rpc_params, + CheckPermissionResult& result) OVERRIDE; + + /** + * @brief Clear all record of user consents. Used during Factory Reset. + * @return bool Success of operation + */ + bool ResetUserConsent() OVERRIDE; + + /** + * @brief Checks is PT exceeded kilometers + * @param kilometers current kilometers at odometer + * @return true if exceeded + */ + void KmsChanged(int kilometers) OVERRIDE; + + /** + * @brief Increments counter of ignition cycles + */ + void IncrementIgnitionCycles() OVERRIDE; + + /** + * @brief Exchange by hmi or mobile request + * @return Current status of policy table + */ + std::string ForcePTExchange() OVERRIDE; + + /** + * @brief Exchange by user request + * @return Current status of policy table + */ + std::string ForcePTExchangeAtUserRequest() OVERRIDE; + + /** + * @brief Returns current status of policy table for HMI + * @return Current status of policy table + */ + std::string GetPolicyTableStatus() const OVERRIDE; + + /** + * @brief Resets retry sequence + */ + void ResetRetrySequence() OVERRIDE; + + /** + * @brief Gets timeout to wait before next retry updating PT + * If timeout is less or equal to zero then the retry sequence is not need. + * @return timeout in seconds + */ + int NextRetryTimeout() OVERRIDE; + + /** + * @brief Gets timeout to wait until receive response + * @return timeout in seconds + */ + uint32_t TimeoutExchangeMSec() OVERRIDE; + + /** + * @brief List of timeouts in seconds between retries + * when attempt to update PT fails + * @return List of delays between attempts. + */ + const std::vector RetrySequenceDelaysSeconds() OVERRIDE; + + /** + * @brief Handler of exceeding timeout of exchanging policy table + */ + void OnExceededTimeout() OVERRIDE; + + /** + * @brief GetLockScreenIcon allows to obtain lock screen icon url; + * @return url which point to the resourse where lock screen icon could be + *obtained. + */ + std::string GetLockScreenIconUrl() const OVERRIDE; + + /** + * @brief Handler of PTS sending out + */ + void OnUpdateStarted() OVERRIDE; + + /** + * @brief Sets counter value that passed for receiving PT UPdate. + */ + void PTUpdatedAt(Counters counter, int value) OVERRIDE; + + /** + * @brief Refresh data about retry sequence from policy table */ virtual void RefreshRetrySequence(); - virtual DeviceConsent GetUserConsentForDevice( + + /** + * @brief Gets user consent for mobile device data connection + * @param device_id Unique device identifier + * @return status of device consent + */ + DeviceConsent GetUserConsentForDevice( const std::string& device_id) const OVERRIDE; - virtual void GetUserConsentForApp( + + /** + * @brief Gets user consent for application + * @param device_id Device id + * @param policy_app_id Unique application id + * @param permissions Array of functional groups permissions + */ + void GetUserConsentForApp( const std::string& device_id, const std::string& policy_app_id, - std::vector& permissions); - virtual void SetUserConsentForDevice(const std::string& device_id, - const bool is_allowed); - virtual bool ReactOnUserDevConsentForApp(const std::string& app_id, - const bool is_device_allowed); - virtual bool GetInitialAppData(const std::string& application_id, - StringArray* nicknames = NULL, - StringArray* app_hmi_types = NULL); + std::vector& permissions) OVERRIDE; + + /** + * @brief Set user consent for mobile device data connection + * @param device_id Unique device identifier + * @param is_allowed User consent for usage device data connection + */ + void SetUserConsentForDevice(const std::string& device_id, + const bool is_allowed) OVERRIDE; - virtual void AddDevice(const std::string& device_id, - const std::string& connection_type); + /** + * @brief Update Application Policies as reaction + * on User allowing/disallowing device this app is running on. + * @param app_id Unique application id + * @param is_device_allowed true if user allowing device otherwise false + * @return true if operation was successful + */ + bool ReactOnUserDevConsentForApp(const std::string& app_id, + const bool is_device_allowed) OVERRIDE; - virtual void SetDeviceInfo(const std::string& device_id, - const DeviceInfo& device_info); + /** + * @brief Retrieves data from app_policies about app on its registration: + * @param application_id - id of registered app + * @param nicknames Synonyms for application + * @param app_hmi_types Section on HMI where app can appear (Navigation, Phone + * etc) + */ + bool GetInitialAppData(const std::string& application_id, + StringArray* nicknames = NULL, + StringArray* app_hmi_types = NULL) OVERRIDE; + /** + * @brief Add's device to policy table + * @param device_id Device mac address + * @param connection_type Device connection type + */ + void AddDevice(const std::string& device_id, + const std::string& connection_type) OVERRIDE; + + /** + * @brief Stores device parameters received during application registration + * to policy table + * @param device_id Device mac address + * @param device_info Received device parameters + */ + void SetDeviceInfo(const std::string& device_id, + const DeviceInfo& device_info) OVERRIDE; + + /** + * @brief Set user consent for application functional groups + * @param permissions User-defined application group pemissions. + * The permissions is not const reference because it may contains + * valid data as well as invalid. So we will remove all invalid data + * from this structure. + * @param mode notification mode + */ void SetUserConsentForApp(const PermissionConsent& permissions, const NotificationMode mode) OVERRIDE; - virtual bool GetDefaultHmi(const std::string& policy_app_id, - std::string* default_hmi) const; + /** + * @brief Get default HMI level for application + * @param policy_app_id Unique application id + * @param default_hmi Default HMI level for application or empty, if value + * was not set + * @return true, if succedeed, otherwise - false + */ + bool GetDefaultHmi(const std::string& policy_app_id, + std::string* default_hmi) const OVERRIDE; - virtual bool GetPriority(const std::string& policy_app_id, - std::string* priority) const; + /** + * @brief Get priority for application + * @param policy_app_id Unique application id + * @param priority Priority for application or empty, if value was not set + * @return true, if succedeed, otherwise - false + */ + bool GetPriority(const std::string& policy_app_id, + std::string* priority) const OVERRIDE; - virtual std::vector GetUserFriendlyMessages( + /** + * @brief Get user friendly messages for given RPC messages and language + * @param message_codes RPC message codes + * @param language Language + * @param active_hmi_language Currently active language + * @return Array of structs with appropriate message parameters + */ + std::vector GetUserFriendlyMessages( const std::vector& message_code, const std::string& language, - const std::string& active_hmi_language); + const std::string& active_hmi_language) OVERRIDE; - virtual bool IsApplicationRevoked(const std::string& app_id) const; + /** + * @brief Checks if the application is revoked + * @param app_id application id + * @return true if application is revoked + */ + bool IsApplicationRevoked(const std::string& app_id) const OVERRIDE; - virtual void GetPermissionsForApp( + /** + * @brief Get resulting RPCs permissions for application which started on + * specific device + * @param device_id Device id + * @param policy_app_id Unique application id + * @param permissions Array of functional groups permissions + */ + void GetPermissionsForApp( const std::string& device_id, const std::string& policy_app_id, - std::vector& permissions); + std::vector& permissions) OVERRIDE; - virtual std::string& GetCurrentDeviceId( - const std::string& policy_app_id) const; + /** + * @brief Return device id, which hosts specific application + * @param policy_app_id Application id, which is required to update device id + */ + std::string& GetCurrentDeviceId( + const std::string& policy_app_id) const OVERRIDE; - virtual void SetSystemLanguage(const std::string& language); + /** + * @brief Set current system language + * @param language Language + */ + void SetSystemLanguage(const std::string& language) OVERRIDE; - virtual void SetSystemInfo(const std::string& ccpu_version, - const std::string& wers_country_code, - const std::string& language); - virtual void OnSystemReady(); + /** + * @brief Set data from GetSystemInfo response to policy table + * @param ccpu_version CCPU version + * @param wers_country_code WERS country code + * @param language System language + */ + void SetSystemInfo(const std::string& ccpu_version, + const std::string& wers_country_code, + const std::string& language) OVERRIDE; - virtual uint32_t GetNotificationsNumber( - const std::string& priority) const OVERRIDE; + /** + * @brief Runs necessary operations, which is depends on external system + * state, e.g. getting system-specific parameters which are need to be + * filled into policy table + */ + void OnSystemReady() OVERRIDE; - virtual void SetVINValue(const std::string& value); + /** + * @brief Get number of notification by priority + * @param priority Specified priority + * @return notification number + */ + uint32_t GetNotificationsNumber(const std::string& priority) const OVERRIDE; - // Interface StatisticsManager (begin) - virtual void Increment(usage_statistics::GlobalCounterId type); - virtual void Increment(const std::string& app_id, - usage_statistics::AppCounterId type); - virtual void Set(const std::string& app_id, - usage_statistics::AppInfoId type, - const std::string& value); - virtual void Add(const std::string& app_id, - usage_statistics::AppStopwatchId type, - int32_t timespan_seconds); - // Interface StatisticsManager (end) + /** + * @brief Allows to update Vehicle Identification Number in policy table. + * @param new value for the parameter. + */ + void SetVINValue(const std::string& value) OVERRIDE; + + /** + * @brief Gets specific application permissions changes since last policy + * table update + * @param policy_app_id Unique application id + * @return Permissions changes + */ + AppPermissions GetAppPermissionsChanges( + const std::string& policy_app_id) OVERRIDE; + + /** + * @brief Removes specific application permissions changes + * @param app_id Unique application id + */ + void RemovePendingPermissionChanges(const std::string& app_id) OVERRIDE; - AppPermissions GetAppPermissionsChanges(const std::string& policy_app_id); - void RemovePendingPermissionChanges(const std::string& app_id); + /** + * @brief Send OnPermissionsUpdated for choosen application + * @param application_id Unique application id + */ + void SendNotificationOnPermissionsUpdated( + const std::string& application_id) OVERRIDE; - void SendNotificationOnPermissionsUpdated(const std::string& application_id); + /** + * @brief Removes unpaired device records and related records from DB + * @return true, if succedeed, otherwise - false + */ + bool CleanupUnpairedDevices() OVERRIDE; - bool CleanupUnpairedDevices(); + /** + * @brief Check if app can keep context. + * @param app_id Unique application id + * @return true if app can keep context, otherwise - false + */ + bool CanAppKeepContext(const std::string& app_id) const OVERRIDE; - bool CanAppKeepContext(const std::string& app_id) const; - bool CanAppStealFocus(const std::string& app_id) const; - void MarkUnpairedDevice(const std::string& device_id); + /** + * @brief Check if app can steal focus. + * @param app_id Unique application id + * @return true if app can steal focus, otherwise - false + */ + bool CanAppStealFocus(const std::string& app_id) const OVERRIDE; + /** + * @brief Marks device as upaired + * @param device_id id device + */ + void MarkUnpairedDevice(const std::string& device_id) OVERRIDE; + + /** + * @brief Adds, application to the db or update existed one + * run PTU if policy update is necessary for application. + * @param application_id Unique application id + * @param hmi_types application HMI types + * @return function that will notify update manager about new application + */ StatusNotifier AddApplication( const std::string& application_id, - const rpc::policy_table_interface_base::AppHmiTypes& hmi_types); + const rpc::policy_table_interface_base::AppHmiTypes& hmi_types) OVERRIDE; #ifdef SDL_REMOTE_CONTROL + /** + * @brief Assigns new HMI types for specified application + * @param application_id Unique application id + * @param hmi_types new HMI types list + */ void SetDefaultHmiTypes(const std::string& application_id, - const std::vector& hmi_types); + const std::vector& hmi_types) OVERRIDE; /** - * Gets HMI types - * @param application_id ID application - * @param app_types list to save HMI types - * @return true if policy has specific policy for this application - */ - virtual bool GetHMITypes(const std::string& application_id, - std::vector* app_types) OVERRIDE; - virtual void set_access_remote(utils::SharedPtr access_remote); + * @brief Gets HMI types + * @param application_id ID application + * @param app_types list to save HMI types + * @return true if policy has specific policy for this application + */ + bool GetHMITypes(const std::string& application_id, + std::vector* app_types) OVERRIDE; + + /** + * @brief Setter for access_remote instance + * @param access_remote pointer to new access_remote instance + */ + void set_access_remote(utils::SharedPtr access_remote) OVERRIDE; + + /** + * @brief Sends notification about application HMI level changed + * @param who application information structure + */ void SendHMILevelChanged(const Subject& who); + /** + * @brief Sends notification if application permissions were changed + * @param application_id Unique id of application + */ void OnPrimaryGroupsChanged(const std::string& application_id); #endif // SDL_REMOTE_CONTROL + /** + * @brief Removes consent for application functional group + * @param application_id Unique id of application + * @param group_name application functional group name + */ virtual void RemoveAppConsentForGroup(const std::string& app_id, const std::string& group_name); - virtual uint32_t HeartBeatTimeout(const std::string& app_id) const; + /** + * @brief Returns heart beat timeout + * @param app_id application id + * @return if timeout was set then value in milliseconds greater zero + * otherwise heart beat for specific application isn't set + */ + uint32_t HeartBeatTimeout(const std::string& app_id) const OVERRIDE; - virtual void SaveUpdateStatusRequired(bool is_update_needed); + /** + * @brief SaveUpdateStatusRequired allows to save update status. + * @param is_update_needed true if update needed + */ + void SaveUpdateStatusRequired(bool is_update_needed) OVERRIDE; - virtual bool IsPredataPolicy(const std::string& policy_app_id) const OVERRIDE; - void set_cache_manager(CacheManagerInterface* cache_manager); + /** + * @brief Checks, if application has policy assigned w/o data consent + * @param policy_app_id Unique application id + * @return true, if policy assigned w/o data consent, otherwise -false + */ + bool IsPredataPolicy(const std::string& policy_app_id) const OVERRIDE; - virtual void OnAppsSearchStarted(); + /** + * @brief Setter for cache_manager instance + * @param cache_manager pointer to new cache_manager instance + */ + void set_cache_manager(CacheManagerInterface* cache_manager); - virtual void OnAppsSearchCompleted(const bool trigger_ptu); + /** + * @brief Handler on applications search started + */ + void OnAppsSearchStarted() OVERRIDE; -#ifdef BUILD_TESTS - inline CacheManagerInterfaceSPtr GetCache() { - return cache_; - } - inline void SetSendOnUpdateFlags(const bool send_on_update_sent_out, - const bool wrong_ptu_update_received) { - send_on_update_sent_out_ = send_on_update_sent_out; - wrong_ptu_update_received_ = wrong_ptu_update_received; - } -#endif // BUILD_TESTS + /** + * @brief Handler on applications search completed + * @param trigger_ptu contains true if PTU should be triggered + */ + void OnAppsSearchCompleted(const bool trigger_ptu) OVERRIDE; - virtual const std::vector GetAppRequestTypes( - const std::string policy_app_id) const; + /** + * @brief Gets request types for application + * @param policy_app_id Unique application id + * @return request types of application + */ + const std::vector GetAppRequestTypes( + const std::string policy_app_id) const OVERRIDE; - virtual const VehicleInfo GetVehicleInfo() const; + /** + * @brief Get information about vehicle + * @return vehicle information + */ + const VehicleInfo GetVehicleInfo() const OVERRIDE; - virtual void OnAppRegisteredOnMobile(const std::string& application_id); + /** + * @brief OnAppRegisteredOnMobile allows to handle event when application were + * succesfully registered on mobile device. + * It will send OnAppPermissionSend notification and will try to start PTU. * + * @param application_id registered application. + */ + void OnAppRegisteredOnMobile(const std::string& application_id) OVERRIDE; - virtual const MetaInfo GetMetaInfo() const OVERRIDE; + /** + * @brief Gets meta information + * @return meta information + */ + const MetaInfo GetMetaInfo() const OVERRIDE; - virtual std::string RetrieveCertificate() const OVERRIDE; + /** + * @brief RetrieveCertificate Allows to obtain certificate in order + * to start secure connection. + * @return The certificate in PKCS#7 format. + */ + std::string RetrieveCertificate() const OVERRIDE; - virtual bool HasCertificate() const OVERRIDE; + /** + * @brief HasCertificate check whether policy table has certificate + * int module_config section. + * @return true in case certificate exists, false otherwise + */ + bool HasCertificate() const OVERRIDE; - virtual void SetDecryptedCertificate(const std::string& certificate) OVERRIDE; + /** + * @brief Sets decrypted certificate in policy table + * @param certificate content of certificate + */ + void SetDecryptedCertificate(const std::string& certificate) OVERRIDE; + /** + * @brief Getter for policy settings + * @return policy settings instance + */ const PolicySettings& get_settings() const OVERRIDE; + /** + * @brief Finds the next URL that must be sent on OnSystemRequest retry + * @param urls vector of vectors that contain urls for each application + * @return Pair of policy application id and application url id from the + * urls vector + */ AppIdURL GetNextUpdateUrl(const EndpointUrls& urls) OVERRIDE; + /** + * @brief Checks if there is existing URL in the EndpointUrls vector with + * index saved in the policy manager and if not, it moves to the next + * application index + * @param rs contains the application index and url index from the + * urls vector that are to be sent on the next OnSystemRequest + * @param urls vector of vectors that contain urls for each application + * @return Pair of application index and url index + */ AppIdURL RetrySequenceUrl(const struct RetrySequenceURL& rs, const EndpointUrls& urls) const OVERRIDE; @@ -251,20 +618,90 @@ class PolicyManagerImpl : public PolicyManager { * @return true if such check is needed, false - if not. */ bool IsNeedToUpdateExternalConsentStatus( - const ExternalConsentStatus& status) const; + const ExternalConsentStatus& status) const OVERRIDE; + + /** + * @brief Saves customer connectivity settings status + * @param status ExternalConsent status + * @return true if succeeded, otherwise - false + */ + bool SetExternalConsentStatus(const ExternalConsentStatus& status) OVERRIDE; /** * @brief Gets customer connectivity settings status * @return ExternalConsent status */ - bool SetExternalConsentStatus(const ExternalConsentStatus& status) OVERRIDE; ExternalConsentStatus GetExternalConsentStatus() OVERRIDE; +#ifdef BUILD_TESTS + /** + * @brief Getter for cache_manager instance + * @return cache_manager instance + */ + inline CacheManagerInterfaceSPtr GetCache() { + return cache_; + } + + /** + * @brief Setter for send_on_update_sent_out and wrong_ptu_update_received + * @param send_on_update_sent_out new value of this flag + * @param wrong_ptu_update_received new value of this flag + */ + inline void SetSendOnUpdateFlags(const bool send_on_update_sent_out, + const bool wrong_ptu_update_received) { + send_on_update_sent_out_ = send_on_update_sent_out; + wrong_ptu_update_received_ = wrong_ptu_update_received; + } +#endif // BUILD_TESTS + + // Interface StatisticsManager (begin) + /** + * @brief Increments global counter + * @param type counter type + */ + void Increment(usage_statistics::GlobalCounterId type) OVERRIDE; + + /** + * @brief Increments specified application counter + * @param app_id Unique ID of application + * @param type application counter type + */ + void Increment(const std::string& app_id, + usage_statistics::AppCounterId type) OVERRIDE; + /** + * @brief Sets specified application info value + * @param app_id Unique ID of application + * @param type application info type + * @param value new value for counter + */ + void Set(const std::string& app_id, + usage_statistics::AppInfoId type, + const std::string& value) OVERRIDE; + + /** + * @brief Add seconds for specified application stopwatch + * @param app_id Unique ID of application + * @param type application stopwatch type + * @param timespan_seconds seconds to add + */ + void Add(const std::string& app_id, + usage_statistics::AppStopwatchId type, + int32_t timespan_seconds) OVERRIDE; + // Interface StatisticsManager (end) + protected: + /** + * @brief Parse policy table content and convert to PT object + * @param pt_content binary content of PT + * @return pointer to converted PT + */ virtual utils::SharedPtr Parse( const BinaryMessage& pt_content); private: + /** + * @brief Checks if PT update should be started and schedules it if needed + */ void CheckTriggers(); /** @@ -362,21 +799,71 @@ class PolicyManagerImpl : public PolicyManager { const std::string& policy_app_id, const std::vector& current_permissions); - virtual void StartPTExchange(); - virtual bool ExceededDays(); - virtual bool ExceededIgnitionCycles(); + /** + * @brief StartPTExchange allows to start PTU. The function will check + * if one is required and starts the update flow in only case when previous + * condition is true. + */ + void StartPTExchange() OVERRIDE; + + /** + * @brief Checks is PT exceeded days + * @return true if exceeded + */ + bool ExceededDays() OVERRIDE; + + /** + * @brief Checks is PT exceeded IgnitionCycles + * @return true if exceeded + */ + bool ExceededIgnitionCycles() OVERRIDE; + + /** + * @brief Checks is specified policy table valid + * @param policy_table pointer to policy table to check + * @param type policy table type + * @return true if policy table valid, otherwise false + */ bool IsPTValid(utils::SharedPtr policy_table, policy_table::PolicyTableType type) const; #ifdef SDL_REMOTE_CONTROL + /** + * @brief Get resulting RPCs permissions for application which started on + * specific device + * @param device_id Device id + * @param policy_app_id Unique application id + * @param permissions Array of RPC param/HMI permissions + */ void GetPermissions(const std::string device_id, const std::string application_id, Permissions* data); - virtual bool CheckModule(const PTString& app_id, const PTString& module); - virtual void SendAppPermissionsChanged(const std::string& device_id, - const std::string& application_id); - virtual bool GetModuleTypes(const std::string& policy_app_id, - std::vector* modules) const; + + /** + * @brief Checks if module for application is present in policy table + * @param app_id id of application + * @param module type + * @return true if module is present, otherwise - false + */ + bool CheckModule(const PTString& app_id, const PTString& module) OVERRIDE; + + /** + * @brief Send OnPermissionsChange notification to mobile app + * when it's permissions are changed. + * @param device_id Device on which app is running + * @param application_id ID of app whose permissions are changed + */ + void SendAppPermissionsChanged(const std::string& device_id, + const std::string& application_id) OVERRIDE; + + /** + * @brief Gets all allowed module types + * @param policy_app_id unique identifier of application + * @param modules list of allowed module types + * @return true if application has allowed modules + */ + bool GetModuleTypes(const std::string& policy_app_id, + std::vector* modules) const OVERRIDE; #endif // SDL_REMOTE_CONTROL /** @@ -479,15 +966,35 @@ class PolicyManagerImpl : public PolicyManager { GroupsNames& out_allowed_groups, GroupsNames& out_disallowed_groups) const; + /** + * @brief pointer to policy table listener for callbacks + */ PolicyListener* listener_; + /** + * @brief UpdateStatusManager instance for controlling PT status + */ UpdateStatusManager update_status_manager_; + + /** + * @brief pointer to CacheManagerInterface instance for getting policy data + */ CacheManagerInterfaceSPtr cache_; #ifdef SDL_REMOTE_CONTROL + /** + * @brief pointer to AccessRemote instance for working with RC applications + */ utils::SharedPtr access_remote_; #endif + /** + * @brief lock guard for protecting applications list access + */ sync_primitives::Lock apps_registration_lock_; + + /** + * @brief lock guard for protecting application permissions access + */ sync_primitives::Lock app_permissions_diff_lock_; /** @@ -499,22 +1006,22 @@ class PolicyManagerImpl : public PolicyManager { PendingPermissions app_permissions_diff_; /** - * Timeout to wait response with UpdatePT + * @brief Timeout to wait response with UpdatePT */ - int retry_sequence_timeout_; + uint32_t retry_sequence_timeout_; /** - * Seconds between retries to update PT + * @brief Seconds between retries to update PT */ std::vector retry_sequence_seconds_; /** - * Current index trying of retry sequence + * @brief Current index trying of retry sequence */ uint32_t retry_sequence_index_; /** - * Lock for guarding retry sequence + * @brief Lock for guarding retry sequence */ sync_primitives::Lock retry_sequence_lock_; @@ -524,8 +1031,14 @@ class PolicyManagerImpl : public PolicyManager { */ mutable std::string last_device_id_; + /** + * @brief Flag for checking first ignition cycle + */ bool ignition_check; + /** + * @brief Pointer to current policy settings structure + */ const PolicySettings* settings_; friend struct CheckAppPolicy; @@ -536,8 +1049,19 @@ class PolicyManagerImpl : public PolicyManager { RetrySequenceURL retry_sequence_url_; friend struct ProccessAppGroups; + /** + * @brief Flag for notifying that invalid PTU was received + */ bool wrong_ptu_update_received_; + + /** + * @brief Flag for notifying that PTU was started + */ bool send_on_update_sent_out_; + + /** + * @brief Flag for notifying that invalid PTU should be triggered + */ bool trigger_ptu_; }; -- cgit v1.2.1