Simple interface for Mbed Cloud Client
Embed:
(wiki syntax)
Show/hide line numbers
update_client_hub.h
00001 // ---------------------------------------------------------------------------- 00002 // Copyright 2016-2017 ARM Ltd. 00003 // 00004 // SPDX-License-Identifier: Apache-2.0 00005 // 00006 // Licensed under the Apache License, Version 2.0 (the "License"); 00007 // you may not use this file except in compliance with the License. 00008 // You may obtain a copy of the License at 00009 // 00010 // http://www.apache.org/licenses/LICENSE-2.0 00011 // 00012 // Unless required by applicable law or agreed to in writing, software 00013 // distributed under the License is distributed on an "AS IS" BASIS, 00014 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00015 // See the License for the specific language governing permissions and 00016 // limitations under the License. 00017 // ---------------------------------------------------------------------------- 00018 00019 #ifndef ARM_UPDATE_CLIENT_HUB_H 00020 #define ARM_UPDATE_CLIENT_HUB_H 00021 00022 #include "update-client-common/arm_uc_common.h" 00023 #include "update-client-source/arm_uc_source.h" 00024 #include "update-client-monitor/arm_uc_monitor.h" 00025 #include "update-client-control-center/arm_uc_control_center.h" 00026 #include "update-client-paal/arm_uc_paal_update.h" 00027 00028 #ifdef __cplusplus 00029 extern "C" { 00030 #endif 00031 00032 /** 00033 * Initialization return codes. 00034 */ 00035 enum { 00036 ARM_UC_INIT_DONE 00037 }; 00038 00039 /** 00040 * @brief Start the initialization of the hub. 00041 * @details When initilisation finishes, the user callback function 00042 * will be called. The "event" parameter to the callback 00043 * function should be ignored. 00044 * 00045 * @param function to be called when initilisation is finished. 00046 * @return Error code. 00047 */ 00048 arm_uc_error_t ARM_UC_HUB_Initialize(void (*callback)(int32_t)); 00049 00050 /** 00051 * @brief Process events in the event queue. 00052 * @details The update client is driven by events in an atomic queue, 00053 * the user need to call this function periodically to process 00054 * events in the queue and hence move the client forward. 00055 * 00056 * @return Error code. 00057 * @note Here's a code snippet to suggest how this API might be used by callers: 00058 * \code 00059 * int main() { 00060 * retval = ARM_UC_Hub.Initialize(init_finish_cb); 00061 * while(true) { 00062 * ARM_UC_Hub.ProcessEvents(); 00063 * __WFI(); 00064 * } 00065 * } 00066 * \endcode 00067 */ 00068 arm_uc_error_t ARM_UC_HUB_ProcessEvents(void); 00069 00070 /** 00071 * @brief Register callback function for when callbacks are added to an 00072 * empty queue. 00073 * @details This function is called at least once (maybe more) when 00074 * callbacks are added to an empty queue. Useful for scheduling 00075 * when the queue needs to be processed. 00076 * @param handler Function pointer to function to be called when elements are 00077 * added to an empty queue. 00078 */ 00079 arm_uc_error_t ARM_UC_HUB_AddNotificationHandler(void (*handler)(void)); 00080 00081 /** 00082 * @brief Add sources to the update client. 00083 * @details Sources are transport methods for manifest and firmwares. 00084 * 00085 * @param sources Pointer to an array of source pointers. 00086 * @param size Number of elements in the pointer array. 00087 * @return Error code. 00088 */ 00089 arm_uc_error_t ARM_UC_HUB_SetSources(const ARM_UPDATE_SOURCE* sources[], 00090 uint8_t size); 00091 00092 /** 00093 * @brief Set implementation for storing firmware. 00094 * @details Storage abstraction for handling different storage medium. 00095 * 00096 * @param implementation Function pointer struct to Update PAL implementation. 00097 * @return Error code. 00098 */ 00099 arm_uc_error_t ARM_UC_HUB_SetStorage(const ARM_UC_PAAL_UPDATE* implementation); 00100 00101 /** 00102 * @brief Add monitor to the update client. 00103 * @details Monitors send the update status and results. 00104 * 00105 * @param monitor The monitor to be added to the update client. 00106 * @return Error code. 00107 */ 00108 arm_uc_error_t ARM_UC_HUB_AddMonitor(const ARM_UPDATE_MONITOR* monitor); 00109 00110 /** 00111 * @brief Temporary error reporting function. 00112 * @details This function will be absorbed into the add monitor call. 00113 * 00114 * @param callback Error reporting function. 00115 */ 00116 void ARM_UC_HUB_AddErrorCallback(void (*callback)(int32_t error)); 00117 00118 /** 00119 * @brief Authorize request. 00120 * @details Function is called when the user application authorizes 00121 * requests from the Update Client. 00122 * 00123 * @param request Requests are passed through the callback function. 00124 * @return Error code. 00125 */ 00126 arm_uc_error_t ARM_UC_Authorize(arm_uc_request_t request); 00127 00128 /** 00129 * @brief Set callback for receiving download progress. 00130 * @details User application call for setting callback handler. 00131 * The callback function takes the progreess in percent as argument. 00132 * 00133 * @param callback Function pointer to the progress function. 00134 * @return Error code. 00135 */ 00136 arm_uc_error_t ARM_UC_SetProgressHandler(void (*callback)(uint32_t progress, uint32_t total)); 00137 00138 /** 00139 * @brief Set callback function for authorizing requests. 00140 * @details User application call for setting callback handler. 00141 * The callback function takes an enum request and an authorization 00142 * function pointer. To authorize the given request, the caller 00143 * invokes the authorization function. 00144 * 00145 * @param callback Function pointer to the authorization function. 00146 * @return Error code. 00147 */ 00148 arm_uc_error_t ARM_UC_SetAuthorizeHandler(void (*callback)(int32_t)); 00149 00150 /** 00151 * @brief Override update authorization handler. 00152 * @details Force download and update to progress regardless of authorization 00153 * handler. This function is used for unblocking an update in a buggy 00154 * application. 00155 */ 00156 void ARM_UC_OverrideAuthorization(void); 00157 00158 /** 00159 * @brief Add certificate. 00160 * @details [long description] 00161 * 00162 * @param certificate Pointer to certiface being added. 00163 * @param certificate_length Certificate length. 00164 * @param fingerprint Pointer to the fingerprint of the certificate being added. 00165 * @param fingerprint_length Fingerprint length. 00166 * @param callback Callback handler for certificate insertion events. 00167 * @return Error code. 00168 */ 00169 arm_uc_error_t ARM_UC_AddCertificate(const uint8_t* certificate, 00170 uint16_t certificate_length, 00171 const uint8_t* fingerprint, 00172 uint16_t fingerprint_length, 00173 void (*callback)(arm_uc_error_t, const arm_uc_buffer_t*)); 00174 00175 /** 00176 * @brief Set pointer to pre-shared-key with the given size. 00177 * 00178 * @param key Pointer to pre-shared-key. 00179 * @param bits Key size in bits. 00180 * 00181 * @return Error code. 00182 */ 00183 arm_uc_error_t ARM_UC_AddPreSharedKey(const uint8_t* key, uint16_t bits); 00184 00185 /** 00186 * @brief Function for setting the vendor ID. 00187 * @details The ID is copied to a 16 byte struct. Any data after the first 00188 * 16 bytes will be ignored. 00189 * @param id Pointer to ID. 00190 * @param length Length of ID. 00191 * @return Error code. 00192 */ 00193 arm_uc_error_t ARM_UC_SetVendorId(const uint8_t* id, uint8_t length); 00194 00195 /** 00196 * @brief Function for setting the class ID. 00197 * @details The ID is copied to a 16 byte struct. Any data after the first 00198 * 16 bytes will be ignored. 00199 * @param id Pointer to ID. 00200 * @param length Length of ID. 00201 * @return Error code. 00202 */ 00203 arm_uc_error_t ARM_UC_SetClassId(const uint8_t* id, uint8_t length); 00204 00205 /** 00206 * @brief Function for setting the device ID. 00207 * @details The ID is copied to a 16 byte struct. Any data after the first 00208 * 16 bytes will be ignored. 00209 * @param id Pointer to ID. 00210 * @param length Length of ID. 00211 * @return Error code. 00212 */ 00213 arm_uc_error_t ARM_UC_SetDeviceId(const uint8_t* id, uint8_t length); 00214 00215 /** 00216 * @brief Function for reporting the vendor ID. 00217 * @details 16 bytes are copied into the supplied buffer. 00218 * @param id Pointer to storage for ID. MUST be at least 16 bytes long. 00219 * @param id_max the size of the ID buffer 00220 * @param id_size pointer to a variable to receive the size of the ID 00221 * written into the buffer (always 16). 00222 * @return Error code. 00223 */ 00224 arm_uc_error_t ARM_UC_GetVendorId(uint8_t* id, 00225 const size_t id_max, 00226 size_t* id_size); 00227 00228 /** 00229 * @brief Function for reporting the class ID. 00230 * @details 16 bytes are copied into the supplied buffer. 00231 * @param id Pointer to storage for ID. MUST be at least 16 bytes long. 00232 * @param id_max the size of the ID buffer 00233 * @param id_size pointer to a variable to receive the size of the ID 00234 * written into the buffer (always 16). 00235 * @return Error code. 00236 */ 00237 arm_uc_error_t ARM_UC_GetClassId(uint8_t* id, 00238 const size_t id_max, 00239 size_t* id_size); 00240 00241 /** 00242 * @brief Function for reporting the device ID. 00243 * @details 16 bytes are copied into the supplied buffer. 00244 * @param id Pointer to storage for ID. MUST be at least 16 bytes long. 00245 * @param id_max the size of the ID buffer 00246 * @param id_size pointer to a variable to receive the size of the ID 00247 * written into the buffer (always 16). 00248 * @return Error code. 00249 */ 00250 arm_uc_error_t ARM_UC_GetDeviceId(uint8_t* id, 00251 const size_t id_max, 00252 size_t* id_size); 00253 00254 00255 /** 00256 * @brief Delete any global allocations. 00257 */ 00258 arm_uc_error_t ARM_UC_HUB_Uninitialize(); 00259 00260 #ifdef __cplusplus 00261 } 00262 #endif 00263 00264 #endif /* ARM_UPDATE_CLIENT_HUB_H */
Generated on Tue Jul 12 2022 19:01:38 by 1.7.2