src/lib/support/BytesToHex.h

   1 /*
   2  *
   3  *    Copyright (c) 2021 Project CHIP Authors
   4  *
   5  *    Licensed under the Apache License, Version 2.0 (the "License");
   6  *    you may not use this file except in compliance with the License.
   7  *    You may obtain a copy of the License at
   8  *
   9  *        http://www.apache.org/licenses/LICENSE-2.0
  10  *
  11  *    Unless required by applicable law or agreed to in writing, software
  12  *    distributed under the License is distributed on an "AS IS" BASIS,
  13  *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14  *    See the License for the specific language governing permissions and
  15  *    limitations under the License.
  16  */
  17
  18 #pragma once
  19
  20 #include <core/CHIPError.h>
  21 #include <support/BitFlags.h>
  22
  23 #include <stdint.h>
  24 #include <stdlib.h>
  25
  26 namespace chip {
  27 namespace Encoding {
  28
  29 enum class HexFlags : int
  30 {
  31     kNone = 0u,
  32     // Use uppercase A-F if set otherwise, lowercase a-f
  33     kUppercase = (1u << 0),
  34     // Null-terminate buffer
  35     kNullTerminate = (1u << 1),
  36     // Both use uppercase and null-termination.
  37     // Separately stated to avoid casts for common case.
  38     kUppercaseAndNullTerminate = ((1u << 0) | (1u << 1))
  39 };
  40
  41 /**
  42  * Encode a buffer of bytes into hexadecimal, with or without null-termination
  43  * and using either lowercase or uppercase hex.
  44  *
  45  * Default is lowercase output, not null-terminated.
  46  *
  47  * If `flags` has `HexFlags::kNullTerminate` set, treat `dest_hex` as a
  48  * null-terminated string buffer. The function returns CHIP_ERROR_BUFFER_TOO_SMALL
  49  * if `dest_size_max` can't fit the entire encoded buffer, and the
  50  * null-terminator if enabled. This function will never output truncated data.
  51  * The result either fits and is written, or does not fit and nothing is written
  52  * to `dest_hex`.
  53  *
  54  * If `src_bytes` and `dest_hex` overlap, the results may be incorrect, depending
  55  * on overlap, but only the core validity checks are done and it's possible to
  56  * get CHIP_NO_ERROR with erroneous output.
  57  *
  58  * On success, number of bytes written to destination is always:
  59  *   output_size = (src_size * 2) + ((flags & HexFlags::kNullTerminate) ? 1 : 0);
  60  *
  61  * @param src_bytes Pointer to non-null buffer to convert
  62  * @param src_size Number of bytes to convert from src_bytes
  63  * @param [out] dest_hex Destination buffer to receive hex encoding
  64  * @param dest_size_max Maximum buffer size for the hex encoded `dest_hex` buffer
  65  *                      including null-terminator if needed.
  66  * @param flags Flags from `HexFlags` for formatting options
  67  *
  68  * @return CHIP_ERROR_BUFFER_TOO_SMALL on dest_max_size too small to fit output
  69  * @return CHIP_ERROR_INVALID_ARGUMENT if either src_bytes or dest_hex is nullptr
  70  * @return CHIP_NO_ERROR on success
  71  */
  72
  73 CHIP_ERROR BytesToHex(const uint8_t * src_bytes, size_t src_size, char * dest_hex, size_t dest_size_max, BitFlags<HexFlags> flags);
  74
  75 // Alias for Uppercase option, no null-termination
  76 inline CHIP_ERROR BytesToUppercaseHexBuffer(const uint8_t * src_bytes, size_t src_size, char * dest_hex_buf, size_t dest_size_max)
  77 {
  78     return BytesToHex(src_bytes, src_size, dest_hex_buf, dest_size_max, HexFlags::kUppercase);
  79 }
  80
  81 // Alias for Lowercase option, no null-termination
  82 inline CHIP_ERROR BytesToLowercaseHexBuffer(const uint8_t * src_bytes, size_t src_size, char * dest_hex_buf, size_t dest_size_max)
  83 {
  84     return BytesToHex(src_bytes, src_size, dest_hex_buf, dest_size_max, HexFlags::kNone);
  85 }
  86
  87 // Alias for Uppercase option, with null-termination
  88 inline CHIP_ERROR BytesToUppercaseHexString(const uint8_t * src_bytes, size_t src_size, char * dest_hex_str, size_t dest_size_max)
  89 {
  90     return BytesToHex(src_bytes, src_size, dest_hex_str, dest_size_max, HexFlags::kUppercaseAndNullTerminate);
  91 }
  92
  93 // Alias for Lowercase option, with null-termination
  94 inline CHIP_ERROR BytesToLowercaseHexString(const uint8_t * src_bytes, size_t src_size, char * dest_hex_str, size_t dest_size_max)
  95 {
  96     return BytesToHex(src_bytes, src_size, dest_hex_str, dest_size_max, HexFlags::kNullTerminate);
  97 }
  98
  99 } // namespace Encoding
 100 } // namespace chip