service/system/interface_unified/library/include/system_service/ss_templates.h

   1 /*
   2  * @copyright Copyright (c) 2016-2020 TOYOTA MOTOR CORPORATION.
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *      http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 ///////////////////////////////////////////////////////////////////////////////
  18 /// This file supports templates for high use common tasks.
  19 ///////////////////////////////////////////////////////////////////////////////
  20 /**
  21  * @file ss_templates.h
  22  */
  23
  24 /** @addtogroup BaseSystem
  25  *  @{
  26  */
  27 /** @addtogroup system_service
  28  *  @ingroup BaseSystem
  29  *  @{
  30  */
  31 /** @addtogroup system_manager
  32  *  @ingroup system_service
  33  *  @{
  34  */
  35 #ifndef __SS_TEMPLATES_H__  // NOLINT (build/header_guard)
  36 #define __SS_TEMPLATES_H__
  37
  38 #include <stdio.h>
  39 #include <errno.h>
  40 #include <native_service/frameworkunified_types.h>
  41 #include <native_service/ns_logger_if.h>
  42 #include <native_service/frameworkunified_framework_if.h>
  43 #include <map>
  44 #include "system_service/ss_system_types.h"
  45 #include "system_service/ss_string_maps.h"
  46
  47 #ifndef ZONE_ERR
  48 #define ZONE_ERR     ZONEMASK(31)
  49 #endif
  50
  51 /////////////////////////////////////////////////////////////////////////////////////
  52 /// \ingroup ReadMsg
  53 /// \~english @par Summary
  54 ///       check the data information of msg.
  55 /// \~english @param [in] hApp
  56 ///       HANDLE - HANDLE Application
  57 /// \~english @param [in] Data
  58 ///       T - The reference to the Data memory location
  59 /// \~english @param [in] f_eRetrieveMethod
  60 ///       ESMRetrieveTypes - The msg retrieval method ( release or retain )
  61 /// \~english @par
  62 ///            T template type
  63 /// \~english @retval eFrameworkunifiedStatusOK Success
  64 /// \~english @retval eFrameworkunifiedStatusInvldHandle Invalid handle
  65 /// \~english @retval eFrameworkunifiedStatusInvldParam Invalid parameter
  66 /// \~english @par Preconditions
  67 ///       -
  68 /// \~english @par Change of the internal state
  69 ///       - The internal state is not changed.
  70 /// \~english @par Causes of failures
  71 ///       - System Manager handle for the session is NULL. [eFrameworkunifiedStatusInvldHandle]
  72 ///       - data'size is not corruct. [eFrameworkunifiedStatusInvldParam]
  73 /// \~english @par Classification
  74 ///       Public
  75 /// \~english @par Type
  76 ///       Method only
  77 /// \~english @par Detail
  78 ///       Check hApp ptr, msg size, msg reception, read msg if all ok
  79 /// \~english @par
  80 ///             eFrameworkunifiedStatus:Result
  81 ///                - eFrameworkunifiedStatusOK:Success
  82 ///                - Except eFrameworkunifiedStatusOK:Fail
  83 /// \~english @see  None
  84 ////////////////////////////////////////////////////////////////////////////////////
  85 template <typename T> EFrameworkunifiedStatus ReadMsg(
  86                      HANDLE hApp,
  87                      T &Data,  // NOLINT (runtime/references)
  88                      ESMRetrieveTypes f_eRetrieveMethod = eSMRRelease) {
  89   EFrameworkunifiedStatus l_eStatus = eFrameworkunifiedStatusOK;
  90   if ( NULL == hApp ) {
  91     FRAMEWORKUNIFIEDLOG(ZONE_ERR, __FUNCTION__, " Error: NULL = hApp");
  92     l_eStatus = eFrameworkunifiedStatusInvldHandle;
  93   } else if (sizeof(Data) != FrameworkunifiedGetMsgLength(hApp)) {
  94     FRAMEWORKUNIFIEDLOG(ZONE_ERR, __FUNCTION__
  95        , " Error: message buffer sizes mismatch: expected %ld, received %d"
  96        , sizeof(Data), FrameworkunifiedGetMsgLength(hApp));
  97     l_eStatus = eFrameworkunifiedStatusInvldParam;
  98   } else if ( eFrameworkunifiedStatusOK != (l_eStatus =
  99                  FrameworkunifiedGetMsgDataOfSize(hApp, (PVOID)&Data, sizeof(Data), f_eRetrieveMethod))) {
 100     FRAMEWORKUNIFIEDLOG(ZONE_ERR, __FUNCTION__
 101        , " Error: FrameworkunifiedGetMsgDataOfSize() errored: 0x%x", l_eStatus);
 102   }
 103   return l_eStatus;
 104 }  // End of template <typename T> EFrameworkunifiedStatus ReadMsg ()
 105   /* Copy & paste easy-to-use little 't' template
 106   // ReadMsg():                                                        *
 107   //     Check hApp ptr, msg size, msg reception, read msg if all ok.  *
 108   //     Report any errors found.                                      *
 109   //                                                                   *
 110   if ( eFrameworkunifiedStatusOK != ( l_eStatus = ReadMsg<T>
 111                                             ( hApp
 112                                             , Data )))
 113   {
 114     LOG_ERROR("ReadMsg()");
 115   }
 116   else
 117   */
 118
 119 //****************************************************************************
 120 /*!
 121   \def LOG_ERROR(pStr)
 122    Log pStr and l_eStatus
 123  */
 124 #define  LOG_ERROR(pStr)                     \
 125     FRAMEWORKUNIFIEDLOG(ZONE_ERR, __FUNCTION__            \
 126            , " Error: %s errored: %d/'%s'"   \
 127            , pStr                            \
 128            , l_eStatus                       \
 129            , GetStr(static_cast<EFrameworkunifiedStatus>(l_eStatus)).c_str());
 130
 131 //****************************************************************************
 132 /*!
 133   \def LOG_ERROR(pStr)
 134    Log pStr and l_eStatus
 135  */
 136 #define  LOG_SUCCESS(pStr) \
 137   FRAMEWORKUNIFIEDLOG(ZONE_INFO, __FUNCTION__, " %s successful", pStr);
 138
 139 //****************************************************************************
 140 /*!
 141   \def LOG_STATUS(l_eStatus,pStr)
 142    Log pStr and success or failure. Include l_eStatus when not successful.
 143  */
 144 #define LOG_STATUS(l_eStatus, pStr)  \
 145     if ( eFrameworkunifiedStatusOK != l_eStatus ) \
 146     {                                \
 147         LOG_ERROR(pStr);             \
 148     }                                \
 149     else                             \
 150     {                                \
 151         LOG_SUCCESS(pStr);           \
 152     }  // End of #define LOG_STATUS(l_eStatus,pStr)
 153
 154 //****************************************************************************
 155 /*!
 156   \def CALL_AND_LOG_STATUS(fnc)
 157      Call the function and log the returned EFrameworkunifiedStatus.
 158  */
 159 #define CALL_AND_LOG_STATUS(fnc)           \
 160     l_eStatus = (fnc);                     \
 161     LOG_STATUS(l_eStatus, #fnc)
 162     // End of #define CALL_AND_LOG_STATUS(fnc)
 163
 164 //****************************************************************************
 165 /*!
 166   \def LOG_STATUS_IF_ERRORED(l_eStatus, pStr)
 167    Log pStr on failure, including EFrameworkunifiedStatus.
 168  */
 169 #define LOG_STATUS_IF_ERRORED(l_eStatus, pStr)         \
 170     if ( eFrameworkunifiedStatusOK != l_eStatus )                   \
 171     {                                                  \
 172         LOG_ERROR(pStr);                               \
 173     }  // End of #define LOG_STATUS_IF_ERRORED(l_eStatus,pStr)
 174
 175 //****************************************************************************
 176 /*!
 177   \def CALL_AND_LOG_STATUS_IF_ERRORED(fnc)
 178    Call the function and log the returned EFrameworkunifiedStatus on failure.
 179  */
 180 #define CALL_AND_LOG_STATUS_IF_ERRORED(fnc) \
 181     l_eStatus = (fnc);                      \
 182     LOG_STATUS_IF_ERRORED(l_eStatus, #fnc)
 183     // End of #define CALL_AND_LOG_STATUS_IF_ERRORED(fnc)
 184
 185 //****************************************************************************
 186 /*!
 187   \def MAP_ENTRY( f_map, f_enum )
 188   Simplify initializing string map entry.
 189
 190   Use to set a map entry's key and value to the specified enum and the enum's
 191   literal text ( i.e., stringified ) equivalent.
 192  */
 193 #define MAP_ENTRY(f_map, f_enum) \
 194   f_map[ f_enum ] = #f_enum
 195
 196 //****************************************************************************
 197 /*!
 198   \def INTERFACEUNIFIEDLOG_RECEIVED_FROM
 199    Log whom we received message or notification from.
 200
 201    Use this macro to ensure that the string "Received from" is uniformly
 202    logged; this string can be grepped on to find when/where callback functions
 203    were invoked.
 204  */
 205 #define INTERFACEUNIFIEDLOG_RECEIVED_FROM(hApp) \
 206   FRAMEWORKUNIFIEDLOG(ZONE_INFO, __FUNCTION__, " Received from %s", FrameworkunifiedGetMsgSrc(hApp))
 207
 208 //****************************************************************************
 209 /*!
 210   \def INTERFACEUNIFIEDLOG_WHEN_COMPILED
 211   Log when this file was compiled.
 212
 213   Useful when overlaying a delivered object file ( from an official build ) with
 214   a debug-built obj file - verifies that the debug file did indeed get loaded.
 215   */
 216 #define INTERFACEUNIFIEDLOG_WHEN_COMPILED \
 217   FRAMEWORKUNIFIEDLOG(ZONE_INFO, __FUNCTION__, " %s was compiled at %s @ %s", \
 218     __FILE__, __DATE__, __TIME__);
 219
 220
 221 #define SS_ASERT(x) \
 222   if (!(x)) { \
 223     FRAMEWORKUNIFIEDLOG(ZONE_ERR, __FUNCTION__, "SS_ASSERT"); \
 224   }
 225
 226 #define SS_ASERT_ERRNO(x) \
 227   if (!(x)) { \
 228     FRAMEWORKUNIFIEDLOG(ZONE_ERR, __FUNCTION__, "SS_ASSERT %d:%s", errno, strerror(errno)); \
 229   }
 230
 231 #define SS_ASERT_LOG(x, fmt, ...) \
 232   if (!(x)) { \
 233     FRAMEWORKUNIFIEDLOG(ZONE_ERR, __FUNCTION__, "SS_ASSERT " fmt, ## __VA_ARGS__); \
 234   }
 235
 236 #define SS_STATIC_ASERT(expr) \
 237   { \
 238     char STATIC_ASSERTION_FAILED[(expr) ? 1 : -1]; \
 239     (void)STATIC_ASSERTION_FAILED; \
 240   }
 241
 242 /**
 243  * @class EnumStringMap
 244  * \~english @brief EnumStringMap
 245  * \~english @par   Brief Introduction
 246  *        Class to provide EnumStringMap template function
 247  *
 248  */
 249 template <typename enumT, void(*fp)(std::map<enumT, SS_String> & m_strMap)> class EnumStringMap {  // NOLINT (runtime/references)
 250 public:
 251   /////////////////////////////////////////////////////////////////////////////////////
 252   /// \ingroup EnumStringMap
 253   /// \~english @par Summary
 254   ///       Default constructor of EnumStringMap class.
 255   /// \~english @param None
 256   /// \~english @retval None
 257   /// \~english @par Preconditions
 258   ///       - None.
 259   /// \~english @par Change of the internal state
 260   ///       - The internal state is not changed.
 261   /// \~english @par Causes of failures
 262   ///       None
 263   /// \~english @par Classification
 264   ///       Public
 265   /// \~english @par Type
 266   ///       None
 267   /// \~english @par Detail
 268   ///       To generate a EnumStringMap class, and initialize member variables. \n
 269   ///       After the constructor, be sure to call the Initialize. \n
 270   /// \~english @see  ~EnumStringMap, Initialize
 271   ////////////////////////////////////////////////////////////////////////////////////
 272   EnumStringMap() {
 273     (*fp)(m_strMap);
 274   }
 275   /////////////////////////////////////////////////////////////////////////////////////
 276   /// \ingroup ~EnumStringMap
 277   /// \~english @par Summary
 278   ///
 279   /// \~english @param None
 280   /// \~english @retval None
 281   /// \~english @par Preconditions
 282   ///       - None.
 283   /// \~english @par Change of the internal state
 284   ///       - The internal state is not changed.
 285   /// \~english @par Causes of failures
 286   ///       None
 287   /// \~english @par Classification
 288   ///       Public
 289   /// \~english @par Type
 290   ///       None
 291   /// \~english @par Detail
 292   ///       To delete a EnumStringMap object. \n
 293   /// \~english @see  EnumStringMap
 294   ////////////////////////////////////////////////////////////////////////////////////
 295   ~EnumStringMap() {}
 296   SS_String GetStr( enumT f_enum) { return m_strMap[ f_enum ];}
 297 private:
 298   std::map<enumT, SS_String> m_strMap;
 299 };
 300 // End of template <typename enumT, void(*fp)(std::map<enumT, SS_String> & m_strMap)> class EnumStringMap
 301
 302 #endif /* __SS_TEMPLATES_H__ */  // NOLINT (build/header_guard)
 303