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_types.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  *          is currently a placeholder that always returns ARM_UC_INIT_DONE.
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)(uintptr_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(void);
00259 
00260 /**
00261  * @brief Return the details of the active firmware.
00262  * @param details Pointer to the firmware details structure.
00263  * @return ARM_UC_HUB_ERR_NOT_AVAILABLE if the active firmware details
00264  *         are not yet available, ERR_INVALID_PARAMETER if "details" is
00265  *         NULL or ERR_NONE for success.
00266  */
00267 arm_uc_error_t ARM_UC_API_GetActiveFirmwareDetails(arm_uc_firmware_details_t *details);
00268 
00269 #ifdef __cplusplus
00270 }
00271 #endif
00272 
00273 #endif /* ARM_UPDATE_CLIENT_HUB_H */