X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=inc%2FFAppAppManager.h;h=8f99c43e5541ea24514955e3580ebc68862486dc;hb=07a771d39ebf4c7f26a04aeb3e06f9d7eb1c6dc2;hp=a0e0dc4fbb0c094efe83bcdf0841e63891d9de0b;hpb=9a0df6cc2044f98f0401ce8d288716f8f91dc87b;p=platform%2Fframework%2Fnative%2Fappfw.git diff --git a/inc/FAppAppManager.h b/inc/FAppAppManager.h old mode 100755 new mode 100644 index a0e0dc4..8f99c43 --- a/inc/FAppAppManager.h +++ b/inc/FAppAppManager.h @@ -1,5 +1,4 @@ // -// Open Service Platform // Copyright (c) 2012 Samsung Electronics Co., Ltd. // // Licensed under the Apache License, Version 2.0 (the License); @@ -58,10 +57,10 @@ class MapDataControl; * @final This class is not intended for extension. * * The %AppManager class manages all the applications. - * The application manager supports normal and conditional application launch, and application control search and launch. + * The application manager supports both normal and conditional application launch as well as application control search and launch. * It looks up the specific application control from the application control registry and creates an application control instance. - * @n - * For more information on the class features, see Launching Other Applications and Registering a Launch Condition, and Application Controls. + * + * For more information on the class features, see Launching Other Applications, Registering a Launch Condition, and Application Controls. */ class _OSP_EXPORT_ AppManager : public Tizen::Base::Object @@ -76,7 +75,7 @@ public: */ enum LaunchOption { - LAUNCH_OPTION_DEFAULT /**< The launch option: default */ + LAUNCH_OPTION_DEFAULT /**< The default launch option */ }; /** @@ -85,85 +84,84 @@ public: * * @since 2.0 * - * @return A pointer to the newly created AppControl instance if a matched %AppControl is found, @n - * else @c null + * @return A pointer to the newly created AppControl instance, if a matched %AppControl is found, @n + * else @c null if it fails * @param[in] appId The application ID * @param[in] operationId The operation ID * @exception E_SUCCESS The method is successful. - * @exception E_OBJ_NOT_FOUND The application control is not found. - * @exception E_SYSTEM A system error has occurred. @n - * Either the file operation or the DB operation has failed. - * @remarks The specific error code can be accessed using the GetLastResult() method. - * @remarks %Tizen platform defines platform-defined alias for application ID and this aliased application ID + * @exception E_OBJ_NOT_FOUND The application control has not been found. + * @exception E_SYSTEM Either of the following conditions has occurred: + * - A system error has occurred. + * - Either the file operation or the DB operation has failed. + * @remarks + * - The specific error code can be accessed using the GetLastResult() method. + * - The %Tizen platform defines a platform-defined alias for the application ID and this aliased application ID * can be used to find the AppControl. For more information, see - * here. + * here. * * The following example demonstrates how to use the %FindAppControlN() method to find the application control. * * @code - * ArrayList dataList(SingleObjectDeleter); - * dataList.Construct(); - * dataList.Add(new String(L"tel:1234567900")); - * dataList.Add(new String(L"type:voice")); + * String telUri = L"tel:12345678900"; * - * AppControl* pAc = AppManager::FindAppControlN(L"tizen.phone", L"http://tizen.org/appcontrol/operation/call"); - * pAc->Start(&dataList, null); + * AppControl* pAc = AppManager::FindAppControlN(L"tizen.phone", L"http://tizen.org/appcontrol/operation/dial"); + * pAc->Start(&telUri, null, null, null); * @endcode */ static AppControl* FindAppControlN(const AppId& appId, const Tizen::Base::String& operationId); /** - * Finds a list of AppControl instances that matches the specified operation ID, category, + * Finds a list of AppControl instances that match the specified operation ID, category, * data type, and URI pattern. * * @since 2.0 * - * @return A pointer to the list of the AppControl instances that matches the specified operation ID, category, URI, and data type, @n - * else @c null if it fails - * @param[in] pOperationId The operation ID - * @param[in] pCategory The application category - * @param[in] pDataType The MIME type (RFC 2046) or file extension @n - * The '.' prefix must be used when specifying the file extension. - * @param[in] pUriPattern The URI pattern + * @return A pointer to the list of the AppControl instances that match the specified operation ID, category, URI, and data type, @n + * else @c null if it fails + * @param[in] pOperationId The operation ID + * @param[in] pCategory The application category + * @param[in] pDataType The MIME type (RFC 2046) or file extension @n + * The '.' prefix must be used while specifying the file extension. + * @param[in] pUriPattern The URI pattern * - * @exception E_SUCCESS The method is successful. - * @exception E_INVALID_ARG At least one of the specified @c pOperationId, @c pCategory, @c pDataType, or @c pUriScheme must not be @c null. - * @exception E_INVALID_FORMAT The specified URI scheme is invalid (RFC 2396). + * @exception E_SUCCESS The method is successful. + * @exception E_INVALID_ARG At least one of the specified @c pOperationId, @c pCategory, @c pDataType, or @c pUriScheme must not be @c null. + * @exception E_INVALID_FORMAT The specified URI scheme is invalid (RFC 2396). * @exception E_UNSUPPORTED_FORMAT The specified file extension for @c pDataType is not supported. - * @exception E_OBJ_NOT_FOUND The application control is not found. - * @exception E_SYSTEM A system error has occurred. @n - * Either the file operation or the DB operation has failed. + * @exception E_OBJ_NOT_FOUND The application control has not been found. + * @exception E_SYSTEM Either of the following conditions has occurred: + * - A system error has occurred. + * - Either the file operation or the DB operation has failed. * @remarks The specific error code can be accessed using the GetLastResult() method. - * @remarks For the delivered launch arguments, see App::GetAppArgumentListN(). */ static Tizen::Base::Collection::IList* FindAppControlsN(const Tizen::Base::String* pOperationId, const Tizen::Base::String* pCategory, const Tizen::Base::String* pDataType, const Tizen::Base::String* pUriPattern); /** * @if OSPDEPREC * Starts the application control if there is only one application control that matches the specified URI, operation ID, and data type. @n - * If there are more than one application controls, the one that the user selects is started. + * If there are more than one application controls, then the user selected one is started. * - * @brief [Deprecated] + * @brief [Deprecated] * @deprecated This method is deprecated because IAppControlListener is deprecated and replaced by IAppControlResponselistener. * Instead of using this method, use AppControl::FindAndStart(). * @since 2.0 * @privlevel public - * @privilege http://tizen.org/privilege/application.launch + * @privilege %http://tizen.org/privilege/application.launch * * @return An error code - * @param[in] uriData The URI that has a maximum size of @c 1024 bytes - * @param[in] pOperationId The operation ID - * @param[in] pDataType The MIME type (RFC 2046) or file extension @n - * The '.' prefix must be used for the @c dataType when specifying the file extension. - * @param[in] pListener A listener that gets notified when the resolved application control has started - * @exception E_SUCCESS The method is successful. - * @exception E_MAX_EXCEEDED The size of @c uri has exceeded the maximum limit. + * @param[in] uriData The URI that has a maximum size of @c 1024 bytes + * @param[in] pOperationId The operation ID + * @param[in] pDataType The MIME type (RFC 2046) or file extension @n + * The '.' prefix must be used for the @c dataType while specifying the file extension. + * @param[in] pListener The listener that gets notified when the resolved application control is started + * @exception E_SUCCESS The method is successful. + * @exception E_MAX_EXCEEDED The size of @c uri has exceeded the maximum limit. * @exception E_UNSUPPORTED_FORMAT The specified file extension for @c pDataType is not supported. - * @exception E_OUT_OF_MEMORY The memory is insufficient. - * @exception E_OBJ_NOT_FOUND The application control is not found. - * @exception E_IN_PROGRESS The target application control is in progress. - * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method. - * @exception E_SYSTEM The method cannot proceed due to a severe system error. + * @exception E_OUT_OF_MEMORY The memory is insufficient. + * @exception E_OBJ_NOT_FOUND The application control has not been found. + * @exception E_IN_PROGRESS The target application control is in progress. + * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method. + * @exception E_SYSTEM The method cannot proceed due to a severe system error. * * @see App::GetAppArgumentListN() * @see FindAppControlN() @@ -182,34 +180,33 @@ public: /** * @if OSPDEPREC * Starts the application control if there is only one application control that matches the specified operation ID, category, URI, and data type. @n - * If there are more than one application controls, the one that the user selects is started. + * If there are more than one application controls, then the user selected one is started. * - * @brief [Deprecated] + * @brief [Deprecated] * @deprecated This method is deprecated because IAppControlListener is deprecated and replaced by IAppControlResponselistener. * Instead of using this method, use AppControl::FindAndStart(). * @since 2.0 * @privlevel public - * @privilege http://tizen.org/privilege/application.launch + * @privilege %http://tizen.org/privilege/application.launch * - * @return An error code - * @param[in] pOperationId The operation ID - * @param[in] pCategory The application control category - * @param[in] pDataType The MIME type (RFC 2046) or file extension @n - * The '.' prefix must be used when specifying the file extension. - * @param[in] pUriPattern A URI pattern which is used for application control resolution and delivered as the argument - * @param[in] pDataList The data list that is delivered to the resolved application control @n - * It has a maximum size of @c 1024 bytes. - * @param[in] pListener A listener that gets notified when the resolved application control has started - * @exception E_SUCCESS The method is successful. - * @exception E_INVALID_ARG At least one of the specified @c pOperationId, @c pCategory, @c pDataType, or @c pUri must not be @c null. - * @exception E_MAX_EXCEEDED The size of @c pDataList has exceeded the maximum limit. + * @return An error code + * @param[in] pOperationId The operation ID + * @param[in] pCategory The application control category + * @param[in] pDataType The MIME type (RFC 2046) or file extension @n + * The '.' prefix must be used while specifying the file extension. + * @param[in] pUriPattern The URI pattern which is used for the application control resolution and is delivered as an argument + * @param[in] pDataList The data list that is delivered to the resolved application control @n + * It has a maximum size of @c 1024 bytes. + * @param[in] pListener The listener that gets notified when the resolved application control is started + * @exception E_SUCCESS The method is successful. + * @exception E_INVALID_ARG At least one of the specified @c pOperationId, @c pCategory, @c pDataType, or @c pUri must not be @c null. + * @exception E_MAX_EXCEEDED The size of @c pDataList has exceeded the maximum limit. * @exception E_UNSUPPORTED_FORMAT The specified file extension for @c pDataType is not supported. - * @exception E_OBJ_NOT_FOUND The application control is not found. - * @exception E_IN_PROGRESS The target application control is in progress. - * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method. - * @exception E_SYSTEM The method cannot proceed due to a severe system error. + * @exception E_OBJ_NOT_FOUND The application control has not been found. + * @exception E_IN_PROGRESS The target application control is in progress. + * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method. + * @exception E_SYSTEM The method cannot proceed due to a severe system error. * @remarks For delivered launch arguments, see App::GetAppArgumentListN(). - * @see App::GetAppArgumentListN() * @see FindAppControlsN() * @see AppControl::Start() * @endif @@ -222,12 +219,12 @@ public: * * @since 2.0 * - * @return A pointer to the SqlDataControl instance if a matching data control is found, @n - * else @c null + * @return A pointer to the SqlDataControl instance, if a matching data control is found, @n + * else @c null if it fails * @param[in] providerId The provider ID * @exception E_SUCCESS The method is successful. - * @exception E_OBJ_NOT_FOUND The data control specified with the @c providerId is not found. - * @exception E_ILLEGAL_ACCESS Access is denied due to insufficient permission. + * @exception E_OBJ_NOT_FOUND The data control specified with the @c providerId has not been found. + * @exception E_ILLEGAL_ACCESS The access is denied due to insufficient permission. * @exception E_OUT_OF_MEMORY The memory is insufficient. * @exception E_SYSTEM A system error has occurred. * @remarks The specific error code can be accessed using the GetLastResult() method. @@ -240,12 +237,12 @@ public: * * @since 2.0 * - * @return A pointer to the MapDataControl instance if a matching data control is found, @n - * else @c null + * @return A pointer to the MapDataControl instance, if a matching data control is found, @n + * else @c null if it fails * @param[in] providerId The provider ID * @exception E_SUCCESS The method is successful. - * @exception E_OBJ_NOT_FOUND The data control specified with the @c providerId is not found. - * @exception E_ILLEGAL_ACCESS Access is denied due to insufficient permission. + * @exception E_OBJ_NOT_FOUND The data control specified with the @c providerId has not been found. + * @exception E_ILLEGAL_ACCESS The access is denied due to insufficient permission. * @exception E_OUT_OF_MEMORY The memory is insufficient. * @exception E_SYSTEM A system error has occurred. * @remarks The specific error code can be accessed using the GetLastResult() method. @@ -253,7 +250,7 @@ public: static MapDataControl* GetMapDataControlN(const Tizen::Base::String& providerId); /** - * Gets the path of the read-only shared directory exported by an other application specified with an application ID. + * Gets the path of the read-only shared directory exported by another application specified with an application ID. * * @since 2.0 * @@ -261,14 +258,18 @@ public: * else an empty string if an exception occurs * @param[in] appId The application ID * @exception E_SUCCESS The method is successful. - * @exception E_APP_NOT_INSTALLED The expected shared directory cannot be found - * because the application specified with @c appId cannot be installed. - * @remarks The specific error code can be accessed using the GetLastResult() method. + * @exception E_APP_NOT_INSTALLED The expected shared directory has not been found + * because the application specified by @c appId cannot be installed. + * @remarks + * - The returned path can be invalid when the application specified by @c appId is uninstalled. + * - The specific error code can be accessed using the GetLastResult() method. + * - If the platform policy is changed or the device is different, the returned file path can be different. @n + * Rather than changing the returned file path as hard coding, use as it is. */ static Tizen::Base::String GetAppSharedPath(const AppId& appId); /** - * Gets the application manager instance. + * Gets a pointer to the %AppManager instance. * * @since 2.0 * @@ -280,28 +281,28 @@ public: /** * @if OSPDEPREC * Launches the default application with the given @c appId. @n - * The launch arguments are given as App::OnUserEventReceivedN() or can be obtained by - * invoking App::GetAppArgumentListN(), especially within App::OnAppInitializing(). + * The launch arguments are given by the App::OnUserEventReceivedN() method or can be obtained by + * invoking the App::GetAppArgumentListN() method, especially within App::OnAppInitializing(). * * @brief [Deprecated] - * @deprecated This method is deprecated because sending argument with %LaunchApplication() is not recommended. @n - * Instead of using this method, use %LaunchApplication() without launch arguments or AppControl::Start(). - * @since 2.0 + * @deprecated This method is deprecated because sending arguments through the %LaunchApplication() method is not recommended. @n + * Instead of using this method, use the %LaunchApplication() method without launch arguments or AppControl::Start(). + * @since 2.0 * @privlevel public - * @privilege http://tizen.org/privilege/application.launch + * @privilege %http://tizen.org/privilege/application.launch * - * @return An error code - * @param[in] appId The application's ID to execute + * @return An error code + * @param[in] appId The ID of the application to execute * @param[in] pArguments A pointer to the list of string arguments that has a maximum size of @c 1024 bytes * @param[in] option The launch option (currently only AppManager::LAUNCH_OPTION_DEFAULT is available) * @exception E_SUCCESS The method is successful. * @exception E_SYSTEM The method cannot proceed due to a severe system error. * @exception E_INVALID_ARG The specified @c appId is empty. - * @exception E_OBJ_NOT_FOUND The target application is not installed. + * @exception E_OBJ_NOT_FOUND The target application has not been installed. * @exception E_OUT_OF_MEMORY The memory is insufficient. * @exception E_MAX_EXCEEDED The size of @c appId or @c pArguments has exceeded the maximum limit. * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method. - * @exception E_ILLEGAL_ACCESS The application is not signed with the same certificate of target application. @b Since: @b 2.1 + * @exception E_ILLEGAL_ACCESS The application is not signed with the same certificate as that of the target application. @b Since: @b 2.1 * @endif */ result LaunchApplication(const AppId& appId, const Tizen::Base::Collection::IList* pArguments, LaunchOption option = LAUNCH_OPTION_DEFAULT); @@ -309,18 +310,18 @@ public: /** * Launches the default application with the given @c appId. * - * @since 2.0 + * @since 2.0 * @privlevel public - * @privilege http://tizen.org/privilege/application.launch + * @privilege %http://tizen.org/privilege/application.launch * - * @return An error code - * @param[in] appId The application's ID to execute + * @return An error code + * @param[in] appId The ID of the application to execute * @param[in] option The launch option (currently only AppManager::LAUNCH_OPTION_DEFAULT is available) * @exception E_SUCCESS The method is successful. * @exception E_SYSTEM The method cannot proceed due to a severe system error. - * @exception E_APP_NOT_INSTALLED The target application is not installed. + * @exception E_APP_NOT_INSTALLED The target application has not been installed. * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method. - * @exception E_ILLEGAL_ACCESS The application is not signed with the same certificate of target application. @b Since: @b 2.1 + * @exception E_ILLEGAL_ACCESS The application is not signed with the same certificate as that of the target application. @b Since: @b 2.1 */ result LaunchApplication(const AppId& appId, LaunchOption option = LAUNCH_OPTION_DEFAULT); @@ -329,35 +330,38 @@ public: * * @since 2.0 * @privlevel partner - * @privilege http://tizen.org/privilege/application.kill + * @privilege %http://tizen.org/privilege/appmanager.kill @n + * (%http://tizen.org/privilege/application.kill is deprecated.) * - * @return An error code - * @param[in] appId The application's ID to execute + * @return An error code + * @param[in] appId The ID of the application to execute * @exception E_SUCCESS The method is successful. * @exception E_SYSTEM A system error has occurred. - * @exception E_OBJ_NOT_FOUND The application is either not installed or is not running. + * @exception E_OBJ_NOT_FOUND Either of the following conditions has occurred: + * - The application is not installed. + * - The application is not running. * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method. */ result TerminateApplication(const AppId& appId); /** - * Checks whether an application is running. + * Checks whether the application is running. * * @since 2.0 * - * @return @c true if the application is running, @n - * else @c false - * @param[in] appId The installed application ID + * @return @c true if the application is running, @n + * else @c false + * @param[in] appId The installed application's ID */ bool IsRunning(const AppId& appId) const; /** - * Gets a list of running applications at the time of invocation. + * Gets the list of running applications at the time of the invocation. * * @since 2.0 * - * @return A pointer to the running state application list (AppId), @n - * else @c null if an error occurs + * @return A pointer to the running state application list (AppId), @n + * else @c null if an error occurs * @exception E_SUCCESS The method is successful. * @exception E_OUT_OF_MEMORY The memory is insufficient. * @exception E_SYSTEM A system error has occurred. @@ -367,53 +371,59 @@ public: /** * Registers an application with a specific condition and launches it if the condition is met. @n - * If the requested application is already running, the application is notified through IAppLaunchConditionEventListener::OnAppLaunchConditionMetN(). - * The launch arguments are given as input parameters to %IAppLaunchConditionEventListener::OnAppLaunchConditionMetN(). + * If the requested application is already running, the application is notified through the IAppLaunchConditionEventListener::OnAppLaunchConditionMetN() method. + * The launch arguments are given as input parameters to the %IAppLaunchConditionEventListener::OnAppLaunchConditionMetN() method. * - * @since 2.0 + * @since 2.0 * @privlevel public - * @privilege http://tizen.org/privilege/application.launch + * @privilege %http://tizen.org/privilege/application.launch + * @feature %http://tizen.org/feature/network.nfc for L"NFC='command'" or %http://tizen.org/feature/usb.accessory for "Serial='command'" in the value of @c condition * * @return An error code * @param[in] condition The launch condition for the application @n - * The condition has L"Key='value'" format and is case sensitive. To use single or double quotes in the condition values, prefix them with a slash (\' or \"). @n - * For more information on the condition formats, see Registering a Launch Condition. - *
Condition Format | Meaning |
---|---|
L"DateTime='mm/dd/yyyy hh:mm:ss'" | -The specified condition is the local due time. |
L"DueTime='mm/dd/yyyy hh:mm:ss' LaunchPeriod='mm'" | -The specific condition is the time period after due time. |
L"WeeklyTime='EEE HH:mm:ss'" | -The specified condition is a day of week with specific time to launch an application for every week. For multiple description, "," delimiter can be used like following example. i"Mon 09:00:00, Tue 09:00:00, Wed 09:00:00, Thu 09:00:00, Fir 09:00:00" The format of a day of week is support following string only. Mon: Monday Tue: Tuesday Wed: Wednesday Thu: Thursday Fri: Friday Sat: Saturday Sun: Sunday |
L"Serial='command'" | The specified condition is a serial - communication input command. |
L"NFC='command'" | The specified condition is a Near Field Communication (NFC) tag that has the NFC Data Exchange Format (NDEF) data. - |
Condition Format | Meaning |
---|---|
L"DateTime='mm/dd/yyyy hh:mm:ss'" | + *The specified condition is the local due time. |
L"DueTime='mm/dd/yyyy hh:mm:ss' LaunchPeriod='mm'" | + *The specified condition is the time period after the due time. |
L"WeeklyTime='EEE HH:mm:ss'" | + *The specified condition is a day of a week with a specific time at which the application is launched on a weekly basis. For multiple descriptions, "," delimiter can be used as shown in the following example: i"'Mon 09:00:00', 'Tue 09:00:00', 'Wed 09:00:00', 'Thu 09:00:00', 'Fri 09:00:00'" To specify the day of the week, it must be in one of the following supported string format: Mon: Monday Tue: Tuesday Wed: Wednesday Thu: Thursday Fri: Friday Sat: Saturday Sun: Sunday |
L"Serial='command'" | The specified condition is a serial + * communication input command. |
L"NFC='command'" | The specified condition is a Near Field Communication (NFC) tag that has the NFC Data Exchange Format (NDEF) data. + * |
Condition Format | Meaning |
---|---|
L"DateTime='mm/dd/yyyy hh:mm:ss'" | -The specified condition is the local due time. |
L"DueTime='mm/dd/yyyy hh:mm:ss' LaunchPeriod='mm'" | -The specific condition is the time period after due time. |
L"Serial='command'" | The specified condition is a serial - communication input command. |
L"NFC='command'" | The specified condition is a Near Field Communication (NFC) tag that has the NFC Data Exchange Format (NDEF) data. - |
Condition Format | Meaning |
---|---|
L"DateTime='mm/dd/yyyy hh:mm:ss'" | + *The specified condition is the local due time. |
L"DueTime='mm/dd/yyyy hh:mm:ss' LaunchPeriod='mm'" | + *The specified condition is the time period after the due time. |
L"WeeklyTime='EEE HH:mm:ss'" | + *The specified condition is a day of a week with a specific time at which the application is launched on a weekly basis. For multiple descriptions, "," delimiter can be used as shown in the following example: i"'Mon 09:00:00', 'Tue 09:00:00', 'Wed 09:00:00', 'Thu 09:00:00', 'Fri 09:00:00'" To specify the day of the week, it must be in one of the following supported string format: Mon: Monday Tue: Tuesday Wed: Wednesday Thu: Thursday Fri: Friday Sat: Saturday Sun: Sunday |
L"Serial='command'" | The specified condition is a serial + * communication input command. |
L"NFC='command'" | The specified condition is a Near Field Communication (NFC) tag that has the NFC Data Exchange Format (NDEF) data. + * |