Matter SDK Coverage Report
Current view: top level - lib/core - ErrorStr.cpp (source / functions) Coverage Total Hit
Test: SHA:4d2388ac7eed75b2fe5e05e20de377999c632502 Lines: 97.7 % 43 42
Test Date: 2025-07-27 07:17:09 Functions: 100.0 % 5 5

            Line data    Source code
       1              : /*
       2              :  *
       3              :  *    Copyright (c) 2020 Project CHIP Authors
       4              :  *    Copyright (c) 2013-2017 Nest Labs, Inc.
       5              :  *
       6              :  *    Licensed under the Apache License, Version 2.0 (the "License");
       7              :  *    you may not use this file except in compliance with the License.
       8              :  *    You may obtain a copy of the License at
       9              :  *
      10              :  *        http://www.apache.org/licenses/LICENSE-2.0
      11              :  *
      12              :  *    Unless required by applicable law or agreed to in writing, software
      13              :  *    distributed under the License is distributed on an "AS IS" BASIS,
      14              :  *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
      15              :  *    See the License for the specific language governing permissions and
      16              :  *    limitations under the License.
      17              :  */
      18              : #include <lib/core/ErrorStr.h>
      19              : 
      20              : #include <lib/core/CHIPConfig.h>
      21              : #include <lib/core/CHIPError.h>
      22              : #include <lib/support/DLLUtil.h>
      23              : 
      24              : #include <inttypes.h>
      25              : #include <stdio.h>
      26              : 
      27              : namespace chip {
      28              : 
      29              : /**
      30              :  * Buffer to store the formatted error string.
      31              :  */
      32              : #if CHIP_SYSTEM_CONFIG_THREAD_LOCAL_STORAGE
      33              : static thread_local ErrorStrStorage sErrorStr;
      34              : #else  // CHIP_SYSTEM_CONFIG_THREAD_LOCAL_STORAGE
      35              : static ErrorStrStorage sErrorStr;
      36              : #endif // CHIP_SYSTEM_CONFIG_THREAD_LOCAL_STORAGE
      37              : 
      38              : /**
      39              :  * Linked-list of error formatter functions.
      40              :  */
      41              : static ErrorFormatter * sErrorFormatterList = nullptr;
      42              : 
      43              : /**
      44              :  * This routine returns a human-readable NULL-terminated C string
      45              :  * describing the provided error.
      46              :  *
      47              :  * If CHIP_SYSTEM_CONFIG_THREAD_LOCAL_STORAGE is enabled, this function uses
      48              :  * thread-local storage to store the formatted error string. Otherwise, it uses
      49              :  * a global static buffer.
      50              :  *
      51              :  * @param[in] err                      The error for format and describe.
      52              :  * @param[in] withSourceLocation       Whether or not to include the source
      53              :  * location in the output string. Only used if CHIP_CONFIG_ERROR_SOURCE &&
      54              :  * !CHIP_CONFIG_SHORT_ERROR_STR. Defaults to true.
      55              :  *
      56              :  * @return A pointer to a NULL-terminated C string describing the
      57              :  *         provided error.
      58              :  */
      59         5880 : DLL_EXPORT const char * ErrorStr(CHIP_ERROR err, bool withSourceLocation)
      60              : {
      61         5880 :     return ErrorStr(err, withSourceLocation, sErrorStr);
      62              : }
      63              : 
      64              : /**
      65              :  * This routine writes a human-readable NULL-terminated C string into the buf
      66              :  * which describes the provided error.
      67              :  *
      68              :  * @param[in] err                      The error for format and describe.
      69              :  * @param[in] withSourceLocation       Whether or not to include the source
      70              :  * @param[in] storage                  ErrorStrStorage to write into
      71              :  * location in the output string. Only used if CHIP_CONFIG_ERROR_SOURCE &&
      72              :  * !CHIP_CONFIG_SHORT_ERROR_STR. Defaults to true.
      73              :  *
      74              :  * @return A pointer to a NULL-terminated C string describing the
      75              :  *         provided error.
      76              :  */
      77         6133 : DLL_EXPORT const char * ErrorStr(CHIP_ERROR err, bool withSourceLocation, ErrorStrStorage & storage)
      78              : {
      79         6133 :     char * formattedError   = storage.buff;
      80         6133 :     uint16_t formattedSpace = storage.kBufferSize;
      81              : 
      82              : #if CHIP_CONFIG_ERROR_SOURCE && !CHIP_CONFIG_SHORT_ERROR_STR
      83              : 
      84         6133 :     if (const char * const file = err.GetFile(); withSourceLocation && file != nullptr)
      85              :     {
      86          694 :         int n = snprintf(formattedError, formattedSpace, "%s:%u: ", file, err.GetLine());
      87          694 :         if (n > formattedSpace)
      88              :         {
      89            0 :             n = formattedSpace;
      90              :         }
      91          694 :         formattedError += n;
      92          694 :         formattedSpace = static_cast<uint16_t>(formattedSpace - n);
      93              :     }
      94              : #endif // CHIP_CONFIG_ERROR_SOURCE && !CHIP_CONFIG_SHORT_ERROR_STR
      95              : 
      96         6133 :     if (err == CHIP_NO_ERROR)
      97              :     {
      98         5165 :         (void) snprintf(formattedError, formattedSpace, CHIP_NO_ERROR_STRING);
      99         5165 :         return storage.buff;
     100              :     }
     101              : 
     102              :     // Search the registered error formatter for one that will format the given
     103              :     // error code.
     104         1749 :     for (const ErrorFormatter * errFormatter = sErrorFormatterList; errFormatter != nullptr; errFormatter = errFormatter->Next)
     105              :     {
     106         1627 :         if (errFormatter->FormatError(formattedError, formattedSpace, err))
     107              :         {
     108          846 :             return storage.buff;
     109              :         }
     110              :     }
     111              : 
     112              :     // Use a default formatting if no formatter found.
     113          122 :     FormatError(formattedError, formattedSpace, nullptr, err, nullptr);
     114          122 :     return storage.buff;
     115              : }
     116              : 
     117              : /**
     118              :  * Add a new error formatter function to the global list of error formatters.
     119              :  *
     120              :  * @param[in] errFormatter             An ErrorFormatter structure containing a
     121              :  *                                     pointer to the new error function.  Note
     122              :  *                                     that a pointer to the supplied ErrorFormatter
     123              :  *                                     structure will be retained by the function.
     124              :  *                                     Thus the memory for the structure must
     125              :  *                                     remain reserved.
     126              :  */
     127          945 : DLL_EXPORT void RegisterErrorFormatter(ErrorFormatter * errFormatter)
     128              : {
     129              :     // Do nothing if a formatter with the same format function is already in the list.
     130         1835 :     for (ErrorFormatter * existingFormatter = sErrorFormatterList; existingFormatter != nullptr;
     131          890 :          existingFormatter                  = existingFormatter->Next)
     132              :     {
     133         1558 :         if (existingFormatter->FormatError == errFormatter->FormatError)
     134              :         {
     135          668 :             return;
     136              :         }
     137              :     }
     138              : 
     139              :     // Add the formatter to the global list.
     140          277 :     errFormatter->Next  = sErrorFormatterList;
     141          277 :     sErrorFormatterList = errFormatter;
     142              : }
     143              : 
     144              : /**
     145              :  * Remove an error formatter function from the global list of error formatters.
     146              :  *
     147              :  * @param[in] errFormatter             An ErrorFormatter structure containing a
     148              :  *                                     pointer to the new error function.
     149              :  */
     150           11 : DLL_EXPORT void DeregisterErrorFormatter(ErrorFormatter * errFormatter)
     151              : {
     152              :     // Remove the formatter if present
     153           30 :     for (ErrorFormatter ** lfp = &sErrorFormatterList; *lfp != nullptr;)
     154              :     {
     155              :         // Remove the formatter from the global list, if found.
     156           19 :         if (*lfp == errFormatter)
     157              :         {
     158           10 :             *lfp = errFormatter->Next;
     159              :         }
     160              :         else
     161              :         {
     162            9 :             lfp = &(*lfp)->Next;
     163              :         }
     164              :     }
     165           11 : }
     166              : 
     167              : #if !CHIP_CONFIG_CUSTOM_ERROR_FORMATTER
     168              : 
     169              : /**
     170              :  * Generates a human-readable NULL-terminated C string describing the provided error.
     171              :  *
     172              :  * @param[in] buf                   Buffer into which the error string will be placed.
     173              :  * @param[in] bufSize               Size of the supplied buffer in bytes.
     174              :  * @param[in] subsys                A short string describing the subsystem that originated
     175              :  *                                  the error, or NULL if the origin of the error is
     176              :  *                                  unknown/unavailable.  This string should be 10
     177              :  *                                  characters or less.
     178              :  * @param[in] err                   The error to be formatted.
     179              :  * @param[in] desc                  A string describing the cause or meaning of the error,
     180              :  *                                  or NULL if no such information is available.
     181              :  */
     182          973 : DLL_EXPORT void FormatError(char * buf, uint16_t bufSize, const char * subsys, CHIP_ERROR err, const char * desc)
     183              : {
     184              : #if CHIP_CONFIG_SHORT_ERROR_STR
     185              : 
     186              :     if (subsys == nullptr)
     187              :     {
     188              :         (void) snprintf(buf, bufSize, "Error " CHIP_CONFIG_SHORT_FORM_ERROR_VALUE_FORMAT, err.AsInteger());
     189              :     }
     190              :     else
     191              :     {
     192              :         (void) snprintf(buf, bufSize, "Error %s:" CHIP_CONFIG_SHORT_FORM_ERROR_VALUE_FORMAT, subsys, err.AsInteger());
     193              :     }
     194              : 
     195              : #else // CHIP_CONFIG_SHORT_ERROR_STR
     196              : 
     197          973 :     const char * subsysSep = " ";
     198          973 :     const char * descSep   = ": ";
     199              : 
     200          973 :     if (subsys == nullptr)
     201              :     {
     202          124 :         subsys    = "";
     203          124 :         subsysSep = "";
     204              :     }
     205          973 :     if (desc == nullptr)
     206              :     {
     207          124 :         desc    = "";
     208          124 :         descSep = "";
     209              :     }
     210              : 
     211          973 :     (void) snprintf(buf, bufSize, "%s%sError 0x%08" PRIX32 "%s%s", subsys, subsysSep, err.AsInteger(), descSep, desc);
     212              : 
     213              : #endif // CHIP_CONFIG_SHORT_ERROR_STR
     214          973 : }
     215              : 
     216              : #endif // CHIP_CONFIG_CUSTOM_ERROR_FORMATTER
     217              : 
     218              : } // namespace chip
        

Generated by: LCOV version 2.0-1