git.sur5r.net Git - freertos/blob - FreeRTOS-Plus/Source/FreeRTOS-IoT-Libraries/c_sdk/standard/common/include/private/iot_error.h

   1 /*\r
   2  * Amazon FreeRTOS Common V1.0.0\r
   3  * Copyright (C) 2018 Amazon.com, Inc. or its affiliates.  All Rights Reserved.\r
   4  *\r
   5  * Permission is hereby granted, free of charge, to any person obtaining a copy of\r
   6  * this software and associated documentation files (the "Software"), to deal in\r
   7  * the Software without restriction, including without limitation the rights to\r
   8  * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of\r
   9  * the Software, and to permit persons to whom the Software is furnished to do so,\r
  10  * subject to the following conditions:\r
  11  *\r
  12  * The above copyright notice and this permission notice shall be included in all\r
  13  * copies or substantial portions of the Software.\r
  14  *\r
  15  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\r
  16  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS\r
  17  * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR\r
  18  * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER\r
  19  * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN\r
  20  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\r
  21  *\r
  22  * http://aws.amazon.com/freertos\r
  23  * http://www.FreeRTOS.org\r
  24  */\r
  25 \r
  26 /**\r
  27  * @file iot_error.h\r
  28  * @brief Provides macros for error checking and function cleanup.\r
  29  *\r
  30  * The macros in this file are generic. They may be customized by each library\r
  31  * by setting the library prefix.\r
  32  */\r
  33 \r
  34 #ifndef IOT_ERROR_H_\r
  35 #define IOT_ERROR_H_\r
  36 \r
  37 /* The config header is always included first. */\r
  38 #include "iot_config.h"\r
  39 \r
  40 /**\r
  41  * @brief Declare the status variable and an initial value.\r
  42  *\r
  43  * This macro should be at the beginning of any functions that use cleanup sections.\r
  44  *\r
  45  * @param[in] statusType The type of the status variable for this function.\r
  46  * @param[in] initialValue The initial value to assign to the status variable.\r
  47  */\r
  48 #define IOT_FUNCTION_ENTRY( statusType, initialValue )    statusType status = initialValue\r
  49 \r
  50 /**\r
  51  * @brief Declares the label that begins a cleanup section.\r
  52  *\r
  53  * This macro should be placed at the end of a function and followed by\r
  54  * #IOT_FUNCTION_CLEANUP_END.\r
  55  */\r
  56 #define IOT_FUNCTION_CLEANUP_BEGIN()                      iotCleanup:\r
  57 \r
  58 /**\r
  59  * @brief Declares the end of a cleanup section.\r
  60  *\r
  61  * This macro should be placed at the end of a function and preceded by\r
  62  * #IOT_FUNCTION_CLEANUP_BEGIN.\r
  63  */\r
  64 #define IOT_FUNCTION_CLEANUP_END()                        return status\r
  65 \r
  66 /**\r
  67  * @brief Declares an empty cleanup section.\r
  68  *\r
  69  * This macro should be placed at the end of a function to exit on error if no\r
  70  * cleanup is required.\r
  71  */\r
  72 #define IOT_FUNCTION_EXIT_NO_CLEANUP()                    IOT_FUNCTION_CLEANUP_BEGIN(); IOT_FUNCTION_CLEANUP_END()\r
  73 \r
  74 /**\r
  75  * @brief Jump to the cleanup section.\r
  76  */\r
  77 #define IOT_GOTO_CLEANUP()                                goto iotCleanup\r
  78 \r
  79 /**\r
  80  * @brief Assign a value to the status variable and jump to the cleanup section.\r
  81  *\r
  82  * @param[in] statusValue The value to assign to the status variable.\r
  83  */\r
  84 #define IOT_SET_AND_GOTO_CLEANUP( statusValue )           { status = ( statusValue ); IOT_GOTO_CLEANUP(); }\r
  85 \r
  86 /**\r
  87  * @brief Jump to the cleanup section if a condition is `false`.\r
  88  *\r
  89  * This macro may be used in place of `assert` to exit a function is a condition\r
  90  * is `false`.\r
  91  *\r
  92  * @param[in] condition The condition to check.\r
  93  */\r
  94 #define IOT_GOTO_CLEANUP_IF_FALSE( condition )            { if( ( condition ) == false ) { IOT_GOTO_CLEANUP(); } }\r
  95 \r
  96 /**\r
  97  * @brief Assign a value to the status variable and jump to the cleanup section\r
  98  * if a condition is `false`.\r
  99  *\r
 100  * @param[in] statusValue The value to assign to the status variable.\r
 101  * @param[in] condition The condition to check.\r
 102  */\r
 103 #define IOT_SET_AND_GOTO_CLEANUP_IF_FALSE( statusValue, condition ) \\r
 104     if( ( condition ) == false )                                    \\r
 105         IOT_SET_AND_GOTO_CLEANUP( statusValue )\r
 106 \r
 107 /**\r
 108  * @brief Check a condition; if `false`, assign the "Bad parameter" status value\r
 109  * and jump to the cleanup section.\r
 110  *\r
 111  * @param[in] libraryPrefix The library prefix of the status variable.\r
 112  * @param[in] condition The condition to check.\r
 113  */\r
 114 #define IOT_VALIDATE_PARAMETER( libraryPrefix, condition ) \\r
 115     IOT_SET_AND_GOTO_CLEANUP_IF_FALSE( libraryPrefix ## _BAD_PARAMETER, condition )\r
 116 \r
 117 #endif /* ifndef IOT_ERROR_H_ */\r