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