From: Sunmin Lee Date: Thu, 9 Aug 2018 08:54:36 +0000 (+0900) Subject: Upload update-control header for API X-Git-Tag: submit/tizen/20180911.115509~3 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=b818dee66142193f7d8112eda8a0dc7ac4fb541e;p=platform%2Fcore%2Fsystem%2Fupdate-control.git Upload update-control header for API Change-Id: Ib9b76f1df2bbd4b5c3e10e4a373c0fc4e81390fe Signed-off-by: Sunmin Lee --- diff --git a/doc/update_control_doc.h b/doc/update_control_doc.h new file mode 100644 index 0000000..0ad2bc5 --- /dev/null +++ b/doc/update_control_doc.h @@ -0,0 +1,52 @@ +/* + * 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_SYSTEM_UPDATE_CONTROL_DOC_H__ +#define __TIZEN_SYSTEM_UPDATE_CONTROL_DOC_H__ + + +/** + * @ingroup CAPI_SYSTEM_FRAMEWORK + * @defgroup CAPI_SYSTEM_UPDATE_CONTROL_MODULE Update Control + * @brief The Update Control API provides functions which implement update operations + This section provides more information about the Update Control API. + * @section CAPI_SYSTEM_UPDATE_CONTROL_MODULE_HEADER Required Header + * \#include + * + * @section CAPI_SYSTEM_UPDATE_CONTROL_MODULE_OVERVIEW Overview + * The Update Control API provides functions which implement update operations such as connect to update server, request update information, and set update configurations. + * It enables the application to get the update information and control the platform version of the device. + * Therefore this API should be used by authorized developer like platform provider only. + * Because the update server may have various protocols, the implementation of APIs is able to be substituted by custom functions which connect to the server serviced by each service provider. + * As a default implementation, the agent for STDM (SmartThings Device Manager) is offered. + * SmartThings Device Manager Console + * + * @section CAPI_SYSTEM_UPDATE_CONTROL_MODULE_FEATURE Related Features + * This API is related with the following features:\n + * - http://tizen.org/feature/device_update\n + * + * It is recommended to design applications with regard to features, for reliability.\n + * + * You can check if a device supports the related features for this API by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, and control your application's actions accordingly.\n + * + * To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.\n + * + * More details on using features in your application can be found in the feature element description. + */ + + +#endif /* __TIZEN_SYSTEM_UPDATE_CONTROL_DOC_H__ */ diff --git a/include/update_control.h b/include/update_control.h new file mode 100644 index 0000000..e4ae758 --- /dev/null +++ b/include/update_control.h @@ -0,0 +1,230 @@ +/* + * 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_SYSTEM_UPDATE_CONTROL_H__ +#define __TIZEN_SYSTEM_UPDATE_CONTROL_H__ + +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @addtogroup CAPI_SYSTEM_UPDATE_CONTROL_MODULE + * @{ + */ + + +/** + * @brief Enumeration for the update control error. + * @since_tizen 5.0 + */ +typedef enum { + UPDATE_CONTROL_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */ + UPDATE_CONTROL_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */ + UPDATE_CONTROL_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of memory */ + UPDATE_CONTROL_ERROR_FILE_NO_SPACE_ON_DEVICE = TIZEN_ERROR_FILE_NO_SPACE_ON_DEVICE, /**< No space left on device */ + UPDATE_CONTROL_ERROR_KEY_NOT_FOUND = TIZEN_ERROR_KEY_NOT_AVAILABLE, /**< Specified key is not found */ + UPDATE_CONTROL_ERROR_KEY_REJECTED = TIZEN_ERROR_KEY_REJECTED, /**< Key is not available */ + UPDATE_CONTROL_ERROR_NOT_SUPPORTED = TIZEN_ERROR_NOT_SUPPORTED, /**< Not supported */ + UPDATE_CONTROL_ERROR_PERMISSION_DENIED = TIZEN_ERROR_PERMISSION_DENIED, /**< Permission denied */ + UPDATE_CONTROL_ERROR_CONNECTION_ABORTED = TIZEN_ERROR_CONNECTION_ABORTED, /**< Software caused connection abort */ + UPDATE_CONTROL_ERROR_CONNECTION_REFUSED = TIZEN_ERROR_CONNECTION_REFUSED, /**< Connection refused */ + UPDATE_CONTROL_ERROR_PROTOCOL_NOT_SUPPORTED = TIZEN_ERROR_PROTOCOL_NOT_SUPPORTED, /**< Protocol not supported */ + UPDATE_CONTROL_ERROR_TIMED_OUT = TIZEN_ERROR_TIMED_OUT, /**< Time out */ + UPDATE_CONTROL_ERROR_INVALID_OPERATION = TIZEN_ERROR_INVALID_OPERATION, /**< Function not implemented */ + UPDATE_CONTROL_ERROR_INVALID_PACKAGE = TIZEN_ERROR_UPDATE_CONTROL | 0x01, /**< Invalid package */ + UPDATE_CONTROL_ERROR_INVALID_URI = TIZEN_ERROR_UPDATE_CONTROL | 0x02, /**< Invalid URI */ + UPDATE_CONTROL_ERROR_PACKAGE_NOT_SUPPORTED = TIZEN_ERROR_UPDATE_CONTROL | 0x03, /**< Package type not supported */ + UPDATE_CONTROL_ERROR_SYSTEM_ERROR = TIZEN_ERROR_UPDATE_CONTROL | 0x04, /**< System error */ +} update_control_error_e; + + +/** + * @brief Enumeration for the update control properties. + * @since_tizen 5.0 + */ +typedef enum { + UPDATE_CONTROL_PROPERTY_NEW_VERSION = 0, /**< New version */ + UPDATE_CONTROL_PROPERTY_PACKAGE_URI, /**< URI for update package */ + UPDATE_CONTROL_PROPERTY_RESULT, /**< Update result */ + UPDATE_CONTROL_PROPERTY_PACKAGE_SIZE, /**< Size of update package */ + UPDATE_CONTROL_PROPERTY_DESCRIPTION, /**< Update description */ + UPDATE_CONTROL_PROPERTY_UPDATE_AVAILABLE, /**< Updatability flag */ +} update_control_property_e; + + +/** + * @brief Initializes the update controller. + * + * @since_tizen 5.0 + * @return @c 0 on success, + * otherwise a negative error value + * @retval #UPDATE_CONTROL_ERROR_NONE Successful + * @retval #UPDATE_CONTROL_ERROR_OUT_OF_MEMORY Out of memory + * @retval #UPDATE_CONTROL_ERROR_SYSTEM_ERROR System error + * @retval #UPDATE_CONTROL_ERROR_INVALID_OPERATION Function not implemented + * @retval #UPDATE_CONTROL_ERROR_NOT_SUPPORTED Not supported + * @see update_control_deinitialize() + */ +int update_control_initialize(void); + + +/** + * @brief Deinitializes the update controller. + * + * @since_tizen 5.0 + * @return @c 0 on success, + * otherwise a negative error value + * @retval #UPDATE_CONTROL_ERROR_NONE Successful + * @retval #UPDATE_CONTROL_ERROR_OUT_OF_MEMORY Out of memory + * @retval #UPDATE_CONTROL_ERROR_SYSTEM_ERROR System error + * @retval #UPDATE_CONTROL_ERROR_INVALID_OPERATION Function not implemented + * @retval #UPDATE_CONTROL_ERROR_NOT_SUPPORTED Not supported + * @see update_control_initialize() + */ +int update_control_deinitialize(void); + + +/** + * @brief Requests checking new version of firmware. + * + * @since_tizen 5.0 + * @return @c 0 on success, + * otherwise a negative error value + * @retval #UPDATE_CONTROL_ERROR_NONE Successful + * @retval #UPDATE_CONTROL_ERROR_CONNECTION_REFUSED Connection refused + * @retval #UPDATE_CONTROL_ERROR_SYSTEM_ERROR System error + * @retval #UPDATE_CONTROL_ERROR_INVALID_OPERATION Function not implemented + * @retval #UPDATE_CONTROL_ERROR_NOT_SUPPORTED Not supported + */ +int update_control_check_new_version(void); + + +/** + * @brief Requests downloading new version of firmware. + * + * @since_tizen 5.0 + * @return @c 0 on success, + * otherwise a negative error value + * @retval #UPDATE_CONTROL_ERROR_NONE Successful + * @retval #UPDATE_CONTROL_ERROR_FILE_NO_SPACE_ON_DEVICE No space left on device + * @retval #UPDATE_CONTROL_ERROR_OUT_OF_MEMORY Out of memory + * @retval #UPDATE_CONTROL_ERROR_CONNECTION_REFUSED Connection refused + * @retval #UPDATE_CONTROL_ERROR_CONNECTION_ABORTED Software caused connection abort + * @retval #UPDATE_CONTROL_ERROR_PROTOCOL_NOT_SUPPORTED Protocol not supported + * @retval #UPDATE_CONTROL_ERROR_INVALID_URI Invalid URI + * @retval #UPDATE_CONTROL_ERROR_SYSTEM_ERROR System error + * @retval #UPDATE_CONTROL_ERROR_INVALID_OPERATION Function not implemented + * @retval #UPDATE_CONTROL_ERROR_NOT_SUPPORTED Not supported + */ +int update_control_download_package(void); + + +/** + * @platform + * @brief Requests triggering update to new firmware. + * + * @since_tizen 5.0 + * @privlevel platform + * @privilege %http://tizen.org/privilege/updatecontrol.admin + * @return @c 0 on success, + * otherwise a negative error value + * @retval #UPDATE_CONTROL_ERROR_NONE Successful + * @retval #UPDATE_CONTROL_ERROR_PERMISSION_DENIED Permission denied + * @retval #UPDATE_CONTROL_ERROR_TIMED_OUT Time out + * @retval #UPDATE_CONTROL_ERROR_INVALID_PACKAGE Invalid package + * @retval #UPDATE_CONTROL_ERROR_PACKAGE_NOT_SUPPORTED Package type not supported + * @retval #UPDATE_CONTROL_ERROR_SYSTEM_ERROR System error + * @retval #UPDATE_CONTROL_ERROR_INVALID_OPERATION Function not implemented + * @retval #UPDATE_CONTROL_ERROR_NOT_SUPPORTED Not supported + */ +int update_control_do_update(void); + + +/** + * @platform + * @brief Makes reservation for update. + * @details Makes update reservation at a specific time. At the given time, it automatically checks, downloads and updates to a new version. To cancel the reservation, call update_control_cancel_reservation(). + * + * @since_tizen 5.0 + * @privlevel platform + * @privilege %http://tizen.org/privilege/updatecontrol.admin + * @remarks Only one reservation can be used at any given time. If a new reservation is made, the previous one will be removed. + * @param[in] reservation_time The time to start update + * @return @c 0 on success, + * otherwise a negative error value + * @retval #UPDATE_CONTROL_ERROR_NONE Successful + * @retval #UPDATE_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #UPDATE_CONTROL_ERROR_PERMISSION_DENIED Permission denied + * @retval #UPDATE_CONTROL_ERROR_SYSTEM_ERROR System error + * @retval #UPDATE_CONTROL_ERROR_INVALID_OPERATION Function not implemented + * @retval #UPDATE_CONTROL_ERROR_NOT_SUPPORTED Not supported + */ +int update_control_make_reservation(struct tm *reservation_time); + + +/** + * @platform + * @brief Cancels the update reservation. + * + * @since_tizen 5.0 + * @privlevel platform + * @privilege %http://tizen.org/privilege/updatecontrol.admin + * @return @c 0 on success, + * otherwise a negative error value + * @retval #UPDATE_CONTROL_ERROR_NONE Successful + * @retval #UPDATE_CONTROL_ERROR_PERMISSION_DENIED Permission denied + * @retval #UPDATE_CONTROL_ERROR_SYSTEM_ERROR System error + * @retval #UPDATE_CONTROL_ERROR_INVALID_OPERATION Function not implemented + * @retval #UPDATE_CONTROL_ERROR_NOT_SUPPORTED Not supported + */ +int update_control_cancel_reservation(void); + + +/** + * @brief Gets the update property of the given key. + * + * @since_tizen 5.0 + * @remarks The @a value must be released using free() + * @param[in] property The key of property to get + * @param[out] value The value of given property + * @return @c 0 on success, + * otherwise a negative error value + * @retval #UPDATE_CONTROL_ERROR_NONE Successful + * @retval #UPDATE_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #UPDATE_CONTROL_ERROR_OUT_OF_MEMORY Out of memory + * @retval #UPDATE_CONTROL_ERROR_KEY_NOT_FOUND Specified property not found + * @retval #UPDATE_CONTROL_ERROR_KEY_REJECTED Specified property not available + * @retval #UPDATE_CONTROL_ERROR_SYSTEM_ERROR System error + * @retval #UPDATE_CONTROL_ERROR_INVALID_OPERATION Function not implemented + * @retval #UPDATE_CONTROL_ERROR_NOT_SUPPORTED Not supported + */ +int update_control_get_property(update_control_property_e property, void **value); + + +/** + * @} + */ + +#ifdef __cplusplus +} +#endif + +#endif /* __TIZEN_SYSTEM_UPDATE_CONTROL_H__ */