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      *          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)(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(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 */