UpdateClient.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 MBED_CLOUD_CLIENT_UPDATE_CLIENT_H
00020 #define MBED_CLOUD_CLIENT_UPDATE_CLIENT_H
00021 
00022 #include "mbed-client/m2minterface.h"
00023 #include "update-client-hub/update_client_public.h"
00024 
00025 namespace UpdateClient
00026 {
00027     /**
00028      * Error codes used by the Update Client.
00029      *
00030      * Warning: a recoverable error occured, no user action required.
00031      * Error  : a recoverable error occured, action required. E.g. the
00032      *          application has to free some space and let the Update
00033      *          Service try again.
00034      * Fatal  : a non-recoverable error occured, application should safe
00035      *          ongoing work and reboot the device.
00036      */
00037     enum {
00038         WarningBase                     = 0x0400, // Range reserved for Update Error from 0x0400 - 0x04FF
00039         WarningCertificateNotFound      = WarningBase + ARM_UC_WARNING_CERTIFICATE_NOT_FOUND,
00040         WarningIdentityNotFound         = WarningBase + ARM_UC_WARNING_IDENTITY_NOT_FOUND,
00041         WarningVendorMismatch           = WarningBase + ARM_UC_WARNING_VENDOR_MISMATCH,
00042         WarningClassMismatch            = WarningBase + ARM_UC_WARNING_CLASS_MISMATCH,
00043         WarningDeviceMismatch           = WarningBase + ARM_UC_WARNING_DEVICE_MISMATCH,
00044         WarningCertificateInvalid       = WarningBase + ARM_UC_WARNING_CERTIFICATE_INVALID,
00045         WarningSignatureInvalid         = WarningBase + ARM_UC_WARNING_SIGNATURE_INVALID,
00046         WarningURINotFound              = WarningBase + ARM_UC_WARNING_URI_NOT_FOUND,
00047         WarningRollbackProtection       = WarningBase + ARM_UC_WARNING_ROLLBACK_PROTECTION,
00048         WarningUnknown                  = WarningBase + ARM_UC_WARNING_UNKNOWN,
00049         WarningCertificateInsertion,
00050         ErrorBase,
00051         ErrorWriteToStorage             = ErrorBase + ARM_UC_ERROR_WRITE_TO_STORAGE,
00052         ErrorInvalidHash                = ErrorBase + ARM_UC_ERROR_INVALID_HASH,
00053         FatalBase
00054     };
00055 
00056     enum {
00057         RequestInvalid                  = ARM_UCCC_REQUEST_INVALID,
00058         RequestDownload                 = ARM_UCCC_REQUEST_DOWNLOAD,
00059         RequestInstall                  = ARM_UCCC_REQUEST_INSTALL
00060     };
00061 
00062     /**
00063      * \brief Initialization function for the Update Client.
00064      * \param Callback to error handler.
00065      */
00066     void UpdateClient(FP1<void, int32_t> callback);
00067 
00068     /**
00069      * \brief Populate M2MObjectList with Update Client objects.
00070      * \details The function takes an existing object list and adds LWM2M
00071      *          objects needed by the Update Client.
00072      *
00073      * \param list M2MObjectList reference.
00074      */
00075     void populate_object_list(M2MBaseList& list);
00076 
00077     /**
00078      * \brief Registers a callback function for authorizing firmware downloads and reboots.
00079      * \param handler Callback function.
00080      */
00081     void set_update_authorize_handler(void (*handler)(int32_t request));
00082 
00083     /**
00084      * \brief Authorize request passed to authorization handler.
00085      * \param request Request being authorized.
00086      */
00087     void update_authorize(int32_t request);
00088 
00089     /**
00090      * \brief Registers a callback function for monitoring download progress.
00091      * \param handler Callback function.
00092      */
00093     void set_update_progress_handler(void (*handler)(uint32_t progress, uint32_t total));
00094 
00095     /**
00096      * \brief Fills the buffer with the 16-byte vendor UUID
00097      * \param buffer The buffer to fill with the UUID
00098      * \param buffer_size_max The maximum avaliable space in the buffer
00099      * \param value_size A pointer to a length variable to populate with the length of the UUID (always 16)
00100      * \retval CCS_STATUS_MEMORY_ERROR when the buffer is less than 16 bytes
00101      * \retval CCS_STATUS_KEY_DOESNT_EXIST when no vendor ID is present
00102      * \retval CCS_STATUS_SUCCESS on success
00103      */
00104     int getVendorId(uint8_t* buffer, size_t buffer_size_max, size_t* value_size);
00105     /**
00106      * \brief Fills the buffer with the 16-byte device class UUID
00107      * \param buffer The buffer to fill with the UUID
00108      * \param buffer_size_max The maximum avaliable space in the buffer
00109      * \param value_size A pointer to a length variable to populate with the length of the UUID (always 16)
00110      * \retval CCS_STATUS_MEMORY_ERROR when the buffer is less than 16 bytes
00111      * \retval CCS_STATUS_KEY_DOESNT_EXIST when no device class ID is present
00112      * \retval CCS_STATUS_SUCCESS on success
00113      */
00114     int getClassId(uint8_t* buffer, size_t buffer_size_max, size_t* value_size);
00115     /**
00116      * \brief Fills the buffer with the 16-byte device UUID
00117      * \param buffer The buffer to fill with the UUID
00118      * \param buffer_size_max The maximum avaliable space in the buffer
00119      * \param value_size A pointer to a length variable to populate with the length of the UUID (always 16)
00120      * \retval CCS_STATUS_MEMORY_ERROR when the buffer is less than 16 bytes
00121      * \retval CCS_STATUS_KEY_DOESNT_EXIST when no device ID is present
00122      * \retval CCS_STATUS_SUCCESS on success
00123      */
00124     int getDeviceId(uint8_t* buffer, size_t buffer_size_max, size_t* value_size);
00125 }
00126 
00127 #endif // MBED_CLOUD_CLIENT_UPDATE_CLIENT_H