arm_uc_utilities.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_COMMON_UTILITIES_H
00020 #define ARM_UPDATE_COMMON_UTILITIES_H
00021 
00022 #include "update-client-common/arm_uc_types_internal.h"
00023 #include "update-client-common/arm_uc_error.h"
00024 #include <string.h>
00025 #include <stdbool.h>
00026 
00027 #ifdef __cplusplus
00028 extern "C" {
00029 #endif
00030 
00031 #define ARM_UC_util_min(A,B)\
00032     ((A) < (B) ? (A) : (B))
00033 
00034 /* lookup table for printing hexadecimal characters. */
00035 extern const uint8_t arm_uc_hex_table[16];
00036 
00037 /**
00038  * @brief Parse a uri string to populate a arm_uc_uri_t struct
00039  * @detail Format of uri scheme:[//]host[:port]/path
00040  *         [] means optional, path will always start with a '/'
00041  *
00042  * @param str Pointer to string containing URI.
00043  * @param size String length.
00044  * @param uri The arm_uc_uri_t struct to be populated
00045  */
00046 arm_uc_error_t arm_uc_str2uri(const uint8_t *str, uint32_t size, arm_uc_uri_t *uri);
00047 
00048 /**
00049  * @brief Find substring inside string.
00050  * @details The size of both string and substring is explicitly passed so no
00051  *          assumptions are made about NULL termination.
00052  *
00053  * @param big_buffer Pointer to the string to be searched.
00054  * @param big_length Length of the string to be searched.
00055  * @param little_buffer Pointer to the substring being searched for.
00056  * @param little_length Length of the substring being searched for.
00057  * @return Index to where the substring was found inside the string. If the
00058  *         string doesn't contain the subtring, UINT32_MAX is returned.
00059  */
00060 uint32_t arm_uc_strnstrn(const uint8_t *big_buffer,
00061                          uint32_t big_length,
00062                          const uint8_t *little_buffer,
00063                          uint32_t little_length);
00064 
00065 /**
00066  * @brief Find string length.
00067  * @details Custom implementation of strnlen which is a GNU extension.
00068  *          Returns either the string length or max_length.
00069  *
00070  * @param buffer Pointer to string.
00071  * @param max_length Maximum buffer length.
00072  *
00073  * @return String length or max_length.
00074  */
00075 uint32_t arm_uc_strnlen(const uint8_t *buffer, uint32_t max_length);
00076 
00077 /**
00078  * @brief Convert string to unsigned 32 bit integer.
00079  * @details Function tries to parse string as an unsigned 32 bit integer
00080  *          and return the value. The function will set the third parameter
00081  *          to true if the parsing was successful.
00082  *
00083  * @param buffer Pointer to string.
00084  * @param max_length Maximum buffer length.
00085  * @param success Pointer to boolean indicating whether the parsing was successful.
00086  * @return Parsed value. Only valid if success it true.
00087  */
00088 uint32_t arm_uc_str2uint32(const uint8_t *buffer,
00089                            uint32_t max_length,
00090                            bool *success);
00091 
00092 /**
00093  * @brief Do a shallow copy of a buffer.
00094  * @details Copies each field of a buffer from `src` to `dest`. This creates another reference to the buffer that
00095  *          backs `src` and drops any reference to a buffer that backs `dest`.
00096  *
00097  * @param[out] dest Pointer to a buffer structure that will receive a reference to the buffer that backs `src`
00098  * @param[in] src Pointer to a buffer to copy into dest
00099  */
00100 static inline void ARM_UC_buffer_shallow_copy(arm_uc_buffer_t *dest, arm_uc_buffer_t *src)
00101 {
00102     dest->size_max = src->size_max;
00103     dest->size     = src->size;
00104     dest->ptr      = src->ptr;
00105 }
00106 
00107 /**
00108  * @brief Do a deep copy of a buffer.
00109  * @details Copies the content of `src->ptr` to `dest->ptr`
00110  * If the space used in the source memory, referenced by the source buffer, is less than the maximum space available in
00111  * the destination memory, referenced by the destination buffer, copies the source into the destination.
00112  *
00113  * @param[out] dest Pointer to a buffer structure that references destination memory
00114  * @param[in] src Pointer to a buffer that references the data to copy into the destination memory
00115  * @retval MFST_ERR_SIZE when the source size is larger than the destination's maximum size
00116  * @retval MFST_ERR_NULL_PTR when any expected pointer is NULL
00117  * @retval ERR_NONE on success
00118  */
00119 static inline arm_uc_error_t ARM_UC_buffer_deep_copy(arm_uc_buffer_t *dest, arm_uc_buffer_t *src)
00120 {
00121     ARM_UC_INIT_ERROR(retval, MFST_ERR_NULL_PTR);
00122 
00123     /* NULL pointer check */
00124     if (dest &&
00125             dest->ptr &&
00126             src &&
00127             src->ptr) {
00128         /* destination buffer is large enough */
00129         if (src->size <= dest->size_max) {
00130             /* copy content and set new size */
00131             memcpy(dest->ptr, src->ptr, src->size);
00132             dest->size = src->size;
00133 
00134             ARM_UC_CLEAR_ERROR(retval);
00135         } else {
00136             ARM_UC_SET_ERROR(retval, MFST_ERR_SIZE);
00137         }
00138     } else {
00139         ARM_UC_SET_ERROR(retval, MFST_ERR_NULL_PTR);
00140     }
00141 
00142     return retval;
00143 }
00144 
00145 uint8_t *ARM_UC_Base64Enc(uint8_t *buf, const uint32_t size, const arm_uc_buffer_t *bin);
00146 void ARM_UC_Base64Dec(arm_uc_buffer_t *bin, const uint32_t size, const uint8_t *buf);
00147 
00148 /**
00149  * @brief Calculate what is the length of string needed to contain full HTTP/COAP URI for download
00150  * @details Calculation includes uri->size (size of ptr which is server address only in this case), uri->path (filename)
00151  *          and length of SCHEME-string (https:// or coaps://)
00152 
00153  *
00154  * @param[in] uri The URI -structure which has been already parsed in arm_uc_str2uri
00155  * @return  length of char* buffer needed for everything in URI. If scheme is not supported return 0
00156  */
00157 size_t arm_uc_calculate_full_uri_length(const arm_uc_uri_t *uri);
00158 
00159 #ifdef __cplusplus
00160 }
00161 #endif
00162 
00163 #endif // ARM_UPDATE_COMMON_UTILITIES_H