From: Sangyoon Jang Date: Tue, 2 Jun 2015 08:41:25 +0000 (+0900) Subject: Update doxygen X-Git-Tag: submit/tizen/20170725.231500~6^2~119 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=9d28301e1b67dd26cee475b328c435faa3b3e1db;p=platform%2Fcore%2Fapi%2Fpreference.git Update doxygen update doxygen from Tizen 2.4 seperate errno definition Change-Id: I6a36796c7cac94dda3c43ebb78c250ffc51e5b0e Signed-off-by: Sangyoon Jang --- diff --git a/include/app.h b/include/app.h index c54b3e1..26fc695 100644 --- a/include/app.h +++ b/include/app.h @@ -25,6 +25,7 @@ #include #include #include +#include #ifdef __cplusplus extern "C" { @@ -36,20 +37,6 @@ extern "C" { */ -/** - * @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 Called at the start of the application. * diff --git a/include/app_alarm.h b/include/app_alarm.h index c61d2b1..96f78cf 100644 --- 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. */ @@ -26,32 +26,40 @@ 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 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,34 +73,41 @@ 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. + * @deprecated Deprecated since 2.4. [Use alarm_schedule_once_after_delay() instead] + * @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 - * - * @remarks If application is uninstalled after setting an alarm, the alarm is canceled automatically. + * 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. * - * @param[in] app_control The destination app_control 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() @@ -102,24 +117,30 @@ int alarm_schedule_after_delay(app_control_h app_control, int delay, int period, /** - * @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 - * - * @remarks If application is uninstalled after setting an alarm, the alarm is canceled automatically. + * @deprecated Deprecated since 2.4. [Use alarm_schedule_once_at_date() instead] + * @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. * * @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() @@ -127,7 +148,6 @@ int alarm_schedule_after_delay(app_control_h app_control, int delay, int period, */ 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 after a specific time. * @details The alarm will go off @a delay seconds later. @@ -183,28 +203,33 @@ int alarm_schedule_once_after_delay(app_control_h app_control, int delay, int *a */ int alarm_schedule_once_at_date(app_control_h app_control, struct tm *date, 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] 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 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 */ @@ -213,13 +238,20 @@ int alarm_schedule_with_recurrence_week_flag(app_control_h app_control, struct t /** * @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 */ @@ -227,11 +259,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() @@ -241,11 +278,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() @@ -255,29 +296,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() @@ -286,15 +335,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() @@ -303,25 +357,32 @@ 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 app_control to be invoked when the the alarm is triggered - * @remarks The @a app_control must be released with app_control_destroy() by you. - * @param[in] alarm_id The alarm ID uniquely identifies an alarm + * @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 0 on success, otherwise a negative error value. + * @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() diff --git a/include/app_common.h b/include/app_common.h index 7bb505c..f025299 100644 --- a/include/app_common.h +++ b/include/app_common.h @@ -18,6 +18,8 @@ #ifndef __TIZEN_APPFW_APP_COMMON_H__ #define __TIZEN_APPFW_APP_COMMON_H__ +#include + #ifdef __cplusplus extern "C" { #endif @@ -34,7 +36,7 @@ extern "C" { /** * @brief Enumeration for system events - * @since_tizen 2.3 + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif */ typedef enum { @@ -48,7 +50,7 @@ typedef enum /** * @brief Enumeration for device orientation. - * @since_tizen 2.3 + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif */ typedef enum { @@ -61,7 +63,7 @@ typedef enum /** * @brief Enumeration for low memory status. - * @since_tizen 2.3 + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif */ typedef enum { @@ -73,7 +75,7 @@ typedef enum /** * @brief Enumeration for battery status. - * @since_tizen 2.3 + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif */ typedef enum { @@ -85,7 +87,7 @@ typedef enum /** * @brief The event handler that returned from add event handler function * - * @since_tizen 2.3 + * @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 @@ -97,7 +99,7 @@ typedef struct app_event_handler* app_event_handler_h; /** * @brief The system event information * - * @since_tizen 2.3 + * @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 @@ -110,7 +112,7 @@ typedef struct app_event_info* app_event_info_h; /** * @brief The system event callback function * - * @since_tizen 2.3 + * @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 * @@ -123,7 +125,7 @@ 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 2.3 + * @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 * @@ -141,7 +143,7 @@ int app_event_get_low_memory_status(app_event_info_h event_info, app_event_low_m /** * @brief Gets the low battery status from given event info * - * @since_tizen 2.3 + * @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 * @@ -159,7 +161,7 @@ int app_event_get_low_battery_status(app_event_info_h event_info, app_event_low_ /** * @brief Gets the language from given event info * - * @since_tizen 2.3 + * @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 @@ -177,7 +179,7 @@ int app_event_get_language(app_event_info_h event_info, char **lang); /** * @brief Gets the region format from given event info * - * @since_tizen 2.3 + * @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 @@ -195,7 +197,7 @@ 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 2.3 + * @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 * @@ -213,7 +215,7 @@ int app_event_get_device_orientation(app_event_info_h event_info, app_device_ori /** * @brief Gets the ID of the application. * - * @since_tizen 2.3 + * @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 @@ -232,7 +234,7 @@ int app_get_id(char **id); /** * @brief Gets the localized name of the application. * - * @since_tizen 2.3 + * @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 @@ -251,7 +253,7 @@ int app_get_name(char **name); /** * @brief Gets the version of the application package. * - * @since_tizen 2.3 + * @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 @@ -271,7 +273,7 @@ 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 2.3 + * @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 @@ -284,7 +286,7 @@ 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 2.3 + * @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. @@ -299,7 +301,7 @@ 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 2.3 + * @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 @@ -313,7 +315,7 @@ char *app_get_resource_path(void); * 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 2.3 + * @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 @@ -327,7 +329,7 @@ char *app_get_shared_data_path(void); * 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 2.3 + * @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 @@ -342,7 +344,7 @@ char *app_get_shared_resource_path(void); * @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 2.3 + * @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 @@ -356,7 +358,7 @@ char *app_get_shared_trusted_path(void); * store data of the application. * @details An application can read and write its own files in the application's external data * directory. - * @since_tizen 2.3 + * @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. @@ -372,7 +374,7 @@ char *app_get_external_data_path(void); * 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 2.3 + * @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 @@ -390,7 +392,7 @@ char *app_get_external_cache_path(void); * 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 2.3 + * @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 diff --git a/include/app_control.h b/include/app_control.h index 7671bad..be6427e 100644 --- a/include/app_control.h +++ b/include/app_control.h @@ -35,38 +35,39 @@ extern "C" { typedef struct _bundle_t bundle; - +typedef unsigned char bundle_raw; /** * @brief App Control handle. - * @since_tizen 2.3 + * @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 2.3 + * @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_CLASS | 0x21, /**< The application is not found */ + 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_CLASS | 0x22, /**< Invalid data type */ - APP_CONTROL_ERROR_LAUNCH_REJECTED = TIZEN_ERROR_APPLICATION_CLASS | 0x23, /**< The application cannot be launched now*/ + 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_CLASS | 0x24, /**< Internal launch error */ - APP_CONTROL_ERROR_TIMED_OUT = TIZEN_ERROR_TIMED_OUT /**< Time out */ + 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_IO_ERROR = TIZEN_ERROR_IO_ERROR /**< IO error */ } app_control_error_e; /** * @brief Enumeration for App Control Result. - * @since_tizen 2.3 + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif */ typedef enum { @@ -75,52 +76,60 @@ typedef enum APP_CONTROL_RESULT_CANCELED = -2, /**< Operation canceled by the framework */ } app_control_result_e; +/** + * @brief Enumeration for App Control Launch Mode. + * @since_tizen 2.4 + */ +typedef enum { + APP_CONTROL_LAUNCH_MODE_SINGLE = 0, + APP_CONTROL_LAUNCH_MODE_GROUP, +} app_control_launch_mode_e; /** * @brief Definition for the app_control operation: main operation for an explicit launch. - * @since_tizen 2.3 + * @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 2.3 + * @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 2.3 + * @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 2.3 + * @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 2.3 + * @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 2.3 + * @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 2.3 + * @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. @@ -130,69 +139,69 @@ typedef enum /** * @brief Definition for the app_control operation: delivers some data to someone else. - * @since_tizen 2.3 + * @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 2.3 + * @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 2.3 + * @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 2.3 + * @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 2.3 + * @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 2.3 + * @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 2.3 + * @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 2.3 + * @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 2.3 + * @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 2.3 + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif */ #define APP_CONTROL_OPERATION_COMPOSE "http://tizen.org/appcontrol/operation/compose" @@ -206,63 +215,63 @@ typedef enum /** * @brief Definition for app_control optional data: the subject of a message. - * @since_tizen 2.3 + * @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 2.3 + * @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 2.3 + * @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 2.3 + * @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 2.3 + * @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 2.3 + * @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 2.3 + * @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 2.3 + * @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 2.3 + * @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" @@ -270,7 +279,7 @@ typedef enum /** * @brief Called when the reply of the launch request is delivered. * - * @since_tizen 2.3 + * @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. * @@ -288,7 +297,7 @@ typedef void (*app_control_reply_cb) (app_control_h request, app_control_h reply /** * @brief Called to retrieve the extra data contained in the app_control. * - * @since_tizen 2.3 + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif * * @remarks The @a key must not be deallocated by the application. * @@ -306,7 +315,7 @@ typedef bool (*app_control_extra_data_cb)(app_control_h app_control, const char /** * @brief Called once for each matched application that can be launched to handle the given app_control request. * - * @since_tizen 2.3 + * @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 @@ -323,7 +332,7 @@ typedef int (*app_control_host_res_fn)(void *data); /** * @brief Creates an app_control handle. * - * @since_tizen 2.3 + * @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, @@ -339,7 +348,7 @@ int app_control_create(app_control_h *app_control); /** * @brief Destroys the app_control handle and releases all its resources. * - * @since_tizen 2.3 + * @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 @@ -351,27 +360,13 @@ int app_control_create(app_control_h *app_control); int app_control_destroy(app_control_h app_control); -/** - * @internal - * @brief Converts the app_control handle to bundle data. - * - * @since_tizen 2.3 - * @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 2.3 + * @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, @@ -396,7 +391,7 @@ int app_control_set_operation(app_control_h app_control, const char *operation); /** * @brief Gets the operation to be performed. * - * @since_tizen 2.3 + * @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 @@ -413,7 +408,7 @@ int app_control_get_operation(app_control_h app_control, char **operation); /** * @brief Sets the URI of the data. * - * @since_tizen 2.3 + * @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, @@ -428,7 +423,7 @@ int app_control_set_uri(app_control_h app_control, const char *uri); /** * @brief Gets the URI of the data. * - * @since_tizen 2.3 + * @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 @@ -445,7 +440,7 @@ int app_control_get_uri(app_control_h app_control, char **uri); /** * @brief Sets the explicit MIME type of the data. * - * @since_tizen 2.3 + * @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, @@ -460,7 +455,7 @@ int app_control_set_mime(app_control_h app_control, const char *mime); /** * @brief Gets the explicit MIME type of the data. * - * @since_tizen 2.3 + * @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 @@ -477,7 +472,7 @@ int app_control_get_mime(app_control_h app_control, char **mime); /** * @brief Sets the explicit category. * - * @since_tizen 2.3 + * @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, @@ -492,7 +487,7 @@ int app_control_set_category(app_control_h app_control, const char *category); /** * @brief Gets the explicit category. * - * @since_tizen 2.3 + * @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 @@ -509,7 +504,7 @@ int app_control_get_category(app_control_h app_control, char **category); /** * @brief Sets the ID of the application to explicitly launch. * - * @since_tizen 2.3 + * @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, @@ -525,7 +520,7 @@ 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 2.3 + * @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 @@ -538,44 +533,10 @@ int app_control_set_app_id(app_control_h app_control, const char *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 2.3 - * @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 2.3 - * @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 2.3 + * @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. @@ -597,7 +558,7 @@ int app_control_add_extra_data(app_control_h app_control, const char *key, const /** * @brief Adds the extra data array to the app_control. * - * @since_tizen 2.3 + * @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. @@ -620,7 +581,7 @@ int app_control_add_extra_data_array(app_control_h app_control, const char *key, /** * @brief Removes the extra data from the app_control. * - * @since_tizen 2.3 + * @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, @@ -638,7 +599,7 @@ 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 2.3 + * @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 @@ -663,7 +624,7 @@ int app_control_get_extra_data(app_control_h app_control, const char *key, char /** * @brief Gets the extra data array from the app_control. * - * @since_tizen 2.3 + * @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 @@ -688,7 +649,7 @@ int app_control_get_extra_data_array(app_control_h app_control, const char *key, /** * @brief Checks whether the extra data associated with the given @a key is of array data type. * - * @since_tizen 2.3 + * @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, @@ -710,7 +671,7 @@ int app_control_is_extra_data_array(app_control_h app_control, const char *key, * @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 2.3 + * @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 @@ -727,7 +688,7 @@ int app_control_foreach_extra_data(app_control_h app_control, app_control_extra_ /** * @brief Retrieves all applications that can be launched to handle the given app_control request. * - * @since_tizen 2.3 + * @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 @@ -747,9 +708,10 @@ int app_control_foreach_app_matched(app_control_h app_control, app_control_app_m * @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. - * @since_tizen 2.3 + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif * @privlevel public * @privilege %http://tizen.org/privilege/appmanager.launch + * @remarks The function returns #APP_CONTROL_ERROR_LAUNCH_REJECTED if the operation value is #APP_CONTROL_OPERATION_LAUNCH_ON_EVENT which is only for handling the event from the platform or other application, refer to @a Event module. * @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 @@ -773,7 +735,7 @@ int app_control_send_launch_request(app_control_h app_control, app_control_reply /** * @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 2.3 + * @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 @@ -789,7 +751,7 @@ 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 2.3 + * @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 @@ -806,7 +768,7 @@ int app_control_reply_to_launch_request(app_control_h reply, app_control_h reque /** * @brief Creates and returns a copy of the given app_control handle. * - * @since_tizen 2.3 + * @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 @@ -824,7 +786,7 @@ 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 2.3 + * @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(). @@ -842,7 +804,7 @@ 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 2.3 + * @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() @@ -857,22 +819,36 @@ int app_control_get_caller(app_control_h app_control, char **id); 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. + * @brief Sets the launch mode of the application. * - * @since_tizen 2.3 - * @remarks The @a callee_id window is transient for the top-level caller window and should be handled accordingly. + * @since_tizen 2.4 * @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. + * @param[in] launch_mode The launch mode of app + * + * @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_set_launch_mode() + * @see app_control_launch_mode_e */ -int app_control_request_transient_app(app_control_h app_control, unsigned int callee_id, app_control_host_res_fn cbfunc, void *data); +int app_control_set_launch_mode(app_control_h app_control, + app_control_launch_mode_e mode); +/** + * @brief Gets the launch mode of the application. + * + * @since_tizen 2.4 + * @param[in] app_control The app_control handle + * @param[out] launch_mode The launch mode of app + * + * @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_get_launch_mode() + * @see app_control_launch_mode_e + */ +int app_control_get_launch_mode(app_control_h app_control, + app_control_launch_mode_e *mode); /** * @} */ diff --git a/include/app_control_internal.h b/include/app_control_internal.h index 3daa86b..0da484a 100644 --- a/include/app_control_internal.h +++ b/include/app_control_internal.h @@ -84,6 +84,54 @@ int app_control_create_request(bundle *data, app_control_h *app_control); int app_control_create_event(bundle *data, app_control_h *app_control); +int app_control_to_bundle(app_control_h app_control, bundle **data); + +/** + * @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); + +/** + * @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 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); + /** * @} */ diff --git a/include/app_i18n.h b/include/app_i18n.h index d6f1e81..69e0ce7 100644 --- 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_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 + +/** + * @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__ */