stub/clock/client_clock/include/stub/Clock_API.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  * @file Clock_API.h
  18  * @brief System community functions header file.
  19  */
  20
  21 /*******************************************************************************
  22 * $Header::                                                                   $
  23 * $Revision::                                                                 $
  24 *******************************************************************************/
  25
  26  /******************************************************************************
  27  * file name            : Clock_API.h
  28  *  system name         : PND-A
  29  *  sub system name     : system common function group header file
  30  *  program name        :
  31 ****************************************************************************/
  32 #ifndef CLOCK_CLIENT_CLOCK_INCLUDE_VEHICLE_SERVICE_CLOCK_API_H_
  33 #define CLOCK_CLIENT_CLOCK_INCLUDE_VEHICLE_SERVICE_CLOCK_API_H_
  34
  35 #include <time.h>
  36
  37 /** @addtogroup BaseSystem
  38  *  @{
  39  */
  40 /** @addtogroup vehicle_service
  41  *  @ingroup BaseSystem
  42  *  @{
  43  */
  44 /** @addtogroup clock
  45  *  @ingroup vehicle_service
  46  *  @{
  47  */
  48
  49 #ifdef  __cplusplus
  50 extern "C" {
  51 #endif
  52
  53 /**
  54  * \~english The time corrected by GPS.
  55  */
  56 #define CLOCK_CORRECTED_TIME      (0U)
  57
  58 /**
  59  * \~english The time not corrected by GPS.
  60  */
  61 #define CLOCK_NOT_CORRECTED_TIME  (1U)
  62
  63 /**
  64  * \~english The time synchronized by GPS RTC.
  65  */
  66 #define CLOCK_RTC_TIME            (2U)
  67
  68 /**
  69  * \~english GPS time error.
  70  */
  71 #define CLOCK_INVALID_TIME        (3U)
  72
  73 /**
  74  * \~english The max size memory for time zone.
  75  */
  76 #define TIME_ZONE_MAX_SIZE        256
  77
  78 /**
  79  * \~english Return value define.
  80  */
  81 typedef enum tagCLOCK_RETURN {
  82           CLOCK_OK,              //!< \~english Return successful
  83           CLOCK_ERROR,           //!< \~english Return failed
  84           CLOCK_ERROR_ARGUMENTS  //!< \~english Arguments error
  85 } CLOCK_RETURN;
  86 /*
  87  data type definition
  88 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
  89
  90 /*
  91  \~english API function prototype defined
  92 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
  93 /**
  94  * \ingroup Clock_getSystemTime
  95  * \~english @par Brief
  96  *      - Get the system time.
  97  * \~english @param [out]  time       Store system time data
  98  * \~english @param [out]  status     Store time data status\n
  99  *                                    Time status:\n
 100  *                                     Valid time  : CLOCK_CORRECTED_TIME\n
 101  *                                     Invalid time: CLOCK_INVALID_TIME\n
 102  *                                       NOTE:When can't communication with Clock service, return "CLOCK_INVALID_TIME"
 103  * \~english @retval  CLOCK_OK               success
 104  * \~english @retval  CLOCK_ERROR            fail
 105  * \~english @retval  CLOCK_ERROR_ARGUMENTS  arguments error
 106  * \~english @par Prerequisite
 107  *      - Clock service's availability is TRUE.
 108  * \~english @par Change of internal state
 109  *      - Change of internal state according to the API does not occur.
 110  * \~english @par Conditions of processing failure
 111  *      - The argument used for store system time data is NULL. [CLOCK_ERROR_ARGUMENTS]
 112  *      - The argument used for store time data status is NULL. [CLOCK_ERROR_ARGUMENTS]
 113  *      - Get system time error. [CLOCK_ERROR]
 114  * \~english @par Classification
 115  *      - Public
 116  * \~english @par Type
 117  *      - Sync
 118  * \~english @par Detail
 119  *      - The API is sync(return after call end), please check it when used the API.
 120  *      - Call this API to get the system time and status.
 121  *      - NOTE:Local time can be got by calling Clock_getLocalTime which parameter is the result of this API.
 122  *      - The time returned by calling this API is UTC time, its range is from\n
 123  *        "1970-01-01 00:00:00" to "2038-01-19 03:14:07".
 124  *      - Clock_getSystemTimeY2K38 can be used to get time later than "2038-01-19 03:14:08".
 125  *      - Result : "System time and time status" to "System time and status" will be stored in arguments.
 126  * \~english @see Clock_getLocalTime, Clock_getSystemTimeY2K38, McOpenSender,\n
 127  *                McCreateInvokerName, McOpenSyncReceiver, McInvokeSync
 128  */
 129 CLOCK_RETURN Clock_getSystemTime(struct timespec* time, uint8_t* status);
 130
 131 /**
 132  * \ingroup Clock_getLocalTime
 133  * \~english @par Brief
 134  *      - Get the local time.
 135  * \~english @param [in]   base_time       Pointer to store base time(seconds)
 136  * \~english @param [out]  local_time      Pointer to store local time
 137  * \~english @retval  CLOCK_OK               success
 138  * \~english @retval  CLOCK_ERROR            fail
 139  * \~english @retval  CLOCK_ERROR_ARGUMENTS  arguments error
 140  * \~english @par Prerequisite
 141  *      - Clock service's availability is TRUE.
 142  * \~english @par Change of internal state
 143  *      - Change of internal state according to the API does not occur.
 144  * \~english @par Conditions of processing failure
 145  *      - The argument used to store base time(seconds) is NULL. [CLOCK_ERROR_ARGUMENTS]
 146  *      - The argument used to store local time is NULL. [CLOCK_ERROR_ARGUMENTS]
 147  *      - Get local time failed. [CLOCK_ERROR]
 148  * \~english @par Classification
 149  *      - Public
 150  * \~english @par Type
 151  *      - Sync
 152  * \~english @par Detail
 153  *      - The API is sync(return before call end), please check it when used the API.
 154  *      - Call this API to get local time.
 155  *      - The time returned by calling this API is UTC time, its range is from\n
 156  *        "1970-01-01 00:00:00" to "2038-01-19 03:14:07".
 157  *      - Clock_getSystemTimeY2K38 can be used to get time later than "2038-01-19 03:14:08".
 158  *      - Result : Local time will be stored in arguments.
 159  *      -          tm which is changed base on base_time will be returned when the timezone is not set.
 160  * \~english @see Clock_getSystemTime, Clock_getSystemTimeY2K38
 161  */
 162 CLOCK_RETURN Clock_getLocalTime(const time_t* base_time, struct tm* local_time);
 163
 164 /**
 165  * \ingroup Clock_CnvSecToDate
 166  * \~english @par Brief
 167  *      - Convert specified elapsed seconds to date and time.\n
 168  *        The specified elapsed seconds are regarded as elapsed time from 1970/01/01 00:00:00.
 169  * \~english @param [in]   timep       The pointer to store the seconds
 170  * \~english @param [out]  result      The pointer to store date time
 171  * \~english @retval  CLOCK_OK               success
 172  * \~english @retval  CLOCK_ERROR            fail
 173  * \~english @retval  CLOCK_ERROR_ARGUMENTS  arguments error
 174  * \~english @par Prerequisite
 175  *      - Clock service's availability is TRUE.
 176  * \~english @par Change of internal state
 177  *      - Change of internal state according to the API does not occur.
 178  * \~english @par Conditions of processing failure
 179  *      - The pointer used to store the seconds from base date time is NULL. [CLOCK_ERROR_ARGUMENTS]
 180  *      - The pointer used to store the date time is NULL. [CLOCK_ERROR_ARGUMENTS]
 181  *      - Convert the seconds from base date time to date time failed. [CLOCK_ERROR]
 182  * \~english @par Classification
 183  *      - Public
 184  * \~english @par Type
 185  *      - Sync
 186  * \~english @par Detail
 187  *      - The API is sync(return before call end), please check it when used the API.
 188  *      - Call this API to convert the seconds which is "1970-01-01 00:00:00" to date time.
 189  *      - The time returned by calling this API is UTC time, its range is from\n
 190  *        "1970-01-01 00:00:00" to "2038-01-19 03:14:07".
 191  *      - Clock_getSystemTimeY2K38 can be used to get time later than "2038-01-19 03:14:08".
 192  *      - Result :Convert the seconds to date time. The seconds is from "1970-01-01 00:00:00".
 193  * \~english @see Clock_CnvDateToSec, Clock_CnvSecToDateY2K38
 194  */
 195 CLOCK_RETURN Clock_CnvSecToDate(const time_t* timep, struct tm *result);
 196
 197 /**
 198  * \ingroup Clock_CnvDateToSec
 199  * \~english @par Brief
 200  *      - Convert specified date and time to elapsed seconds from 1970/01/01 00:00:00.
 201  * \~english @param [in]   tm          The pointer to store date time to convert
 202  * \~english @param [out]  result      The pointer to store seconds from base time
 203  * \~english @retval  CLOCK_OK               success
 204  * \~english @retval  CLOCK_ERROR_ARGUMENTS  arguments error
 205  * \~english @par Prerequisite
 206  *      - Clock service's availability is TRUE.
 207  * \~english @par Change of internal state
 208  *      - Change of internal state according to the API does not occur.
 209  * \~english @par Conditions of processing failure
 210  *      - The pointer used to store the date time is NULL. [CLOCK_ERROR_ARGUMENTS]
 211  *      - The pointer used to store the seconds from base date time is NULL. [CLOCK_ERROR_ARGUMENTS]
 212  * \~english @par Classification
 213  *      - Public
 214  * \~english @par Type
 215  *      - Sync
 216  * \~english @par Detail
 217  *      - The API is sync(return before call end), please check it when used the API.
 218  *      - Call this API to convert the seconds which from "1970-01-01 00:00:00" to date time.
 219  *      - The API is used when UTC time is in the range from "1970-01-01 00:00:00" to "2038-01-19 03:14:07".
 220  *      - For more then "2038-01-19 03:14:08", please use Clock_CnvDateToSecY2K38.
 221  *      - Result : Convert date time to seconds from "1970-01-01 00:00:00".
 222  * \~english @see Clock_CnvSecToDate, Clock_CnvDateToSecY2K38
 223  */
 224 CLOCK_RETURN Clock_CnvDateToSec(const struct tm* tm, time_t* result);
 225
 226 /**
 227  * \ingroup Clock_setUserTime
 228  * \~english @par Brief
 229  *      - Set the display time when GPS synchronization setting is off.
 230  * \~english @param [in]   user_time       The pointer to store the time(second from base time)
 231  * \~english @retval  CLOCK_OK               success
 232  * \~english @retval  CLOCK_ERROR            fail
 233  * \~english @retval  CLOCK_ERROR_ARGUMENTS  arguments error
 234  * \~english @par Prerequisite
 235  *      - Clock service's availability is TRUE.
 236  * \~english @par Change of internal state
 237  *      - Change of internal state according to the API does not occur.
 238  * \~english @par Conditions of processing failure
 239  *      - The pointer used to store the time from base date time is NULL. [CLOCK_ERROR_ARGUMENTS]
 240  *      - Get thread name of caller failed. [CLOCK_ERROR]
 241  *      - Get handle of Clock service message queue failed. [CLOCK_ERROR]
 242  *      - Generate message queue name for sync call failed. [CLOCK_ERROR]
 243  *      - Generate message queue for receiving failed. [CLOCK_ERROR]
 244  *      - Message sync communicate failed. [CLOCK_ERROR]
 245  *      - Message buffer received sync communicate message is error. [CLOCK_ERROR]
 246  *      - Clock service handle failed. [CLOCK_ERROR]
 247  * \~english @par Classification
 248  *      - Public
 249  * \~english @par Type
 250  *      - Sync
 251  * \~english @par Detail
 252  *      - The API is sync(return before call end), please check it when used the API.
 253  *      - This API called for user set time to user time when GPS corrected off.
 254  *      - Result : Set user time when GPS corrected off.
 255  * \~english @see Clock_getUserTime, Clock_addUserTimeOffset, McOpenSender,\n
 256  *                McCreateInvokerName, McOpenSyncReceiver, McInvokeSync
 257  */
 258 CLOCK_RETURN Clock_setUserTime(const time_t* user_time);
 259
 260 /**
 261  * \ingroup Clock_getUserTime
 262  * \~english @par Brief
 263  *      - Get the display time when GPS synchronization setting is off.
 264  * \~english @param [out]   user_time       The pointer to store the time(second from base time)
 265  * \~english @param [out]   status          The pointer to store time status\n
 266  *                                           time status\n
 267  *                                           Valid time: CLOCK_CORRECTED_TIME\n
 268  *                                           Invalid time: CLOCK_INVALID_TIME\n
 269  * \~english @retval  CLOCK_OK               success
 270  * \~english @retval  CLOCK_ERROR            fail
 271  * \~english @retval  CLOCK_ERROR_ARGUMENTS  arguments error
 272  * \~english @par Prerequisite
 273  *      - Clock service's availability is TRUE.
 274  * \~english @par Change of internal state
 275  *      - Change of internal state according to the API does not occur.
 276  * \~english @par Conditions of processing failure
 277  *      - When GPS corrected off, the pointer to store user time date is NULL. [CLOCK_ERROR_ARGUMENTS]
 278  *      - The pointer to store time status is NULL. [CLOCK_ERROR_ARGUMENTS]
 279  *      - The caller thread name get failed. [CLOCK_ERROR]
 280  *      - Get Clock service message queue handle failed. [CLOCK_ERROR]
 281  *      - Generate message queue name for sync call failed. [CLOCK_ERROR]
 282  *      - Generate message queue handle for sync call failed. [CLOCK_ERROR]
 283  *      - Message sync communicate failed. [CLOCK_ERROR]
 284  *      - Message buffer received sync communicate message is error. [CLOCK_ERROR]
 285  * \~english @par Classification
 286  *      - Public
 287  * \~english @par Type
 288  *      - Sync
 289  * \~english @par Detail
 290  *      - The API is sync(return before call end), please check it when used the API.
 291  *      - Call the API, can get the status for user time invalid or valid, when GPS corrected off.
 292  *      - Note : Get local time, use Clock_getLocalTIme with arguments.\n
 293  *        The API used to get user time when GPS corrected off.
 294  *      - Result : Get user time when GPS corrected off.
 295  * \~english @see Clock_setUserTime, Clock_addUserTimeOffset, Clock_getLocalTime,\n
 296  *                 McOpenSender, McCreateInvokerName, McOpenSyncReceiver, McInvokeSync
 297  */
 298 CLOCK_RETURN Clock_getUserTime(time_t* user_time, uint8_t* status);
 299
 300 /**
 301  * \ingroup Clock_addUserTimeOffset
 302  * \~english @par Brief
 303  *      - Adjust the display time when GPS synchronization setting is off.
 304  * \~english @param [in]   offset        The pointer to store offset for add(sub) user time.\n
 305  *                                       Note : Member has limit as follow. \n
 306  *                                       int tm_hour: hour(-12 to 12)\n
 307  *                                       int tm_min : minute(-59 to 59)\n
 308  *                                       year, month, day, second and so on not used, please set 0.
 309  * \~english @retval  CLOCK_OK               success
 310  * \~english @retval  CLOCK_ERROR            fail
 311  * \~english @retval  CLOCK_ERROR_ARGUMENTS  arguments error
 312  * \~english @par Prerequisite
 313  *      - Clock service's availability is TRUE.
 314  * \~english @par Change of internal state
 315  *      - Change of internal state according to the API does not occur.
 316  * \~english @par Conditions of processing failure
 317  *      - The pointer to store offset for add(sub) user time is NULL. [CLOCK_ERROR_ARGUMENTS]
 318  *      - The parameter offset->tm_sec set second not 0. [CLOCK_ERROR_ARGUMENTS]
 319  *      - The parameter offset->tm_mday set day not 0. [CLOCK_ERROR_ARGUMENTS]
 320  *      - The parameter offset->tm_mon set month not 0. [CLOCK_ERROR_ARGUMENTS]
 321  *      - The parameter offset->tm_year set year not 0. [CLOCK_ERROR_ARGUMENTS]
 322  *      - The parameter offset->tm_wday set day in week not 0. [CLOCK_ERROR_ARGUMENTS]
 323  *      - The parameter offset->tm_yday set day in year not 0. [CLOCK_ERROR_ARGUMENTS]
 324  *      - The parameter offset->tm_isdst set daylight save time not 0. [CLOCK_ERROR_ARGUMENTS]
 325  *      - The parameter offset->tm_hour set hour bigger then 12. [CLOCK_ERROR_ARGUMENTS]
 326  *      - The parameter offset->tm_hour set hour smaller then -12. [CLOCK_ERROR_ARGUMENTS]
 327  *      - The parameter offset->tm_min set minute bigger then 59. [CLOCK_ERROR_ARGUMENTS]
 328  *      - The parameter offset->tm_min set minute smaller then -59. [CLOCK_ERROR_ARGUMENTS]
 329  *      - The caller thread name get failed. [CLOCK_ERROR]
 330  *      - Get Clock service message queue handle failed. [CLOCK_ERROR]
 331  *      - Generate message queue name for sync call failed. [CLOCK_ERROR]
 332  *      - Generate message queue handle for sync call failed. [CLOCK_ERROR]
 333  *      - Message sync communicate failed. [CLOCK_ERROR]
 334  *      - Clock service handle failed. [CLOCK_ERROR]
 335  *      - Message buffer received sync communicate message is error. [CLOCK_ERROR]
 336  * \~english @par Classification
 337  *      - Public
 338  * \~english @par Type
 339  *      - Sync
 340  * \~english @par Detail
 341  *      - The API is sync(return before call end), please check it when used the API.
 342  *      - The API used for add(sub) user time when user set GPS correct off.
 343  *      - Result : User time add(sub) offset when GPS correct off.
 344  * \~english @see Clock_setUserTime, Clock_getUserTime, McOpenSender, McCreateInvokerName,\n
 345  *                McOpenSyncReceiver, McInvokeSync
 346  */
 347 CLOCK_RETURN Clock_addUserTimeOffset(const struct tm* offset);
 348
 349 /* Clock_getSystemTimeY2K38 can be used to get time later than "2038-01-19 03:14:08"(UTC). */
 350 /**
 351  * \ingroup Clock_getSystemTimeY2K38
 352  * \~english @par Brief
 353  *      - Get the system time(2038 issue fixed).
 354  * \~english @param [out]   time       Store system time data
 355  * \~english @param [out]   status     Store time data status\n
 356  *                                    Time status:\n
 357  *                                     Valid time  : CLOCK_CORRECTED_TIME\n
 358  *                                     Invalid time: CLOCK_INVALID_TIME\n
 359  *                                     Note : When can't communication with Clock service, return "CLOCK_INVALID_TIME".
 360  * \~english @retval  CLOCK_OK               success
 361  * \~english @retval  CLOCK_ERROR            fail
 362  * \~english @retval  CLOCK_ERROR_ARGUMENTS  arguments error
 363  * \~english @par Prerequisite
 364  *      - Clock service's availability is TRUE.
 365  * \~english @par Change of internal state
 366  *      - Change of internal state according to the API does not occur.
 367  * \~english @par Conditions of processing failure
 368  *      - When the storage area of the system time data is NULL. [CLOCK_ERROR_ARGUMENTS]
 369  *      - When the time data status storage area is NULL. [CLOCK_ERROR_ARGUMENTS]
 370  *      - In case of system time acquisition failure. [CLOCK_ERROR]
 371  * \~english @par Classification
 372  *      - Public
 373  * \~english @par Type
 374  *      - Sync
 375  * \~english @par Detail
 376  *      - The API is sync(return before call end), please check it when used the API.
 377  *      - Call the API, can get the status for system time invalid or valid.
 378  *      - Get local time, use Clock_getLocalTIme with arguments. The API used to get system time.
 379  *      - The API is used when UTC time is in the range from "1970-01-01 00:00:00" to "2016-01-19 03:14:07".
 380  *      - Result : System time and time status will be stored in arguments.
 381  * \~english @see Clock_getSystemTime, Clock_getLocalTimeY2K38, McOpenSender,\n
 382  *                McCreateInvokerName, McOpenSyncReceiver, McInvokeSync
 383  */
 384 CLOCK_RETURN Clock_getSystemTimeY2K38(uint32_t* time, uint8_t* status);
 385
 386 /**
 387  * \ingroup Clock_getLocalTimeY2K38
 388  * \~english @par Brief
 389  *      - Get the local time(2038 issue fixed).
 390  * \~english @param [in]    base_time     Pointer to store base time(seconds)
 391  * \~english @param [out]   local_time    Pointer to store local time
 392  * \~english @retval  CLOCK_OK               success
 393  * \~english @retval  CLOCK_ERROR            fail
 394  * \~english @retval  CLOCK_ERROR_ARGUMENTS  arguments error
 395  * \~english @par Prerequisite
 396  *      - Clock service's availability is TRUE.
 397  * \~english @par Change of internal state
 398  *      - Change of internal state according to the API does not occur.
 399  * \~english @par Conditions of processing failure
 400  *      - The argument used to store base time(seconds) is NULL. [CLOCK_ERROR_ARGUMENTS]
 401  *      - The argument used to store local time is NULL. [CLOCK_ERROR_ARGUMENTS]
 402  *      - The argument named base_time bigger then up limit(4293400447) of fixed 2038 issue. [CLOCK_ERROR_ARGUMENTS]
 403  *      - Get local time failed. [CLOCK_ERROR]
 404  * \~english @par Classification
 405  *      - Public
 406  * \~english @par Type
 407  *      - Sync
 408  * \~english @par Detail
 409  *      - The API is sync(return before call end), please check it when used the API.
 410  *      - Call this API to get local time.
 411  *      - Return local time by add time zone information to base time.
 412  *      - The API is used when UTC time is in the range from "1970-01-01 00:00:00" to "2106-01-19 03:14:07".
 413  *      - The parameter base_time bigger then up limit(4293400447), convert error.
 414  *      - Also, this API does not support day of the week (Member tm_wday acquired always stores -1.)\n
 415  *        what the caller sought from year/nomth/data information.
 416  *      - Result : Local time will be stored in arguments.
 417  *      -          If time zone not set, it will return change base_time type to tm
 418  * \~english @see Clock_getLocalTime, Clock_getSystemTimeY2K38
 419  */
 420 CLOCK_RETURN Clock_getLocalTimeY2K38(const uint32_t* base_time, struct tm* local_time);
 421
 422 /**
 423  * \ingroup Clock_CnvSecToDateY2K38
 424  * \~english @par Brief
 425  *      - Convert specified elapsed seconds to date and time(2038 issue fixed).\n
 426  *        The specified elapsed seconds are regarded as elapsed time from 1970/01/01 00:00:00.
 427  * \~english @param [in]    time     Pointer to the storage destination
 428  * \~english @param [out]   result   Pointer to storage location of converted date/time
 429  * \~english @retval  CLOCK_OK               success
 430  * \~english @retval  CLOCK_ERROR            fail
 431  * \~english @retval  CLOCK_ERROR_ARGUMENTS  arguments error
 432  * \~english @par Prerequisite
 433  *      - Clock service's availability is TRUE.
 434  * \~english @par Change of internal state
 435  *      - Change of internal state according to the API does not occur.
 436  * \~english @par Conditions of processing failure
 437  *      - When the accumulated second storage area from the date conuting point to be converted is NULL.\n
 438  *        [CLOCK_ERROR_ARGUMENTS]
 439  *      - When the converted date/time storage area is NULL. [CLOCK_ERROR_ARGUMENTS]
 440  *      - When the regerence time (seconds) specified by the argument time is greater than\n
 441  *        the conuntermeasure upper limit value (4293400447) of the 2038 root problem. [CLOCK_ERROR_ARGUMENTS]
 442  *      - In case of a date/time conversion failure as a cumulative second from the specified date\n
 443  *        in the specified integration seconds. [CLOCK_ERROR]
 444  * \~english @par Classification
 445  *      - Public
 446  * \~english @par Type
 447  *      - Sync
 448  * \~english @par Detail
 449  *      - The API is sync(return before call end), please check it when used the API.
 450  *      - Call this API to convert the specified integration seconds to the date and\n
 451  *        time as the integration seconds from "1970-01-01 00:00:00" at the date conuting point.
 452  *      - The API is used when UTC time is in the range from "1970-01-01 00:00:00" to "2106-01-19 03:14:07".
 453  *      - If the argument time exceeds the above upper limit(4293400447), it can not be converted properly.
 454  *      - Also, this API does not support day of the week (Member tm_wday acquired always stores -1.)\n
 455  *        what the caller sought from year/nomth/data information.
 456  *      - Result: Converts the specified integration seconds to the date and time\n
 457  *        as the integration seconds from "1970-01-01 00:00:00" at the date conuting point.
 458  * \~english @see Clock_CnvSecToDate, Clock_CnvDateToSecY2K38
 459  */
 460 CLOCK_RETURN Clock_CnvSecToDateY2K38(const uint32_t* time, struct tm *result);
 461
 462 /**
 463  * \ingroup Clock_CnvDateToSecY2K38
 464  * \~english @par Brief
 465  *      - Convert specified date and time to elapsed seconds from 1970/01/01 00:00:00.(2038 issue fixed)
 466  * \~english @param [in]    tm       Pointer to the storage location of the date and time to be converted.
 467  * \~english @param [out]   result   Pointer to storage detination of accumulated seconds from date counting point.
 468  * \~english @retval  CLOCK_OK               success
 469  * \~english @retval  CLOCK_ERROR_ARGUMENTS  Invalide parameter
 470  * \~english @par Prerequisite
 471  *      - Clock service's availability is TRUE.
 472  * \~english @par Change of internal state
 473  *      - Change of internal state according to the API does not occur.
 474  * \~english @par Conditions of processing failure
 475  *      - When the date time storage area to be converted is NULL. [CLOCK_ERROR_ARGUMENTS]
 476  *      - When the accumulated second storage area from the date conuting point is NULL. [CLOCK_ERROR_ARGUMENTS]
 477  *      - When the conversion result (result) is greater than the conuntermeasure upper\n
 478  *        limit value (4293400447) of the 2038 root problem. [CLOCK_ERROR_ARGUMENTS]
 479  * \~english @par Classification
 480  *      - Public
 481  * \~english @par Type
 482  *      - Sync
 483  * \~english @par Detail
 484  *      - The API is sync(return before call end), please check it when used the API.
 485  *      - Call this API to convert the specified time to integration seconds from "1970-01-01 00:00:00"\n
 486  *        (date conuting point).
 487  *      - The API is used when UTC time is in the range from "1970-01-01 00:00:00" to "2106-01-19 03:14:07".
 488  *      - The maximum value of result that can be obtained is 4293400447(sec).
 489  *      - Result: Converts the specified date and time to integration seconds from "1970-01-01 00:00:00"\n
 490  *        (date counting point).
 491  * \~english @see Clock_CnvDateToSec, Clock_CnvSecToDateY2K38
 492  */
 493 CLOCK_RETURN Clock_CnvDateToSecY2K38(const struct tm* tm, uint32_t* result);
 494
 495 #ifdef  __cplusplus
 496 }
 497 #endif  // __cplusplus
 498
 499 /** @}*/  // end of clock
 500 /** @}*/  // end of vehicle_service
 501 /** @}*/  // end of BaseSystem
 502
 503 #endif  // CLOCK_CLIENT_CLOCK_INCLUDE_VEHICLE_SERVICE_CLOCK_API_H_