diff options
author | jk7744.park <jk7744.park@samsung.com> | 2015-09-08 22:08:01 +0900 |
---|---|---|
committer | jk7744.park <jk7744.park@samsung.com> | 2015-09-08 22:08:01 +0900 |
commit | b0dd9c11be43272070381ddb3bda44fb5faeb72a (patch) | |
tree | a7829810a1f9ad743f532b0b7ad032d9c6a893ff /include | |
parent | f569fd2849e68809db66bf2cf468b30ca5c535a5 (diff) | |
download | application-tizen_2.3.1.tar.gz application-tizen_2.3.1.tar.bz2 application-tizen_2.3.1.zip |
tizen 2.3.1 releasetizen_2.3.1_releasesubmit/tizen_2.3.1/20150915.075619tizen_2.3.1
Diffstat (limited to 'include')
-rwxr-xr-x | include/app.h | 469 | ||||
-rwxr-xr-x | include/app_alarm.h | 278 | ||||
-rw-r--r-- | include/app_common.h | 411 | ||||
-rwxr-xr-x | include/app_control.h | 877 | ||||
-rw-r--r-- | include/app_control_internal.h | 95 | ||||
-rwxr-xr-x | include/app_i18n.h | 22 | ||||
-rwxr-xr-x | include/app_internal.h (renamed from include/app_private.h) | 37 | ||||
-rwxr-xr-x | include/app_preference.h | 176 | ||||
-rwxr-xr-x | include/app_preference_internal.h | 152 | ||||
-rwxr-xr-x | include/app_preference_log.h | 92 | ||||
-rwxr-xr-x | include/app_preference_private.h | 52 | ||||
-rwxr-xr-x | include/app_service.h | 672 | ||||
-rwxr-xr-x | include/app_service_private.h | 37 | ||||
-rw-r--r-- | include/app_storage.h | 226 | ||||
-rwxr-xr-x | include/app_storage_private.h | 60 | ||||
-rw-r--r-- | include/app_types.h | 52 | ||||
-rwxr-xr-x | include/app_ui_notification.h | 459 |
17 files changed, 2269 insertions, 1898 deletions
diff --git a/include/app.h b/include/app.h index 362178b..f1bb296 100755 --- a/include/app.h +++ b/include/app.h @@ -11,199 +11,190 @@ * distributed under the License is distributed on an AS IS BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and - * limitations under the License. + * limitations under the License. */ #ifndef __TIZEN_APPFW_APP_H__ #define __TIZEN_APPFW_APP_H__ -#include <tizen.h> -#include <app_service.h> -#include <app_alarm.h> -#include <app_preference.h> -#include <app_storage.h> +#include <app_control.h> +#include <app_common.h> #include <app_i18n.h> -#include <app_ui_notification.h> +#include <app_types.h> #ifdef __cplusplus extern "C" { #endif /** - * @addtogroup CAPI_APPLICATION_MODULE - * @{ + * @file app.h */ - -/** - * @brief Enumerations of error code for Application. - */ -typedef enum -{ - APP_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */ - APP_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */ - APP_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of memory */ - APP_ERROR_INVALID_CONTEXT = TIZEN_ERROR_NOT_PERMITTED, /**< Invalid application context */ - APP_ERROR_NO_SUCH_FILE = TIZEN_ERROR_NO_SUCH_FILE, /**< No such file or directory */ - APP_ERROR_ALREADY_RUNNING = TIZEN_ERROR_ALREADY_IN_PROGRESS, /**< Application is already running */ -} app_error_e; - - /** - * @brief Enumerations of the device orientation. + * @addtogroup CAPI_APPLICATION_MODULE + * @{ */ -typedef enum -{ - APP_DEVICE_ORIENTATION_0 = 0, /**< The device is oriented in natural position */ - APP_DEVICE_ORIENTATION_90 = 90, /**< The device's left side is at the top */ - APP_DEVICE_ORIENTATION_180 = 180, /**< The device is upside down */ - APP_DEVICE_ORIENTATION_270 = 270, /**<The device's right side is to the top */ -} app_device_orientation_e; /** - * @brief Called at the start of the application. - * - * @details The callback function is called before the main loop of application starts. - * In this callback you can initialize application resources like window creation, data structure, etc. - * After this callback function returns @c true, the main loop starts up and app_service_cb() is subsequently called. - * If this callback function returns @c false, the main loop doesn't start and app_terminate_cb() is subsequently called. - * - * @param[in] user_data The user data passed from the callback registration function - * @return @c true on success, otherwise @c false - * @pre app_efl_main() will invoke this callback function. - * @see app_efl_main() - * @see #app_event_callback_s + * @brief Called when the application starts. + * + * @details The callback function is called before the main loop of the application starts. + * In this callback, you can initialize application resources like window creation, data structure, and so on. + * After this callback function returns @c true, the main loop starts up and app_control_cb() is subsequently called. + * If this callback function returns @c false, the main loop doesn't start and app_terminate_cb() is subsequently called. + * + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @param[in] user_data The user data passed from the callback registration function + * @return @c true on success, + * otherwise @c false + * @pre ui_app_main() will invoke this callback function. + * @see ui_app_main() + * @see #ui_app_lifecycle_callback_s */ typedef bool (*app_create_cb) (void *user_data); /** - * @brief Called when the application is completely obscured by another application and becomes invisible. + * @brief Called when the application is completely obscured by another application and becomes invisible. * - * @details The application is not terminated and still running in paused state. + * @details The application is not terminated and still running in the paused state. * - * @param[in] user_data The user data passed from the callback registration function - * @see app_efl_main() - * @see #app_event_callback_s + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @param[in] user_data The user data passed from the callback registration function + * @see ui_app_main() + * @see #ui_app_lifecycle_callback_s */ typedef void (*app_pause_cb) (void *user_data); /** - * @brief Called when the application becomes visible. + * @brief Called when the application becomes visible. * - * @remarks This callback function is not called when the application moved from created state to running state. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif * - * @param[in] user_data The user data passed from the callback registration function - * @see app_efl_main() - * @see #app_event_callback_s + * @param[in] user_data The user data passed from the callback registration function + * @see ui_app_main() + * @see #ui_app_lifecycle_callback_s */ typedef void (*app_resume_cb) (void *user_data); /** - * @brief Called once after the main loop of application exits. + * @brief Called when the application's main loop exits. * @details You should release the application's resources in this function. * - * @param[in] user_data The user data passed from the callback registration function - * @see app_efl_main() - * @see #app_event_callback_s + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @param[in] user_data The user data passed from the callback registration function + * @see ui_app_main() + * @see #ui_app_lifecycle_callback_s */ typedef void (*app_terminate_cb) (void *user_data); /** - * @brief Called when other application send the launch request to the application. - * - * @details When the application is launched, this callback function is called after the main loop of application starts up. - * The passed service handle describes the launch request and contains the information about why the application is launched. - * If the launch request is sent to the application on running or pause state, - * this callback function can be called again to notify that the application is asked to be launched. - * - * The application could be explicitly launched by the user from the application launcher or be launched to perform the specific operation by other application. - * The application is responsible for handling the each launch request and responding appropriately. - * Using the Service API, the application can get the information what has to perform. - * If the application is launched from the application launcher or explicitly launched by other application, - * the passed service handle may include only the default operation (#SERVICE_OPERATION_DEFAULT) without any data - * For more information, see The @ref CAPI_SERVICE_MODULE API description. - * - * @param[in] service The handle to the service - * @param[in] user_data The user data passed from the callback registration function - * @see app_efl_main() - * @see #app_event_callback_s - * @see @ref CAPI_SERVICE_MODULE API + * @brief Called when another application sends a launch request to the application. + * + * @details When the application is launched, this callback function is called after the main loop of the application starts up. + * The passed app_control handle describes the launch request and contains the information about why the application is launched. + * If the launch request is sent to the application in the running or pause state, + * this callback function can be called again to notify that the application has been asked to launch. + * + * The application could be explicitly launched by the user from the application launcher or be launched to perform the specific operation by another application. + * The application is responsible for handling each launch request and responding appropriately. + * Using the App Control API, the application can get information about what is to be performed. + * If the application is launched from the application launcher or explicitly launched by another application, + * the passed app_control handle may include only the default operation (#APP_CONTROL_OPERATION_DEFAULT) without any data. + * For more information, see The @ref CAPI_APP_CONTROL_MODULE API description. + * + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @param[in] app_control The handle to the app_control + * @param[in] user_data The user data passed from the callback registration function + * @see ui_app_main() + * @see #ui_app_lifecycle_callback_s + * @see @ref CAPI_APP_CONTROL_MODULE API */ -typedef void (*app_service_cb) (service_h service, void *user_data); +typedef void (*app_control_cb) (app_control_h app_control, void *user_data); /** - * @brief Called when the system memory is running low. + * @internal + * @brief Called when the system memory is running low. * - * @details - * When low memory event is dispatched, the application should immediately save state and release resources to save as much memory as possible. \n - * If enough memory is not reclaimed during low memory conditions, the system will terminate some of the applications to reclaim the memory. + * @details When a low memory event is dispatched, the application should immediately save state and release resources to save as much memory as possible. \n + * If enough memory is not reclaimed during low memory conditions, the system will terminate some of the applications to reclaim the memory. * - * @param[in] user_data The user data passed from the callback registration function - * @see app_efl_main() + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @param[in] user_data The user data passed from the callback registration function + * @see app_main() * @see #app_event_callback_s */ typedef void (*app_low_memory_cb) (void *user_data); /** - * @brief Called when the battery power is running low. + * @internal + * @brief Called when the battery power is running low. * @details When the battery level falls below 5%, it is called. * - * @param[in] user_data The user data passed from the callback registration function - * @see app_efl_main() + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @param[in] user_data The user data passed from the callback registration function + * @see app_main() * @see #app_event_callback_s */ typedef void (*app_low_battery_cb) (void *user_data); /** - * @brief Called when the orientation of device changes. + * @internal + * @brief Called when the orientation of the device changes. * - * @param[in] orientation The orientation of device - * @param[in] user_data The user data passed from the callback registration function - * @see app_efl_main() + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @param[in] orientation The orientation of the device + * @param[in] user_data The user data passed from the callback registration function + * @see app_main() * @see #app_event_callback_s */ typedef void (*app_device_orientation_cb) (app_device_orientation_e orientation, void *user_data); /** - * @brief Called when language setting changes. + * @internal + * @brief Called when language setting changes. * - * @param [in] user_data The user data passed from the callback registration function - * @see app_efl_main() + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @param[in] user_data The user data passed from the callback registration function + * @see app_main() * @see #app_event_callback_s */ typedef void (*app_language_changed_cb) (void *user_data); /** - * @brief Called when region format setting changes. + * @internal + * @brief Called when region format setting changes. * - * @param [in] user_data The user data passed from the callback registration function - * @see app_efl_main() + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @param[in] user_data The user data passed from the callback registration function + * @see app_main() * @see #app_event_callback_s */ typedef void (*app_region_format_changed_cb) (void *user_data); /** - * @brief The structure type to contain the set of callback functions for handling application events. - * @details It is one of the input parameters of the app_efl_main() function. + * @internal + * @brief The structure type containing the set of callback functions for handling application events. + * @details It is one of the input parameters of the app_main() function. * - * @see app_efl_main() + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @see app_main() * @see app_create_cb() * @see app_pause_cb() * @see app_resume_cb() * @see app_terminate_cb() - * @see app_service_cb() + * @see app_control_cb() * @see app_low_memory_cb() * @see app_low_battery_cb() * @see app_device_orientation_cb() @@ -213,42 +204,104 @@ typedef void (*app_region_format_changed_cb) (void *user_data); typedef struct { app_create_cb create; /**< This callback function is called at the start of the application. */ - app_terminate_cb terminate; /**< This callback function is called once after the main loop of application exits. */ + app_terminate_cb terminate; /**< This callback function is called once after the main loop of the application exits. */ app_pause_cb pause; /**< This callback function is called each time the application is completely obscured by another application and becomes invisible to the user. */ app_resume_cb resume; /**< This callback function is called each time the application becomes visible to the user. */ - app_service_cb service; /**< This callback function is called when other application send the launch request to the application. */ + app_control_cb app_control; /**< This callback function is called when another application sends the launch request to the application. */ app_low_memory_cb low_memory; /**< The registered callback function is called when the system runs low on memory. */ - app_low_battery_cb low_battery; /**< The registered callback function is called when battery is low. */ - app_device_orientation_cb device_orientation; /**< The registered callback function is called when the orientation of device changes */ + app_low_battery_cb low_battery; /**< The registered callback function is called when the battery is low. */ + app_device_orientation_cb device_orientation; /**< The registered callback function is called when the orientation of the device changes */ app_language_changed_cb language_changed; /**< The registered callback function is called when language setting changes. */ - app_region_format_changed_cb region_format_changed; /**< The registered callback function is called when region format setting is changes. */ + app_region_format_changed_cb region_format_changed; /**< The registered callback function is called when region format setting changes. */ } app_event_callback_s; /** - * @brief Runs the main loop of application until app_efl_exit() is called + * @brief The structure type containing the set of callback functions for handling application lifecycle events. + * @details It is one of the input parameters of the ui_app_main() function. + * + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @see ui_app_main() + * @see app_create_cb() + * @see app_pause_cb() + * @see app_resume_cb() + * @see app_terminate_cb() + * @see app_control_cb() + */ +typedef struct +{ + app_create_cb create; /**< This callback function is called at the start of the application. */ + app_terminate_cb terminate; /**< This callback function is called once after the main loop of the application exits. */ + app_pause_cb pause; /**< This callback function is called each time the application is completely obscured by another application and becomes invisible to the user. */ + app_resume_cb resume; /**< This callback function is called each time the application becomes visible to the user. */ + app_control_cb app_control; /**< This callback function is called when another application sends the launch request to the application. */ +} ui_app_lifecycle_callback_s; + + +/** + * @internal + * @brief Runs the application's main loop until app_exit() is called. * * @details This function is the main entry point of the Tizen application. - * The app_create_cb() callback function is called to initialize the application before the main loop of application starts up. - * After the app_create_cb() callback function returns true, the main loop starts up and the app_service_cb() callback function is subsequently called. - * If the app_create_cb() callback function returns false, the main loop doesn't start up and app_terminate_cb() callback function is called + * The app_create_cb() callback function is called to initialize the application before the main loop of application starts up. + * After the app_create_cb() callback function returns true, the main loop starts up and the app_control_cb() callback function is subsequently called. + * If the app_create_cb() callback function returns false, the main loop doesn't start up and app_terminate_cb() callback function is called. * - * @param [in] argc The argument count - * @param [in] argv The argument vector - * @param [in] callback The set of callback functions to handle application events - * @param [in] user_data The user data to be passed to the callback functions + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @param[in] argc The argument count + * @param[in] argv The argument vector + * @param[in] callback The set of callback functions to handle application events + * @param[in] user_data The user data to be passed to the callback functions * - * @return 0 on success, otherwise a negative error value. + * @return 0 on success, otherwise a negative error value * @retval #APP_ERROR_NONE Successful * @retval #APP_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #APP_ERROR_INVALID_CONTEXT The application is illegally launched, not launched by the launch system. + * @retval #APP_ERROR_INVALID_CONTEXT The application is illegally launched, not launched by the launch system * @retval #APP_ERROR_ALREADY_RUNNING The main loop already starts * * @see app_create_cb() * @see app_terminate_cb() * @see app_pause_cb() * @see app_resume_cb() - * @see app_service_cb() + * @see app_control_cb() + * @see app_low_memory_cb() + * @see app_low_battery_cb() + * @see app_device_orientation_cb() + * @see app_language_changed_cb() + * @see app_region_format_changed_cb() + * @see app_exit() + * @see #app_event_callback_s + */ +int app_main(int argc, char **argv, app_event_callback_s *callback, void *user_data); + + +/** + * @internal + * @brief Runs the application's main loop until app_efl_exit() is called. + * + * @details This function is the main entry point of the Tizen application. + * The app_create_cb() callback function is called to initialize the application before the main loop of the application starts up. + * After the app_create_cb() callback function returns @c true, the main loop starts up and the app_control_cb() callback function is subsequently called. + * If the app_create_cb() callback function returns @c false, the main loop doesn't start up and the app_terminate_cb() callback function is called. + * + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @param[in] argc The argument count + * @param[in] argv The argument vector + * @param[in] callback The set of callback functions to handle application events + * @param[in] user_data The user data to be passed to the callback functions + * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #APP_ERROR_NONE Successful + * @retval #APP_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #APP_ERROR_INVALID_CONTEXT The application is illegally launched, not launched by the launch system + * @retval #APP_ERROR_ALREADY_RUNNING The main loop has already started + * + * @see app_create_cb() + * @see app_terminate_cb() + * @see app_pause_cb() + * @see app_resume_cb() + * @see app_control_cb() * @see app_low_memory_cb() * @see app_low_battery_cb() * @see app_device_orientation_cb() @@ -261,133 +314,169 @@ int app_efl_main(int *argc, char ***argv, app_event_callback_s *callback, void * /** + * @internal * @brief Exits the main loop of application. * - * @details The main loop of application stops and app_terminate_cb() is invoked + * @details The main loop of application stops and app_terminate_cb() is invoked. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @see app_main() + * @see app_terminate_cb() + */ +void app_exit(void); + + +/** + * @internal + * @brief Exits the main loop of the application. + * + * @details The main loop of the application stops and app_terminate_cb() is invoked. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif * @see app_efl_main() - * @see app_terminate_cb() + * @see app_terminate_cb() */ void app_efl_exit(void); /** - * @brief Gets the name of the application package. - * - * @remarks @a package must be released with free() by you. - * - * @param [out] package The name of the application package - * - * @return 0 on success, otherwise a negative error value. + * @brief Gets the current device orientation. * - * @retval #APP_ERROR_NONE Successful - * @retval #APP_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #APP_ERROR_INVALID_CONTEXT The application is illegally launched, not launched by the launch system. - * @retval #APP_ERROR_OUT_OF_MEMORY Out of memory + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @return The current device orientation */ -int app_get_package(char **package); +app_device_orientation_e app_get_device_orientation(void); /** - * @brief Gets the ID of the application. - * - * @remarks @a ID must be released with free() by you. + * @internal + * @brief Sets whether reclaiming system cache is enabled in the pause state. * - * @param [out] id The ID of the application + * @details If reclaiming system cache is enabled, the system caches are released as possible when the application's state changes to the pause state. * - * @return 0 on success, otherwise a negative error value. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @remarks Reclaiming system cache is enabled by default. * - * @retval #APP_ERROR_NONE Successful - * @retval #APP_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #APP_ERROR_INVALID_CONTEXT The application is illegally launched, not launched by the launch system. - * @retval #APP_ERROR_OUT_OF_MEMORY Out of memory + * @param[in] enable If @c true reclaiming system cache is enabled, + * otherwise @c false */ -int app_get_id(char **id); - +void app_set_reclaiming_system_cache_on_pause(bool enable); /** - * @brief Gets the localized name of the application. - * - * @remarks @a name must be released with free() by you. + * @internal + * @brief Gets the preinitialized window object. * - * @param [out] name The name of the application + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @remarks This API only supports BASIC type window. * - * @return 0 on success, otherwise a negative error value. + * @param[in] win_name The name to be set for the preinitialized window * - * @retval #APP_ERROR_NONE Successful - * @retval #APP_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #APP_ERROR_INVALID_CONTEXT The application is illegally launched, not launched by the launch system. - * @retval #APP_ERROR_OUT_OF_MEMORY Out of memory + * @return A @a window object on success, + * otherwise @c NULL */ -int app_get_name(char **name); - +void* app_get_preinitialized_window(const char* win_name); /** - * @brief Gets the version of the application package. + * @internal + * @brief Gets the preinitialized background object added to the preinitialized window. * - * @remarks @a version must be released with free() by you. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @remarks This API should be called after calling app_get_preinitizlized_window(). * - * @param [out] version The version of the application + * @return A @a background object on success, + * otherwise @c NULL + */ +void* app_get_preinitialized_background(void); + +/** + * @internal + * @brief Gets the preinitialized conformant widget added to the preinitialized window. * - * @return 0 on success, otherwise a negative error value. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @remarks This API should be called after calling app_get_preinitizlized_window(). * - * @retval #APP_ERROR_NONE Successful - * @retval #APP_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #APP_ERROR_INVALID_CONTEXT The application is illegally launched, not launched by the launch system. - * @retval #APP_ERROR_OUT_OF_MEMORY Out of memory + * @return A conformant object on success, + * otherwise @c NULL */ -int app_get_version(char **version); +void* app_get_preinitialized_conformant(void); /** - * @brief Gets the absolute path to the resource included in application package + * @brief Runs the application's main loop until ui_app_exit() is called. * - * @details The application cannot write and modify any resource files. - * - * @remarks This function stores the absolute path into the @a buffer at most one less than @a size bytes - * and a null character is appended in @a buffer after the path stored. + * @details This function is the main entry point of the Tizen application. + * The app_create_cb() callback function is called to initialize the application before the main loop of application starts up. + * After the app_create_cb() callback function returns true, the main loop starts up and the app_control_cb() callback function is subsequently called. + * If the app_create_cb() callback function returns false, the main loop doesn't start up and app_terminate_cb() callback function is called. + * This main loop supports event handling for the Ecore Main Loop. + * + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @param[in] argc The argument count + * @param[in] argv The argument vector + * @param[in] callback The set of callback functions to handle application lifecycle events + * @param[in] user_data The user data to be passed to the callback functions + * + * @return 0 on success, otherwise a negative error value + * @retval #APP_ERROR_NONE Successful + * @retval #APP_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #APP_ERROR_INVALID_CONTEXT The application is illegally launched, not launched by the launch system + * @retval #APP_ERROR_ALREADY_RUNNING The main loop already starts * - * @param [in] resource The resource's path relative to the resource directory of the application package (e.g. edje/app.edj or images/background.png) - * @param [in] buffer The pre-allocated buffer where the absolute path to the resource is stored. - * @param [in] size The size of @a buffer in bytes - * @return @a buffer on success, otherwise NULL. + * @see app_create_cb() + * @see app_terminate_cb() + * @see app_pause_cb() + * @see app_resume_cb() + * @see app_control_cb() + * @see ui_app_exit() + * @see #ui_app_lifecycle_callback_s */ -char* app_get_resource(const char *resource, char *buffer, int size); +int ui_app_main(int argc, char **argv, ui_app_lifecycle_callback_s *callback, void *user_data); /** - * @brief Gets the absolute path to the application's data directory. - * - * @details An application can read and write its own data files in the application's data directory. + * @brief Exits the main loop of application. * - * @remarks This function stores the absolute path into the @a buffer at most one less than @a size bytes - * and a null character is appended in @a buffer after the path stored. + * @details The main loop of application stops and app_terminate_cb() is invoked. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif * - * @param [in] buffer The pre-allocated buffer where the absolute path to the application data directory - * @param [in] size The size of @a buffer in bytes - * @return @a buffer on success, otherwise NULL. + * @see ui_app_main() + * @see app_terminate_cb() */ -char* app_get_data_directory(char *buffer, int size); +void ui_app_exit(void); /** - * @brief Gets the current device orientation. + * @brief Adds the system event handler * - * @return The current device orientation + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @param[out] event_handler The event handler + * @param[in] event_type The system event type + * @param[in] callback The callback function + * @param[in] user_data The user data to be passed to the callback functions + * + * @return 0 on success, otherwise a negative error value + * @retval #APP_ERROR_NONE Successful + * @retval #APP_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #APP_ERROR_OUT_OF_MEMORY Out of memory + * + * @see app_event_type_e + * @see app_event_cb + * @see ui_app_remove_event_handler */ -app_device_orientation_e app_get_device_orientation(void); +int ui_app_add_event_handler(app_event_handler_h *event_handler, app_event_type_e event_type, app_event_cb callback, void *user_data); /** - * @brief Sets whether reclaiming system cache is enabled in the pause state. + * @brief Removes registered event handler * - * @details If the reclaiming system cache is enabled, the system caches are released as possible when the application's state changes to the pause state. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @param[in] event_handler The event handler * - * @remarks The reclaiming system cache is enabled by default + * @return 0 on success, otherwise a negative error value + * @retval #APP_ERROR_NONE Successful + * @retval #APP_ERROR_INVALID_PARAMETER Invalid parameter * - * @param [in] enable whether reclaiming system cache is enabled + * @see ui_app_add_event_handler */ -void app_set_reclaiming_system_cache_on_pause(bool enable); - +int ui_app_remove_event_handler(app_event_handler_h event_handler); /** * @} diff --git a/include/app_alarm.h b/include/app_alarm.h index 5dba683..ba2b4fb 100755 --- a/include/app_alarm.h +++ b/include/app_alarm.h @@ -11,7 +11,7 @@ * distributed under the License is distributed on an AS IS BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and - * limitations under the License. + * limitations under the License. */ @@ -20,38 +20,46 @@ #include <tizen.h> #include <time.h> -#include <app_service.h> +#include <app_control.h> #ifdef __cplusplus extern "C" { #endif /** + * @file app_alarm.h + */ + +/** * @addtogroup CAPI_ALARM_MODULE * @{ */ /** - * @brief Service extra data : the id of the alarm registered + * @brief Definition to app_control extra data : the ID of the alarm registered. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif */ -#define SERVICE_DATA_ALARM_ID "http://tizen.org/appcontrol/data/alarm_id" +#define APP_CONTROL_DATA_ALARM_ID "http://tizen.org/appcontrol/data/alarm_id" /** - * @brief Enumerations of error codes for the alarm + * @brief Enumeration for Alarm Error. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif */ typedef enum { ALARM_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */ ALARM_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */ - ALARM_ERROR_INVALID_TIME = TIZEN_ERROR_APPLICATION_CLASS | 0x05, /**< Invalid time */ - ALARM_ERROR_INVALID_DATE = TIZEN_ERROR_APPLICATION_CLASS | 0x06, /**< Invalid date */ - ALARM_ERROR_CONNECTION_FAIL = TIZEN_ERROR_APPLICATION_CLASS | 0x07, /**< The alarm service connection failed */ - ALARM_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY /**< Out of memory */ + ALARM_ERROR_INVALID_TIME = TIZEN_ERROR_APPLICATION | 0x05, /**< Invalid time */ + ALARM_ERROR_INVALID_DATE = TIZEN_ERROR_APPLICATION | 0x06, /**< Invalid date */ + ALARM_ERROR_CONNECTION_FAIL = TIZEN_ERROR_APPLICATION | 0x07, /**< The alarm service connection failed */ + ALARM_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of memory */ + ALARM_ERROR_PERMISSION_DENIED = TIZEN_ERROR_PERMISSION_DENIED /**< Permission denied */ } alarm_error_e; /** - * @brief Enumerations of the days of the week. + * @brief Enumeration for Alarm Week Flag, the days of the week. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif */ typedef enum { @@ -65,105 +73,128 @@ typedef enum } alarm_week_flag_e; /** - * @brief Called once for each scheduled alarm to get the alarm ID. + * @brief Called once for each scheduled alarm to get the alarm ID. * - * @param[in] alarm_id The alarm ID returned when the alarm is scheduled - * @param[in] user_data The user data passed from the foreach function - * @return @c true to continue with the next iteration of the loop, \n @c false to break out of the loop. - * @pre alarm_foreach_registered_alarm() will invoke this callback to get all registered alarm IDs. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @param[in] alarm_id The alarm ID returned when the alarm is scheduled + * @param[in] user_data The user data passed from the foreach function + * @return @c true to continue with the next iteration of the loop, + * otherwise @c false to break out of the loop + * @pre alarm_foreach_registered_alarm() will invoke this callback to get all the registered alarm IDs. * @see alarm_foreach_registered_alarm() */ typedef bool (*alarm_registered_alarm_cb)(int alarm_id, void *user_data); /** - * @brief Sets an alarm to be triggered after specific time. + * @brief Sets an alarm to be triggered after a specific time. * @details The alarm will first go off @a delay seconds later and then will go off every certain amount of time defined using @a period seconds. - * If @a period is bigger than 0, the alarm will be scheduled after the @a period time. - * If @a period is set to 0, the alarm will go off just once without repetition. - * To cancel the alarm, call alarm_cancel() with @alarm_id + * If @a period is bigger than @c 0, the alarm will be scheduled after the @a period time. + * If @a period is set to @c 0, the alarm will go off just once without repetition. + * To cancel the alarm, call alarm_cancel() with @a alarm_id. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @privlevel public + * @privilege %http://tizen.org/privilege/alarm.set + * @remarks If the application is uninstalled after setting an alarm, the alarm is cancelled automatically. * - * @remarks If application is uninstalled after setting an alarm, the alarm is canceled automatically. - * - * @param[in] service The destination service to perform specific work when the alarm is triggered. - * @param[in] delay The amount of time before first execution(in second) - * @param[in] period The amount of time between subsequent alarms(in second) - * @param[out] alarm_id The alarm ID uniquely identifies an alarm - * @return 0 on success, otherwise a negative error value. + * @param[in] app_control The destination app_control to perform a specific task when the alarm is triggered + * @param[in] delay The amount of time before the first execution (in seconds) + * @param[in] period The amount of time between subsequent alarms (in seconds) + * @param[out] alarm_id The alarm ID that uniquely identifies an alarm + * @return @c 0 on success, + * otherwise a negative error value * @retval #ALARM_ERROR_NONE Successful * @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter * @retval #ALARM_ERROR_INVALID_TIME Triggered time is invalid * @retval #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server + * @retval #ALARM_ERROR_PERMISSION_DENIED Permission denied * @see alarm_cancel() * @see alarm_cancel_all() * @see alarm_get_scheduled_date() * @see alarm_get_scheduled_period() */ -int alarm_schedule_after_delay(service_h service, int delay, int period, int *alarm_id); +int alarm_schedule_after_delay(app_control_h app_control, int delay, int period, int *alarm_id); /** - * @brief Sets an alarm to be triggered at a specific time. - * @details - * The @a date describes the time of first occurrence. - * If @a period is bigger than 0, the alarm will be scheduled after the @a period time. - * If @a period is set to 0, the alarm will go off just once without repetition. - * To cancel the alarm, call alarm_cancel() with alarm id + * @brief Sets an alarm to be triggered at a specific time. + * @details The @a date describes the time of the first occurrence. + * If @a period is bigger than @c 0, the alarm will be scheduled after the @a period time. + * If @a period is set to @c 0, the alarm will go off just once without repetition. + * To cancel the alarm, call alarm_cancel() with @a alarm_id. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @privlevel public + * @privilege %http://tizen.org/privilege/alarm.set + * @remarks If application is uninstalled after setting an alarm, the alarm is cancelled automatically. + * If the operation of @a app_control is not specified, #APP_CONTROL_OPERATION_DEFAULT is used for the launch request. + * If the operation of @a app_control is #APP_CONTROL_OPERATION_DEFAULT, the package information is mandatory to explicitly launch the application. * - * @remarks If application is uninstalled after setting an alarm, the alarm is canceled automatically. - * - * @param[in] service The destination service to perform specific work when the alarm is triggered + * @param[in] app_control The destination app_control to perform specific work when the alarm is triggered * @param[in] date The first active alarm time * @param[in] period The amount of time between subsequent alarms(in second) - * @param[out] alarm_id The alarm ID uniquely identifies an alarm - * @return 0 on success, otherwise a negative error value. + * @param[out] alarm_id The alarm ID that uniquely identifies an alarm + * @return @c 0 on success, + * otherwise a negative error value * @retval #ALARM_ERROR_NONE Successful * @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter * @retval #ALARM_ERROR_INVALID_DATE Triggered date is invalid * @retval #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server + * @retval #ALARM_ERROR_PERMISSION_DENIED Permission denied * @see alarm_cancel() * @see alarm_cancel_all() * @see alarm_get_scheduled_date() * @see alarm_get_scheduled_period() */ -int alarm_schedule_at_date(service_h service, struct tm *date, int period, int *alarm_id); - +int alarm_schedule_at_date(app_control_h app_control, struct tm *date, int period, int *alarm_id); /** - * @brief Sets an alarm to be triggered at a specific time with recurrence repeat. - * @details - * The @a date describes the time of first occurrence. - * @a week_flag is the repeat value of days of the week. If @a week_flag is #ALARM_WEEK_FLAG_TUESDAY, the alarm will repeat at every Tuesday specific time. - * To cancel the alarm, call alarm_cancel() with the @alarm_id - * @remarks If application is uninstalled after setting an alarm, the alarm is canceled automatically. + * @brief Sets an alarm to be triggered periodically, starting at a specific time. + * @details The @a date describes the time of the first occurrence. + * @a week_flag is the repeat value of the days of the week. + * If @a week_flag is #ALARM_WEEK_FLAG_TUESDAY, the alarm will repeat every Tuesday at a specific time. + * To cancel the alarm, call alarm_cancel() with @a alarm_id. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @privlevel public + * @privilege %http://tizen.org/privilege/alarm.set + * @remarks If the application is uninstalled after setting an alarm, the alarm is cancelled automatically. + * If the operation of @a app_control is not specified, #APP_CONTROL_OPERATION_DEFAULT is used for the launch request. + * If the operation of @a app_control is #APP_CONTROL_OPERATION_DEFAULT, the package information is mandatory to explicitly launch the application. * - * @param[in] service The destination service to perform specific work when the alarm is triggered. - * @param[in] date The first active alarm time - * @param[in] week_flag The day of the week, @a week_flag may be a combination of days, like #ALARM_WEEK_FLAG_TUESDAY | #ALARM_WEEK_FLAG_FRIDAY. - * @param[out] alarm_id The alarm ID uniquely identifies an alarm - * @return 0 on success, otherwise a negative error value. - * @retval #ALARM_ERROR_NONE Successful - * @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #ALARM_ERROR_INVALID_DATE Triggered date is invalid - * @retval #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server + * @param[in] app_control The destination app_control to perform specific work when the alarm is triggered + * @param[in] date The first active alarm time + * @param[in] week_flag The day of the week, @a week_flag may be a combination of days, like #ALARM_WEEK_FLAG_TUESDAY | #ALARM_WEEK_FLAG_FRIDAY + * @param[out] alarm_id The alarm ID that uniquely identifies an alarm + * @return @c 0 on success, + * otherwise a negative error value + * @retval #ALARM_ERROR_NONE Successful + * @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #ALARM_ERROR_INVALID_DATE Triggered date is invalid + * @retval #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server + * @retval #ALARM_ERROR_PERMISSION_DENIED Permission denied * @see alarm_cancel() * @see alarm_cancel_all() * @see alarm_get_scheduled_recurrence_week_flag() - * @see alarm_get_scheduled_recurrence_week_flag() * @see alarm_get_scheduled_date() * @see #alarm_week_flag_e */ -int alarm_schedule_with_recurrence_week_flag(service_h service, struct tm *date, int week_flag,int *alarm_id); +int alarm_schedule_with_recurrence_week_flag(app_control_h app_control, struct tm *date, int week_flag,int *alarm_id); /** * @brief Gets the recurrence days of the week. - * @remarks If the given @a alarm_id is not obtained by using the alarm_schedule_with_recurrence_week_flag() function, - * an error (error code #ALARM_ERROR_INVALID_PARAMETER) will occur because this alarm is scheduled with no recurrence. - * @param[in] alarm_id The alarm ID returned when the alarm is scheduled - * @param[out] week_flag The recurrence days of the week, @a week_flag may be a combination of days, like #ALARM_WEEK_FLAG_TUESDAY | #ALARM_WEEK_FLAG_FRIDAY. - * @return 0 on success, otherwise a negative error value. - * @retval #ALARM_ERROR_NONE Successful - * @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @privlevel public + * @privilege %http://tizen.org/privilege/alarm.get + * @remarks If the given @a alarm_id is not obtained by using the alarm_schedule_with_recurrence_week_flag() function, + * an error (error code #ALARM_ERROR_INVALID_PARAMETER) will occur because this alarm is scheduled with no recurrence. + * If the operation of @a app_control is not specified, #APP_CONTROL_OPERATION_DEFAULT is used for the launch request. + * If the operation of @a app_control is #APP_CONTROL_OPERATION_DEFAULT, the package information is mandatory to explicitly launch the application. + * @param[in] alarm_id The alarm ID returned when the alarm is scheduled + * @param[out] week_flag The recurrence days of the week, @a week_flag may be a combination of days, like #ALARM_WEEK_FLAG_TUESDAY | #ALARM_WEEK_FLAG_FRIDAY + * @return @c 0 on success, + * otherwise a negative error value + * @retval #ALARM_ERROR_NONE Successful + * @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #ALARM_ERROR_PERMISSION_DENIED Permission denied * @see alarm_schedule_with_recurrence_week_flag() * @see #alarm_week_flag_e */ @@ -171,11 +202,16 @@ int alarm_get_scheduled_recurrence_week_flag(int alarm_id, int *week_flag); /** - * @brief Cancels the alarm with the specific alarm ID. - * @param[in] alarm_id The alarm ID that will be canceled - * @return 0 on success, otherwise a negative error value. - * @retval #ALARM_ERROR_NONE Successful - * @retval #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server + * @brief Cancels the alarm with the specific alarm ID. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @privlevel public + * @privilege %http://tizen.org/privilege/alarm.set + * @param[in] alarm_id The alarm ID that is cancelled + * @return @c 0 on success, + * otherwise a negative error value + * @retval #ALARM_ERROR_NONE Successful + * @retval #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server + * @retval #ALARM_ERROR_PERMISSION_DENIED Permission denied * @see alarm_schedule_at_date() * @see alarm_schedule_after_delay() * @see alarm_schedule_with_recurrence_week_flag() @@ -185,11 +221,15 @@ int alarm_cancel(int alarm_id); /** - * @brief Cancels all alarms scheduled. - * - * @return 0 on success, otherwise a negative error value. + * @brief Cancels all scheduled alarms that are registered by the application that calls this API. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @privlevel public + * @privilege %http://tizen.org/privilege/alarm.set + * @return @c 0 on success, + * otherwise a negative error value * @retval #ALARM_ERROR_NONE Successful * @retval #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server + * @retval #ALARM_ERROR_PERMISSION_DENIED Permission denied * @see alarm_schedule_at_date() * @see alarm_schedule_after_delay() * @see alarm_schedule_with_recurrence_week_flag() @@ -199,29 +239,37 @@ int alarm_cancel_all(void); /** - * @brief Retrieves the IDs of all registered alarms by invoking callback once for each scheduled alarm. - * - * @param[in] callback The callback function to invoke - * @param[in] user_data The user data to be passed to the callback function - * @return 0 on success, otherwise a negative error value. - * @retval #ALARM_ERROR_NONE Successful - * @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server - * @post This function invokes alarm_registered_alarm_cb() repeatedly for each registered alarm. + * @brief Retrieves the IDs of all registered alarms by invoking a callback once for each scheduled alarm. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @privlevel public + * @privilege %http://tizen.org/privilege/alarm.get + * @param[in] callback The callback function to invoke + * @param[in] user_data The user data to be passed to the callback function + * @return @c 0 on success, + * otherwise a negative error value + * @retval #ALARM_ERROR_NONE Successful + * @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server + * @retval #ALARM_ERROR_PERMISSION_DENIED Permission denied + * @post This function invokes alarm_registered_alarm_cb() repeatedly for each registered alarm. * @see alarm_registered_alarm_cb() */ int alarm_foreach_registered_alarm(alarm_registered_alarm_cb callback, void *user_data); /** - * @brief Gets the scheduled time from the given alarm ID in C standard time struct. - * - * @param[in] alarm_id The alarm ID returned when the alarm is scheduled - * @param[out] date The time value of next alarm event - * @return 0 on success, otherwise a negative error value. - * @retval #ALARM_ERROR_NONE Successful - * @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server + * @brief Gets the scheduled time from the given alarm ID in C standard time struct. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @privlevel public + * @privilege %http://tizen.org/privilege/alarm.get + * @param[in] alarm_id The alarm ID returned when the alarm is scheduled + * @param[out] date The time value of the next alarm event + * @return @c 0 on success, + * otherwise a negative error value + * @retval #ALARM_ERROR_NONE Successful + * @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server + * @retval #ALARM_ERROR_PERMISSION_DENIED Permission denied * @see alarm_schedule_at_date() * @see alarm_schedule_after_delay() * @see alarm_schedule_with_recurrence_week_flag() @@ -230,15 +278,20 @@ int alarm_get_scheduled_date(int alarm_id, struct tm *date); /** - * @brief Gets the period of time between the recurrent alarms. - * @remarks If the given @a alarm_id is not obtained by using the alarm_get_scheduled_date() or alarm_schedule_after_delay() function, - * an error (error code #ALARM_ERROR_INVALID_PARAMETER) will occur. - * @param[in] alarm_id The alarm ID returned when the alarm is scheduled - * @param[out] period The period of time between recurrent alarms in seconds - * @return 0 on success, otherwise a negative error value. - * @retval #ALARM_ERROR_NONE Successful - * @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server + * @brief Gets the period of time between the recurrent alarms. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @privlevel public + * @privilege %http://tizen.org/privilege/alarm.get + * @remarks If the given @a alarm_id is not obtained by using the alarm_get_scheduled_date() or alarm_schedule_after_delay() function, + * an error (error code #ALARM_ERROR_INVALID_PARAMETER) will occur. + * @param[in] alarm_id The alarm ID returned when the alarm is scheduled + * @param[out] period The period of time between recurrent alarms in seconds + * @return @c 0 on success, + * otherwise a negative error value + * @retval #ALARM_ERROR_NONE Successful + * @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server + * @retval #ALARM_ERROR_PERMISSION_DENIED Permission denied * @see alarm_schedule_at_date() * @see alarm_schedule_after_delay() * @see alarm_schedule_with_recurrence_week_flag() @@ -247,30 +300,37 @@ int alarm_get_scheduled_period(int alarm_id, int *period); /** - * @brief Gets the current system time using C standard time struct. - * + * @brief Gets the current system time using C standard time struct. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif * @param[out] date The current system time - * @return 0 on success, otherwise a negative error value. - * @retval #ALARM_ERROR_NONE Successful - * @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter + * @return @c 0 on success, + * otherwise a negative error value + * @retval #ALARM_ERROR_NONE Successful + * @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #ALARM_ERROR_PERMISSION_DENIED Permission denied */ int alarm_get_current_time(struct tm *date); /** - * @brief Gets the service to be invoked when the the alarm is triggered - * @remarks The @a service must be released with service_destroy() by you. - * @param[in] alarm_id The alarm ID uniquely identifies an alarm - * @param[out] service The service handle to launch when the alarm is triggered - * @return 0 on success, otherwise a negative error value. + * @brief Gets the app_control to be invoked when the the alarm is triggered. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @privlevel public + * @privilege %http://tizen.org/privilege/alarm.get + * @remarks The @a app_control must be released using app_control_destroy(). + * @param[in] alarm_id The alarm ID uniquely identifies an alarm + * @param[out] app_control The app_control handle to launch when the alarm is triggered + * @return @c 0 on success, + * otherwise a negative error value * @retval #ALARM_ERROR_NONE Successful * @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter * @retval #ALARM_ERROR_OUT_OF_MEMORY Out of memory + * @retval #ALARM_ERROR_PERMISSION_DENIED Permission denied * @see alarm_schedule_at_date() * @see alarm_schedule_after_delay() * @see alarm_schedule_with_recurrence_week_flag() */ -int alarm_get_service(int alarm_id, service_h *service); +int alarm_get_app_control(int alarm_id, app_control_h *app_control); /** * @} diff --git a/include/app_common.h b/include/app_common.h new file mode 100644 index 0000000..f025299 --- /dev/null +++ b/include/app_common.h @@ -0,0 +1,411 @@ +/* + * Copyright (c) 2014 Samsung Electronics Co., Ltd All Rights Reserved + * + * Licensed under the Apache License, Version 2.0 (the License); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an AS IS BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + + +#ifndef __TIZEN_APPFW_APP_COMMON_H__ +#define __TIZEN_APPFW_APP_COMMON_H__ + +#include <app_types.h> + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @file app_common.h + */ + +/** + * @addtogroup CAPI_APP_COMMON_MODULE + * @{ + */ + + +/** + * @brief Enumeration for system events + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + */ +typedef enum +{ + APP_EVENT_LOW_MEMORY, /**< The low memory event */ + APP_EVENT_LOW_BATTERY, /**< The low battery event */ + APP_EVENT_LANGUAGE_CHANGED, /**< The system language changed event */ + APP_EVENT_DEVICE_ORIENTATION_CHANGED, /**< The device orientation changed event */ + APP_EVENT_REGION_FORMAT_CHANGED, /**< The region format changed event */ +} app_event_type_e; + + +/** + * @brief Enumeration for device orientation. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + */ +typedef enum +{ + APP_DEVICE_ORIENTATION_0 = 0, /**< The device is oriented in a natural position */ + APP_DEVICE_ORIENTATION_90 = 90, /**< The device's left side is at the top */ + APP_DEVICE_ORIENTATION_180 = 180, /**< The device is upside down */ + APP_DEVICE_ORIENTATION_270 = 270, /**< The device's right side is at the top */ +} app_device_orientation_e; + + +/** + * @brief Enumeration for low memory status. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + */ +typedef enum +{ + APP_EVENT_LOW_MEMORY_NORMAL = 0x01, /**< Normal status */ + APP_EVENT_LOW_MEMORY_SOFT_WARNING = 0x02, /**< Soft warning status */ + APP_EVENT_LOW_MEMORY_HARD_WARNING = 0x04, /**< Hard warning status */ +} app_event_low_memory_status_e; + + +/** + * @brief Enumeration for battery status. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + */ +typedef enum +{ + APP_EVENT_LOW_BATTERY_POWER_OFF = 1, /**< The battery status is under 1% */ + APP_EVENT_LOW_BATTERY_CRITICAL_LOW, /**< The battery status is under 5% */ +} app_event_low_battery_status_e; + + +/** + * @brief The event handler that returned from add event handler function + * + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @see app_event_type_e + * @see app_add_event_handler + * @see app_remove_event_handler + * @see app_event_info_h + */ +typedef struct app_event_handler* app_event_handler_h; + + +/** + * @brief The system event information + * + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @see app_event_get_low_memory_status + * @see app_event_get_low_battery_status + * @see app_event_get_language + * @see app_event_get_region_format + * @see app_event_get_device_orientation + */ +typedef struct app_event_info* app_event_info_h; + + +/** + * @brief The system event callback function + * + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @param[in] event_info The system event information + * @param[in] user_data The user data passed from the add event handler function + * + * @see app_add_event_handler + * @see app_event_info_h + */ +typedef void (*app_event_cb)(app_event_info_h event_info, void *user_data); + + +/** + * @brief Gets the low memory status from given event info + * + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @param[in] event_info The system event info + * @param[out] status The low memory status + * + * @return 0 on success, otherwise a negative error value + * @retval #APP_ERROR_NONE Successful + * @retval #APP_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #APP_ERROR_INVALID_CONTEXT Invalid event context + * + * @see app_event_info_h + * @see app_event_low_memory_status_e + */ +int app_event_get_low_memory_status(app_event_info_h event_info, app_event_low_memory_status_e *status); + + +/** + * @brief Gets the low battery status from given event info + * + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @param[in] event_info The system event info + * @param[out] status The low battery status + * + * @return 0 on success, otherwise a negative error value + * @retval #APP_ERROR_NONE Successful + * @retval #APP_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #APP_ERROR_INVALID_CONTEXT Invalid event context + * + * @see app_event_info_h + * @see app_event_low_battery_status_e + */ +int app_event_get_low_battery_status(app_event_info_h event_info, app_event_low_battery_status_e *status); + + +/** + * @brief Gets the language from given event info + * + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @remarks @a lang must be released using free() + * @param[in] event_info The system event info + * @param[out] lang The language changed + * + * @return 0 on success, otherwise a negative error value + * @retval #APP_ERROR_NONE Successful + * @retval #APP_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #APP_ERROR_INVALID_CONTEXT Invalid event context + * + * @see app_event_info_h + */ +int app_event_get_language(app_event_info_h event_info, char **lang); + + +/** + * @brief Gets the region format from given event info + * + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @remarks @a region must be released using free() + * @param[in] event_info The system event info + * @param[out] region The region format changed + * + * @return 0 on success, otherwise a negative error value + * @retval #APP_ERROR_NONE Successful + * @retval #APP_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #APP_ERROR_INVALID_CONTEXT Invalid event context + * + * @see app_event_info_h + */ +int app_event_get_region_format(app_event_info_h event_info, char **region); + + +/** + * @brief Gets the device orientation from given event info + * + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @param[in] event_info The system event info + * @param[out] orientation The device orientation changed + * + * @return 0 on success, otherwise a negative error value + * @retval #APP_ERROR_NONE Successful + * @retval #APP_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #APP_ERROR_INVALID_CONTEXT Invalid event context + * + * @see app_event_info_h + * @see app_device_orientation_e + */ +int app_event_get_device_orientation(app_event_info_h event_info, app_device_orientation_e *orientation); + + +/** + * @brief Gets the ID of the application. + * + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @remarks @a id must be released using free(). + * + * @param[out] id The ID of the application + * + * @return @c 0 on success, + * otherwise a negative error value + * + * @retval #APP_ERROR_NONE Successful + * @retval #APP_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #APP_ERROR_INVALID_CONTEXT The application is illegally launched, not launched by the launch system + * @retval #APP_ERROR_OUT_OF_MEMORY Out of memory + */ +int app_get_id(char **id); + + +/** + * @brief Gets the localized name of the application. + * + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @remarks @a name must be released using free(). + * + * @param[out] name The name of the application + * + * @return @c 0 on success, + * otherwise a negative error value + * + * @retval #APP_ERROR_NONE Successful + * @retval #APP_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #APP_ERROR_INVALID_CONTEXT The application is illegally launched, not launched by the launch system + * @retval #APP_ERROR_OUT_OF_MEMORY Out of memory + */ +int app_get_name(char **name); + + +/** + * @brief Gets the version of the application package. + * + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @remarks @a version must be released using free(). + * + * @param[out] version The version of the application + * + * @return @c 0 on success, + * otherwise a negative error value + * + * @retval #APP_ERROR_NONE Successful + * @retval #APP_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #APP_ERROR_INVALID_CONTEXT The application is illegally launched, not launched by the launch system + * @retval #APP_ERROR_OUT_OF_MEMORY Out of memory + */ +int app_get_version(char **version); + + +/** + * @brief Gets the absolute path to the application's data directory which is used to store private + * data of the application. + * @details An application can read and write its own files in the application's data directory. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @remarks The returned path should be released. + * + * @return The absolute path to the application's data directory, @n + * otherwise a null pointer if the memory is insufficient + */ +char *app_get_data_path(void); + + +/** + * @brief Gets the absolute path to the application's cache directory which is used to store + * temporary data of the application. + * @details An application can read and write its own files in the application's cache directory. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @remarks The returned path should be released. @n + * The files stored in the application's cache directory can be removed by Setting + * application or platform while the application is running. + * + * @return The absolute path to the application's cache directory, @n + * otherwise a null pointer if the memory is insufficient + */ +char *app_get_cache_path(void); + + +/** + * @brief Gets the absolute path to the application resource directory. The resource files + * are delivered with the application package. + * @details An application can only read its own files in the application's resource directory. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @remarks The returned path should be released. + * + * @return The absolute path to the application's resource directory, @n + * otherwise a null pointer if the memory is insufficient + */ +char *app_get_resource_path(void); + + +/** + * @brief Gets the absolute path to the application's shared data directory which is used to share + * data with other applications. + * @details An application can read and write its own files in the application's shared data + * directory and others can only read the files. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @remarks The returned path should be released. + * + * @return The absolute path to the application's shared data directory, @n + * otherwise a null pointer if the memory is insufficient + */ +char *app_get_shared_data_path(void); + + +/** + * @brief Gets the absolute path to the application's shared resource directory which is used to + * share resources with other applications. + * @details An application can read its own files in the application's shared resource directory + * and others can only read the files. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @remarks The returned path should be released. + * + * @return The absolute path to the application's shared resource directory, @n + * otherwise a null pointer if the memory is insufficient + */ +char *app_get_shared_resource_path(void); + + +/** + * @brief Gets the absolute path to the application's shared trusted directory which is used to share data + * with a family of trusted applications. + * @details An application can read and write its own files in the application's shared trusted directory + * and the family applications signed with the same certificate can read and write the files in the + * shared trusted directory. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @remarks The returned path should be released. + * + * @return The absolute path to the application's shared trusted directory, @n + * otherwise a null pointer if the memory is insufficient + */ +char *app_get_shared_trusted_path(void); + + +/** + * @brief Gets the absolute path to the application's external data directory which is used to + * store data of the application. + * @details An application can read and write its own files in the application's external data + * directory. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @remarks The returned path should be released. @n + * The important files stored in the application's external data directory should be + * encrypted because they can be exported via the external sdcard. + * + * @return The absolute path to the application's external data directory, @n + * otherwise a null pointer if the memory is insufficient + */ +char *app_get_external_data_path(void); + + +/** + * @brief Gets the absolute path to the application's external cache directory which is used to + * store temporary data of the application. + * @details An application can read and write its own files in the application's external cache + * directory. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @remarks The returned path should be released. @n + * The files stored in the application's external cache directory can be removed by + * Setting application while the application is running. @n + * The important files stored in the application's external cache directory should be + * encrypted because they can be exported via the external sdcard. + * + * @return The absolute path to the application's external cache directory, @n + * otherwise a null pointer if the memory is insufficient + */ +char *app_get_external_cache_path(void); + + +/** + * @brief Gets the absolute path to the application's external shared data directory which is + * used to share data with other applications. + * @details An application can read and write its own files in the application's external shared + * data directory and others can only read the files. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @remarks The specified @a path should be released. + * + * @return The absolute path to the application's external shared data directory, @n + * otherwise a null pointer if the memory is insufficient + */ +char *app_get_external_shared_data_path(void); + +/** + * @} + */ + +#ifdef __cplusplus +} +#endif + +#endif /* __TIZEN_APPFW_APP_H__ */ diff --git a/include/app_control.h b/include/app_control.h new file mode 100755 index 0000000..83eddb7 --- /dev/null +++ b/include/app_control.h @@ -0,0 +1,877 @@ +/* + * Copyright (c) 2014 Samsung Electronics Co., Ltd All Rights Reserved + * + * Licensed under the Apache License, Version 2.0 (the License); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an AS IS BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + + +#ifndef __TIZEN_APPFW_APP_CONTROL_H__ +#define __TIZEN_APPFW_APP_CONTROL_H__ + +#include <tizen.h> + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @file app_control.h + */ + +/** + * @addtogroup CAPI_APP_CONTROL_MODULE + * @{ + */ + + +typedef struct _bundle_t bundle; + + +/** + * @brief App Control handle. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + */ +typedef struct app_control_s* app_control_h; + + +/** + * @brief Enumeration for App Control Error. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + */ +typedef enum +{ + APP_CONTROL_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */ + APP_CONTROL_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */ + APP_CONTROL_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of memory */ + APP_CONTROL_ERROR_APP_NOT_FOUND = TIZEN_ERROR_APPLICATION | 0x21, /**< The application is not found */ + APP_CONTROL_ERROR_KEY_NOT_FOUND = TIZEN_ERROR_KEY_NOT_AVAILABLE, /**< Specified key is not found */ + APP_CONTROL_ERROR_KEY_REJECTED = TIZEN_ERROR_KEY_REJECTED, /**< Key is not available */ + APP_CONTROL_ERROR_INVALID_DATA_TYPE = TIZEN_ERROR_APPLICATION | 0x22, /**< Invalid data type */ + APP_CONTROL_ERROR_LAUNCH_REJECTED = TIZEN_ERROR_APPLICATION | 0x23, /**< The application cannot be launched now*/ + APP_CONTROL_ERROR_PERMISSION_DENIED = TIZEN_ERROR_PERMISSION_DENIED, /**< Permission denied */ + APP_CONTROL_ERROR_LAUNCH_FAILED = TIZEN_ERROR_APPLICATION | 0x24, /**< Internal launch error */ + APP_CONTROL_ERROR_TIMED_OUT = TIZEN_ERROR_TIMED_OUT /**< Time out */ +} app_control_error_e; + + +/** + * @brief Enumeration for App Control Result. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + */ +typedef enum +{ + APP_CONTROL_RESULT_SUCCEEDED = 0, /**< Operation succeeded */ + APP_CONTROL_RESULT_FAILED = -1, /**< Operation failed by the callee */ + APP_CONTROL_RESULT_CANCELED = -2, /**< Operation canceled by the framework */ +} app_control_result_e; + + +/** + * @brief Definition for the app_control operation: main operation for an explicit launch. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + */ +#define APP_CONTROL_OPERATION_MAIN "http://tizen.org/appcontrol/operation/main" + + +/** + * @brief Definition for the app_control operation: default operation for an explicit launch. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + */ +#define APP_CONTROL_OPERATION_DEFAULT "http://tizen.org/appcontrol/operation/default" + + +/** + * @brief Definition for the app_control operation: provides an explicit editable access to the given data. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + */ +#define APP_CONTROL_OPERATION_EDIT "http://tizen.org/appcontrol/operation/edit" + + +/** + * @brief Definition for the app_control operation: displays the data. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + */ +#define APP_CONTROL_OPERATION_VIEW "http://tizen.org/appcontrol/operation/view" + + +/** + * @brief Definition for the app_control operation: picks an item from the data, returning what is selected. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + */ +#define APP_CONTROL_OPERATION_PICK "http://tizen.org/appcontrol/operation/pick" + + +/** + * @brief Definition for the app_control operation: creates content, returning what is created. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + */ +#define APP_CONTROL_OPERATION_CREATE_CONTENT "http://tizen.org/appcontrol/operation/create_content" + + +/** + * @brief Definition for the app_control operation: performs a call to someone specified by the data. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @privlevel public + * @privilege %http://tizen.org/privilege/call + * @remarks When you request this operation, you must declare this privilege. + */ +#define APP_CONTROL_OPERATION_CALL "http://tizen.org/appcontrol/operation/call" + + +/** + * @brief Definition for the app_control operation: delivers some data to someone else. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + */ +#define APP_CONTROL_OPERATION_SEND "http://tizen.org/appcontrol/operation/send" + + +/** + * @brief Definition for the app_control operation: delivers text data to someone else. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + */ +#define APP_CONTROL_OPERATION_SEND_TEXT "http://tizen.org/appcontrol/operation/send_text" + + +/** + * @brief Definition for the app_control operation: shares an item with someone else. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + */ +#define APP_CONTROL_OPERATION_SHARE "http://tizen.org/appcontrol/operation/share" + + +/** + * @brief Definition for the app_control operation: shares multiple items with someone else. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + */ +#define APP_CONTROL_OPERATION_MULTI_SHARE "http://tizen.org/appcontrol/operation/multi_share" + + +/** + * @brief Definition for the app_control operation: shares text data with someone else. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + */ +#define APP_CONTROL_OPERATION_SHARE_TEXT "http://tizen.org/appcontrol/operation/share_text" + + +/** + * @brief Definition for the app_control operation: dials a number as specified by the data. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + */ +#define APP_CONTROL_OPERATION_DIAL "http://tizen.org/appcontrol/operation/dial" + + +/** + * @brief Definition for the app_control operation: performs a search. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + */ +#define APP_CONTROL_OPERATION_SEARCH "http://tizen.org/appcontrol/operation/search" + + +/** + * @brief Definition for the app_control operation: downloads an item. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + */ +#define APP_CONTROL_OPERATION_DOWNLOAD "http://tizen.org/appcontrol/operation/download" + + +/** + * @brief Definition for the app_control operation: prints content. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + */ +#define APP_CONTROL_OPERATION_PRINT "http://tizen.org/appcontrol/operation/print" + +/** + * @brief Definition for the app_control operation: composes. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + */ +#define APP_CONTROL_OPERATION_COMPOSE "http://tizen.org/appcontrol/operation/compose" + +/** + * @brief Definition for app_control optional data: the subject of a message. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + */ +#define APP_CONTROL_DATA_SUBJECT "http://tizen.org/appcontrol/data/subject" + + +/** + * @brief Definition for app_control optional data: e-mail addresses. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + */ +#define APP_CONTROL_DATA_TO "http://tizen.org/appcontrol/data/to" + + +/** + * @brief Definition for app_control optional data: e-mail addresses that should be carbon copied. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + */ +#define APP_CONTROL_DATA_CC "http://tizen.org/appcontrol/data/cc" + + +/** + * @brief Definition for app_control optional data: e-mail addresses that should be blind carbon copied. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + */ +#define APP_CONTROL_DATA_BCC "http://tizen.org/appcontrol/data/bcc" + + +/** + * @brief Definition for app_control optional data: the content of the data is associated with #APP_CONTROL_OPERATION_SEND. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + */ +#define APP_CONTROL_DATA_TEXT "http://tizen.org/appcontrol/data/text" + + +/** + * @brief Definition for app_control optional data: the title of the data. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + */ +#define APP_CONTROL_DATA_TITLE "http://tizen.org/appcontrol/data/title" + + +/** + * @brief Definition for app_control optional data: the path of a selected item. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + */ +#define APP_CONTROL_DATA_SELECTED "http://tizen.org/appcontrol/data/selected" + + +/** + * @brief Definition for app_control optional data: multiple item path to deliver. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + */ +#define APP_CONTROL_DATA_PATH "http://tizen.org/appcontrol/data/path" + + +/** + * @brief Definition for app_control optional data: the selection type. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + */ +#define APP_CONTROL_DATA_SELECTION_MODE "http://tizen.org/appcontrol/data/selection_mode" + + +/** + * @brief Called when the reply of the launch request is delivered. + * + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * + * @remarks The @a request and @a reply must not be deallocated by the application. + * + * @param[in] request The app_control handle of the launch request that has been sent + * @param[in] reply The app_control handle in which the results of the callee are contained + * @param[in] result The result code of the launch request + * @param[in] user_data The user data passed from the callback registration function + * @pre When the callee replies to the launch request, this callback will be invoked. + * @see app_control_send_launch_request() + * @see app_control_reply_to_launch_request() + */ +typedef void (*app_control_reply_cb) (app_control_h request, app_control_h reply, app_control_result_e result, void *user_data); + + +/** + * @brief Called to retrieve the extra data contained in the app_control. + * + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * + * @remarks The @a key must not be deallocated by the application. + * + * @param[in] app_control The app_control handle + * @param[in] key The key of the value contained in the app_control + * @param[in] user_data The user data passed from the foreach function + * @return @c true to continue with the next iteration of the loop, + * otherwise @c false to break out of the loop + * @pre app_control_foreach_extra_data() will invoke this callback. + * @see app_control_foreach_extra_data() + */ +typedef bool (*app_control_extra_data_cb)(app_control_h app_control, const char *key, void *user_data); + + +/** + * @brief Called once for each matched application that can be launched to handle the given app_control request. + * + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @param[in] app_control The app_control handle + * @param[in] package The package name of the application that can handle the launch request of the given app_control + * @param[in] user_data The user data passed from the foreach function + * @return @c true to continue with the next iteration of the loop, + * otherwise @c false to break out of the loop + * @pre app_control_foreach_app_matched() will invoke this callback. + * @see app_control_foreach_app_matched() + */ +typedef bool (*app_control_app_matched_cb)(app_control_h app_control, const char *appid, void *user_data); + + +typedef int (*app_control_host_res_fn)(void *data); + +/** + * @brief Creates an app_control handle. + * + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @remarks The @a app_control must be released using app_control_destroy(). + * @param[out] app_control The app_control handle to be newly created on success + * @return @c 0 on success, + * otherwise a negative error value + * @retval #APP_CONTROL_ERROR_NONE Successful + * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory + * @see app_control_destroy() + */ +int app_control_create(app_control_h *app_control); + + +/** + * @brief Destroys the app_control handle and releases all its resources. + * + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @param[in] app_control The app_control handle + * @return @c 0 on success, + * otherwise a negative error value + * @retval #APP_CONTROL_ERROR_NONE Successful + * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory + * @see app_control_create() + */ +int app_control_destroy(app_control_h app_control); + + +/** + * @internal + * @brief Converts the app_control handle to bundle data. + * + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @param[in] app_control The app_control handle + * @param[out] data The bundle data on success + * @return @c 0 on success, + * otherwise a negative error value + * @retval #APP_CONTROL_ERROR_NONE Successful + * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter + */ +int app_control_to_bundle(app_control_h app_control, bundle **data); + +/** + * @brief Sets the operation to be performed. + * + * @details The @a operation is the mandatory information for the launch request. + * If the operation is not specified, #APP_CONTROL_OPERATION_DEFAULT is used for the launch request. + * If the operation is #APP_CONTROL_OPERATION_DEFAULT, the package information is mandatory to explicitly launch the application. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @param[in] app_control The app_control handle + * @param[in] operation The operation to be performed (if the @a operation is @c NULL, it clears the previous value) + * @return @c 0 on success, + * otherwise a negative error value + * @retval #APP_CONTROL_ERROR_NONE Successful + * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter + * @see app_control_get_operation() + * @see APP_CONTROL_OPERATION_DEFAULT + * @see APP_CONTROL_OPERATION_EDIT + * @see APP_CONTROL_OPERATION_VIEW + * @see APP_CONTROL_OPERATION_PICK + * @see APP_CONTROL_OPERATION_CREATE_CONTENT + * @see APP_CONTROL_OPERATION_CALL + * @see APP_CONTROL_OPERATION_SEND + * @see APP_CONTROL_OPERATION_SEND_TEXT + * @see APP_CONTROL_OPERATION_DIAL + * @see APP_CONTROL_OPERATION_SEARCH + */ +int app_control_set_operation(app_control_h app_control, const char *operation); + + +/** + * @brief Gets the operation to be performed. + * + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @remarks The @a operation must be released using free(). + * @param[in] app_control The app_control handle + * @param[out] operation The operation to be performed + * @return @c 0 on success, + * otherwise a negative error value + * @retval #APP_CONTROL_ERROR_NONE Successful + * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory + * @see app_control_set_operation() + */ +int app_control_get_operation(app_control_h app_control, char **operation); + + +/** + * @brief Sets the URI of the data. + * + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @param[in] app_control The app_control handle + * @param[in] uri The URI of the data this app_control is operating on (if the @a uri is @c NULL, it clears the previous value) + * @return @c 0 on success, + * otherwise a negative error value + * @retval #APP_CONTROL_ERROR_NONE Successful + * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter + * @see app_control_get_uri() + */ +int app_control_set_uri(app_control_h app_control, const char *uri); + + +/** + * @brief Gets the URI of the data. + * + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @remarks The @a uri must be released using free(). + * @param[in] app_control The app_control handle + * @param[out] uri The URI of the data this app_control is operating on + * @return @c 0 on success, + * otherwise a negative error value + * @retval #APP_CONTROL_ERROR_NONE Successful + * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory + * @see app_control_set_uri() + */ +int app_control_get_uri(app_control_h app_control, char **uri); + + +/** + * @brief Sets the explicit MIME type of the data. + * + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @param[in] app_control The app_control handle + * @param[in] mime The explicit MIME type of the data this app_control is operating on (if the @a mime is @c NULL, it clears the previous value) + * @return @c 0 on success, + * otherwise a negative error value + * @retval #APP_CONTROL_ERROR_NONE Successful + * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter + * @see app_control_get_mime() + */ +int app_control_set_mime(app_control_h app_control, const char *mime); + + +/** + * @brief Gets the explicit MIME type of the data. + * + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @remarks The @a uri must be released using free(). + * @param[in] app_control The app_control handle + * @param[out] mime The explicit MIME type of the data this app_control is operating on + * @return @c 0 on success, + * otherwise a negative error value + * @retval #APP_CONTROL_ERROR_NONE Successful + * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory + * @see app_control_set_mime() + */ +int app_control_get_mime(app_control_h app_control, char **mime); + + +/** + * @brief Sets the explicit category. + * + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @param[in] app_control The app_control handle + * @param[in] category The explicit category (if the @a category is @c NULL, it clears the previous value) + * @return @c 0 on success, + * otherwise a negative error value + * @retval #APP_CONTROL_ERROR_NONE Successful + * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter + * @see app_control_get_category() + */ +int app_control_set_category(app_control_h app_control, const char *category); + + +/** + * @brief Gets the explicit category. + * + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @remarks The @a category must be released using free(). + * @param[in] app_control The app_control handle + * @param[out] category The explicit category + * @return @c 0 on success, + * otherwise a negative error value + * @retval #APP_CONTROL_ERROR_NONE Successful + * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory + * @see app_control_set_category() + */ +int app_control_get_category(app_control_h app_control, char **category); + + +/** + * @brief Sets the ID of the application to explicitly launch. + * + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @param[in] app_control The app_control handle + * @param[in] app_id The ID of the application to explicitly launch (if the @a app_id is @c NULL, it clears the previous value) + * @return @c 0 on success, + * otherwise a negative error value + * @retval #APP_CONTROL_ERROR_NONE Successful + * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory + * @see app_control_get_app_id() + */ +int app_control_set_app_id(app_control_h app_control, const char *app_id); + + +/** + * @brief Gets the ID of the application to explicitly launch. + * + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @remarks The @a app_id must be released with free(). + * @param[in] app_control The app_control handle + * @param[out] app_id The ID of the application to explicitly launch + * @return @c 0 on success, + * otherwise a negative error value + * @retval #APP_CONTROL_ERROR_NONE Successful + * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory + * @see app_control_set_app_id() + */ +int app_control_get_app_id(app_control_h app_control, char **app_id); + +/** + * @internal + * @brief Sets the window ID of the application. + * + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @param[in] app_control The app_control handle + * @param[in] id The window ID of the caller application (if the @a id is not positive, it clears the previous value) + * @return @c 0 on success, + * otherwise a negative error value + * @retval #APP_CONTROL_ERROR_NONE Successful + * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory + * @see app_control_get_window() + */ +int app_control_set_window(app_control_h app_control, unsigned int id); + + +/** + * @internal + * @brief Gets the window ID of the application. + * + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @param[in] app_control The app_control handle + * @param[out] id The window ID of the caller application + * @return @c 0 on success, + * otherwise a negative error value + * @retval #APP_CONTROL_ERROR_NONE Successful + * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory + * @see app_control_set_app_id() +*/ +int app_control_get_window(app_control_h app_control, unsigned int *id); + + +/** + * @brief Adds extra data to the app_control. + * + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @remarks The function replaces any existing value for the given key. + * @remarks The function returns #APP_CONTROL_ERROR_INVALID_PARAMETER if @a key or @a value is a zero-length string. + * @remarks The function returns #APP_CONTROL_ERROR_KEY_REJECTED if the application tries to use the same key with system-defined key. + * @param[in] app_control The app_control handle + * @param[in] key The name of the extra data + * @param[in] value The value associated with the given key + * @return @c 0 on success, + * otherwise a negative error value + * @retval #APP_CONTROL_ERROR_NONE Successful + * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #APP_CONTROL_ERROR_KEY_REJECTED Key not available + * @see app_control_add_extra_data_array() + * @see app_control_remove_extra_data() + * @see app_control_get_extra_data() + */ +int app_control_add_extra_data(app_control_h app_control, const char *key, const char *value); + + +/** + * @brief Adds the extra data array to the app_control. + * + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @remarks The function replaces any existing value for the given key. + * @remarks The function returns #APP_CONTROL_ERROR_INVALID_PARAMETER if @a key is a zero-length string. + * @remarks The function returns #APP_CONTROL_ERROR_KEY_REJECTED if the application tries to use the same key with system-defined key. + * @param[in] app_control The app_control handle + * @param[in] key The name of the extra data + * @param[in] value The array value associated with the given key + * @param[in] length The length of the array + * @return @c 0 on success, + * otherwise a negative error value + * @retval #APP_CONTROL_ERROR_NONE Successful + * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #APP_CONTROL_ERROR_KEY_REJECTED Key not available + * @see app_control_add_extra_data() + * @see app_control_remove_extra_data() + * @see app_control_get_extra_data() + */ +int app_control_add_extra_data_array(app_control_h app_control, const char *key, const char* value[], int length); + + +/** + * @brief Removes the extra data from the app_control. + * + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @param[in] app_control The app_control handle + * @param[in] key The name of the extra data + * @return @c 0 on success, + * otherwise a negative error value + * @retval #APP_CONTROL_ERROR_NONE Successful + * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #APP_CONTROL_ERROR_KEY_NOT_FOUND Specified key not found + * @see app_control_add_extra_data() + * @see app_control_add_extra_data_array() + * @see app_control_get_extra_data() + */ +int app_control_remove_extra_data(app_control_h app_control, const char *key); + + +/** + * @brief Gets the extra data from the app_control. + * + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @remarks The @a value must be released using free(). + * @remarks The function returns #APP_CONTROL_ERROR_INVALID_DATA_TYPE if @a value is of array data type. + * @param[in] app_control The app_control handle + * @param[in] key The name of the extra data + * @param[out] value The value associated with the given key + * @return @c 0 on success, + * otherwise a negative error value + * @retval #APP_CONTROL_ERROR_NONE Successful + * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #APP_CONTROL_ERROR_KEY_NOT_FOUND Specified key not found + * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory + * @retval #APP_CONTROL_ERROR_INVALID_DATA_TYPE Invalid data type + * @see app_control_add_extra_data() + * @see app_control_add_extra_data_array() + * @see app_control_get_extra_data() + * @see app_control_remove_extra_data() + * @see app_control_foreach_extra_data() + */ +int app_control_get_extra_data(app_control_h app_control, const char *key, char **value); + + +/** + * @brief Gets the extra data array from the app_control. + * + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @remarks The @a value must be released using free(). + * @remarks The function returns #APP_CONTROL_ERROR_INVALID_DATA_TYPE if @a value is not of array data type. + * @param[in] app_control The app_control handle + * @param[in] key The name of the extra data + * @param[out] value The array value associated with the given key + * @param[out] length The length of the array + * @return @c 0 on success, + * otherwise a negative error value + * @retval #APP_CONTROL_ERROR_NONE Successful + * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #APP_CONTROL_ERROR_KEY_NOT_FOUND Specified key not found + * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory + * @retval #APP_CONTROL_ERROR_INVALID_DATA_TYPE Invalid data type + * @see app_control_add_extra_data() + * @see app_control_add_extra_data_array() + * @see app_control_remove_extra_data() + * @see app_control_foreach_extra_data() + */ +int app_control_get_extra_data_array(app_control_h app_control, const char *key, char ***value, int *length); + + +/** + * @brief Checks whether the extra data associated with the given @a key is of array data type. + * + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @param[in] app_control The app_control handle + * @param[in] key The name of the extra data + * @param[out] array If @c true the extra data is of array data type, + * otherwise @c false + * @return @c 0 on success, + * otherwise a negative error value + * @retval #APP_CONTROL_ERROR_NONE Successful + * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter + * @see app_control_add_extra_data() + * @see app_control_add_extra_data_array() + * @see app_control_remove_extra_data() + * @see app_control_foreach_extra_data() + */ +int app_control_is_extra_data_array(app_control_h app_control, const char *key, bool *array); + + +/** + * @brief Retrieves all extra data contained in app_control. + * @details This function calls app_control_extra_data_cb() once for each key-value pair for extra data contained in app_control. \n + * If the app_control_extra_data_cb() callback function returns @c false, then iteration will be finished. + * + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @param[in] app_control The app_control handle + * @param[in] callback The iteration callback function + * @param[in] user_data The user data to be passed to the callback function + * @return @c 0 on success, + * otherwise a negative error value + * @retval #APP_CONTROL_ERROR_NONE Successful + * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter + * @post This function invokes app_control_extra_data_cb(). + * @see app_control_extra_data_cb() + */ +int app_control_foreach_extra_data(app_control_h app_control, app_control_extra_data_cb callback, void *user_data); + + +/** + * @brief Retrieves all applications that can be launched to handle the given app_control request. + * + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @param[in] app_control The app_control handle + * @param[in] callback The iteration callback function + * @param[in] user_data The user data to be passed to the callback function + * @return @c 0 on success, + * otherwise a negative error value + * @retval #APP_CONTROL_ERROR_NONE Success + * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter + * @post This function invokes app_control_app_matched_cb(). + * @see app_control_app_matched_cb() + */ +int app_control_foreach_app_matched(app_control_h app_control, app_control_app_matched_cb callback, void *user_data); + + +/** + * @brief Sends the launch request. + * + * @details The operation is mandatory information for the launch request. \n + * If the operation is not specified, #APP_CONTROL_OPERATION_DEFAULT is used by default. + * If the operation is #APP_CONTROL_OPERATION_DEFAULT, the application ID is mandatory to explicitly launch the application. + * @remarks In some implementations of the Tizen platform, service applications are only allowed to be launched explicitly by the application in the same package; hence you should not use this function to launch the service application that is not in the your application package. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @privlevel public + * @privilege %http://tizen.org/privilege/appmanager.launch + * @param[in] app_control The app_control handle + * @param[in] callback The callback function to be called when the reply is delivered + * @param[in] user_data The user data to be passed to the callback function + * @return @c 0 on success, + * otherwise a negative error value + * @retval #APP_CONTROL_ERROR_NONE Successful + * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory + * @retval #APP_CONTROL_ERROR_APP_NOT_FOUND The application to run the given launch request is not found + * @retval #APP_CONTROL_ERROR_LAUNCH_REJECTED The application cannot be launched in current context + * @retval #APP_CONTROL_ERROR_LAUNCH_FAILED Failed to launch the application + * @retval #APP_CONTROL_ERROR_TIMED_OUT Failed due to timeout. The application that handles @a app_control may be busy + * @retval #APP_CONTROL_ERROR_PERMISSION_DENIED Permission denied + * @post If the launch request is sent for the result, the result will come back through app_control_reply_cb() from the callee application. + * @see app_control_reply_to_launch_request() + * @see app_control_reply_cb() + */ +int app_control_send_launch_request(app_control_h app_control, app_control_reply_cb callback, void *user_data); + + +/** + * @brief Sends the terminate request to the application that is launched by app_control. This API is only effective for some applications that are provided by default for handling platform default app_controls. You are not allowed to terminate other general applications using this API. + * + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @param[in] app_control The app_control handle + * @return @c 0 on success, + * otherwise a negative error value + * @retval #APP_CONTROL_ERROR_NONE Successful + * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #APP_CONTROL_ERROR_PERMISSION_DENIED Permission denied + * @see app_control_send_launch_request() + */ +int app_control_send_terminate_request(app_control_h app_control); + + +/** + * @brief Replies to the launch request sent by the caller. + * @details If the caller application sent the launch request to receive the result, the callee application can return the result back to the caller. + * + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @param[in] reply The app_control handle in which the results of the callee are contained + * @param[in] request The app_control handle sent by the caller + * @param[in] result The result code of the launch request + * @return @c 0 on success, + * otherwise a negative error value + * @retval #APP_CONTROL_ERROR_NONE Successful + * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory + * @see app_control_send_launch_request() + */ +int app_control_reply_to_launch_request(app_control_h reply, app_control_h request, app_control_result_e result); + + +/** + * @brief Creates and returns a copy of the given app_control handle. + * + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @remarks A newly created app_control should be destroyed by calling app_control_destroy() if it is no longer needed. + * + * @param[out] clone If successful, a newly created app_control handle will be returned + * @param[in] app_control The app_control handle + * @return @c 0 on success, + * otherwise a negative error value + * @retval #APP_CONTROL_ERROR_NONE Successful + * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory + * @see app_control_destroy() + */ +int app_control_clone(app_control_h *clone, app_control_h app_control); + + +/** + * @brief Gets the application ID of the caller from the launch request. + * + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @remarks The @a app_control must be the launch request from app_control_cb(). + * @remarks This function returns #APP_CONTROL_ERROR_INVALID_PARAMETER if the given app_control is not the launch request. + * @remarks The @a id must be released using free(). + * @param[in] app_control The app_control handle from app_control_cb() + * @param[out] id The application ID of the caller + * @return @a 0 on success, + * otherwise a negative error value + * @retval #APP_CONTROL_ERROR_NONE Successful + * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory + */ +int app_control_get_caller(app_control_h app_control, char **id); + + +/** + * @brief Checks whether the caller is requesting a reply from the launch request. + * + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @remarks The @a app_control must be the launch request from app_control_cb(). + * @remarks This function returns #APP_CONTROL_ERROR_INVALID_PARAMETER if the given app_control is not the launch request. + * @param[in] app_control The app_control handle from app_control_cb() + * @param[out] requested If @c true a reply is requested by the caller, + * otherwise @c false + * @return @c 0 on success, + * otherwise a negative error value + * @retval #APP_CONTROL_ERROR_NONE Successful + * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory + */ +int app_control_is_reply_requested(app_control_h app_control, bool *requested); + +/** + * @internal + * @brief Requests the specified callee window to be transient for the caller window. + * + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @remarks The @a callee_id window is transient for the top-level caller window and should be handled accordingly. + * @param[in] app_control The app_control handle + * @param[in] callee_id The callee window ID + * @param[in] cbfunc The callback function to be called when the transient is requested + * @param[in] data A data pointer to pass to the callback function + * @return @c 0 on success, + * otherwise a negative error value. + * @retval #APP_CONTROL_ERROR_NONE Successful + * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter + */ +int app_control_request_transient_app(app_control_h app_control, unsigned int callee_id, app_control_host_res_fn cbfunc, void *data); + +/** + * @} + */ + +#ifdef __cplusplus +} +#endif + +#endif /* __TIZEN_APPFW_APP_CONTROL_H__ */ diff --git a/include/app_control_internal.h b/include/app_control_internal.h new file mode 100644 index 0000000..3daa86b --- /dev/null +++ b/include/app_control_internal.h @@ -0,0 +1,95 @@ +/* + * Copyright (c) 2014 Samsung Electronics Co., Ltd All Rights Reserved + * + * Licensed under the Apache License, Version 2.0 (the License); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an AS IS BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +#ifndef __TIZEN_APPFW_APP_CONTROL_INTERNAL_H__ +#define __TIZEN_APPFW_APP_CONTROL_INTERNAL_H__ + +#include <bundle.h> + +#include <app_control.h> + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @file app_control_internal.h + */ + +/** + * @addtogroup CAPI_APP_CONTROL_MODULE + * @{ + */ + +/** + * @brief Replaces all data in the app_control with the bundle + * + * @remarks This function clears all data in the app_control and adds all key-value pairs in the bundle into the app_control + * @param [in] app_control The app_control handle + * @param [in] data The bundle handle + * @return 0 on success, otherwise a negative error value. + * @retval #APP_CONTROL_ERROR_NONE Successful + * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter + * @see app_control_export_as_bundle() + * @code + * + * #include <bundle.h> + * #include <app_control.h> + * + * app_control_h app_control = NULL; + * app_control_create(&app_control); + * app_control_import_from_bundle(app_control, b); + * + * @endcode + * + */ +int app_control_import_from_bundle(app_control_h app_control, bundle *data); + +/** + * @brief Returns a new bundle containing all data contained int the app_control + * + * @remarks The @a data must be released with bundle_free() by you. + * @param [in] app_control The app_control handle + * @param [out] data The bundle handle + * @return 0 on success, otherwise a negative error value. + * @retval #APP_CONTROL_ERROR_NONE Successful + * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter + * @see app_control_import_from_bundle() + * @code + * + * #include <bundle.h> + * #include <app_control.h> + * + * bundle* b = NULL; + * app_control_export_as_bundle(app_control, &b); + * + * @endcode + */ +int app_control_export_as_bundle(app_control_h app_control, bundle **data); + +int app_control_create_request(bundle *data, app_control_h *app_control); + +int app_control_create_event(bundle *data, app_control_h *app_control); + +/** + * @} + */ + +#ifdef __cplusplus +} +#endif + +#endif /* __TIZEN_APPFW_APP_CONTROL_INTERNAL_H__ */ diff --git a/include/app_i18n.h b/include/app_i18n.h index d6f1e81..69e0ce7 100755 --- a/include/app_i18n.h +++ b/include/app_i18n.h @@ -11,7 +11,7 @@ * distributed under the License is distributed on an AS IS BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and - * limitations under the License. + * limitations under the License. */ @@ -25,26 +25,34 @@ extern "C" { #endif +/** + * @file app_i18n.h + */ + /** * @addtogroup CAPI_I18N_MODULE * @{ */ /** - * @brief Marks a string for translation, gets replaced with the translated string at runtime. - * @param [in] msg The string to be translated. + * @brief Definition to mark a string for translation, which is replaced with the translated string at runtime. + * @param[in] msg The string to be translated */ +#ifndef _ #define _(msg) i18n_get_text(msg) +#endif /** * @brief Gets the localized translation for the specified string. * - * @details If a translation was not found in the localization file(.po file), @a message is returned. + * @details If a translation is not found in the localization file(.po file), @a message is returned. * - * @remarks Do not free returned value + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @remarks Do not free the returned value. * - * @param [in] message The string to be translated - * @return The localized translation for the given @a message on success, otherwise the given @a message. + * @param[in] message The string to be translated + * @return The localized translation for the given @a message on success, + * otherwise the given @a message */ char* i18n_get_text(const char *message); diff --git a/include/app_private.h b/include/app_internal.h index e949f8a..c42458e 100755 --- a/include/app_private.h +++ b/include/app_internal.h @@ -11,29 +11,23 @@ * distributed under the License is distributed on an AS IS BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and - * limitations under the License. + * limitations under the License. */ -#ifndef __TIZEN_APPFW_APP_PRIVATE_H__ -#define __TIZEN_APPFW_APP_PRIVATE_H__ - -#include <appcore-common.h> - -// GNU gettext macro is already defined at appcore-common.h -#ifdef _ -#undef _ -#endif - -#include <app.h> +#ifndef __TIZEN_APPFW_APP_INTERNAL_H__ +#define __TIZEN_APPFW_APP_INTERNAL_H__ #ifdef __cplusplus extern "C" { #endif +#include <app.h> +#include <appcore-common.h> + #define TIZEN_PATH_MAX 1024 -#define PATH_FMT_APP_ROOT "/opt/apps" +#define PATH_FMT_APP_ROOT "/opt/usr/apps" #define PATH_FMT_RES_DIR PATH_FMT_APP_ROOT "/%s/res" #define PATH_FMT_LOCALE_DIR PATH_FMT_RES_DIR "/locale" #define PATH_FMT_DATA_DIR PATH_FMT_APP_ROOT "/%s/data" @@ -42,6 +36,19 @@ extern "C" { #define PATH_FMT_RO_RES_DIR PATH_FMT_RO_APP_ROOT "/%s/res" #define PATH_FMT_RO_LOCALE_DIR PATH_FMT_RO_RES_DIR "/locale" +struct app_event_handler { + app_event_type_e type; + app_event_cb cb; + void *data; +}; + +struct app_event_info { + app_event_type_e type; + void *value; +}; + +app_device_orientation_e app_convert_appcore_rm(enum appcore_rm rm); + typedef void (*app_finalizer_cb) (void *data); int app_error(app_error_e error, const char* function, const char *description); @@ -56,8 +63,10 @@ int app_finalizer_remove(app_finalizer_cb callback); void app_finalizer_execute(void); +int app_get_package(char **package); + #ifdef __cplusplus } #endif -#endif /* __TIZEN_APPFW_APP_PRIVATE_H__ */ +#endif /* __TIZEN_APPFW_APP_INTERNAL_H__ */ diff --git a/include/app_preference.h b/include/app_preference.h index 9aeb3af..8b2ff86 100755 --- a/include/app_preference.h +++ b/include/app_preference.h @@ -11,7 +11,7 @@ * distributed under the License is distributed on an AS IS BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and - * limitations under the License. + * limitations under the License. */ @@ -25,32 +25,38 @@ extern "C" { #endif /** - * @addtogroup CAPI_PREFERENCE_MODULE + * @file app_preference.h + */ + +/** + * @addtogroup CAPI_PREFERENCE_MODULE * @{ */ /** - * @brief Enumerations of error code for Preference. + * @brief Enumeration for Preference Error. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif */ typedef enum { PREFERENCE_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */ PREFERENCE_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */ PREFERENCE_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of memory */ - PREFERENCE_ERROR_NO_KEY = TIZEN_ERROR_KEY_NOT_AVAILABLE, /**< Required key not available */ + PREFERENCE_ERROR_NO_KEY = TIZEN_ERROR_APPLICATION | 0x30, /**< Required key not available */ PREFERENCE_ERROR_IO_ERROR = TIZEN_ERROR_IO_ERROR , /**< Internal I/O Error */ } preference_error_e; /** - * @brief Called when the given key's value in the preference changes. + * @brief Called when the given key's value in the preference changes. * - * @details When the @a key is added or removed, this callback function is skipped. (only update can be handled) + * @details When the @a key is added or removed, this callback function is skipped(only update can be handled). * - * @param [in] key The name of the key in the preference - * @param [in] user_data The user data passed from the callback registration function - * @pre This function is invoked when the value of the key is overwritten after you register this callback using preference_set_changed_cb() + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @param[in] key The name of the key in the preference + * @param[in] user_data The user data passed from the callback registration function + * @pre This function is invoked when the value of the key is overwritten after you register this callback using preference_set_changed_cb(). * @see preference_set_changed_cb() * @see preference_unset_changed_cb() * @see preference_set_boolean() @@ -62,42 +68,47 @@ typedef void (*preference_changed_cb) (const char *key, void *user_data); /** -* @brief Called to get key string once for each key-value pair in the preference. -* -* @remarks You should not free @a key returned by this function. -* -* @param [in] key The key of the value added to the preference -* @param [in] value The value associated with the key -* @param [in] user_data The user data passed from the foreach function -* @return @c true to continue with the next iteration of the loop, \n @c false to break out of the loop. -* @pre preference_foreach_item() will invoke this callback function. -* @see preference_foreach_item() -*/ + * @brief Called to get key string, once for each key-value pair in the preference. + * + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @remarks You should not free the @a key returned by this function. + * + * @param[in] key The key of the value added to the preference + * @param[in] value The value associated with the key + * @param[in] user_data The user data passed from the foreach function + * @return @c true to continue with the next iteration of the loop, + * otherwise @c false to break out of the loop + * @pre preference_foreach_item() will invoke this callback function. + * @see preference_foreach_item() + */ typedef bool (*preference_item_cb)(const char *key, void *user_data); /** * @brief Sets an integer value in the preference. * - * @param [in] key The name of the key to modify - * @param [in] value The new @c int value for the given key - * @return 0 on success, otherwise a negative error value. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @param[in] key The name of the key to modify + * @param[in] value The new @c int value for the given key + * @return @c 0 on success, + * otherwise a negative error value * @retval #PREFERENCE_ERROR_NONE Successful * @retval #PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter * @retval #PREFERENCE_ERROR_IO_ERROR Internal I/O Error * @see preference_get_int() - * */ int preference_set_int(const char *key, int value); /** - * @brief Gets a integer value from the preference. + * @brief Gets an integer value from the preference. * - * @param [in] key The name of the key to retrieve - * @param [out] value The @c int value for the given key - * @return 0 on success, otherwise a negative error value. - * @retval #PREFERENCE_ERROR_NONE Successful + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @param[in] key The name of the key to retrieve + * @param[out] value The @c int value for the given key + * @return @c 0 on success, + * otherwise a negative error value + * @retval #PREFERENCE_ERROR_NONE Successful * @retval #PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter * @retval #PREFERENCE_ERROR_NO_KEY Required key not available * @retval #PREFERENCE_ERROR_IO_ERROR Internal I/O Error @@ -109,14 +120,15 @@ int preference_get_int(const char *key, int *value); /** * @brief Sets a double value in the preference. * - * @param [in] key The name of the key to modify - * @param [in] value The new @c double value associated with given key - * @return 0 on success, otherwise a negative error value. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @param[in] key The name of the key to modify + * @param[in] value The new @c double value associated with the given key + * @return @c 0 on success, + * otherwise a negative error value * @retval #PREFERENCE_ERROR_NONE Successful * @retval #PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter * @retval #PREFERENCE_ERROR_IO_ERROR Internal I/O Error * @see preference_get_double() - * */ int preference_set_double(const char *key, double value); @@ -124,15 +136,16 @@ int preference_set_double(const char *key, double value); /** * @brief Gets a double value from the preference. * - * @param [in] key The name of the key to retrieve - * @param [out] value The @c double value associated with given key - * @return 0 on success, otherwise a negative error value. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @param[in] key The name of the key to retrieve + * @param[out] value The @c double value associated with the given key + * @return @c 0 on success, + * otherwise a negative error value * @retval #PREFERENCE_ERROR_NONE Successful * @retval #PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter * @retval #PREFERENCE_ERROR_NO_KEY Required key not available * @retval #PREFERENCE_ERROR_IO_ERROR Internal I/O Error * @see preference_set_double() - * */ int preference_get_double(const char *key, double *value); @@ -141,15 +154,16 @@ int preference_get_double(const char *key, double *value); * @brief Sets a string value in the preference. * * @details It makes a deep copy of the added string value. - * - * @param [in] key The name of the key to modify - * @param [in] value The new @c string value associated with given key - * @return 0 on success, otherwise a negative error value. + * + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @param[in] key The name of the key to modify + * @param[in] value The new @c string value associated with the given key + * @return @c 0 on success, + * otherwise a negative error value * @retval #PREFERENCE_ERROR_NONE Successful * @retval #PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter * @retval #PREFERENCE_ERROR_IO_ERROR Internal I/O Error * @see preference_get_string() - * */ int preference_set_string(const char *key, const char *value); @@ -157,11 +171,13 @@ int preference_set_string(const char *key, const char *value); /** * @brief Gets a string value from the preference. * - * @remarks @a value must be released with free() by you. - * @param [in] key The name of the key to retrieve - * @param [out] value The @c string value associated with given key - * @return 0 on success, otherwise a negative error value. - * @retval #PREFERENCE_ERROR_NONE Successful + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @remarks @a value must be released using free(). + * @param[in] key The name of the key to retrieve + * @param[out] value The @c string value associated with the given key + * @return @c 0 on success, + * otherwise a negative error value + * @retval #PREFERENCE_ERROR_NONE Successful * @retval #PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter * @retval #PREFERENCE_ERROR_OUT_OF_MEMORY Out of memory * @retval #PREFERENCE_ERROR_NO_KEY Required key not available @@ -174,12 +190,14 @@ int preference_get_string(const char *key, char **value); /** * @brief Sets a boolean value in the preference. * - * @param [in] key The name of the key to modify - * @param [in] value The new boolean @c value associated with given key - * @return 0 on success, otherwise a negative error value. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @param[in] key The name of the key to modify + * @param[in] value The new @c boolean value associated with the given key + * @return @c 0 on success, + * otherwise a negative error value * @retval #PREFERENCE_ERROR_NONE Successful * @retval #PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #PREFERENCE_ERROR_IO_ERROR Internal I/O Error + * @retval #PREFERENCE_ERROR_IO_ERROR Internal I/O Error * @see preference_get_boolean() */ int preference_set_boolean(const char *key, bool value); @@ -188,9 +206,11 @@ int preference_set_boolean(const char *key, bool value); /** * @brief Gets a boolean value from the preference. * - * @param [in] key The name of the key to retrieve - * @param [out] value The boolean @c value associated with given key - * @return 0 on success, otherwise a negative error value. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @param[in] key The name of the key to retrieve + * @param[out] value The @c boolean value associated with the given key + * @return @c 0 on success, + * otherwise a negative error value * @retval #PREFERENCE_ERROR_NONE Successful * @retval #PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter * @retval #PREFERENCE_ERROR_NO_KEY Required key not available @@ -203,22 +223,26 @@ int preference_get_boolean(const char *key, bool *value); /** * @brief Removes any value with the given @a key from the preference. * - * @param [in] key The name of the key to remove - * @return 0 on success, otherwise a negative error value. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @param[in] key The name of the key to remove + * @return @c 0 on success, + * otherwise a negative error value * @retval #PREFERENCE_ERROR_NONE Successful - * @retval #PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter * @retval #PREFERENCE_ERROR_IO_ERROR Internal I/O Error - * */ int preference_remove(const char *key); /** - * @brief Checks whether if the given @a key exists in the preference. + * @brief Checks whether the given @a key exists in the preference. * - * @param [in] key The name of the key to check - * @param [out] existing @c true if the @a key exists in the preference, otherwise @c false - * @return 0 on success, otherwise a negative error value. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @param[in] key The name of the key to check + * @param[out] existing If @c true the @a key exists in the preference, + * otherwise @c false + * @return @c 0 on success, + * otherwise a negative error value * @retval #PREFERENCE_ERROR_NONE Successful * @retval #PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter * @retval #PREFERENCE_ERROR_IO_ERROR Internal I/O Error @@ -229,7 +253,9 @@ int preference_is_existing(const char *key, bool *existing); /** * @brief Removes all key-value pairs from the preference. * - * @return 0 on success, otherwise a negative error value. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @return @c 0 on success, + * otherwise a negative error value * @retval #PREFERENCE_ERROR_NONE Successful * @retval #PREFERENCE_ERROR_IO_ERROR Internal I/O Error * @see preference_remove() @@ -240,10 +266,12 @@ int preference_remove_all(void); /** * @brief Registers a callback function to be invoked when value of the given key in the preference changes. * - * @param [in] key The name of the key to monitor - * @param [in] callback The callback function to register - * @param [in] user_data The user data to be passed to the callback function - * @return 0 on success, otherwise a negative error value. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @param[in] key The name of the key to monitor + * @param[in] callback The callback function to register + * @param[in] user_data The user data to be passed to the callback function + * @return @c 0 on success, + * otherwise a negative error value * @retval #PREFERENCE_ERROR_NONE Successful * @retval #PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter * @retval #PREFERENCE_ERROR_OUT_OF_MEMORY Out of memory @@ -259,8 +287,10 @@ int preference_set_changed_cb(const char *key, preference_changed_cb callback, v /** * @brief Unregisters the callback function. * - * @param [in] key The name of the key to monitor - * @return 0 on success, otherwise a negative error value. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @param[in] key The name of the key to monitor + * @return @c 0 on success, + * otherwise a negative error value * @retval #PREFERENCE_ERROR_NONE Successful * @retval #PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter * @retval #PREFERENCE_ERROR_IO_ERROR Internal I/O Error @@ -272,9 +302,11 @@ int preference_unset_changed_cb(const char *key); /** * @brief Retrieves all key-value pairs in the preference by invoking the callback function. * - * @param [in] callback The callback function to get key value once for each key-value pair in the preference - * @param [in] user_data The user data to be passed to the callback function - * @return 0 on success, otherwise a negative error value. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @param[in] callback The callback function to get key value once for each key-value pair in the preference + * @param[in] user_data The user data to be passed to the callback function + * @return @c 0 on success, + * otherwise a negative error value * @retval #PREFERENCE_ERROR_NONE Successful * @retval #PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter * @retval #PREFERENCE_ERROR_IO_ERROR Internal I/O Error diff --git a/include/app_preference_internal.h b/include/app_preference_internal.h new file mode 100755 index 0000000..1d43bc2 --- /dev/null +++ b/include/app_preference_internal.h @@ -0,0 +1,152 @@ +/* + * Copyright (c) 2011 Samsung Electronics Co., Ltd All Rights Reserved + * + * Licensed under the Apache License, Version 2.0 (the License); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an AS IS BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + + +#ifndef __TIZEN_APPFW_PREFERENCE_INTERNAL_H__ +#define __TIZEN_APPFW_PREFERENCE_INTERNAL_H__ + +#ifdef __cplusplus +extern "C" { +#endif + +#include "app_preference_log.h" +#include "linux/limits.h" + +#define BUF_LEN (4096) +#define PREF_DIR ".pref/" + +#define PREFERENCE_KEY_PATH_LEN 1024 +#define ERR_LEN 128 + +#define PREF_DB_NAME ".pref.db" +#define PREF_TBL_NAME "pref" +#define PREF_F_KEY_NAME "pref_key" +#define PREF_F_TYPE_NAME "pref_type" +#define PREF_F_DATA_NAME "pref_data" + +/* ASCII VALUE */ +#define PREF_KEYNAME_C_PAD '=' +#define PREF_KEYNAME_C_PLUS '+' +#define PREF_KEYNAME_C_SLASH '/' + +#define PREF_KEYNAME_C_DOT '.' +#define PREF_KEYNAME_C_UNDERSCORE '_' +#define PREF_KEYNAME_C_HYPHEN '-' + +/** + * @brief Definition for PREFERENCE_ERROR_WRONG_PREFIX. + */ +#define PREFERENCE_ERROR_WRONG_PREFIX -2 + +/** + * @brief Definition for PREFERENCE_ERROR_WRONG_TYPE. + */ +#define PREFERENCE_ERROR_WRONG_TYPE -3 + +/** + * @brief Definition for PREFERENCE_ERROR_FILE_OPEN. + */ +#define PREFERENCE_ERROR_FILE_OPEN -21 + +/** + * @brief Definition for PREFERENCE_ERROR_FILE_FREAD. + */ +#define PREFERENCE_ERROR_FILE_FREAD -22 + +/** + * @brief Definition for PREFERENCE_ERROR_FILE_FGETS. + */ +#define PREFERENCE_ERROR_FILE_FGETS -23 + +/** + * @brief Definition for PREFERENCE_ERROR_FILE_WRITE. + */ +#define PREFERENCE_ERROR_FILE_WRITE -24 + +/** + * @brief Definition for PREFERENCE_ERROR_FILE_SYNC. + */ +#define PREFERENCE_ERROR_FILE_SYNC -25 + +/** + * @brief Definition for PREFERENCE_ERROR_FILE_CHMOD. + */ +#define PREFERENCE_ERROR_FILE_CHMOD -28 + +/** + * @brief Definition for PREFERENCE_ERROR_FILE_LOCK. + */ +#define PREFERENCE_ERROR_FILE_LOCK -29 + +typedef enum +{ + PREFERENCE_TYPE_NONE = 0, + PREFERENCE_TYPE_STRING, + PREFERENCE_TYPE_INT, + PREFERENCE_TYPE_DOUBLE, + PREFERENCE_TYPE_BOOLEAN, +} preference_type_e; + +typedef struct _pref_changed_cb_node_t{ + char *key; + preference_changed_cb cb; + void *user_data; + struct _pref_changed_cb_node_t *prev; + struct _pref_changed_cb_node_t *next; +} pref_changed_cb_node_t; + +typedef struct _keynode_t { + char *keyname; /**< Keyname for keynode */ + int type; /**< Keynode type */ + union { + int i; /**< Integer type */ + int b; /**< Bool type */ + double d; /**< Double type */ + char *s; /**< String type */ + } value; /**< Value for keynode */ + struct _keynode_t *next; /**< Next keynode */ +} keynode_t; + +/** + * @brief The structure type for opaque type. It must be used via accessor functions. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + */ +typedef struct _keylist_t { + int num; /**< Number of list */ + keynode_t *head; /**< Head node */ + keynode_t *cursor; /**< Cursor node */ +} keylist_t; + + +int _preference_kdb_add_notify + (keynode_t *keynode, preference_changed_cb cb, void *data); +int _preference_kdb_del_notify + (keynode_t *keynode); + +int _preference_get_key_path(keynode_t *keynode, char *path); +int _preference_get_key(keynode_t *keynode); + +int _preference_keynode_set_keyname(keynode_t *keynode, const char *keyname); +inline void _preference_keynode_set_null(keynode_t *keynode); +inline keynode_t *_preference_keynode_new(void); +inline void _preference_keynode_free(keynode_t *keynode); + + +#ifdef __cplusplus +} +#endif + +#endif /* __TIZEN_APPFW_PREFERENCE_INTERNAL_H__ */ diff --git a/include/app_preference_log.h b/include/app_preference_log.h new file mode 100755 index 0000000..8bd87a7 --- /dev/null +++ b/include/app_preference_log.h @@ -0,0 +1,92 @@ +/* + * Copyright (c) 2015 Samsung Electronics Co., Ltd All Rights Reserved + * + * Licensed under the Apache License, Version 2.0 (the License); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an AS IS BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +#ifdef LOG_TAG +#undef LOG_TAG +#endif + +#define LOG_TAG "CAPI_APPFW_APPLICATION_PREFERENCE" +#define DBG_MODE (1) + +#ifndef __PREFERENCE_LOG_H__ +#define __PREFERENCE_LOG_H__ + +#include <stdio.h> +#include <unistd.h> +#include <stdlib.h> +#include <dlog.h> + + +#define INFO(fmt, arg...) +#define DBG(fmt, arg...) SECURE_SLOGI(fmt, ##arg) +#define ERR(fmt, arg...) LOGE(fmt, ##arg) +#define SECURE_ERR(fmt, arg...) SECURE_SLOGE(fmt, ##arg) +#define FATAL(fmt, arg...) SECURE_SLOGF(fmt, ##arg) +#define WARN(fmt, arg...) SECURE_SLOGW(fmt, ##arg) + + +/************** Return ***************/ +#define ret_if(expr) \ + do { \ + if (expr) { \ + ERR("(%s) -> %s() return", #expr, __FUNCTION__); \ + return; \ + } \ + } while (0) +#define retv_if(expr, val) \ + do { \ + if (expr) { \ + ERR("(%s) -> %s() return", #expr, __FUNCTION__); \ + return (val); \ + } \ + } while (0) +#define retm_if(expr, fmt, arg...) \ + do { \ + if (expr) { \ + ERR(fmt, ##arg); \ + return; \ + } \ + } while (0) +#define retvm_if(expr, val, fmt, arg...) \ + do { \ + if (expr) { \ + ERR(fmt, ##arg); \ + return (val); \ + } \ + } while (0) +#define retex_if(expr, fmt, arg...) \ + do { \ + if (expr) { \ + ERR(fmt, ##arg); \ + goto CATCH; \ + } \ + } while (0) + + +/************** TimeCheck ***************/ +#ifdef PREFERENCE_TIMECHECK +#define START_TIME_CHECK \ + init_time();\ + startT = set_start_time(); +#define END_TIME_CHECK \ + PREFERENCE_DEBUG("time = %f ms\n", exec_time(startT)); +#else +#define START_TIME_CHECK +#define END_TIME_CHECK +#endif + + +#endif /* __PREFERENCE_LOG_H__ */ diff --git a/include/app_preference_private.h b/include/app_preference_private.h deleted file mode 100755 index aaf4a87..0000000 --- a/include/app_preference_private.h +++ /dev/null @@ -1,52 +0,0 @@ -/* - * Copyright (c) 2011 Samsung Electronics Co., Ltd All Rights Reserved - * - * Licensed under the Apache License, Version 2.0 (the License); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an AS IS BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - - -#ifndef __TIZEN_APPFW_PREFERENCE_PRIVATE_H__ -#define __TIZEN_APPFW_PREFERENCE_PRIVATE_H__ - -#ifdef __cplusplus -extern "C" { -#endif - -#define PREF_DB_NAME ".pref.db" -#define PREF_TBL_NAME "pref" -#define PREF_F_KEY_NAME "pref_key" -#define PREF_F_TYPE_NAME "pref_type" -#define PREF_F_DATA_NAME "pref_data" -#define BUF_LEN (4096) - -typedef enum -{ - PREFERENCE_TYPE_INT = 1, - PREFERENCE_TYPE_BOOLEAN, - PREFERENCE_TYPE_DOUBLE, - PREFERENCE_TYPE_STRING -} preference_type_e; - -typedef struct _pref_changed_cb_node_t{ - char *key; - preference_changed_cb cb; - void *user_data; - struct _pref_changed_cb_node_t *prev; - struct _pref_changed_cb_node_t *next; -} pref_changed_cb_node_t; - -#ifdef __cplusplus -} -#endif - -#endif /* __TIZEN_APPFW_PREFERENCE_PRIVATE_H__ */ diff --git a/include/app_service.h b/include/app_service.h deleted file mode 100755 index ee71d33..0000000 --- a/include/app_service.h +++ /dev/null @@ -1,672 +0,0 @@ -/* - * Copyright (c) 2011 Samsung Electronics Co., Ltd All Rights Reserved - * - * Licensed under the Apache License, Version 2.0 (the License); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an AS IS BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - - -#ifndef __TIZEN_APPFW_SERVICE_H__ -#define __TIZEN_APPFW_SERVICE_H__ - -#include <sys/types.h> -#include <tizen.h> - -#ifdef __cplusplus -extern "C" { -#endif - -/** - * @addtogroup CAPI_SERVICE_MODULE - * @{ - */ - - -/** - * @brief Service handle. - */ -typedef struct service_s *service_h; - - -/** - * @brief Enumerations of error code for Service. - */ -typedef enum -{ - SERVICE_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */ - SERVICE_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */ - SERVICE_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of memory */ - SERVICE_ERROR_APP_NOT_FOUND = TIZEN_ERROR_APPLICATION_CLASS | 0x21, /**< The application was not found */ - SERVICE_ERROR_KEY_NOT_FOUND = TIZEN_ERROR_KEY_NOT_AVAILABLE, /**< Specified key not found */ - SERVICE_ERROR_KEY_REJECTED = TIZEN_ERROR_KEY_REJECTED, /**< Not available key */ - SERVICE_ERROR_INVALID_DATA_TYPE = TIZEN_ERROR_APPLICATION_CLASS | 0x22, /**< Invalid data type */ -} service_error_e; - - -/** - * @brief Enumeration of service result. - */ -typedef enum -{ - SERVICE_RESULT_SUCCEEDED = 0, /**< Operation succeeded */ - SERVICE_RESULT_FAILED = -1, /**< Operation failed by the callee */ - SERVICE_RESULT_CANCELED = -2, /**< Operation canceled by the framework */ -} service_result_e; - - -/** - * @brief Service operation : default operation for explicit launch - */ -#define SERVICE_OPERATION_DEFAULT "http://tizen.org/appcontrol/operation/default" - - -/** - * @brief Service operation : provide explicit editable access to the given data. - */ -#define SERVICE_OPERATION_EDIT "http://tizen.org/appcontrol/operation/edit" - - -/** - * @brief Service operation : display the data. - */ -#define SERVICE_OPERATION_VIEW "http://tizen.org/appcontrol/operation/view" - - -/** - * @brief Service operation : pick an item from the data, returning what was selected. - */ -#define SERVICE_OPERATION_PICK "http://tizen.org/appcontrol/operation/pick" - - -/** - * @brief Service operation : create a content, returning what was created. - */ -#define SERVICE_OPERATION_CREATE_CONTENT "http://tizen.org/appcontrol/operation/create_content" - - -/** - * @brief Service operation : perform a call to someone specified by the data. - */ -#define SERVICE_OPERATION_CALL "http://tizen.org/appcontrol/operation/call" - - -/** - * @brief Service operation : deliver some data to someone else. - */ -#define SERVICE_OPERATION_SEND "http://tizen.org/appcontrol/operation/send" - - -/** - * @brief Service operation : deliver text data to someone else. - */ -#define SERVICE_OPERATION_SEND_TEXT "http://tizen.org/appcontrol/operation/send_text" - - -/** - * @brief Service operation : dial a number as specified by the data. - */ -#define SERVICE_OPERATION_DIAL "http://tizen.org/appcontrol/operation/dial" - - -/** - * @brief Service operation : perform a search. - */ -#define SERVICE_OPERATION_SEARCH "http://tizen.org/appcontrol/operation/search" - - -/** - * @brief Service optional data : the subject of a message. - */ -#define SERVICE_DATA_SUBJECT "http://tizen.org/appcontrol/data/subject" - - -/** - * @brief Service optional data : e-mail addresses. - */ -#define SERVICE_DATA_TO "http://tizen.org/appcontrol/data/to" - - -/** - * @brief Service optional data : e-mail addresses that should be carbon copied. - */ -#define SERVICE_DATA_CC "http://tizen.org/appcontrol/data/cc" - - -/** - * @brief Service optional data : e-mail addresses that should be blind carbon copied. - */ -#define SERVICE_DATA_BCC "http://tizen.org/appcontrol/data/bcc" - - -/** - * @brief Service optional data : the content of the data is associated with #SERVICE_OPERATION_SEND. - */ -#define SERVICE_DATA_TEXT "http://tizen.org/appcontrol/data/text" - - -/** - * @brief Service optional data : the title of the data - */ -#define SERVICE_DATA_TITLE "http://tizen.org/appcontrol/data/title" - - -/** - * @brief Service optional data : the path of selected item. - */ -#define SERVICE_DATA_SELECTED "http://tizen.org/appcontrol/data/selected" - - -/** - * @brief Called when the reply of the launch request is delivered. - * - * @remarks The @a request and @a reply must not be deallocated by an application. - * - * @param [in] request The service handle of the launch request that has sent - * @param [in] reply The service handle in which the results of the callee are contained - * @param [in] result The result code of the launch request - * @param [in] user_data The user data passed from the callback registration function - * @pre When the callee replies to the launch request, this callback will be invoked. - * @see service_send_launch_request() - * @see service_reply_to_launch_request() - */ -typedef void (*service_reply_cb) (service_h request, service_h reply, service_result_e result, void *user_data); - - -/** -* @brief Called to retrieve the extra data that are contained in the service -* -* @remarks The @a key must not be deallocated by an application. -* -* @param[in] service The service handle -* @param[in] key The key of the value contained in the service -* @param[in] user_data The user data passed from the foreach function -* @return @c true to continue with the next iteration of the loop, \n @c false to break out of the loop. -* @pre service_foreach_extra_data() will invoke this callback. -* @see service_foreach_extra_data() -*/ -typedef bool (*service_extra_data_cb)(service_h service, const char *key, void *user_data); - - -/** -* @brief Called once for each matched application that can be launched to handle the given service request. -* -* @param [in] service The service handle -* @param [in] package The package name of the application that can handle the launch request of the given service. -* @param [in] user_data The user data passed from the foreach function -* @return @c true to continue with the next iteration of the loop, \n @c false to break out of the loop. -* @pre service_foreach_app_matched() will invoke this callback. -* @see service_foreach_app_matched() -*/ -typedef bool (*service_app_matched_cb)(service_h service, const char *package, void *user_data); - - -/** - * @brief Creates a service handle. - * - * @remarks The @a service must be released with service_destroy() by you. - * @param [out] service A service handle to be newly created on success - * @return 0 on success, otherwise a negative error value. - * @retval #SERVICE_ERROR_NONE Successful - * @retval #SERVICE_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #SERVICE_ERROR_OUT_OF_MEMORY Out of memory - * @see service_destroy() - */ -int service_create(service_h *service); - - -/** - * @brief Destroys the service handle and releases all its resources. - * - * @param [in] service The service handle - * @return 0 on success, otherwise a negative error value. - * @retval #SERVICE_ERROR_NONE Successful - * @retval #SERVICE_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #SERVICE_ERROR_OUT_OF_MEMORY Out of memory - * @see service_create() - */ -int service_destroy(service_h service); - - -/** - * @brief Sets the operation to be performed. - * - * @details The @a operation is the mandatory information for the launch request. - * If the operation is not specified, #SERVICE_OPERATION_DEFAULT is used for the launch request. - * If the operation is #SERVICE_OPERATION_DEFAULT, the package information is mandatory to explicitly launch the application - * @param [in] service The service handle - * @param [in] operation The operation to be performed \n - * If the @a operation is NULL, it clears the previous value. - * @return 0 on success, otherwise a negative error value. - * @retval #SERVICE_ERROR_NONE Successful - * @retval #SERVICE_ERROR_INVALID_PARAMETER Invalid parameter - * @see service_get_operation() - * @see SERVICE_OPERATION_DEFAULT - * @see SERVICE_OPERATION_EDIT - * @see SERVICE_OPERATION_VIEW - * @see SERVICE_OPERATION_PICK - * @see SERVICE_OPERATION_CREATE_CONTENT - * @see SERVICE_OPERATION_CALL - * @see SERVICE_OPERATION_SEND - * @see SERVICE_OPERATION_SEND_TEXT - * @see SERVICE_OPERATION_DIAL - * @see SERVICE_OPERATION_SEARCH - */ -int service_set_operation(service_h service, const char *operation); - - -/** - * @brief Gets the operation to be performed. - * - * @remarks The @a operation must be released with free() by you. - * @param [in] service The service handle - * @param [out] operation The operation to be performed - * @return 0 on success, otherwise a negative error value. - * @retval #SERVICE_ERROR_NONE Successful - * @retval #SERVICE_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #SERVICE_ERROR_OUT_OF_MEMORY Out of memory - * @see service_set_operation() - */ -int service_get_operation(service_h service, char **operation); - - -/** - * @brief Sets the URI of the data. - * - * @param [in] service The service handle - * @param [in] uri The URI of the data this service is operating on \n - * If the @a uri is NULL, it clears the previous value. - * @return 0 on success, otherwise a negative error value. - * @retval #SERVICE_ERROR_NONE Successful - * @retval #SERVICE_ERROR_INVALID_PARAMETER Invalid parameter - * @see service_get_uri() - */ -int service_set_uri(service_h service, const char *uri); - - -/** - * @brief Gets the URI of the data. - * - * @remarks The @a uri must be released with free() by you. - * @param [in] service The service handle - * @param [out] uri The URI of the data this service is operating on - * @return 0 on success, otherwise a negative error value. - * @retval #SERVICE_ERROR_NONE Successful - * @retval #SERVICE_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #SERVICE_ERROR_OUT_OF_MEMORY Out of memory - * @see service_set_uri() - */ -int service_get_uri(service_h service, char **uri); - - -/** - * @brief Sets the explicit MIME type of the data - * - * @param [in] service The service handle - * @param [in] mime the explicit MIME type of the data this service is operating on \n - * If the @a mime is NULL, it clears the previous value. - * @return 0 on success, otherwise a negative error value. - * @retval #SERVICE_ERROR_NONE Successful - * @retval #SERVICE_ERROR_INVALID_PARAMETER Invalid parameter - * @see service_get_mime() - */ -int service_set_mime(service_h service, const char *mime); - - -/** - * @brief Gets the explicit MIME type of the data. - * - * @remarks The @a uri must be released with free() by you. - * @param [in] service The service handle - * @param [out] mime The explicit MIME type of the data this service is operating on - * @return 0 on success, otherwise a negative error value. - * @retval #SERVICE_ERROR_NONE Successful - * @retval #SERVICE_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #SERVICE_ERROR_OUT_OF_MEMORY Out of memory - * @see service_set_mime() - */ -int service_get_mime(service_h service, char **mime); - - -/** - * @brief Sets the package name of the application to explicitly launch - * - * @remark This function is @b deprecated. Use service_set_app_id() instead. - * @param [in] service The service handle - * @param [in] package The package name of the application to explicitly launch \n - * If the @a package is NULL, it clears the previous value. - * @return 0 on success, otherwise a negative error value. - * @retval #SERVICE_ERROR_NONE Successful - * @retval #SERVICE_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #SERVICE_ERROR_OUT_OF_MEMORY Out of memory - * @see service_get_package() - */ -int service_set_package(service_h service, const char *package); - - -/** - * @brief Gets the package name of the application to explicitly launch - * - * @remark This function is @b deprecated. Use service_get_app_id() instead. - * @remarks The @a package must be released with free() by you. - * @param [in] service The service handle - * @param [out] package The package name of the application to explicitly launch - * @return 0 on success, otherwise a negative error value. - * @retval #SERVICE_ERROR_NONE Successful - * @retval #SERVICE_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #SERVICE_ERROR_OUT_OF_MEMORY Out of memory - * @see service_set_package() - */ -int service_get_package(service_h service, char **package); - - -/** - * @brief Sets the ID of the application to explicitly launch - * - * @param [in] service The service handle - * @param [in] app_id The ID of the application to explicitly launch \n - * If the @a app_id is NULL, it clears the previous value. - * @return 0 on success, otherwise a negative error value. - * @retval #SERVICE_ERROR_NONE Successful - * @retval #SERVICE_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #SERVICE_ERROR_OUT_OF_MEMORY Out of memory - * @see service_get_app_id() - */ -int service_set_app_id(service_h service, const char *app_id); - - -/** - * @brief Gets the ID of the application to explicitly launch - * - * @remarks The @a app_id must be released with free() by you. - * @param [in] service The service handle - * @param [out] app_id The ID of the application to explicitly launch - * @return 0 on success, otherwise a negative error value. - * @retval #SERVICE_ERROR_NONE Successful - * @retval #SERVICE_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #SERVICE_ERROR_OUT_OF_MEMORY Out of memory - * @see service_set_app_id() - */ -int service_get_app_id(service_h service, char **app_id); - -/** - * @brief Sets the window id of the application - * - * @param [in] service The service handle - * @param [in] id the window id of caller application \n - * If the @a id is not positive, it clears the previous value. - * @return 0 on success, otherwise a negative error value. - * @retval #SERVICE_ERROR_NONE Successful - * @retval #SERVICE_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #SERVICE_ERROR_OUT_OF_MEMORY Out of memory - * @see service_get_window() - */ -int service_set_window(service_h service, unsigned int id); - - -/** -* @brief Gets the window id of the application -* -* @param [in] service The service handle -* @param [out] id The window id of caller application -* @return 0 on success, otherwise a negative error value. -* @retval #SERVICE_ERROR_NONE Successful -* @retval #SERVICE_ERROR_INVALID_PARAMETER Invalid parameter -* @retval #SERVICE_ERROR_OUT_OF_MEMORY Out of memory -* @see service_set_package() -*/ -int service_get_window(service_h service, unsigned int *id); - - -/** - * @brief Adds the extra data to the service. - * - * @remarks The function replaces any existing value for the given key. - * @remarks The function returns #SERVICE_ERROR_INVALID_PARAMETER if key or value is zero-length string. - * @remarks The function returns #SERVICE_ERROR_KEY_REJECTED if the application tries to use same key with system-defined key - * @param [in] service The service handle - * @param [in] key The name of the extra data - * @param [in] value The value associated with given key - * @return 0 on success, otherwise a negative error value. - * @retval #SERVICE_ERROR_NONE Successful - * @retval #SERVICE_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #SERVICE_ERROR_KEY_REJECTED Not available key - * @see service_add_extra_data_array() - * @see service_remove_extra_data() - * @see service_get_extra_data() - */ -int service_add_extra_data(service_h service, const char *key, const char *value); - - -/** - * @brief Adds the extra data array to the service. - * - * @remarks The function replaces any existing value for the given key. - * @remarks The function returns #SERVICE_ERROR_INVALID_PARAMETER if key is zero-length string. - * @remarks The function returns #SERVICE_ERROR_KEY_REJECTED if the application tries to use same key with system-defined key - * @param [in] service The service handle - * @param [in] key The name of the extra data - * @param [in] value The array value associated with given key - * @param [in] length The length of the array - * @return 0 on success, otherwise a negative error value. - * @retval #SERVICE_ERROR_NONE Successful - * @retval #SERVICE_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #SERVICE_ERROR_KEY_REJECTED Not available key - * @see service_add_extra_data() - * @see service_remove_extra_data() - * @see service_get_extra_data() - */ -int service_add_extra_data_array(service_h service, const char *key, const char* value[], int length); - - -/** - * @brief Removes the extra data from the service. - * - * @param [in] service The service handle - * @param [in] key The name of the extra data - * @return 0 on success, otherwise a negative error value. - * @retval #SERVICE_ERROR_NONE Successful - * @retval #SERVICE_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #SERVICE_ERROR_KEY_NOT_FOUND Specified key not found - * @see service_add_extra_data() - * @see service_add_extra_data_array() - * @see service_get_extra_data() - */ -int service_remove_extra_data(service_h service, const char *key); - - -/** - * @brief Gets the extra data from the service. - * - * @remarks The @a value must be released with free() by you. - * @remarks The function returns #SERVICE_ERROR_INVALID_DATA_TYPE if the value is array data type. - * @param [in] service The service handle - * @param [int] key The name of the extra data - * @param [out] value The value associated with given key - * @return 0 on success, otherwise a negative error value. - * @retval #SERVICE_ERROR_NONE Successful - * @retval #SERVICE_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #SERVICE_ERROR_KEY_NOT_FOUND Specified key not found - * @retval #SERVICE_ERROR_OUT_OF_MEMORY Out of memory - * @retval #SERVICE_ERROR_INVALID_DATA_TYPE Invalid data type - * @see service_add_extra_data() - * @see service_add_extra_data_array() - * @see service_get_extra_data() - * @see service_remove_extra_data() - * @see service_foreach_extra_data() - */ -int service_get_extra_data(service_h service, const char *key, char **value); - - -/** - * @brief Gets the extra data array from the service. - * - * @remarks The @a value must be released with free() by you. - * @remarks The function returns #SERVICE_ERROR_INVALID_DATA_TYPE if the value is not array data type. - * @param [in] service The service handle - * @param [int] key The name of the extra data - * @param [out] value The array value associated with given key - * @param [out] length The length of the array - * @return 0 on success, otherwise a negative error value. - * @retval #SERVICE_ERROR_NONE Successful - * @retval #SERVICE_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #SERVICE_ERROR_KEY_NOT_FOUND Specified key not found - * @retval #SERVICE_ERROR_OUT_OF_MEMORY Out of memory - * @retval #SERVICE_ERROR_INVALID_DATA_TYPE Invalid data type - * @see service_add_extra_data() - * @see service_add_extra_data_array() - * @see service_remove_extra_data() - * @see service_foreach_extra_data() - */ -int service_get_extra_data_array(service_h service, const char *key, char ***value, int *length); - - -/** - * @brief Checks whether if the extra data associated with given @a key is array data type. - * - * @param [in] service The service handle - * @param [int] key The name of the extra data - * @param [out] array @c True if the extra data is array data type, otherwise @c false - * @return 0 on success, otherwise a negative error value. - * @retval #SERVICE_ERROR_NONE Successful - * @retval #SERVICE_ERROR_INVALID_PARAMETER Invalid parameter - * @see service_add_extra_data() - * @see service_add_extra_data_array() - * @see service_remove_extra_data() - * @see service_foreach_extra_data() - */ -int service_is_extra_data_array(service_h service, const char *key, bool *array); - - -/** - * @brief Retrieves all extra data contained in service. - * @details This function calls service_extra_data_cb() once for each key-value pair for extra data contained in service. \n - * If service_extra_data_cb() callback function returns false, then iteration will be finished. - * - * @param [in] service The service handle - * @param [in] callback The iteration callback function - * @param [in] user_data The user data to be passed to the callback function - * @return 0 on success, otherwise a negative error value. - * @retval #SERVICE_ERROR_NONE Successful - * @retval #SERVICE_ERROR_INVALID_PARAMETER Invalid parameter - * @post This function invokes service_extra_data_cb(). - * @see service_extra_data_cb() - */ -int service_foreach_extra_data(service_h service, service_extra_data_cb callback, void *user_data); - - -/** - * @brief Retrieves all applications that can be launched to handle the given service request. - * - * @param [in] service The service handle - * @param [in] callback The iteration callback function - * @param [in] user_data The user data to be passed to the callback function - * @return 0 on success, otherwise a negative error value. - * @retval #SERVICE_ERROR_NONE Success - * @retval #SERVICE_ERROR_INVALID_PARAMETER Invalid parameter - * @post This function invokes service_app_matched_cb(). - * @see service_app_matched_cb() - */ -int service_foreach_app_matched(service_h service, service_app_matched_cb callback, void *user_data); - - -/** - * @brief Sends the launch request. - * - * @details The operation is mandatory information for the launch request. \n - * If the operation is not specified, #SERVICE_OPERATION_DEFAULT is used by default. - * If the operation is #SERVICE_OPERATION_DEFAULT, the application ID is mandatory to explicitly launch the application - * @param [in] service The service handle - * @param [in] callback The callback function to be called when the reply is delivered - * @param [in] user_data The user data to be passed to the callback function - * @return 0 on success, otherwise a negative error value. - * @retval #SERVICE_ERROR_NONE Successful - * @retval #SERVICE_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #SERVICE_ERROR_OUT_OF_MEMORY Out of memory - * @retval #SERVICE_ERROR_APP_NOT_FOUND The application was not found to run the given launch request - * @post If the launch request is sent for the result, the result will come back through service_reply_cb() from the callee application - * @see service_reply_to_launch_request() - * @see service_reply_cb() - */ -int service_send_launch_request(service_h service, service_reply_cb callback, void *user_data); - - -/** - * @brief Replies to the launch request that the caller sent - * @details If the caller application sent the launch request to receive the result, the callee application can return the result back to the caller. - * - * @param [in] reply The service handle in which the results of the callee are contained - * @param [in] request The service handle that the caller sent - * @param [in] result The result code of the launch request - * @return 0 on success, otherwise a negative error value. - * @retval #SERVICE_ERROR_NONE Successful - * @retval #SERVICE_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #SERVICE_ERROR_OUT_OF_MEMORY Out of memory - * @see service_send_launch_request() - */ -int service_reply_to_launch_request(service_h reply, service_h request, service_result_e result); - - -/** - * @brief Creates and returns a copy of the given service handle. - * - * @remarks A newly created service should be destroyed by calling service_destroy() if it is no longer needed. - * - * @param [out] clone If successful, a newly created service handle will be returned. - * @param [in] service The service handle - * @return 0 on success, otherwise a negative error value. - * @retval #SERVICE_ERROR_NONE Successful - * @retval #SERVICE_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #SERVICE_ERROR_OUT_OF_MEMORY Out of memory - * @see service_destroy() - */ -int service_clone(service_h *clone, service_h service); - - -/** - * @brief Gets the application ID of the caller from the launch request - * - * @remarks The @a service must be the launch reqeust from app_service_cb(). - * @remarks This function returns #SERVICE_ERROR_INVALID_PARAMETER if the given service is not the launch request. - * @remarks The @a id must be released with free() by you. - * @param [in] service The service handle from app_service_cb() - * @param [out] id The application ID of the caller - * @return 0 on success, otherwise a negative error value. - * @retval #SERVICE_ERROR_NONE Successful - * @retval #SERVICE_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #SERVICE_ERROR_OUT_OF_MEMORY Out of memory - */ -int service_get_caller(service_h service, char **id); - - -/** - * @brief Check whether the caller is requesting a reply from the launch reqeust - * - * @remarks The @a service must be the launch reqeust from app_service_cb(). - * @remarks This function returns #SERVICE_ERROR_INVALID_PARAMETER if the given service is not the launch request. - * @param [in] service The service handle from app_service_cb() - * @param [out] requested whether a reply is requested by the caller - * @return 0 on success, otherwise a negative error value. - * @retval #SERVICE_ERROR_NONE Successful - * @retval #SERVICE_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #SERVICE_ERROR_OUT_OF_MEMORY Out of memory - */ -int service_is_reply_requested(service_h service, bool *requested); - -/** - * @} - */ - -#ifdef __cplusplus -} -#endif - -#endif /* __TIZEN_APPFW_SERVICE_H__ */ diff --git a/include/app_service_private.h b/include/app_service_private.h deleted file mode 100755 index 6f71533..0000000 --- a/include/app_service_private.h +++ /dev/null @@ -1,37 +0,0 @@ -/* - * Copyright (c) 2011 Samsung Electronics Co., Ltd All Rights Reserved - * - * Licensed under the Apache License, Version 2.0 (the License); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an AS IS BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - - -#ifndef __TIZEN_APPFW_SERVICE_PRIVATE_H__ -#define __TIZEN_APPFW_SERVICE_PRIVATE_H__ - -#include <bundle.h> - -#ifdef __cplusplus -extern "C" { -#endif - -int service_create_request(bundle *data, service_h *service); - -int service_create_event(bundle *data, service_h *service); - -int service_to_bundle(service_h service, bundle **data); - -#ifdef __cplusplus -} -#endif - -#endif /* __TIZEN_APPFW_SERVICE_PRIVATE_H__ */ diff --git a/include/app_storage.h b/include/app_storage.h deleted file mode 100644 index 0afe823..0000000 --- a/include/app_storage.h +++ /dev/null @@ -1,226 +0,0 @@ -/* - * Copyright (c) 2011 Samsung Electronics Co., Ltd All Rights Reserved - * - * Licensed under the Apache License, Version 2.0 (the License); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an AS IS BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -#ifndef __TIZEN_APPFW_STORAGE_H__ -#define __TIZEN_APPFW_STORAGE_H__ - -#include <tizen.h> - -#ifdef __cplusplus -extern "C" -{ -#endif - - /** - * @addtogroup CAPI_STORAGE_MODULE - * @{ - */ - - -/** - * @brief Enumerations of error code for Storage. - */ -typedef enum -{ - STORAGE_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */ - STORAGE_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */ - STORAGE_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of memory */ - STORAGE_ERROR_NOT_SUPPORTED = TIZEN_ERROR_NO_SUCH_DEVICE /**< Not supported storage */ -} storage_error_e; - - -/** - * @brief Enumerations of the storage type. - */ -typedef enum -{ - STORAGE_TYPE_INTERNAL, /**< Internal device storage (built-in storage in a device, non-removable) */ - STORAGE_TYPE_EXTERNAL, /**< External storage */ -} storage_type_e; - - -/** - * @brief Enumerations of the state of storage device. - */ -typedef enum -{ - STORAGE_STATE_UNMOUNTABLE = -2, /**< Storage is present but cannot be mounted. Typically it happens if the file system of the storage is corrupted. */ - STORAGE_STATE_REMOVED = -1, /**< Storage is not present. */ - STORAGE_STATE_MOUNTED = 0, /**< Storage is present and mounted with read/write access. */ - STORAGE_STATE_MOUNTED_READ_ONLY = 1, /**< Storage is present and mounted with read only access. */ -} storage_state_e; - - -/** -* @brief Called to get information once for each supported storage. -* -* @param [in] storage The unique storage ID -* @param [in] type The type of the storage -* @param [in] state The current state of the storage -* @param [in] path The absolute path to the root directory of the @a storage -* @param [in] user_data The user data passed from the foreach function -* @return @c true to continue with the next iteration of the loop, \n @c false to break out of the loop. -* @pre storage_foreach_device_supported() will invoke this callback function. -* @see storage_foreach_device_supported() -*/ -typedef bool (*storage_device_supported_cb)(int storage, storage_type_e type, storage_state_e state, const char *path, void *user_data); - - -/** -* @brief Called when the state of storage changes -* -* @param [in] storage The unique storage ID -* @param [in] state The current state of the storage -* @param [in] user_data The user data passed from the foreach function -* @pre storage_set_state_changed_cb() will invoke this callback function. -* @see storage_set_state_changed_cb() -* @see storage_unset_state_changed_cb() -*/ -typedef void (*storage_state_changed_cb)(int storage, storage_state_e state, void *user_data); - - -/** - * @brief Retrieves all storage in device. - * @details This function invokes the callback function once for each @a storage in device. \n - * If storage_device_supported_cb() returns @c false, then iteration will be finished. - * - * @param [in] callback The iteration callback function - * @param [in] user_data The user data to be passed to the callback function - * @return 0 on success, otherwise a negative error value. - * @retval #STORAGE_ERROR_NONE Successful - * @retval #STORAGE_ERROR_INVALID_PARAMETER Invalid parameter - * @post This function invokes storage_device_supported_cb() repeatedly for each supported device. - * @see storage_device_supported_cb() - */ -int storage_foreach_device_supported(storage_device_supported_cb callback, void *user_data); - - -/** - * @brief Gets the absolute path to the root directory of the given @a storage. - * @details - * Files saved on the internal/external storage are readable or writeable by all applications. - * When an application is uninstalled, the files written by that application are not removed from the internal/external storage. - * - * @remarks @a path must be released with free() by you. - * - * @param[in] storage The storage device - * @param[out] path The absolute path to the storage directory - * @return 0 on success, otherwise a negative error value. - * @retval #STORAGE_ERROR_NONE Successful - * @retval #STORAGE_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #STORAGE_ERROR_OUT_OF_MEMORY Out of memory - * @retval #STORAGE_ERROR_NOT_SUPPORTED Not supported storage - * @see storage_get_state() - */ -int storage_get_root_directory(int storage, char **path); - - -/** - * @brief Gets the type of the given @a storage. - * - * @param[in] storage The storage device - * @param[out] type The type of the storage - * @return 0 on success, otherwise a negative error value. - * @retval #STORAGE_ERROR_NONE Successful - * @retval #STORAGE_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #STORAGE_ERROR_NOT_SUPPORTED Not supported storage - */ -int storage_get_type(int storage, storage_type_e *type); - - -/** - * @brief Gets the current state of the given @a storage. - * - * @param[in] storage The storage device - * @param[out] state The current state of the storage, - * @return 0 on success, otherwise a negative error value. - * @retval #STORAGE_ERROR_NONE Successful - * @retval #STORAGE_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #STORAGE_ERROR_NOT_SUPPORTED Not supported storage - * @see storage_get_root_directory() - * @see storage_get_total_space() - * @see storage_get_available_space() - */ -int storage_get_state(int storage, storage_state_e *state); - - -/** - * @brief Registers a callback function to be invoked when the state of the storage changes. - * - * @param[in] storage The storage device - * @param[in] callback The callback function to register - * @param[in] user_data The user data to be passed to the callback function - * @return 0 on success, otherwise a negative error value. - * @retval #STORAGE_ERROR_NONE Successful - * @retval #STORAGE_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #STORAGE_ERROR_NOT_SUPPORTED Not supported storage - * @post storage_state_changed_cb() will be invoked if the state of registered storage changes. - * @see storage_state_changed_cb() - * @see storage_unset_state_changed_cb() - */ -int storage_set_state_changed_cb(int storage, storage_state_changed_cb callback, void *user_data); - - -/** - * @brief Unregisters the callback function. - * - * @param [in] storage The storage device to monitor - * @return 0 on success, otherwise a negative error value. - * @retval #STORAGE_ERROR_NONE Successful - * @retval #STORAGE_ERROR_NOT_SUPPORTED Not supported storage - * @see storage_state_changed_cb() - * @see storage_set_state_changed_cb() - */ -int storage_unset_state_changed_cb(int storage); - -/** - * @brief Gets the total space of the given @a storage in bytes. - * - * @param[in] storage The storage device - * @param[out] bytes The total space size of the storage (bytes) - * @return 0 on success, otherwise a negative error value - * @retval #STORAGE_ERROR_NONE Successful - * @retval #STORAGE_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #STORAGE_ERROR_NOT_SUPPORTED Not supported storage - * @see storage_get_state() - * @see storage_get_available_space() - */ -int storage_get_total_space(int storage, unsigned long long *bytes); - -/** - * @brief Gets the available space size of the given @a storage in bytes. - * - * @param[in] storage The storage device - * @param[out] bytes The available space size of the storage (bytes) - * @return 0 on success, otherwise a negative error value. - * @retval #STORAGE_ERROR_NONE Successful - * @retval #STORAGE_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #STORAGE_ERROR_NOT_SUPPORTED Not supported storage - - * @see storage_get_state() - * @see storage_get_total_space() - */ -int storage_get_available_space(int storage, unsigned long long *bytes); - -/** - * @} - */ - -#ifdef __cplusplus -} -#endif - -#endif /* __TIZEN_APPFW_STORAGE_H__ */ diff --git a/include/app_storage_private.h b/include/app_storage_private.h deleted file mode 100755 index e5bf36c..0000000 --- a/include/app_storage_private.h +++ /dev/null @@ -1,60 +0,0 @@ -/* - * Copyright (c) 2011 Samsung Electronics Co., Ltd All Rights Reserved - * - * Licensed under the Apache License, Version 2.0 (the License); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an AS IS BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - - -#ifndef __TIZEN_APPFW_STORAGE_PRIVATE_H__ -#define __TIZEN_APPFW_STORAGE_PRIVATE_H__ - -#include <tizen.h> - -#ifdef __cplusplus -extern "C" -{ -#endif - -typedef int (*storage_dev_get_state)(void); -typedef int (*storage_dev_set_state_cb)(void *data); -typedef void (*storage_dev_unset_state_cb)(void); -typedef int (*storage_dev_get_space)(unsigned long long *total, unsigned long long *available); - -typedef struct storage_device_s -{ - storage_type_e type; - char *path; - storage_dev_get_state get_state; - storage_dev_set_state_cb set_state_cb; - storage_dev_unset_state_cb unset_state_cb; - storage_dev_get_space get_space; -} *storage_device_h; - -typedef struct storage_info_s -{ - int id; - storage_device_h device; - storage_state_e state; - storage_state_changed_cb state_cb; - void *state_cb_data; -} *storage_info_h; - -void storage_dispatch_state_event(storage_state_e state, void* data); - -int storage_statfs(const char *directory, unsigned long long *total, unsigned long long *available); - -#ifdef __cplusplus -} -#endif - -#endif /* __TIZEN_APPFW_STORAGE_PRIVATE_H__ */ diff --git a/include/app_types.h b/include/app_types.h new file mode 100644 index 0000000..80c19d0 --- /dev/null +++ b/include/app_types.h @@ -0,0 +1,52 @@ +/* + * Copyright (c) 2011 Samsung Electronics Co., Ltd All Rights Reserved + * + * Licensed under the Apache License, Version 2.0 (the License); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an AS IS BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. +*/ + + +#ifndef __TIZEN_APPFW_APP_TYPES_H__ +#define __TIZEN_APPFW_APP_TYPES_H__ + +#include <tizen.h> + +/** + * @file app_types.h + */ + +/** + * @addtogroup CAPI_APPLICATION_MODULE + * @{ + */ + +/** + * @brief Enumeration for application error. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + */ + +typedef enum +{ + APP_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */ + APP_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */ + APP_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of memory */ + APP_ERROR_INVALID_CONTEXT = TIZEN_ERROR_APPLICATION | 0x01, /**< Invalid application context */ + APP_ERROR_NO_SUCH_FILE = TIZEN_ERROR_NO_SUCH_FILE, /**< No such file or directory */ + APP_ERROR_ALREADY_RUNNING = TIZEN_ERROR_ALREADY_IN_PROGRESS, /**< Application is already running */ + APP_ERROR_PERMISSION_DENIED = TIZEN_ERROR_PERMISSION_DENIED, /**< Permission denied @if MOBILE (Since 2.3.1) @endif */ +} app_error_e; + +/** + * @} + */ + +#endif /* __TIZEN_APPFW_APP_TYPES_H__ */ diff --git a/include/app_ui_notification.h b/include/app_ui_notification.h deleted file mode 100755 index ba17898..0000000 --- a/include/app_ui_notification.h +++ /dev/null @@ -1,459 +0,0 @@ -/* - * Copyright (c) 2011 Samsung Electronics Co., Ltd All Rights Reserved - * - * Licensed under the Apache License, Version 2.0 (the License); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an AS IS BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - - -#ifndef __TIZEN_APPFW_UI_NOTIFICATION_H__ -#define __TIZEN_APPFW_UI_NOTIFICATION_H__ - -#include <tizen.h> -#include <time.h> -#include <app_service.h> - -#ifdef __cplusplus -extern "C" -{ -#endif - - /** - * @addtogroup CAPI_UI_NOTIFICATION_MODULE - * @{ - */ - -/** - * @brief Notification handle. - */ -typedef struct ui_notification_s *ui_notification_h; - -/** - * @brief Enumerations of error code for notification. - */ -typedef enum { - UI_NOTIFICATION_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */ - UI_NOTIFICATION_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */ - UI_NOTIFICATION_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of memory */ - UI_NOTIFICATION_ERROR_DB_FAILED = TIZEN_ERROR_APPLICATION_CLASS | 0x31, /**< DB operation failed */ - UI_NOTIFICATION_ERROR_NO_SUCH_FILE = TIZEN_ERROR_NO_SUCH_FILE, /**< No such file */ - UI_NOTIFICATION_ERROR_INVALID_STATE = TIZEN_ERROR_APPLICATION_CLASS | 0x32, /**< Invalid state */ -} ui_notification_error_e; - -/** - * @brief Enumeration of progress type for ongoing notification - */ -typedef enum { - UI_NOTIFICATION_PROGRESS_TYPE_SIZE, /**< Size in bytes */ - UI_NOTIFICATION_PROGRESS_TYPE_PERCENTAGE, /**< Percentage (between 0.0 and 1.0) */ -} ui_notification_progress_type_e; - -/** -* @brief Called to retrieve the notifications posted. -* @remarks You should not free @a notification returned by this function. -* @param[in] notification The notification handle -* @param[in] user_data The user data passed from the foreach function -* @return @c true to continue with the next iteration of the loop, \n @c false to break out of the loop. -* @pre ui_notification_foreach_notification_posted() will invoke this callback. -* @see ui_notification_foreach_notification_posted() -* @see ui_notification_clone() -*/ -typedef bool (*ui_notification_cb)(ui_notification_h notification, void *user_data); - -/** - * @brief Creates a notification handle. - * @remarks The @a notification must be released with ui_notification_destroy() by you. - * @param[in] ongoing A boolean value that sets whether this is an ongoing notification. - * @param[out] notification A UI notification handle to be newly created on success - * @return 0 on success, otherwise a negative error value. - * @retval #UI_NOTIFICATION_ERROR_NONE Successful - * @retval #UI_NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #UI_NOTIFICATION_ERROR_OUT_OF_MEMORY Out of memory - * @see ui_notification_destroy() - */ -int ui_notification_create(bool ongoing, ui_notification_h *notification); - -/** - * @brief Destroys the notification handle and releases all its resources. - * @param[in] notification The notification handle - * @return 0 on success, otherwise a negative error value. - * @retval #UI_NOTIFICATION_ERROR_NONE Successful - * @retval #UI_NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter - * @see ui_notification_create() - */ -int ui_notification_destroy(ui_notification_h notification); - -/** - * @brief Checks whether the notification is ongoing or not - * @param[in] notification The notification handle - * @param[out] ongoing A boolean value that sets whether this is an ongoing notification. - * @return 0 on success, otherwise a negative error value. - * @retval #UI_NOTIFICATION_ERROR_NONE Successful - * @retval #UI_NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter - * @see ui_notification_create() - */ -int ui_notification_is_ongoing(ui_notification_h notification, bool *ongoing); - -/** - * @brief Sets the full path of the icon image to display in the notification. - * @remarks The @a path should be the absolute path. If the icon is not set, the icon of the application will be displayed. \n - * This function should be called before posting or updating the notification (see ui_notification_post(), ui_notification_update()). - * @param[in] notification The notification handle - * @param[in] path The absolute path to the specified icon \n - * If the @a path is NULL, it clears the previous value. - * @return 0 on success, otherwise a negative error value. - * @retval #UI_NOTIFICATION_ERROR_NONE Successful - * @retval #UI_NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #UI_NOTIFICATION_ERROR_OUT_OF_MEMORY Out of memory - * @see ui_notification_get_icon() - */ -int ui_notification_set_icon(ui_notification_h notification, const char *path); - -/** - * @brief Gets the absolute path to the icon to display in the notification. - * @remarks The @a path must be released with free() by you. - * @param[in] notification The notification handle - * @param[out] path The absolute path to the icon - * @return 0 on success, otherwise a negative error value. - * @retval #UI_NOTIFICATION_ERROR_NONE Successful - * @retval #UI_NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #UI_NOTIFICATION_ERROR_OUT_OF_MEMORY Out of memory - * @see ui_notification_set_icon() - */ -int ui_notification_get_icon(ui_notification_h notification, char **path); - -/** - * @brief Sets the time that the notification occurred. - * @remarks This function should be called before posting or updating the notification (see ui_notification_post(), ui_notification_update()). - * @param[in] notification The notification handle - * @param[in] time The time that the notification occurred \n - * If the @a time is NULL, it clears the previous value. - * @return 0 on success, otherwise a negative error value. - * @retval #UI_NOTIFICATION_ERROR_NONE Successful - * @retval #UI_NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #UI_NOTIFICATION_ERROR_OUT_OF_MEMORY Out of memory - * @see ui_notification_get_time() - */ -int ui_notification_set_time(ui_notification_h notification, struct tm *time); - -/** - * @brief Gets the time that the notification occured. - * @param[in] notification The notification handle - * @param[out] time The time that the notification occured - * @return 0 on success, otherwise a negative error value. - * @retval #UI_NOTIFICATION_ERROR_NONE Successful - * @retval #UI_NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #UI_NOTIFICATION_ERROR_OUT_OF_MEMORY Out of memory - * @see ui_notification_set_time() - */ -int ui_notification_get_time(ui_notification_h notification, struct tm **time); - -/** - * @brief Sets the title to display in the notification. - * @remarks If the title is not set, the name of the application will be displayed. \n - * This function should be called before posting or updating the notification (see ui_notification_post(), ui_notification_update()). - * @param[in] notification The notification handle - * @param[in] title The title to display in the notification \n - * If the @a title is NULL, it clears the previous value. - * @return 0 on success, otherwise a negative error value. - * @retval #UI_NOTIFICATION_ERROR_NONE Successful - * @retval #UI_NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #UI_NOTIFICATION_ERROR_OUT_OF_MEMORY Out of memory - * @see ui_notification_get_title() - */ -int ui_notification_set_title(ui_notification_h notification, const char *title); - -/** - * @brief Gets the title to display in the notification. - * @remarks The @a title must be released with free() by you. - * @param[in] notification The notification handle - * @param[out] title The title to display in the notification - * @return 0 on success, otherwise a negative error value. - * @retval #UI_NOTIFICATION_ERROR_NONE Successful - * @retval #UI_NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #UI_NOTIFICATION_ERROR_OUT_OF_MEMORY Out of memory - * @see ui_notification_set_title() - */ -int ui_notification_get_title(ui_notification_h notification, char **title); - -/** - * @brief Sets the content to display in the notification - * @remarks This function should be called before posting or updating the notification (see ui_notification_post(), ui_notification_update()). - * @param[in] notification The notification handle - * @param[in] content The content to display in the notification \n - * If the @a content is NULL, it clears the previous value. - * @return 0 on success, otherwise a negative error value. - * @retval #UI_NOTIFICATION_ERROR_NONE Successful - * @retval #UI_NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #UI_NOTIFICATION_ERROR_OUT_OF_MEMORY Out of memory - * @see ui_notification_get_content() - */ -int ui_notification_set_content(ui_notification_h notification, const char *content); - -/** - * @brief Gets the content to display in the notification - * @remarks The @a content must be released with free() by you. - * @param[in] notification The notification handle - * @param[out] content The content to display in the notification - * @return 0 on success, otherwise a negative error value. - * @retval #UI_NOTIFICATION_ERROR_NONE Successful - * @retval #UI_NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #UI_NOTIFICATION_ERROR_OUT_OF_MEMORY Out of memory - * @see ui_notification_set_content() - */ -int ui_notification_get_content(ui_notification_h notification, char **content); - -/** - * @brief Sets the path of sound file to play when the notification is shown. - * @remarks The @a path should be the absolute path. \n - * The sound file is only supported wave file format. \n - * This function should be called before posting or updating the notification (see ui_notification_post(), ui_notification_update()). - * @param[in] notification The notification handle - * @param[in] path The path of sound file to play when the notification is shown \n - * If the @a path is NULL, it clears the previous value. - * @return 0 on success, otherwise a negative error value. - * @retval #UI_NOTIFICATION_ERROR_NONE Successful - * @retval #UI_NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #UI_NOTIFICATION_ERROR_OUT_OF_MEMORY Out of memory - * @see ui_notification_get_sound() - */ -int ui_notification_set_sound(ui_notification_h notification, const char *path); - -/** - * @brief Gets the path of sound file to play when the notification is shown. - * @remarks The @a path must be released with free() by you. - * @param[in] notification The notification handle - * @param[out] path The path of sound file to play when the notification is shown \n - * @return 0 on success, otherwise a negative error value. - * @retval #UI_NOTIFICATION_ERROR_NONE Successful - * @retval #UI_NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #UI_NOTIFICATION_ERROR_OUT_OF_MEMORY Out of memory - * @see ui_notification_set_sound() - */ -int ui_notification_get_sound(ui_notification_h notification, char **path); - -/** - * @brief Sets whether to use vibration when the notification is shown. - * @remarks This function should be called before posting or updating the notification (see ui_notification_post(), ui_notification_update()). - * @param[in] notification The notification handle - * @param[in] value A boolean value that sets whether to use vibration. - * @return 0 on success, otherwise a negative error value. - * @retval #UI_NOTIFICATION_ERROR_NONE Successful - * @retval #UI_NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #UI_NOTIFICATION_ERROR_OUT_OF_MEMORY Out of memory - * @see ui_notification_get_vibration() - */ -int ui_notification_set_vibration(ui_notification_h notification, bool value); - -/** - * @brief Gets whether to use vibration when the notification is shown. - * @param[in] notification The notification handle - * @param[out] value A boolean value that sets whether to use vibration. - * @return 0 on success, otherwise a negative error value. - * @retval #UI_NOTIFICATION_ERROR_NONE Successful - * @retval #UI_NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #UI_NOTIFICATION_ERROR_OUT_OF_MEMORY Out of memory - * @see ui_notification_set_vibration() - */ -int ui_notification_get_vibration(ui_notification_h notification, bool *value); - -/** - * @brief Sets the service to launch when the notification is selected from the notification tray. - * @details When the notification is selected from the notification tray, the application which is described by the specified service is launched. \n - * If you want to launch the current application, use the explicit launch of the @ref CAPI_SERVICE_MODULE API - * @remarks If the service is not set, the selected notification will be cleared from both the notification tray and the status bar without any action. \n - * This function should be called before posting or updating the notification (see ui_notification_post(), ui_notification_update()). - * @param[in] notification The notification handle - * @param[in] service The service handle to launch when the notification is selected \n - * If the @a service is NULL, it clears the previous value. - * @return 0 on success, otherwise a negative error value. - * @retval #UI_NOTIFICATION_ERROR_NONE Successful - * @retval #UI_NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #UI_NOTIFICATION_ERROR_OUT_OF_MEMORY Out of memory - * @see ui_notification_get_service() - * @see service_create() - */ -int ui_notification_set_service(ui_notification_h notification, service_h service); - -/** - * @brief Gets the service to launch when the notification is selected from the notification tray - * @remarks The @a service must be released with service_destroy() by you. - * @param[in] notification The notification handle - * @param[out] service The service handle to launch when the notification is selected - * @return 0 on success, otherwise a negative error value. - * @retval #UI_NOTIFICATION_ERROR_NONE Successful - * @retval #UI_NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #UI_NOTIFICATION_ERROR_OUT_OF_MEMORY Out of memory - * @see ui_notification_set_service() - */ -int ui_notification_get_service(ui_notification_h notification, service_h *service); - -/** - * @brief Posts the notification to display in the notification tray and the status bar - * @param[in] notification The notification handle - * @return 0 on success, otherwise a negative error value. - * @retval #UI_NOTIFICATION_ERROR_NONE Successful - * @retval #UI_NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #UI_NOTIFICATION_ERROR_DB_FAILED DB failed - * @retval #UI_NOTIFICATION_ERROR_NO_SUCH_FILE DB No such icon file - * @retval #UI_NOTIFICATION_ERROR_INVALID_STATE The notification was already posted - * @post The posted notification can be canceled or updated. - * @see ui_notification_cancel() - * @see ui_notification_cancel_all() - * @see ui_notification_update() - * @see ui_notification_update_progress() - * @see ui_notification_foreach_notification_posted() - */ -int ui_notification_post(ui_notification_h notification); - -/** - * @brief Cancels the previously posted notification. - * @details The previously posted notification is removed from the notification tray and the status bar. - * @remarks The canceled @a notification is not be released automatically, must be released with ui_notification_destroy() by you. - * @param[in] notification The notification handle - * @return 0 on success, otherwise a negative error value. - * @retval #UI_NOTIFICATION_ERROR_NONE Successful - * @retval #UI_NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #UI_NOTIFICATION_ERROR_INVALID_STATE The notification was not posted or the notification was either cleared or canceled. - * @pre The notification must be posted before canceling it. - * @see ui_notification_post() - * @see ui_notification_cancel_all() - */ -int ui_notification_cancel(ui_notification_h notification); - -/** - * @brief Cancels all previously posted notifications by the current application. - * @details All previously posted notifications are removed from the notification tray and the status bar. - * @remarks The notifications posted by other applications are not canceled from the notification tray and the status bar. - * @see ui_notification_post() - * @see ui_notification_cancel() - */ -void ui_notification_cancel_all(void); - -/** - * @brief Cancels selected type of previously posted notifications by the current application. - * @details Selected type of previously posted notifications are removed from the notification tray and the status bar. - * @remarks The notifications posted by other applications are not cancelled from the notification tray and the status bar. - * @param[in] ongoing A boolean value that indicates whether the notification type is ongoing to cancel. - * @see ui_notification_post() - * @see ui_notification_cancel() - * @see ui_notification_cancel_all() - */ -void ui_notification_cancel_all_by_type(bool ongoing); - -/** - * @brief Cancels selected type of previously posted notifications by the given application. - * @details Selected type of previously posted notifications are removed from the notification tray and the status bar. - * @remark This function is @b deprecated. Use app_manager_app_context_cb() instead. - * @param[in] package The package name of the application to calcel the posted notifications. - * @param[in] ongoing A boolean value that indicates whether the notification type is ongoing to cancel. - * @see ui_notification_post() - * @see ui_notification_cancel() - * @see ui_notification_cancel_all() - */ -void ui_notification_cancel_all_by_package(const char *package, bool ongoing); - -/** - * @brief Cancels selected type of previously posted notifications by the given application ID. - * @details Selected type of previously posted notifications are removed from the notification tray and the status bar. - * @param[in] id The ID of the application to calcel the posted notifications. - * @param[in] ongoing A boolean value that indicates whether the notification type is ongoing to cancel. - * @return 0 on success, otherwise a negative error value. - * @retval #UI_NOTIFICATION_ERROR_NONE Successful - * @retval #UI_NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter - * @see ui_notification_post() - * @see ui_notification_cancel() - * @see ui_notification_cancel_all() - */ -int ui_notification_cancel_all_by_app_id(const char *app_id, bool ongoing); - -/** - * @brief Updates the notification posted. - * @remarks You cannot update the notification which was cleared or canceled. - * @param[in] notification The notification handle - * @return 0 on success, otherwise a negative error value. - * @retval #UI_NOTIFICATION_ERROR_NONE Successful - * @retval #UI_NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #UI_NOTIFICATION_ERROR_DB_FAILED DB failed - * @retval #UI_NOTIFICATION_ERROR_NO_SUCH_FILE DB No such icon file - * @retval #UI_NOTIFICATION_ERROR_INVALID_STATE The notification was not posted or the notification was either cleared or canceled. - * @pre The notification must be posted before updating it. - * @see ui_notification_post() - * @see ui_notification_update_progress() - */ -int ui_notification_update(ui_notification_h notification); - -/** - * @brief Updates the progress to the specified value - * @remarks You cannot update the notification which was cleared or canceled. - * @param[in] notification The notification handle \n - * It must be ongoing notification. \n - * If not, #UI_NOTIFICATION_ERROR_INVALID_PARAMETER will occur - * @param[in] type The progress type - * @param[in] value The value of the progress \n - * The @a value must be greater than or equal to zero. \n - * if @a type is #UI_NOTIFICATION_PROGRESS_TYPE_SIZE, it must be in bytes. \n - * If @a type is #UI_NOTIFICATION_PROGRESS_TYPE_PERCENTAGE, It must be a floating-point value between 0.0 and 1.0. - * @return 0 on success, otherwise a negative error value. - * @retval #UI_NOTIFICATION_ERROR_NONE Successful - * @retval #UI_NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #UI_NOTIFICATION_ERROR_INVALID_STATE The notification was not posted or the notification was canceled. - * @pre The notification must be posted before updating the progress to the specified value - * @see ui_notification_create() - * @see ui_notification_post() - * @see ui_notification_update() - * @see #ui_notification_progress_type_e - */ -int ui_notification_update_progress(ui_notification_h notification, ui_notification_progress_type_e type, double value); - -/** - * @brief Retrieves all posted notifications. - * @details This function calls ui_notification_cb() once for each notification which was posted and is being shown. \n - * If ui_notification_cb() callback function returns false, then iteration will be finished. - * - * @param [in] ongoing A boolean value that sets whether the type is an ongoing notification. - * @param [in] callback The iteration callback function - * @param [in] user_data The user data to be passed to the callback function - * @return 0 on success, otherwise a negative error value. - * @retval #UI_NOTIFICATION_ERROR_NONE Successful - * @retval #UI_NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter - * @post This function invokes ui_notification_cb(). - * @see ui_notification_cb() - */ -int ui_notification_foreach_notification_posted(bool ongoing, ui_notification_cb callback, void *user_data); - -/** - * @brief Creates and returns a copy of the given notification handle. - * - * @remarks A newly created notification handle should be destroyed by calling ui_notification_destroy() if it is no longer needed. - * - * @param [out] clone If successful, a newly created notification handle will be returned. - * @param [in] service The notification handle - * @return 0 on success, otherwise a negative error value. - * @retval #UI_NOTIFICATION_ERROR_NONE Successful - * @retval #UI_NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #UI_NOTIFICATION_ERROR_OUT_OF_MEMORY Out of memory - * @see ui_notification_create() - * @see ui_notification_destroy() - */ -int ui_notification_clone(ui_notification_h *clone, ui_notification_h notification); - - -/** - * @} - */ - -#ifdef __cplusplus -} -#endif - -#endif /* __TIZEN_APPFW_UI_NOTIFICATION_H__ */ |