/*
 * Copyright (c) 2018 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_WATCHFACE_COMPLICATION_H__
#define __TIZEN_APPFW_WATCHFACE_COMPLICATION_H__

#include <tizen.h>
#include <bundle.h>
#include <time.h>

#include <watchface-common.h>

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @file watchface-complication.h
 * @brief This file contains APIs and enumerations for Watchface complication.
 */

/**
 * @addtogroup WATCHFACE_COMPLICATION_COMPLICATION_MODULE
 * @{
 */

/**
 * @brief The complication handle.
 * @since_tizen 5.0
 */
typedef void *complication_h;

/**
 * @brief Called when the complication is updated.
 * @since_tizen 5.0
 * @param[in] complication_id A number that identifies the complication
 * @param[in] provider_id The name of the provider
 *            The @a provider_id can be used only in the callback. To use outside, make a copy.
 * @param[in] type The type shown in the complication
 * @param[in] data The data of the complication provided by the provider
 *            The @a data can be used only in the callback. To use outside, make a copy.
 * @param[in] user_data The user data passed from the callback function
 */
typedef void (*watchface_complication_updated_cb)(
			int complication_id,
			const char *provider_id,
			watchface_complication_type_e type,
			const bundle *data,
			void *user_data);

/**
 * @brief Called when the complication provider error is occured.
 * @details Following error codes can be delivered.
 *          #WATCHFACE_COMPLICATION_ERROR_PROVIDER_NOT_AVAILABLE : Provider application is not available now for some reason. (eg. uninstall, disable) \n
 *          #WATCHFACE_COMPLICATION_ERROR_IO_ERROR : Provider application is not responding for update request. \n
 *          #WATCHFACE_COMPLICATION_ERROR_OUT_OF_MEMORY : Out of memory.
 * @since_tizen 5.0
 * @param[in] complication_id A number that identifies the complication
 * @param[in] provider_id The name of the provider.
 *            The @a provider_id can be used only in the callback. To use outside, make a copy.
 * @param[in] type The type shown in the complication
 * @param[in] error The error related with complication provider
 * @param[in] user_data The user data passed from the callback function
 */
typedef void (*watchface_complication_error_cb)(
            int complication_id,
            const char *provider_id,
            watchface_complication_type_e type,
            watchface_complication_error_e error,
            void *user_data);

/**
 * @brief Gets the id of provider in the complication.
 * @since_tizen 5.0
 * @remarks The @a cur_provider should be released using free().
 * @param[in] handle Complication handle
 * @param[out] cur_provider The name of the provider supplying the data
 * @return #WATCHFACE_COMPLICATION_ERROR_NONE if success, other value if failure
 * @retval #WATCHFACE_COMPLICATION_ERROR_NONE Success
 * @retval #WATCHFACE_COMPLICATION_ERROR_NOT_SUPPORTED Not supported
 * @retval #WATCHFACE_COMPLICATION_ERROR_INVALID_PARAMETER Invalid parameter
 * @retval #WATCHFACE_COMPLICATION_ERROR_NO_DATA No data
 * @pre Complication handle should be created by watchface_complication_create().
 * @par Sample code:
 * @code
#include <watchface-complication.h>
{
	int ret;
	int comp_id = 1;
	complication_h complication;
	const char *cur_provider_id;

	ret = watchface_complication_create(comp_id, "org.tizen.sample",
		WATCHFACE_COMPLICATION_TYPE_SHORT_TEXT, WATCHFACE_COMPLICATION_TYPE_SHORT_TEXT,
		WATCHFACE_COMPLICATION_EVENT_TAP,
		&complication);
	if (ret != WATCHFACE_COMPLICATION_ERROR_NONE || complication == NULL)
		return ret;

	ret = watchface_complication_get_current_provider_id(complication, &cur_provider_id);
	if (ret != WATCHFACE_COMPLICATION_ERROR_NONE)
		return ret;
}
 * @endcode
 */
int watchface_complication_get_current_provider_id(complication_h handle,
			char **cur_provider);

/**
 * @brief Gets the currently set type of the complication.
 * @since_tizen 5.0
 * @param[in] handle Complication handle
 * @param[out] cur_type The type shown in the complication
 * @return #WATCHFACE_COMPLICATION_ERROR_NONE if success, other value if failure
 * @retval #WATCHFACE_COMPLICATION_ERROR_NONE Success
 * @retval #WATCHFACE_COMPLICATION_ERROR_NOT_SUPPORTED Not supported
 * @retval #WATCHFACE_COMPLICATION_ERROR_INVALID_PARAMETER Invalid parameter
 * @retval #WATCHFACE_COMPLICATION_ERROR_NO_DATA No data
 * @par Sample code:
 * @code
#include <watchface-complication.h>
{
	int ret;
	int comp_id = 1;
	complication_h complication;
	watchface_complication_type_e cur_type;

	ret = watchface_complication_create(comp_id, "org.tizen.sample",
		WATCHFACE_COMPLICATION_TYPE_SHORT_TEXT, WATCHFACE_COMPLICATION_TYPE_SHORT_TEXT,
		WATCHFACE_COMPLICATION_EVENT_TAP,
		&complication);
	if (ret != WATCHFACE_COMPLICATION_ERROR_NONE || complication == NULL)
		return ret;

	ret = watchface_complication_get_current_type(complication, &cur_type);
	if (ret != WATCHFACE_COMPLICATION_ERROR_NONE)
		return ret;
}
 * @endcode
 */
int watchface_complication_get_current_type(complication_h handle,
			watchface_complication_type_e *cur_type);

/**
 * @brief Adds the callback function to use for complication update.
 * @since_tizen 5.0
 * @privlevel public
 * @privilege http://tizen.org/privilege/datasharing
 * @param[in] handle Complication handle
 * @param[in] cb The callback function
 * @param[in] error_cb The error callback function
 * @param[in] user_data The user data to pass to the callback function
 * @return #WATCHFACE_COMPLICATION_ERROR_NONE if success, other value if failure
 * @retval #WATCHFACE_COMPLICATION_ERROR_NONE Success
 * @retval #WATCHFACE_COMPLICATION_ERROR_NOT_SUPPORTED Not supported
 * @retval #WATCHFACE_COMPLICATION_ERROR_PERMISSION_DENIED Permission denied
 * @retval #WATCHFACE_COMPLICATION_ERROR_INVALID_PARAMETER Invalid parameter
 * @retval #WATCHFACE_COMPLICATION_ERROR_OUT_OF_MEMORY Out of memory
 * @retval #WATCHFACE_COMPLICATION_ERROR_IO_ERROR I/O error
 * @pre Complication handle should be created by watchface_complication_create().
 * @see watchface_complication_updated_cb()
 * @see watchface_complication_error_cb()
 * @par Sample code:
 * @code
#include <watchface-complication.h>
{
	int ret;
	int comp_id = 1;
	complication_h complication;

	ret = watchface_complication_create(comp_id, "org.tizen.sample",
		WATCHFACE_COMPLICATION_TYPE_SHORT_TEXT, WATCHFACE_COMPLICATION_TYPE_SHORT_TEXT,
		WATCHFACE_COMPLICATION_EVENT_TAP,
		&complication);
	if (ret != WATCHFACE_COMPLICATION_ERROR_NONE || complication == NULL)
		return ret;

	ret = watchface_complication_add_updated_cb(complication,
			_watchface_complication_updated_cb,
			_watchface_complication_error_cb, NULL);
	if (ret != WATCHFACE_COMPLICATION_ERROR_NONE)
		return ret;
}
 * @endcode
 */
int watchface_complication_add_updated_cb(complication_h handle,
			watchface_complication_updated_cb cb,
			watchface_complication_error_cb error_cb,
			void *user_data);

/**
 * @brief Removes the callback function.
 * @since_tizen 5.0
 * @param[in] handle Complication handle
 * @param[in] cb The callback function
 * @return #WATCHFACE_COMPLICATION_ERROR_NONE if success, other value if failure
 * @retval #WATCHFACE_COMPLICATION_ERROR_NONE Success
 * @retval #WATCHFACE_COMPLICATION_ERROR_NOT_SUPPORTED Not supported
 * @retval #WATCHFACE_COMPLICATION_ERROR_INVALID_PARAMETER Invalid parameter
 * @see watchface_complication_updated_cb()
 * @par Sample code:
 * @code
#include <watchface-complication.h>
{
	int ret;

	ret = watchface_complication_remove_updated_cb(complication,
			_watchface_complication_updated_cb);
	if (ret != WATCHFACE_COMPLICATION_ERROR_NONE)
		return ret;
}
 * @endcode
 */
int watchface_complication_remove_updated_cb(complication_h handle,
			watchface_complication_updated_cb cb);

/**
 * @brief Sends request the provider to update the complication.
 * @since_tizen 5.0
 * @privlevel public
 * @privilege http://tizen.org/privilege/appmanager.launch
 * @privilege http://tizen.org/privilege/datasharing
 * @remarks The watchface complication provider application can declare
 *          privileges for specific provider id in manifest xml file, in that case,
 *          the watchface application needs those privileges to use this function.
 *          If your app doesn't have those privileges, this function will return #WATCHFACE_COMPLICATION_ERROR_PERMISSION_DENIED.
 * @param[in] handle Complication handle
 * @return #WATCHFACE_COMPLICATION_ERROR_NONE if success, other value if failure
 * @retval #WATCHFACE_COMPLICATION_ERROR_NONE Success
 * @retval #WATCHFACE_COMPLICATION_ERROR_NOT_SUPPORTED Not supported
 * @retval #WATCHFACE_COMPLICATION_ERROR_PERMISSION_DENIED Permission denied
 * @retval #WATCHFACE_COMPLICATION_ERROR_INVALID_PARAMETER Invalid parameter
 * @retval #WATCHFACE_COMPLICATION_ERROR_IO_ERROR I/O error
 * @retval #WATCHFACE_COMPLICATION_ERROR_OUT_OF_MEMORY Out of memory
 * @retval #WATCHFACE_COMPLICATION_ERROR_DB Database error
 * @par Sample code:
 * @code
#include <watchface-complication.h>
{
	int ret;
	int comp_id = 1;
	complication_h complication;
	int supported_types;

	ret = watchface_complication_create(comp_id, "org.tizen.sample",
		WATCHFACE_COMPLICATION_TYPE_SHORT_TEXT, WATCHFACE_COMPLICATION_TYPE_SHORT_TEXT,
		WATCHFACE_COMPLICATION_EVENT_TAP,
		&complication);
	if (ret != WATCHFACE_COMPLICATION_ERROR_NONE || complication == NULL)
		return ret;

	ret = watchface_complication_send_update_request(complication);
	if (ret != WATCHFACE_COMPLICATION_ERROR_NONE)
		return ret;
}
 * @endcode
 */
int watchface_complication_send_update_request(complication_h handle);

/**
 * @brief Creates a complication handle.
 * @details The default provider and type are the items to set for initial display.
 *          If user selects the other provider and type, they are no longer used.
 *          You can specify @a supported_types by combining the types you want to show in the complication.
 *          You can specify @a supported_event_types by combining the event types you want to handle for the complication.
 * @since_tizen 5.0
 * @privlevel public
 * @privilege http://tizen.org/privilege/packagemanager.info
 * @remarks The @a created_handle should be released using watchface_complication_destroy().
 *          Package manager privilege is needed to lookup provider application.
 *          The @a default_provider_id and the @a default_type are not always first setted value of the @a created_handle,
 *          it can be other value if user changed provider and type using watchface editor.
 *          Sum up, the @a created_handle will have @a default_provider_id and  @a default_type as current value,
 *          if user never changed it before.
 * @param[in] complication_id A number that identifies the complication
 * @param[in] default_provider_id The default provider id
 * @param[in] default_type The default type to display
 * @param[in] supported_types The type shown in the complication, values of #watchface_complication_type_e combined with bitwise 'or'.
 * @param[in] supported_event_types The event type supported by complication, values of #watchface_complication_event_type_e combined with bitwise 'or'.
 *          Complication can send supported event to the provider using watchface_complication_transfer_event().
 * @param[out] created_handle Complication handle on success
 * @return #WATCHFACE_COMPLICATION_ERROR_NONE if success, other value if failure
 * @retval #WATCHFACE_COMPLICATION_ERROR_NONE Success
 * @retval #WATCHFACE_COMPLICATION_ERROR_NOT_SUPPORTED Not supported
 * @retval #WATCHFACE_COMPLICATION_ERROR_PERMISSION_DENIED Permission denied
 * @retval #WATCHFACE_COMPLICATION_ERROR_INVALID_PARAMETER Invalid parameter
 * @retval #WATCHFACE_COMPLICATION_ERROR_IO_ERROR I/O error
 * @retval #WATCHFACE_COMPLICATION_ERROR_EXIST_ID Already exist @a complication_id
 * @retval #WATCHFACE_COMPLICATION_ERROR_NOT_EXIST Provider does not exist
 * @retval #WATCHFACE_COMPLICATION_ERROR_OUT_OF_MEMORY Out of memory
 * @retval #WATCHFACE_COMPLICATION_ERROR_DB Database error
 * @retval #WATCHFACE_COMPLICATION_ERROR_PROVIDER_NOT_AVAILABLE Provider application is not available now for some reason. (eg. uninstall, disable)
 * @see watchface_complication_type_e
 * @see watchface_complication_event_type_e
 * @see watchface_complication_transfer_event()
 * @par Sample code:
 * @code
#include <watchface-complication.h>

complication_h complication;
void on_tap() {
	watchface_complication_transfer_event(complication,
			WATCHFACE_COMPLICATION_EVENT_TAP);
}

{
	int ret;
	int comp_id = 1;

	ret = watchface_complication_create(comp_id, "org.tizen.sample",
		WATCHFACE_COMPLICATION_TYPE_SHORT_TEXT,
		WATCHFACE_COMPLICATION_TYPE_SHORT_TEXT|WATCHFACE_COMPLICATION_TYPE_ICON,
		WATCHFACE_COMPLICATION_EVENT_TAP,
		&complication);
	if (ret != WATCHFACE_COMPLICATION_ERROR_NONE || complication == NULL)
		return ret;
}
 * @endcode
 */
int watchface_complication_create(int complication_id,
			const char *default_provider_id,
			watchface_complication_type_e default_type,
			int supported_types,
			int supported_event_types,
			complication_h *created_handle);

/**
 * @brief Destroys a complication handle.
 * @since_tizen 5.0
 * @param[in] handle Complication handle
 * @return #WATCHFACE_COMPLICATION_ERROR_NONE if success, other value if failure
 * @retval #WATCHFACE_COMPLICATION_ERROR_NONE Success
 * @retval #WATCHFACE_COMPLICATION_ERROR_NOT_SUPPORTED Not supported
 * @retval #WATCHFACE_COMPLICATION_ERROR_INVALID_PARAMETER Invalid parameter
 * @pre Complication handle should be created by watchface_complication_create().
 * @see watchface_complication_create()
 * @par Sample code:
 * @code
#include <watchface-complication.h>
{
	int ret;
	complication_h complication;

	// Create complication

	// Do something

	ret = watchface_complication_destroy(complication);
	if (ret != WATCHFACE_COMPLICATION_ERROR_NONE)
		return;
}
 * @endcode
 */
int watchface_complication_destroy(complication_h handle);

/**
 * @brief Gets data type of complication data.
 * @details Developer can get different set of data from data depends on data type.
 *          Data will be passed through #watchface_complication_updated_cb callback and sent by complication provider app.
 * @since_tizen 5.0
 * @param[in] data The data received from complication provider app
 * @param[out] type The data type
 * @return #WATCHFACE_COMPLICATION_ERROR_NONE on success,
 *         otherwise an error code (see #watchface_complication_error_e) on failure
 * @retval #WATCHFACE_COMPLICATION_ERROR_NONE Successful
 * @retval #WATCHFACE_COMPLICATION_ERROR_NOT_SUPPORTED Not supported
 * @retval #WATCHFACE_COMPLICATION_ERROR_INVALID_PARAMETER Invalid parameter
 * @retval #WATCHFACE_COMPLICATION_ERROR_NO_DATA No data
 * @retval #WATCHFACE_COMPLICATION_ERROR_IO_ERROR I/O error
 * @see watchface_complication_type_e
 * @see watchface_complication_updated_cb()
 * @par Sample code:
 * @code
#include <watchface-complication.h>
void _on_complication_update(int complication_id,
		const char *provider_id,
		watchface_complication_type_e type,
		const bundle *data, void *user_data)
{
	watchface_complication_type_e type;
	watchface_complication_data_get_type(data, &type);
}
 * @endcode
 */
int watchface_complication_data_get_type(const bundle *data,
			watchface_complication_type_e *type);

/**
 * @brief Gets short text from complication data.
 * @since_tizen 5.0
 * @remarks The @a short_text should be freed using free().
 * @param[in] data The data received from complication provider app
 * @param[out] short_text The short text data
 * @return #WATCHFACE_COMPLICATION_ERROR_NONE on success,
 *         otherwise an error code (see #watchface_complication_error_e) on failure
 * @retval #WATCHFACE_COMPLICATION_ERROR_NONE Successful
 * @retval #WATCHFACE_COMPLICATION_ERROR_NOT_SUPPORTED Not supported
 * @retval #WATCHFACE_COMPLICATION_ERROR_INVALID_PARAMETER Invalid parameter
 * @retval #WATCHFACE_COMPLICATION_ERROR_OUT_OF_MEMORY Out of memory
 * @retval #WATCHFACE_COMPLICATION_ERROR_NO_DATA No data
 * @see watchface_complication_type_e
 * @see watchface_complication_updated_cb()
 * @par Sample code:
 * @code
#include <watchface-complication.h>
void _on_complication_update(int complication_id,
		const char *provider_id,
		watchface_complication_type_e type,
		const bundle *data, void *user_data)
{
	char *value;
	watchface_complication_type_e type;

	watchface_complication_data_get_type(data, &type);
	if (type == WATCHFACE_COMPLICATION_TYPE_SHORT_TEXT)
		watchface_complication_data_get_short_text(data, &value);
}
 * @endcode
 */
int watchface_complication_data_get_short_text(const bundle *data,
			char **short_text);

/**
 * @brief Gets long text from complication data.
 * @since_tizen 5.0
 * @remarks The @a long_text should be freed using free().
 * @param[in] data The data received from complication provider app
 * @param[out] long_text The long text data
 * @return #WATCHFACE_COMPLICATION_ERROR_NONE on success,
 *         otherwise an error code (see #watchface_complication_error_e) on failure
 * @retval #WATCHFACE_COMPLICATION_ERROR_NONE Successful
 * @retval #WATCHFACE_COMPLICATION_ERROR_NOT_SUPPORTED Not supported
 * @retval #WATCHFACE_COMPLICATION_ERROR_INVALID_PARAMETER Invalid parameter
 * @retval #WATCHFACE_COMPLICATION_ERROR_OUT_OF_MEMORY Out of memory
 * @retval #WATCHFACE_COMPLICATION_ERROR_NO_DATA No data
 * @see watchface_complication_type_e
 * @see watchface_complication_updated_cb()
 * @par Sample code:
 * @code
#include <watchface-complication.h>
void _on_complication_update(int complication_id,
		const char *provider_id,
		watchface_complication_type_e type,
		const bundle *data, void *user_data)
{
	char *value;
	watchface_complication_type_e type;

	watchface_complication_data_get_type(data, &type);
	if (type == WATCHFACE_COMPLICATION_TYPE_LONG_TEXT)
		watchface_complication_data_get_long_text(data, &value);
}
 * @endcode
 */
int watchface_complication_data_get_long_text(const bundle *data,
			char **long_text);

/**
 * @brief Gets title text from complication data.
 * @since_tizen 5.0
 * @remarks The @a title should be freed using free().
 * @param[in] data The data received from complication provider app
 * @param[out] title The title text data
 * @return #WATCHFACE_COMPLICATION_ERROR_NONE on success,
 *         otherwise an error code (see #watchface_complication_error_e) on failure
 * @retval #WATCHFACE_COMPLICATION_ERROR_NONE Successful
 * @retval #WATCHFACE_COMPLICATION_ERROR_NOT_SUPPORTED Not supported
 * @retval #WATCHFACE_COMPLICATION_ERROR_INVALID_PARAMETER Invalid parameter
 * @retval #WATCHFACE_COMPLICATION_ERROR_OUT_OF_MEMORY Out of memory
 * @retval #WATCHFACE_COMPLICATION_ERROR_NO_DATA No data
 * @see watchface_complication_type_e
 * @see watchface_complication_updated_cb()
 * @par Sample code:
 * @code
#include <watchface-complication.h>
void _on_complication_update(int complication_id,
		const char *provider_id,
		watchface_complication_type_e type,
		const bundle *data, void *user_data)
{
	char *value;

	watchface_complication_data_get_title(data, &value);
}
 * @endcode
 */
int watchface_complication_data_get_title(const bundle *data, char **title);

/**
 * @deprecated Deprecated since 5.5. Use watchface_complication_data_get_timeinfo() instead.
 * @brief Gets timestamp from complication data.
 * @since_tizen 5.0
 * @param[in] data The data received from complication provider app
 * @param[out] timestamp The timestamp
 * @return #WATCHFACE_COMPLICATION_ERROR_NONE on success,
 *         otherwise an error code (see #watchface_complication_error_e) on failure
 * @retval #WATCHFACE_COMPLICATION_ERROR_NONE Successful
 * @retval #WATCHFACE_COMPLICATION_ERROR_NOT_SUPPORTED Not supported
 * @retval #WATCHFACE_COMPLICATION_ERROR_INVALID_PARAMETER Invalid parameter
 * @retval #WATCHFACE_COMPLICATION_ERROR_NO_DATA No data
 * @retval #WATCHFACE_COMPLICATION_ERROR_IO_ERROR I/O error
 * @see watchface_complication_type_e
 * @see watchface_complication_updated_cb()
 * @par Sample code:
 * @code
#include <watchface-complication.h>
void _on_complication_update(int complication_id,
		const char *provider_id,
		watchface_complication_type_e type,
		const bundle *data, void *user_data)
{
	long value;
	watchface_complication_type_e type;

	watchface_complication_data_get_type(data, &type);
	if (type == WATCHFACE_COMPLICATION_TYPE_TIME)
		watchface_complication_data_get_timestamp(data, &value);
}
 * @endcode
 */
int watchface_complication_data_get_timestamp(const bundle *data,
			long *timestamp) TIZEN_DEPRECATED_API;

/**
 * @brief Gets timeinfo from complication data.
 * @since_tizen 5.5
 * @remarks The @a info should be destroyed using watchface_complication_timeinfo_destroy().
 * @param[in] data The data received from complication provider app
 * @param[out] info The time information handle
 * @return #WATCHFACE_COMPLICATION_ERROR_NONE on success,
 *         otherwise an error code (see #watchface_complication_error_e) on failure
 * @retval #WATCHFACE_COMPLICATION_ERROR_NONE Successful
 * @retval #WATCHFACE_COMPLICATION_ERROR_NOT_SUPPORTED Not supported
 * @retval #WATCHFACE_COMPLICATION_ERROR_INVALID_PARAMETER Invalid parameter
 * @retval #WATCHFACE_COMPLICATION_ERROR_OUT_OF_MEMORY Out of memory
 * @retval #WATCHFACE_COMPLICATION_ERROR_NO_DATA No data
 * @retval #WATCHFACE_COMPLICATION_ERROR_IO_ERROR I/O error
 * @see #complication_time_info_h
 * @see watchface_complication_timeinfo_get_timezone()
 * @see watchface_complication_timeinfo_get_timezone_id()
 * @see watchface_complication_timeinfo_get_timezone_country()
 * @see watchface_complication_timeinfo_get_timezone_city()
 * @see watchface_complication_timeinfo_destroy()
 * @par Sample code:
 * @code
#include <watchface-complication.h>
void _on_complication_update(int complication_id,
		const char *provider_id,
		watchface_complication_type_e type,
		const bundle *data, void *user_data)
{
	complication_time_info_h info;
	watchface_complication_type_e type;

	watchface_complication_data_get_type(data, &type);
	if (type == WATCHFACE_COMPLICATION_TYPE_TIME) {
		watchface_complication_data_get_timeinfo(data, &info);
		watchface_complication_timeinfo_destroy(info);
	}
}
 * @endcode
 */
int watchface_complication_data_get_timeinfo(const bundle *data,
            complication_time_info_h *info);

/**
 * @brief Gets timezone from timeinfo.
 * @since_tizen 5.5
 * @remarks The @a timezone should be freed using free().
 * @param[in] info The time information handle
 * @param[out] timezone The timezone
 * @return #WATCHFACE_COMPLICATION_ERROR_NONE on success,
 *         otherwise an error code (see #watchface_complication_error_e) on failure
 * @retval #WATCHFACE_COMPLICATION_ERROR_NONE Successful
 * @retval #WATCHFACE_COMPLICATION_ERROR_NOT_SUPPORTED Not supported
 * @retval #WATCHFACE_COMPLICATION_ERROR_INVALID_PARAMETER Invalid parameter
 * @retval #WATCHFACE_COMPLICATION_ERROR_NO_DATA No data
 * @retval #WATCHFACE_COMPLICATION_ERROR_IO_ERROR I/O error
 * @see #complication_time_info_h
 * @see watchface_complication_data_get_timeinfo()
 * @see watchface_complication_timeinfo_get_timezone_id()
 * @see watchface_complication_timeinfo_get_timezone_country()
 * @see watchface_complication_timeinfo_get_timezone_city()
 * @see watchface_complication_timeinfo_destroy()
 * @par Sample code:
 * @code
#include <watchface-complication.h>
void _on_complication_update(int complication_id,
		const char *provider_id,
		watchface_complication_type_e type,
		const bundle *data, void *user_data)
{
	complication_time_info_h info;
	watchface_complication_type_e type;
	char *timezone;

	watchface_complication_data_get_type(data, &type);
	if (type == WATCHFACE_COMPLICATION_TYPE_TIME) {
		watchface_complication_data_get_timeinfo(data, &info);
		watchface_complication_timeinfo_get_timezone(info, &timezone);
		watchface_complication_timeinfo_destroy(info);
	}
}
 * @endcode
 */
int watchface_complication_timeinfo_get_timezone(complication_time_info_h info,
            char **timezone);

/**
 * @brief Gets timezone ID from timeinfo.
 * @since_tizen 5.5
 * @remarks The @a timezone_id should be freed using free().
 * @param[in] info The time information handle
 * @param[out] timezone_id The timezone ID
 * @return #WATCHFACE_COMPLICATION_ERROR_NONE on success,
 *         otherwise an error code (see #watchface_complication_error_e) on failure
 * @retval #WATCHFACE_COMPLICATION_ERROR_NONE Successful
 * @retval #WATCHFACE_COMPLICATION_ERROR_NOT_SUPPORTED Not supported
 * @retval #WATCHFACE_COMPLICATION_ERROR_INVALID_PARAMETER Invalid parameter
 * @retval #WATCHFACE_COMPLICATION_ERROR_NO_DATA No data
 * @retval #WATCHFACE_COMPLICATION_ERROR_IO_ERROR I/O error
 * @see #complication_time_info_h
 * @see watchface_complication_timeinfo_get_timezone()
 * @see watchface_complication_data_get_timeinfo()
 * @see watchface_complication_timeinfo_get_timezone_country()
 * @see watchface_complication_timeinfo_get_timezone_city()
 * @see watchface_complication_timeinfo_destroy()
 * @par Sample code:
 * @code
#include <watchface-complication.h>
void _on_complication_update(int complication_id,
		const char *provider_id,
		watchface_complication_type_e type,
		const bundle *data, void *user_data)
{
	complication_time_info_h info;
	watchface_complication_type_e type;
	char *timezone_id;

	watchface_complication_data_get_type(data, &type);
	if (type == WATCHFACE_COMPLICATION_TYPE_TIME) {
		watchface_complication_data_get_timeinfo(data, &info);
		watchface_complication_timeinfo_get_timezone_id(info, &timezone_id);
		watchface_complication_timeinfo_destroy(info);
	}
}
 * @endcode
 */
int watchface_complication_timeinfo_get_timezone_id(complication_time_info_h info,
            char **timezone_id);

/**
 * @brief Gets timezone country from timeinfo.
 * @since_tizen 5.5
 * @remarks The @a country should be freed using free().
 * @param[in] info The time information handle
 * @param[out] country The timezone country
 * @return #WATCHFACE_COMPLICATION_ERROR_NONE on success,
 *         otherwise an error code (see #watchface_complication_error_e) on failure
 * @retval #WATCHFACE_COMPLICATION_ERROR_NONE Successful
 * @retval #WATCHFACE_COMPLICATION_ERROR_NOT_SUPPORTED Not supported
 * @retval #WATCHFACE_COMPLICATION_ERROR_INVALID_PARAMETER Invalid parameter
 * @retval #WATCHFACE_COMPLICATION_ERROR_NO_DATA No data
 * @retval #WATCHFACE_COMPLICATION_ERROR_IO_ERROR I/O error
 * @see #complication_time_info_h
 * @see watchface_complication_timeinfo_get_timezone()
 * @see watchface_complication_data_get_timeinfo()
 * @see watchface_complication_timeinfo_get_timezone_id()
 * @see watchface_complication_timeinfo_get_timezone_city()
 * @see watchface_complication_timeinfo_destroy()
 * @par Sample code:
 * @code
#include <watchface-complication.h>
void _on_complication_update(int complication_id,
		const char *provider_id,
		watchface_complication_type_e type,
		const bundle *data, void *user_data)
{
	complication_time_info_h info;
	watchface_complication_type_e type;
	char *country;

	watchface_complication_data_get_type(data, &type);
	if (type == WATCHFACE_COMPLICATION_TYPE_TIME) {
		watchface_complication_data_get_timeinfo(data, &info);
		watchface_complication_timeinfo_get_timezone_country(info, &country);
		watchface_complication_timeinfo_destroy(info);
	}
}
 * @endcode
 */
int watchface_complication_timeinfo_get_timezone_country(complication_time_info_h info,
            char **country);

/**
 * @brief Gets timezone city from timeinfo.
 * @since_tizen 5.5
 * @remarks The @a city should be freed using free().
 * @param[in] info The time information handle
 * @param[out] city The timezone city
 * @return #WATCHFACE_COMPLICATION_ERROR_NONE on success,
 *         otherwise an error code (see #watchface_complication_error_e) on failure
 * @retval #WATCHFACE_COMPLICATION_ERROR_NONE Successful
 * @retval #WATCHFACE_COMPLICATION_ERROR_NOT_SUPPORTED Not supported
 * @retval #WATCHFACE_COMPLICATION_ERROR_INVALID_PARAMETER Invalid parameter
 * @retval #WATCHFACE_COMPLICATION_ERROR_NO_DATA No data
 * @retval #WATCHFACE_COMPLICATION_ERROR_IO_ERROR I/O error
 * @see #complication_time_info_h
 * @see watchface_complication_timeinfo_get_timezone()
 * @see watchface_complication_data_get_timeinfo()
 * @see watchface_complication_timeinfo_get_timezone_id()
 * @see watchface_complication_timeinfo_get_timezone()
 * @see watchface_complication_timeinfo_destroy()
 * @par Sample code:
 * @code
#include <watchface-complication.h>
void _on_complication_update(int complication_id,
		const char *provider_id,
		watchface_complication_type_e type,
		const bundle *data, void *user_data)
{
	complication_time_info_h info;
	watchface_complication_type_e type;
	char *city;

	watchface_complication_data_get_type(data, &type);
	if (type == WATCHFACE_COMPLICATION_TYPE_TIME) {
		watchface_complication_data_get_timeinfo(data, &info);
		watchface_complication_timeinfo_get_timezone_city(info, &city);
		watchface_complication_timeinfo_destroy(info);
	}
}
 * @endcode
 */
int watchface_complication_timeinfo_get_timezone_city(complication_time_info_h info,
            char **city);

/**
 * @brief Gets timestamp from timeinfo.
 * @since_tizen 5.5
 * @remarks The @a info should contain a timezone ID.
 *         If @a info doesn't contain a timezone ID, this function will return #WATCHFACE_COMPLICATION_ERROR_INVALID_PARAMETER.
 * @param[in] info The time information handle
 * @param[out] timestamp The number of seconds since 00:00, Jan 1 1970 UTC, corresponding to POSIX time.
 * @return #WATCHFACE_COMPLICATION_ERROR_NONE on success,
 *         otherwise an error code (see #watchface_complication_error_e) on failure
 * @retval #WATCHFACE_COMPLICATION_ERROR_NONE Successful
 * @retval #WATCHFACE_COMPLICATION_ERROR_NOT_SUPPORTED Not supported
 * @retval #WATCHFACE_COMPLICATION_ERROR_INVALID_PARAMETER Invalid parameter
 * @retval #WATCHFACE_COMPLICATION_ERROR_NO_DATA No data
 * @retval #WATCHFACE_COMPLICATION_ERROR_IO_ERROR I/O error
 * @see #complication_time_info_h
 * @see watchface_complication_data_get_timeinfo()
 * @see watchface_complication_timeinfo_get_timezone_id()
 * @see watchface_complication_timeinfo_get_timezone()
 * @see watchface_complication_timeinfo_destroy()
 * @par Sample code:
 * @code
#include <watchface-complication.h>
void _on_complication_update(int complication_id,
		const char *provider_id,
		watchface_complication_type_e type,
		const bundle *data, void *user_data)
{
	complication_time_info_h info;
	watchface_complication_type_e type;
	time_t timestamp;

	watchface_complication_data_get_type(data, &type);
	if (type == WATCHFACE_COMPLICATION_TYPE_TIME) {
		watchface_complication_data_get_timeinfo(data, &info);
		watchface_complication_timeinfo_get_timestamp(info, &timestamp);
		watchface_complication_timeinfo_destroy(info);
	}
}
 * @endcode
 */
int watchface_complication_timeinfo_get_timestamp(complication_time_info_h info,
            time_t *timestamp);

/**
 * @brief Destroys time information handle.
 * @since_tizen 5.5
 * @param[in] info The time information handle
 * @return #WATCHFACE_COMPLICATION_ERROR_NONE on success,
 *         otherwise an error code (see #watchface_complication_error_e) on failure
 * @retval #WATCHFACE_COMPLICATION_ERROR_NONE Successful
 * @retval #WATCHFACE_COMPLICATION_ERROR_NOT_SUPPORTED Not supported
 * @retval #WATCHFACE_COMPLICATION_ERROR_INVALID_PARAMETER Invalid parameter
 * @see #complication_time_info_h
 * @see watchface_complication_data_get_timeinfo()
 * @par Sample code:
 * @code
#include <watchface-complication.h>
void _on_complication_update(int complication_id,
		const char *provider_id,
		watchface_complication_type_e type,
		const bundle *data, void *user_data)
{
	complication_time_info_h info;
	watchface_complication_type_e type;

	watchface_complication_data_get_type(data, &type);
	if (type == WATCHFACE_COMPLICATION_TYPE_TIME) {
		watchface_complication_data_get_timeinfo(data, &info);
		watchface_complication_timeinfo_destroy(info);
	}
}
 * @endcode
 */
int watchface_complication_timeinfo_destroy(complication_time_info_h info);

/**
 * @brief Gets image path from complication data.
 * @since_tizen 5.0
 * @remarks The @a image_path should be freed using free().
 * @param[in] data The data received from complication provider app
 * @param[out] image_path The image path data
 * @return #WATCHFACE_COMPLICATION_ERROR_NONE on success,
 *         otherwise an error code (see #watchface_complication_error_e) on failure
 * @retval #WATCHFACE_COMPLICATION_ERROR_NONE Successful
 * @retval #WATCHFACE_COMPLICATION_ERROR_NOT_SUPPORTED Not supported
 * @retval #WATCHFACE_COMPLICATION_ERROR_INVALID_PARAMETER Invalid parameter
 * @retval #WATCHFACE_COMPLICATION_ERROR_OUT_OF_MEMORY Out of memory
 * @retval #WATCHFACE_COMPLICATION_ERROR_NO_DATA No data
 * @see watchface_complication_type_e
 * @see watchface_complication_updated_cb()
 * @par Sample code:
 * @code
#include <watchface-complication.h>
void _on_complication_update(int complication_id,
		const char *provider_id,
		watchface_complication_type_e type,
		const bundle *data, void *user_data)
{
	char *value;
	watchface_complication_type_e type;

	watchface_complication_data_get_type(data, &type);
	if (type == WATCHFACE_COMPLICATION_TYPE_IMAGE)
		watchface_complication_data_get_image_path(data, &value);
}
 * @endcode
 */
int watchface_complication_data_get_image_path(const bundle *data,
			char **image_path);

/**
 * @brief Gets ranged value from complication data.
 * @since_tizen 5.0
 * @param[in] data The data received from complication provider app
 * @param[out] current_value The current value
 * @param[out] min_value The minimum value
 * @param[out] max_value The max value
 * @return #WATCHFACE_COMPLICATION_ERROR_NONE on success,
 *         otherwise an error code (see #watchface_complication_error_e) on failure
 * @retval #WATCHFACE_COMPLICATION_ERROR_NONE Successful
 * @retval #WATCHFACE_COMPLICATION_ERROR_NOT_SUPPORTED Not supported
 * @retval #WATCHFACE_COMPLICATION_ERROR_INVALID_PARAMETER Invalid parameter
 * @retval #WATCHFACE_COMPLICATION_ERROR_NO_DATA No data
 * @retval #WATCHFACE_COMPLICATION_ERROR_IO_ERROR I/O error
 * @see watchface_complication_type_e
 * @see watchface_complication_updated_cb()
 * @par Sample code:
 * @code
#include <watchface-complication.h>
void _on_complication_update(int complication_id,
		const char *provider_id,
		watchface_complication_type_e type,
		const bundle *data, void *user_data)
{
	double cur_val, min_val, max_val;
	watchface_complication_type_e type;

	watchface_complication_data_get_type(data, &type);
	if (type == WATCHFACE_COMPLICATION_TYPE_RANGED_VALUE)
		watchface_complication_data_get_ranged_value(data, &cur_val, &min_val, &max_val);
}
 * @endcode
 */
int watchface_complication_data_get_ranged_value(const bundle *data,
		double *current_value, double *min_value, double *max_value);

/**
 * @brief Gets icon path from complication data.
 * @since_tizen 5.0
 * @remarks The @a icon_path should be freed using free().
 * @param[in] data The data received from complication provider app
 * @param[out] icon_path The icon path data
 * @return #WATCHFACE_COMPLICATION_ERROR_NONE on success,
 *         otherwise an error code (see #watchface_complication_error_e) on failure
 * @retval #WATCHFACE_COMPLICATION_ERROR_NONE Successful
 * @retval #WATCHFACE_COMPLICATION_ERROR_NOT_SUPPORTED Not supported
 * @retval #WATCHFACE_COMPLICATION_ERROR_INVALID_PARAMETER Invalid parameter
 * @retval #WATCHFACE_COMPLICATION_ERROR_OUT_OF_MEMORY Out of memory
 * @retval #WATCHFACE_COMPLICATION_ERROR_NO_DATA No data
 * @see watchface_complication_type_e
 * @see watchface_complication_updated_cb()
 * @par Sample code:
 * @code
#include <watchface-complication.h>
void _on_complication_update(int complication_id,
		const char *provider_id,
		watchface_complication_type_e type,
		const bundle *data, void *user_data)
{
	char *value;
	watchface_complication_type_e type;

	watchface_complication_data_get_type(data, &type);
	if (type == WATCHFACE_COMPLICATION_TYPE_ICON)
		watchface_complication_data_get_icon_path(data, &value);
}
 * @endcode
 */
int watchface_complication_data_get_icon_path(const bundle *data,
			char **icon_path);

/**
 * @brief Gets extra data from complication data.
 * @since_tizen 5.0
 * @remarks The @a extra_data should be freed using free().
 * @param[in] data The data received from complication provider app
 * @param[out] extra_data The extra data
 * @return #WATCHFACE_COMPLICATION_ERROR_NONE on success,
 *         otherwise an error code (see #watchface_complication_error_e) on failure
 * @retval #WATCHFACE_COMPLICATION_ERROR_NONE Successful
 * @retval #WATCHFACE_COMPLICATION_ERROR_NOT_SUPPORTED Not supported
 * @retval #WATCHFACE_COMPLICATION_ERROR_INVALID_PARAMETER Invalid parameter
 * @retval #WATCHFACE_COMPLICATION_ERROR_OUT_OF_MEMORY Out of memory
 * @retval #WATCHFACE_COMPLICATION_ERROR_NO_DATA No data
 * @see watchface_complication_type_e
 * @see watchface_complication_updated_cb()
 * @par Sample code:
 * @code
#include <watchface-complication.h>
void _on_complication_update(int complication_id,
		const char *provider_id,
		watchface_complication_type_e type,
		const bundle *data, void *user_data)
{
	char *value;
	watchface_complication_data_get_extra_data(data, &value);
}
 * @endcode
 */
int watchface_complication_data_get_extra_data(const bundle *data,
			char **extra_data);

/**
 * @brief Gets screen reader text from complication data.
 * @since_tizen 5.0
 * @remarks The @a screen_reader_text should be freed using free().
 * @param[in] data The data received from complication provider app
 * @param[out] screen_reader_text The screen reader text
 * @return #WATCHFACE_COMPLICATION_ERROR_NONE on success,
 *         otherwise an error code (see #watchface_complication_error_e) on failure
 * @retval #WATCHFACE_COMPLICATION_ERROR_NONE Successful
 * @retval #WATCHFACE_COMPLICATION_ERROR_NOT_SUPPORTED Not supported
 * @retval #WATCHFACE_COMPLICATION_ERROR_INVALID_PARAMETER Invalid parameter
 * @retval #WATCHFACE_COMPLICATION_ERROR_OUT_OF_MEMORY Out of memory
 * @retval #WATCHFACE_COMPLICATION_ERROR_NO_DATA No data
 * @see watchface_complication_updated_cb()
 * @par Sample code:
 * @code
#include <watchface-complication.h>
void _on_complication_update(int complication_id,
		const char *provider_id,
		watchface_complication_type_e type,
		const bundle *data, void *user_data)
{
	char *screen_reader_text;
	watchface_complication_data_get_screen_reader_text(data, &screen_reader_text);
	...
	free(screen_reader_text);
}
 * @endcode
 */
int watchface_complication_data_get_screen_reader_text(const bundle *data,
			char **screen_reader_text);

/**
 * @brief Transfers touch event to the complication provider.
 * @details This function launches the provider application with extra data,
 *          so that provider can tell it is launched by transferred touch event.
 * @since_tizen 5.0
 * @privlevel public
 * @privilege http://tizen.org/privilege/appmanager.launch
 * @privilege http://tizen.org/privilege/datasharing
 * @remarks The watchface complication provider application can declare
 *          privileges for specific provider id in manifest xml file, in that case,
 *          the watchface application needs those privileges to use this function.
 *          If your app doesn't have those privileges, this function will return #WATCHFACE_COMPLICATION_ERROR_PERMISSION_DENIED.
 * @param[in] handle The complication handle
 * @param[in] event_type The event type that is transferred to complication provider
 * @return #WATCHFACE_COMPLICATION_ERROR_NONE on success,
 *         otherwise an error code (see #watchface_complication_error_e) on failure
 * @retval #WATCHFACE_COMPLICATION_ERROR_NONE Successful
 * @retval #WATCHFACE_COMPLICATION_ERROR_NOT_SUPPORTED Not supported
 * @retval #WATCHFACE_COMPLICATION_ERROR_PERMISSION_DENIED Permission denied
 * @retval #WATCHFACE_COMPLICATION_ERROR_INVALID_PARAMETER Invalid parameter
 * @retval #WATCHFACE_COMPLICATION_ERROR_OUT_OF_MEMORY Out of memory
 * @retval #WATCHFACE_COMPLICATION_ERROR_IO_ERROR I/O error
 * @retval #WATCHFACE_COMPLICATION_ERROR_DB Database error
 * @see watchface_complication_provider_event_get_type()
 * @see watchface_complication_provider_event_get_provider_id()
 * @see watchface_complication_provider_event_get_complication_type()
 * @par Sample code:
 * @code
#include <watchface-complication.h>
void _on_complication_clicked(complication_h handle)
{
	watchface_complication_transfer_event(handle, WATCHFACE_COMPLICATION_EVENT_TAP);
}
 * @endcode
 */
int watchface_complication_transfer_event(complication_h handle,
			watchface_complication_event_type_e event_type);

/**
 * @brief The complication allowed list handle.
 * @since_tizen 5.0
 */
typedef struct complication_allowed_list_ *complication_allowed_list_h;

/**
 * @brief Creates allowed list.
 * @details The allowed list created by this function is provider list which
 *          will be shown on the editor app's candidate provider list.
 * @since_tizen 5.0
 * @remarks Created allowed list should be applied with watchface_complication_allowed_list_apply().
 *          Created allowed list should be destroyed after applied.
 * @param[in] handle The complication allowed list handle
 * @return #WATCHFACE_COMPLICATION_ERROR_NONE on success,
 *         otherwise an error code (see #watchface_complication_error_e) on failure
 * @retval #WATCHFACE_COMPLICATION_ERROR_NONE Successful
 * @retval #WATCHFACE_COMPLICATION_ERROR_NOT_SUPPORTED Not supported
 * @retval #WATCHFACE_COMPLICATION_ERROR_INVALID_PARAMETER Invalid parameter
 * @retval #WATCHFACE_COMPLICATION_ERROR_OUT_OF_MEMORY Out of memory
 * @see watchface_complication_allowed_list_destroy()
 * @see watchface_complication_allowed_list_add()
 * @see watchface_complication_allowed_list_delete()
 * @see watchface_complication_allowed_list_get_nth()
 * @see watchface_complication_allowed_list_apply()
 * @see watchface_complication_allowed_list_clear()
 * @par Sample code:
 * @code
#include <watchface-complication.h>

{
  complication_allowed_list_h handle;
  int ret = watchface_complication_allowed_list_create(&handle);
}
 * @endcode
 */
int watchface_complication_allowed_list_create(
		complication_allowed_list_h *handle);

/**
 * @brief Destroys allowed list.
 * @since_tizen 5.0
 * @param[in] handle The complication allowed list handle
 * @return #WATCHFACE_COMPLICATION_ERROR_NONE on success,
 *         otherwise an error code (see #watchface_complication_error_e) on failure
 * @retval #WATCHFACE_COMPLICATION_ERROR_NONE Successful
 * @retval #WATCHFACE_COMPLICATION_ERROR_NOT_SUPPORTED Not supported
 * @retval #WATCHFACE_COMPLICATION_ERROR_INVALID_PARAMETER Invalid parameter
 * @see watchface_complication_allowed_list_create()
 * @see watchface_complication_allowed_list_add()
 * @see watchface_complication_allowed_list_delete()
 * @see watchface_complication_allowed_list_get_nth()
 * @see watchface_complication_allowed_list_apply()
 * @see watchface_complication_allowed_list_clear()
 * @par Sample code:
 * @code
#include <watchface-complication.h>

{
  complication_allowed_list_h handle;
  int ret = watchface_complication_allowed_list_create(&handle);
  ret = watchface_complication_allowed_list_destroy(handle);
}
 * @endcode
 */
int watchface_complication_allowed_list_destroy(
		complication_allowed_list_h handle);

/**
 * @brief Adds provider info to the allowed list.
 * @details Using this function the complication can add provider id and types
 *          which will be shown on the editor app's candidate provider list.
 * @since_tizen 5.0
 * @param[in] handle The complication allowed list handle
 * @param[in] provider_id The complication provider id
 * @param[in] types The complication types, values of #watchface_complication_type_e combined with bitwise 'or'
 * @return #WATCHFACE_COMPLICATION_ERROR_NONE on success,
 *         otherwise an error code (see #watchface_complication_error_e) on failure
 * @retval #WATCHFACE_COMPLICATION_ERROR_NONE Successful
 * @retval #WATCHFACE_COMPLICATION_ERROR_NOT_SUPPORTED Not supported
 * @retval #WATCHFACE_COMPLICATION_ERROR_INVALID_PARAMETER Invalid parameter
 * @retval #WATCHFACE_COMPLICATION_ERROR_OUT_OF_MEMORY Out of memory
 * @retval #WATCHFACE_COMPLICATION_ERROR_EXIST_ID The provider id is already exists in allowed list
 * @see watchface_complication_allowed_list_create()
 * @see watchface_complication_allowed_list_destroy()
 * @see watchface_complication_allowed_list_delete()
 * @see watchface_complication_allowed_list_get_nth()
 * @see watchface_complication_allowed_list_apply()
 * @see watchface_complication_allowed_list_clear()
 * @par Sample code:
 * @code
#include <watchface-complication.h>

{
  complication_allowed_list_h handle;
  int ret = watchface_complication_allowed_list_create(&handle);
  if (ret == WATCHFACE_COMPLICATION_ERROR_NONE)
      ret = watchface_complication_allowed_list_add(handle, provider_id, types);
}
 * @endcode
 */
int watchface_complication_allowed_list_add(complication_allowed_list_h handle,
		const char *provider_id, int types);

/**
 * @brief Deletes provider info from the allowed list.
 * @since_tizen 5.0
 * @param[in] handle The complication allowed list handle
 * @param[in] provider_id The complication provider id
 * @return #WATCHFACE_COMPLICATION_ERROR_NONE on success,
 *         otherwise an error code (see #watchface_complication_error_e) on failure
 * @retval #WATCHFACE_COMPLICATION_ERROR_NONE Successful
 * @retval #WATCHFACE_COMPLICATION_ERROR_NOT_SUPPORTED Not supported
 * @retval #WATCHFACE_COMPLICATION_ERROR_INVALID_PARAMETER Invalid parameter
 * @see watchface_complication_allowed_list_create()
 * @see watchface_complication_allowed_list_destroy()
 * @see watchface_complication_allowed_list_add()
 * @see watchface_complication_allowed_list_get_nth()
 * @see watchface_complication_allowed_list_apply()
 * @see watchface_complication_allowed_list_clear()
 * @par Sample code:
 * @code
#include <watchface-complication.h>

{
  complication_allowed_list_h handle;
  int ret = watchface_complication_allowed_list_create(&handle);
  if (ret == WATCHFACE_COMPLICATION_ERROR_NONE) {
      ret = watchface_complication_allowed_list_add(handle, provider_id, types);
      if (ret == WATCHFACE_COMPLICATION_ERROR_EXIST_ID) {
        watchface_complication_allowed_list_delete(handle, provider_id);
        watchface_complication_allowed_list_add(handle, provider_id, types);
      }
  }
}
 * @endcode
 */
int watchface_complication_allowed_list_delete(complication_allowed_list_h handle,
		const char *provider_id);

/**
 * @brief Gets n-th item of the allowed list.
 * @since_tizen 5.0
 * @remarks The @a provider_id should be freed using free().
 * @param[in] handle The complication allowed list handle
 * @param[in] index Index
 * @param[out] provider_id The complication provider id
 * @param[out] types The complication types, values of #watchface_complication_type_e combined with bitwise 'or'
 * @return #WATCHFACE_COMPLICATION_ERROR_NONE on success,
 *         otherwise an error code (see #watchface_complication_error_e) on failure
 * @retval #WATCHFACE_COMPLICATION_ERROR_NONE Successful
 * @retval #WATCHFACE_COMPLICATION_ERROR_NOT_SUPPORTED Not supported
 * @retval #WATCHFACE_COMPLICATION_ERROR_INVALID_PARAMETER Invalid parameter
 * @retval #WATCHFACE_COMPLICATION_ERROR_IO_ERROR I/O error
 * @retval #WATCHFACE_COMPLICATION_ERROR_OUT_OF_MEMORY Out of memory
 * @see watchface_complication_allowed_list_create()
 * @see watchface_complication_allowed_list_destroy()
 * @see watchface_complication_allowed_list_add()
 * @see watchface_complication_allowed_list_delete()
 * @see watchface_complication_allowed_list_apply()
 * @see watchface_complication_allowed_list_clear()
 * @par Sample code:
 * @code
#include <watchface-complication.h>

{
  complication_allowed_list_h handle;
  int ret = watchface_complication_allowed_list_create(&handle);
  if (ret == WATCHFACE_COMPLICATION_ERROR_NONE) {
      ret = watchface_complication_allowed_list_add(handle, provider_id, types);
      if (ret == WATCHFACE_COMPLICATION_ERROR_EXIST_ID) {
        watchface_complication_allowed_list_delete(handle, provider_id);
        watchface_complication_allowed_list_add(handle, provider_id, types);
      }
      watchface_complication_allowed_list_get_nth(handle, 0, &n_provider_id, &n_types);
  }
}
 * @endcode
 */
int watchface_complication_allowed_list_get_nth(
		complication_allowed_list_h handle, int index,
		char **provider_id, int *types);

/**
 * @brief Applies the allowed list to a complication.
 * @details After using this function, the editor will display providers included in the allowed list handle.
 * @since_tizen 5.0
 * @param[in] handle The complication handle
 * @param[in] list_handle The allowed list handle
 * @return #WATCHFACE_COMPLICATION_ERROR_NONE on success,
 *         otherwise an error code (see #watchface_complication_error_e) on failure
 * @retval #WATCHFACE_COMPLICATION_ERROR_NONE Successful
 * @retval #WATCHFACE_COMPLICATION_ERROR_NOT_SUPPORTED Not supported
 * @retval #WATCHFACE_COMPLICATION_ERROR_INVALID_PARAMETER Invalid parameter
 * @retval #WATCHFACE_COMPLICATION_ERROR_OUT_OF_MEMORY Out of memory
 * @retval #WATCHFACE_COMPLICATION_ERROR_DB Database error
 * @see watchface_complication_allowed_list_create()
 * @see watchface_complication_allowed_list_destroy()
 * @see watchface_complication_allowed_list_add()
 * @see watchface_complication_allowed_list_delete()
 * @see watchface_complication_allowed_list_get_nth()
 * @see watchface_complication_allowed_list_clear()
 * @par Sample code:
 * @code
#include <watchface-complication.h>

{
  complication_h handle;
  complication_allowed_list_h allowed_list;

  // create complication handle

  int ret = watchface_complication_allowed_list_create(&allowed_list);
  if (ret == WATCHFACE_COMPLICATION_ERROR_NONE) {
      ret = watchface_complication_allowed_list_add(allowed_list, provider_id, types);
      if (ret == WATCHFACE_COMPLICATION_ERROR_EXIST_ID) {
        watchface_complication_allowed_list_delete(allowed_list, provider_id);
        watchface_complication_allowed_list_add(allowed_list, provider_id, types);
      }
      watchface_complication_allowed_list_get_nth(allowed_list, 0, &n_provider_id, &n_types);
      watchface_complication_allowed_list_apply(handle, allowed_list);
  }
}
 * @endcode
 */
int watchface_complication_allowed_list_apply(complication_h handle,
		complication_allowed_list_h list_handle);

/**
 * @brief Removes applied allowed list.
 * @since_tizen 5.0
 * @param[in] handle The complication allowed list handle
 * @return #WATCHFACE_COMPLICATION_ERROR_NONE on success,
 *         otherwise an error code (see #watchface_complication_error_e) on failure
 * @retval #WATCHFACE_COMPLICATION_ERROR_NONE Successful
 * @retval #WATCHFACE_COMPLICATION_ERROR_NOT_SUPPORTED Not supported
 * @retval #WATCHFACE_COMPLICATION_ERROR_INVALID_PARAMETER Invalid parameter
 * @see watchface_complication_allowed_list_create()
 * @see watchface_complication_allowed_list_destroy()
 * @see watchface_complication_allowed_list_add()
 * @see watchface_complication_allowed_list_delete()
 * @see watchface_complication_allowed_list_get_nth()
 * @see watchface_complication_allowed_list_apply()
 * @par Sample code:
 * @code
#include <watchface-complication.h>

{
  complication_h handle;
  complication_allowed_list_h allowed_list;

  // create complication handle

  int ret = watchface_complication_allowed_list_create(&allowed_list);
  if (ret == WATCHFACE_COMPLICATION_ERROR_NONE) {
      ret = watchface_complication_allowed_list_add(allowed_list, provider_id, types);
      if (ret == WATCHFACE_COMPLICATION_ERROR_EXIST_ID) {
        watchface_complication_allowed_list_delete(allowed_list, provider_id);
        watchface_complication_allowed_list_add(allowed_list, provider_id, types);
      }
      watchface_complication_allowed_list_get_nth(allowed_list, 0, &n_provider_id, &n_types);
      watchface_complication_allowed_list_apply(handle, allowed_list);
      watchface_complication_allowed_list_clear(handle);
  }
}
 * @endcode
 */
int watchface_complication_allowed_list_clear(complication_h handle);

/**
 * @}
 */

#ifdef __cplusplus
}
#endif

#endif  /* __TIZEN_APPFW_WATCHFACE_COMPLICATION_H__ */
