vehicleservice/positioning/client/include/vehicle_service/POS_gps_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 #ifndef POSITIONING_CLIENT_INCLUDE_VEHICLE_SERVICE_POS_GPS_API_H_
  17 #define POSITIONING_CLIENT_INCLUDE_VEHICLE_SERVICE_POS_GPS_API_H_
  18 /**
  19  * @file POS_gps_API.h
  20  * @brief API definition file for GPS function
  21  */
  22
  23 /** @addtogroup BaseSystem
  24  *  @{
  25  */
  26 /** @addtogroup vehicle_service
  27  *  @ingroup BaseSystem
  28  *  @{
  29  */
  30 /** @addtogroup positioning
  31  *  @ingroup vehicle_service
  32  *  @{
  33  */
  34
  35
  36 /*---------------------------------------------------------------------------------*
  37  * Incluce                                                                         *
  38  *---------------------------------------------------------------------------------*/
  39 #include <vehicle_service/POS_define.h>
  40 #include <gps_hal.h>
  41
  42 /*---------------------------------------------------------------------------------*
  43  * Typedef declaration                                                             *
  44  *---------------------------------------------------------------------------------*/
  45 typedef int32_t NAVIINFO_RET_API;
  46 //!< \~english define return value of Get/Set GPS information API
  47
  48 /*---------------------------------------------------------------------------------*
  49  * Event declaration                                                             *
  50  *---------------------------------------------------------------------------------*/
  51
  52
  53 /**
  54  * \~english @brief  GPS time setting result delivery command ID
  55  * \~english @brief  If you want to catch above envents, use NSFW like below.
  56  * \~english @code
  57  * l_eStatus = FrameworkunifiedAttachCallbackToDispatcher(h_app,POS_NTFY_SEND_THREAD, CID_POSIF_REGISTER_LISTENER_GPS_TIME_SET_REQ, CBCallbackA);
  58  *            @endcode
  59  */
  60 #define CID_POSIF_REGISTER_LISTENER_GPS_TIME_SET_REQ  0x0780
  61
  62 /*---------------------------------------------------------------------------------*
  63  * Struct declaration                                                              *
  64  *---------------------------------------------------------------------------------*/
  65 /**
  66  * @struct SENSOR_MSG_SEND_DAT
  67  * \~english message for setting vehicle sensor data(to vehicle sensor)
  68  */
  69 typedef struct {
  70   DID         did;        //!< \~english data ID
  71   uint16_t    usSize;     //!< \~english data size
  72   uint8_t     data[502];  //!< \~english data body
  73 } SENSOR_MSG_SEND_DAT;
  74
  75 /*---------------------------------------------------------------------------------*
  76  * Prototype Declaration                                                           *
  77  *---------------------------------------------------------------------------------*/
  78 /* GPS_API public API */
  79 #ifdef __cplusplus
  80 extern "C" {
  81 #endif
  82
  83 ////////////////////////////////////////////////////////////////////////////////////////////
  84 /// \ingroup tag_Positioning
  85 /// \~english @par Brief
  86 ///        - GPS setting request
  87 ///
  88 /// \~english @param [in] hApp
  89 ///        - HANDLE - App Handle
  90 /// \~english @param [in] p_data
  91 ///        - SENSOR_MSG_SEND_DAT * - pointer of GPS setting data
  92 ///
  93 /// \~english @par
  94 ///        - SENSOR_MSG_SEND_DAT structure
  95 /// \~english @code
  96 ///   typedef struct
  97 ///   {
  98 ///     DID       did;        /* Data ID */
  99 ///     uint16_t  usSize;     /* Data size */
 100 ///     uint8_t   data[502];  /* Data body */
 101 ///   } SENSOR_MSG_SEND_DAT;
 102 /// @endcode
 103 ///
 104 /// \~english @par
 105 ///        - Data ID(did)
 106 ///        - POS_DID_GPS__CWORD82__SETINITIAL - setting initial location and time data to GPS  \n
 107 ///          (reference to initial location, time setting(_CWORD82_))
 108 ///        - POS_DID_GPS__CWORD82__SETRMODEEX - setting GPS receiver mode(pull extension sentence) \n
 109 ///          (reference to GPS receiver mode setting(_CWORD82_))
 110 ///        - POS_DID_GPS__CWORD82__SELSENT    - setting command to GPS that output any sentence  \n
 111 ///          (reference to output any sentence setting(_CWORD82_))
 112 ///
 113 ///
 114 /// \~english @retval SENSOR_RET_NORMAL normal finish
 115 /// \~english @retval SENSOR_RET_ERROR_CREATE_EVENT event create error
 116 /// \~english @retval SENSOR_RET_ERROR_PARAM parameter error
 117 /// \~english @retval SENSOR_RET_ERROR_DID data ID not registered
 118 /// \~english @retval SENSOR_RET_ERROR_NOSUPPORT unsupported
 119 /// \~english @retval SENSOR_RET_ERROR_RESOURCE lack of resource
 120 ///
 121 /// \~english @par Precondition
 122 ///        - The creation/initialization(FrameworkunifiedCreateDispatcherWithoutLoop and etc.) \n
 123 ///          of the Dispatcher for App are completed.
 124 ///        - Availability of positioning service is TRUE.
 125 ///
 126 /// \~english @par changes of internal status
 127 ///        - There is no changes of internal status by this API
 128 ///
 129 /// \~english @par Failure condition
 130 ///        - The parameter hApp is NULL [SENSOR_RET_ERROR_PARAM]
 131 ///        - The parameter p_data is NULL [SENSOR_RET_ERROR_PARAM]
 132 ///        - Data ID(p_data->did) is not supported [SENSOR_RET_ERROR_DID]
 133 ///        - GPS setting data size(p_data->usSize) is not same with the data  \n
 134 ///          that related to data ID [SENSOR_RET_ERROR_PARAM]
 135 ///        - The count of message in message queue is reach to max [SENSOR_RET_ERROR_RESOURCE]
 136 ///        - The count of mutex is reach to max [SENSOR_RET_ERROR_RESOURCE]
 137 ///        - The count of item in ProcessName-ProcessNo convert table is reach to max [SENSOR_RET_ERROR_RESOURCE]
 138 ///        - The message queue name has not been registered in control table when GPS \n
 139 ///          setting message transfer between processes. [SENSOR_RET_ERROR_CREATE_EVENT]
 140 ///        - Message transfer HANDLE create failed. [SENSOR_RET_ERROR_CREATE_EVENT]
 141 ///        - Message transfer HANDLE get failed from internal table. [SENSOR_RET_ERROR_CREATE_EVENT]
 142 ///        - GPS setting message transfer failed. [SENSOR_RET_ERROR_CREATE_EVENT]
 143 ///
 144 /// \~english @par Detail
 145 ///        - Call this API to set GPS data. \n
 146 ///          The GPS data specified by the parameter p_data will be set in positioning.
 147 ///
 148 /// \~english @par
 149 ///        - Please note the following points when use this API.
 150 ///        - This API is only called by Navigation proxy.
 151 ///
 152 /// \~english @par Classification
 153 ///        - Public
 154 ///
 155 /// \~english @par Type
 156 ///        - Fire and Forget
 157 ///
 158 /// \~english @see
 159 ///        - None
 160 ///
 161 ////////////////////////////////////////////////////////////////////////////////////////////
 162 int32_t POS_ReqGPSSetting(HANDLE hApp, SENSOR_MSG_SEND_DAT *p_data);
 163
 164 ////////////////////////////////////////////////////////////////////////////////////////////
 165 /// \ingroup tag_Positioning
 166 /// \~english @par Brief
 167 ///        - Set GPS information
 168 ///
 169 /// \~english @param [in] hApp
 170 ///        - HANDLE - App Handle
 171 /// \~english @param [in] navilocinfo
 172 ///        - NAVIINFO_ALL * - pointer of GPS information
 173 ///
 174 /// \~english @par
 175 ///        - NAVIINFO_ALL structure
 176 /// \~english @code
 177 ///   typedef struct
 178 ///   {
 179 ///     uint8_t           ucSensorCnt;  /* sensor count */
 180 ///     uint8_t           reserve[3];   /* reserve */
 181 ///     NAVIINFO_DIAG_GPS stDiagGps;    /* position fix related information */
 182 ///     NAVIINFO_NAVI_GPS stNaviGps;    /* other GPS related information */
 183 ///   } NAVIINFO_ALL;
 184 /// @endcode
 185 ///        - sensor count \n
 186 ///          sensor count value when GPS data received
 187 ///
 188 /// \~english @par
 189 ///        - NAVIINFO_DIAG_GPS structure
 190 /// \~english @code
 191 ///   typedef struct
 192 ///   {
 193 ///     NAVIINFO_DIAG_GPS_FIX  stFix;  /* position fix information */
 194 ///     NAVIINFO_DIAG_GPS_SAT  stSat;  /* all satellite information */
 195 ///   } NAVIINFO_DIAG_GPS;
 196 /// @endcode
 197 ///        \n
 198 /// \~english @par
 199 ///        - NAVIINFO_DIAG_GPS_FIX structure
 200 /// \~english @code
 201 ///   typedef struct
 202 ///   {
 203 ///     uint8_t                   ucFixSts;     /* position fix status */
 204 ///     uint8_t                   ucReserve[3]; /* reserve */
 205 ///     NAVIINFO_DIAG_GPS_FIX_CNT stCnt;        /* position fix count data */
 206 ///     NAVIINFO_DIAG_GPS_FIX_XYZ stWgs84;      /* lonlat data(WGS84 geodetic)  */
 207 ///   } NAVIINFO_DIAG_GPS_FIX;
 208 /// @endcode
 209 ///        - position fix status(ucFixSts)
 210 ///        - NAVIINFO_DIAG_GPS_FIX_STS_NON:not fixed
 211 ///        - NAVIINFO_DIAG_GPS_FIX_STS_2D :2D fix
 212 ///        - NAVIINFO_DIAG_GPS_FIX_STS_3D :3D fix
 213 /// \~english @par
 214 ///        - NAVIINFO_DIAG_GPS_FIX_CNT structure
 215 /// \~english @code
 216 ///   typedef struct
 217 ///   {
 218 ///     uint32_t  ulCnt3d;    /* position fix ratio:3D(unit:sec) */
 219 ///     uint32_t  ulCnt2d;    /* position fix ratio:2D(unit:sec) */
 220 ///     uint32_t  ulCntElse;  /* position fix ratio:not fix(unit:sec) */
 221 ///   } NAVIINFO_DIAG_GPS_FIX_CNT;
 222 /// @endcode
 223 ///
 224 /// \~english @par
 225 ///        - NAVIINFO_DIAG_GPS_FIX_XYZ structure
 226 /// \~english @code
 227 ///   typedef struct
 228 ///   {
 229 ///     int32_t   lLat;    /* GPS latitude(unit:1/256sec) (+: north latitude,-: south latitude) */
 230 ///     int32_t   lLon;    /* GPS longitude(unit:1/256sec) (+: east longitude, -: west longitude) */
 231 ///   } NAVIINFO_DIAG_GPS_FIX_XYZ;
 232 /// @endcode
 233 ///
 234 /// \~english @par
 235 ///        - NAVIINFO_DIAG_GPS_SAT structure
 236 /// \~english @code
 237 ///   typedef struct
 238 ///   {
 239 ///     NAVIINFO_DIAG_GPS_PRN   stPrn[12];  /* all satellite information */
 240 ///   } NAVIINFO_DIAG_GPS_SAT;
 241 /// @endcode
 242 ///
 243 /// \~english @par
 244 ///        - NAVIINFO_DIAG_GPS_PRN structure
 245 /// \~english @code
 246 ///   typedef struct
 247 ///   {
 248 ///     uint8_t   ucRcvSts;     /* reception status */
 249 ///     uint8_t   ucPrn;        /* satellite No. */
 250 ///     uint8_t   ucelv;        /* satellite angle(unit:1.0deg) */
 251 ///     uint8_t   ucLv;         /* satellite level */
 252 ///     uint16_t  usAzm;        /* satellite azimuth(unit:1.0deg) (clockwise from north) */
 253 ///     uint8_t   ucReserve[2]; /* reserve */
 254 ///   } NAVIINFO_DIAG_GPS_PRN;
 255 /// @endcode
 256 ///        - reception status(ucRcvSts)
 257 ///        - NAVIINFO_DIAG_GPS_RCV_STS_NOTUSE :not used
 258 ///        - NAVIINFO_DIAG_GPS_RCV_STS_SEARCHING :searching
 259 ///        - NAVIINFO_DIAG_GPS_RCV_STS_TRACHING :tracking
 260 ///        - NAVIINFO_DIAG_GPS_RCV_STS_NOTUSEFIX :not used for position fix
 261 ///        - NAVIINFO_DIAG_GPS_RCV_STS_USEFIX :used for position fix
 262 /// \~english @par
 263 ///        - NAVIINFO_NAVI_GPS structure
 264 /// \~english @code
 265 ///   typedef struct
 266 ///   {
 267 ///     int32_t           altitude;   /* altitude(unit:1m) */
 268 ///     uint16_t          speed;      /* speed(unit:1.00km/h) */
 269 ///     uint16_t          heading;    /* heading(unit:0.1deg) (clockwise from north) */
 270 ///     NAVIINFO_UTCTIME  utc;        /* UTC time */
 271 ///     uint8_t           tdsts;      /* date and time status */
 272 ///     uint8_t           reserve[3]; /* reserve */
 273 ///   } NAVIINFO_NAVI_GPS;
 274 /// @endcode
 275 ///        - altitude(altitude) \n
 276 ///          As the altitude is used as unit [0.01m] in internal, \n
 277 ///          the altitude data range is (-21,474,839~21,474,839).
 278 ///        - UTC(utc)
 279 ///        - The time set after rollover.
 280 ///        - date and time status(tdsts)
 281 ///        - 0= time has not been adjusted after GPS receiver reset(time input or master reset or CSF start)
 282 ///        - 1= time output from RTC Backup(have time adjustment result)
 283 ///        - 2= time adjustment completed
 284 /// \~english @par
 285 ///        - NAVIINFO_UTCTIME structure
 286 /// \~english @code
 287 ///   typedef struct {
 288 ///     uint16_t    year;     /* A.D. (1~) */
 289 ///     uint8_t     month;    /* month(1~12) */
 290 ///     uint8_t     date;     /* date(1~31) */
 291 ///     uint8_t     hour;     /* hour(0~23) */
 292 ///     uint8_t     minute;   /* minute(0~59) */
 293 ///     uint8_t     second;   /* second(0~59) */
 294 ///     uint8_t     reserved; /* not used */
 295 ///   } NAVIINFO_UTCTIME;
 296 /// @endcode
 297 ///
 298 /// \~english @retval NAVIINFO_RET_NORMAL normal finish
 299 /// \~english @retval NAVIINFO_RET_ERROR_PARAM parameter error
 300 /// \~english @retval NAVIINFO_RET_ERROR_INNER internal error
 301 /// \~english @retval NAVIINFO_RET_ERROR_NOSUPPORT unsupported
 302 /// \~english @retval NAVIINFO_RET_ERROR_RESOURCE lack of resource
 303 ///
 304 /// \~english @par Precondition
 305 ///        - The creation/initialization(FrameworkunifiedCreateDispatcherWithoutLoop and etc.) \n
 306 ///          of the Dispatcher for App are completed.
 307 ///        - Availability of positioning service is TRUE.
 308 ///
 309 /// \~english @par changes of internal status
 310 ///        - There is no changes of internal status
 311 ///
 312 /// \~english @par Failure condition
 313 ///        - The parameter navilocinfo is NULL [NAVIINFO_RET_ERROR_PARAM]
 314 ///        - The parameter hApp is NULL [NAVIINFO_RET_ERROR_PARAM]
 315 ///        - GPS setting data size(p_data->usSize) is not same as the data that \n
 316 ///          related to data ID [NAVIINFO_RET_ERROR_RESOURCE]
 317 ///        - The count of message in message queue is reach to max [NAVIINFO_RET_ERROR_RESOURCE]
 318 ///        - The count of mutex is reach to max [NAVIINFO_RET_ERROR_RESOURCE]
 319 ///        - The count of item in ProcessName-ProcessNo convert table is reach to max [NAVIINFO_RET_ERROR_RESOURCE]
 320 ///        - The message queue name has not been registered in control table. [NAVIINFO_RET_ERROR_INNER]
 321 ///        - Message transfer HANDLE create failed. [NAVIINFO_RET_ERROR_INNER]
 322 ///        - Message transfer HANDLE get failed from internal table. [NAVIINFO_RET_ERROR_INNER]
 323 ///        - GPS setting message transfer failed between processes. [NAVIINFO_RET_ERROR_INNER]
 324 ///
 325 /// \~english @par Detail
 326 ///        - Call this API to set GPS information to vehicle sensor.\n
 327 ///        - This API will finish when get the return value.
 328 ///
 329 /// \~english @par
 330 ///        - Please note the following points when use this API.
 331 ///        - This API is only called by Navigation proxy.
 332 ///
 333 /// \~english @par Classification
 334 ///        - Public
 335 ///
 336 /// \~english @par Type
 337 ///        - Fire and Forget and Method and Fire and Forget and Fire and Forget
 338 ///
 339 /// \~english @see
 340 ///        - POS_GetGPSInfo
 341 ////////////////////////////////////////////////////////////////////////////////////////////
 342 NAVIINFO_RET_API POS_SetGPSInfo(HANDLE hApp, NAVIINFO_ALL *navilocinfo);
 343
 344 ////////////////////////////////////////////////////////////////////////////////////////////
 345 /// \ingroup tag_Positioning
 346 /// \~english @par Brief
 347 ///        - Get GPS data
 348 ///
 349 /// \~english @param [in] hApp
 350 ///        - HANDLE - App Handle
 351 /// \~english @param [out] navidiaginfo
 352 ///        - NAVIINFO_DIAG_GPS* - pointer to get GPS data
 353 ///
 354 /// \~english @par
 355 ///        - NAVIINFO_DIAG_GPS structure
 356 /// \~english @code
 357 ///   typedef struct
 358 ///   {
 359 ///     NAVIINFO_DIAG_GPS_FIX stFix;  /* position fix information */
 360 ///     NAVIINFO_DIAG_GPS_SAT stSat;  /* all satellite information */
 361 ///   } NAVIINFO_DIAG_GPS;
 362 /// @endcode
 363 /// \~english @par
 364 ///        - NAVIINFO_DIAG_GPS_FIX structure
 365 /// \~english @code
 366 ///   typedef struct
 367 ///   {
 368 ///     uint8_t                   ucFixSts;     /* position fix status */
 369 ///     uint8_t                   ucReserve[3]; /* reserve */
 370 ///     NAVIINFO_DIAG_GPS_FIX_CNT stCnt;        /* position fix count data */
 371 ///     NAVIINFO_DIAG_GPS_FIX_XYZ stWgs84;      /* lonlat data(WGS84 geodetic)  */
 372 ///   } NAVIINFO_DIAG_GPS_FIX;
 373 /// @endcode
 374 ///        - position fix status(ucFixSts)
 375 ///        - NAVIINFO_DIAG_GPS_FIX_STS_NON:not fixed
 376 ///        - NAVIINFO_DIAG_GPS_FIX_STS_2D :2D fix
 377 ///        - NAVIINFO_DIAG_GPS_FIX_STS_3D :3D fix
 378 /// \~english @par
 379 ///        - NAVIINFO_DIAG_GPS_FIX_CNT structure
 380 /// \~english @code
 381 ///   typedef struct
 382 ///   {
 383 ///     uint32_t    ulCnt3d;    /* position fix count:3D(unit:sec) */
 384 ///     uint32_t    ulCnt2d;    /* position fix count:2D(unit:sec) */
 385 ///     uint32_t    ulCntElse;  /* position fix count:not fix(unit:sec) */
 386 ///   } NAVIINFO_DIAG_GPS_FIX_CNT;
 387 /// @endcode
 388 /// \~english @par
 389 ///        - NAVIINFO_DIAG_GPS_FIX_XYZ structure
 390 /// \~english @code
 391 ///   typedef struct
 392 ///   {
 393 ///     int32_t      lLat;    /* GPS latitude(unit:1/256sec) (+: north latitude, -: south latitude) */
 394 ///     int32_t      lLon;    /* GPS longitude(unit:1/256sec) (+: east longitude, -: west longitude) */
 395 ///   } NAVIINFO_DIAG_GPS_FIX_XYZ;
 396 /// @endcode
 397 /// \~english @par
 398 ///        - NAVIINFO_DIAG_GPS_SAT structure
 399 /// \~english @code
 400 ///   typedef struct
 401 ///   {
 402 ///     NAVIINFO_DIAG_GPS_PRN  stPrn[12];  /* all satellite information */
 403 ///   } NAVIINFO_DIAG_GPS_SAT;
 404 /// @endcode
 405 /// \~english @par
 406 ///        - NAVIINFO_DIAG_GPS_PRN structure
 407 /// \~english @code
 408 ///   typedef struct
 409 ///   {
 410 ///     uint8_t   ucRcvSts;     /* reception status */
 411 ///     uint8_t   ucPrn;        /* satellite No. */
 412 ///     uint8_t   ucelv;        /* satellite angle(unit:1.0deg) */
 413 ///     uint8_t   ucLv;         /* satellite level */
 414 ///     uint16_t  usAzm;        /* satellite azimuth(unit:1.0deg) (clockwise from north) */
 415 ///     uint8_t   ucReserve[2]; /* reserve */
 416 ///   } NAVIINFO_DIAG_GPS_PRN;
 417 /// @endcode
 418 ///        - reception status(ucRcvSts)
 419 ///        - NAVIINFO_DIAG_GPS_RCV_STS_NOTUSE : not used
 420 ///        - NAVIINFO_DIAG_GPS_RCV_STS_SEARCHING : searching
 421 ///        - NAVIINFO_DIAG_GPS_RCV_STS_TRACHING : tracking
 422 ///        - NAVIINFO_DIAG_GPS_RCV_STS_NOTUSEFIX : not used for position fix
 423 ///        - NAVIINFO_DIAG_GPS_RCV_STS_USEFIX : used for position fix
 424 ///
 425 /// \~english @retval NAVIINFO_RET_NORMAL normal finish
 426 /// \~english @retval NAVIINFO_RET_ERROR_PARAM parameter error
 427 /// \~english @retval NAVIINFO_RET_ERROR_INNER internal error
 428 /// \~english @retval NAVIINFO_RET_ERROR_NOSUPPORT unsupported
 429 /// \~english @retval NAVIINFO_RET_ERROR_RESOURCE lack of resource
 430 ///
 431 /// \~english @par Precondition
 432 ///        - The creation/initialization(FrameworkunifiedCreateDispatcherWithoutLoop and etc.) \n
 433 ///          of the dispatcher for App are completed.
 434 ///        - Availability of positioning service is TRUE.
 435 ///
 436 /// \~english @par changes of internal status
 437 ///        - There is no changes of internal status
 438 ///
 439 /// \~english @par Failure condition
 440 ///        - The parameter navidiaginfo is NULL [NAVIINFO_RET_ERROR_PARAM]
 441 ///        - The parameter hApp is NULL [NAVIINFO_RET_ERROR_PARAM]
 442 ///        - The count of message in message queue is reach to max [NAVIINFO_RET_ERROR_RESOURCE]
 443 ///        - The count of mutex is reach to max [NAVIINFO_RET_ERROR_RESOURCE]
 444 ///        - The count of item in ProcessName-ProcessNo convert table is reach to max [NAVIINFO_RET_ERROR_RESOURCE]
 445 ///        - The event is created in same process, but the count of reference is reach to max [NAVIINFO_RET_ERROR_INNER]
 446 ///        - The event is created in system, but the count of reference is reach to max  [NAVIINFO_RET_ERROR_INNER]
 447 ///        - Memory allocate falied during the event table creation for event  \n
 448 ///          registering. [NAVIINFO_RET_ERROR_INNER]
 449 ///        - The thread can not register in the event table. [NAVIINFO_RET_ERROR_INNER]
 450 ///        - Memory allocate failed in event table during the thread table creation. [NAVIINFO_RET_ERROR_INNER]
 451 ///        - After register the thread table in event table, the event flag has already \n
 452 ///          been registered. [NAVIINFO_RET_ERROR_INNER]
 453 ///        - After register the thread table in event table, the event flag register failed. [NAVIINFO_RET_ERROR_INNER]
 454 ///        - The event table is full during event creation. [NAVIINFO_RET_ERROR_INNER]
 455 ///        - The memory for event HANDLE allocate failed during event table creation. [NAVIINFO_RET_ERROR_INNER]
 456 ///        - The thread can not be registered in event table. [NAVIINFO_RET_ERROR_INNER]
 457 ///        - In event table, try to allocate the memory of the thread table creation, but \n
 458 ///          failed. [NAVIINFO_RET_ERROR_INNER]
 459 ///        - After register the thread in event table, the event flag has already been \n
 460 ///          registered. [NAVIINFO_RET_ERROR_INNER]
 461 ///        - After register the thread in event table, the event flag register failed. [NAVIINFO_RET_ERROR_INNER]
 462 ///        - Specified event ID has not been registered in table. [NAVIINFO_RET_ERROR_INNER]
 463 ///        - Initialize event object failed. [NAVIINFO_RET_ERROR_INNER]
 464 ///        - The memory for storing semaphore control data allocate failed. [NAVIINFO_RET_ERROR_INNER]
 465 ///        - Specified semaphore ID has not been registered when semaphore lock. [NAVIINFO_RET_ERROR_INNER]
 466 ///        - Internal mutex HANDLE is NULL when mutex lock. [NAVIINFO_RET_ERROR_INNER]
 467 ///        - Internal mutex HANDLE has not been registered in mutex table when mutex lock. [NAVIINFO_RET_ERROR_INNER]
 468 ///        - The owner of specified mutex is not itself when mutex lock. [NAVIINFO_RET_ERROR_INNER]
 469 ///        - Mutex has been multiple locked [NAVIINFO_RET_ERROR_INNER]
 470 ///        - The HANDLE is NULL when getting usable share memory address. [NAVIINFO_RET_ERROR_INNER]
 471 ///        - Can not get usable share memory address. [NAVIINFO_RET_ERROR_INNER]
 472 ///        - Memory allocate failed for share memory map. [NAVIINFO_RET_ERROR_INNER]
 473 ///        - Memory allocate failed for share memory management. [NAVIINFO_RET_ERROR_INNER]
 474 ///        - Can not open share memory. [NAVIINFO_RET_ERROR_INNER]
 475 ///        - Failed to mapping share memory. [NAVIINFO_RET_ERROR_INNER]
 476 ///        - No empty field in share memory. [NAVIINFO_RET_ERROR_INNER]
 477 ///        - Failed to guarantee share memory. [NAVIINFO_RET_ERROR_INNER]
 478 ///        - ProcessNo has not been registered in message control table when message \n
 479 ///          transfered between processes. [NAVIINFO_RET_ERROR_INNER]
 480 ///        - Message transfer HANDLE get failed when message transfered between processes. [NAVIINFO_RET_ERROR_INNER]
 481 ///        - Message transfer failed between processes. [NAVIINFO_RET_ERROR_INNER]
 482 ///        - The destination process name size is larger than 20 characters when message \n
 483 ///          transfer between processes. [NAVIINFO_RET_ERROR_INNER]
 484 ///        - The message queue name has not been registered in control table when message \n
 485 ///          transfer between processes. [NAVIINFO_RET_ERROR_INNER]
 486 ///        - Message transfer HANDLE create failed when message transfered between processes. [NAVIINFO_RET_ERROR_INNER]
 487 ///        - Message transfer HANDLE get failed from internal table when message transfered \n
 488 ///          between processes. [NAVIINFO_RET_ERROR_INNER]
 489 ///        - Message transfer failed between processes. [NAVIINFO_RET_ERROR_INNER]
 490 ///        - Specified event HANDLE has not been registered in event HANDLE table during \n
 491 ///          event waiting. [NAVIINFO_RET_ERROR_INNER]
 492 ///        - The count of thread arrived max in event management table during event waiting. [NAVIINFO_RET_ERROR_INNER]
 493 ///        - The EV_FLAG_BIT is not set in flagID during event getting. [NAVIINFO_RET_ERROR_INNER]
 494 ///        - The ID of message event queue has not been created during event getting. [NAVIINFO_RET_ERROR_INNER]
 495 ///        - The flagID has not been registered during event getting. [NAVIINFO_RET_ERROR_INNER]
 496 ///        - The interruption happened during event getting [NAVIINFO_RET_ERROR_INNER]
 497 ///        - Whatever error happened during event getting. [NAVIINFO_RET_ERROR_INNER]
 498 ///        - The HANDLE is NULL when getting usable share memory address for accessing \n
 499 ///          received data. [NAVIINFO_RET_ERROR_INNER]
 500 ///        - Can not get usable share memory address for accessing received data. [NAVIINFO_RET_ERROR_INNER]
 501 ///        - Memory for share memory map allocate failed for accessing received data. [NAVIINFO_RET_ERROR_INNER]
 502 ///        - Memory for share memory management allocate failed for accessing received data. [NAVIINFO_RET_ERROR_INNER]
 503 ///        - Can not open share memory for accessing received data. [NAVIINFO_RET_ERROR_INNER]
 504 ///        - Failed to mapping share memory for accessing received data. [NAVIINFO_RET_ERROR_INNER]
 505 ///        - The size of data stored in share memory is larger than the size of \n
 506 ///          received data. [NAVIINFO_RET_ERROR_INNER]
 507 ///        - The result of sensor data get processing is POS_RET_ERROR_RESOURCE. [NAVIINFO_RET_ERROR_RESOURCE]
 508 ///        - The result of sensor data get processing is not POS_RET_ERROR_RESOURCE. [NAVIINFO_RET_ERROR_INNER]
 509 ///
 510 /// \~english @par Detail
 511 ///        - Call this API to get GPS data for diag. \n
 512 ///          This API will finish when get the return value.
 513 ///
 514 /// \~english @par Classification
 515 ///        - Public
 516 ///
 517 /// \~english @par Type
 518 ///        - Sync
 519 ///
 520 /// \~english @see
 521 ///        - POS_SetGPSInfo
 522 ////////////////////////////////////////////////////////////////////////////////////////////
 523 NAVIINFO_RET_API POS_GetGPSInfo(HANDLE hApp, NAVIINFO_DIAG_GPS *navidiaginfo);
 524
 525 ////////////////////////////////////////////////////////////////////////////////////////////
 526 /// \ingroup tag_Positioning
 527 /// \~english @par Brief
 528 ///        - GPS reset request
 529 ///
 530 /// \~english @param [in] hApp
 531 ///        - HANDLE - App Handle
 532 /// \~english @param [in] ResName
 533 ///        - PCSTR - response thread name
 534 /// \~english @param [in] mode
 535 ///        - uint8_t - reset mode
 536 ///
 537 /// \~english @par
 538 ///        - reset mode(mode) \n
 539 ///          If the mode is not one of the following, return POS_RET_ERROR_PARAM
 540 ///        - GPS_RST_COLDSTART - GPS reset request(cold start) \n
 541 ///          Automatic search, track satellite and position fix after RAM initialized(all config \n
 542 ///          items be initialized to default value).\n
 543 ///          Initialize data objects:almanac/ ephemeris data, current position, GPS receiver mode and etc.\n
 544 ///
 545 /// \~english @retval POS_RET_NORMAL normal finish
 546 /// \~english @retval POS_RET_ERROR_PARAM parameter error
 547 /// \~english @retval POS_RET_ERROR_BUSY GPS device is still in setting
 548 /// \~english @retval POS_RET_ERROR_INNER internal error
 549 /// \~english @retval POS_RET_ERROR_NOSUPPORT unsupported
 550 /// \~english @retval POS_RET_ERROR_RESOURCE lack of resource
 551 ///
 552 /// \~english @par Precondition
 553 ///        - The creation/initialization(FrameworkunifiedCreateDispatcherWithoutLoop and etc.) \n
 554 ///          of the Dispatcher for App are completed.
 555 ///        - Availability of positioning service is TRUE.
 556 ///
 557 /// \~english @par changes of internal status
 558 ///        - There is no changes of internal status
 559 ///
 560 /// \~english @par Failure condition
 561 ///        - The parameter hApp is NULL [POS_RET_ERROR_PARAM]
 562 ///        - The parameter ResName is NULL [POS_RET_ERROR_PARAM]
 563 ///        - The parameter mode is not GPS_RST_COLDSTART [POS_RET_ERROR_PARAM]
 564 ///        - The count of message in message queue is reach to max [POS_RET_ERROR_RESOURCE]
 565 ///        - The count of mutex is reach to max [POS_RET_ERROR_RESOURCE]
 566 ///        - The count of item in ProcessName-ProcessNo convert table is reach to max [POS_RET_ERROR_RESOURCE]
 567 ///        - The event is created in same process, but the count of reference is reach to max [POS_RET_ERROR_INNER]
 568 ///        - The event is created in system, but the count of reference is reach to max  [POS_RET_ERROR_INNER]
 569 ///        - Memory allocate falied when the event table creation that for event registering. [POS_RET_ERROR_INNER]
 570 ///        - The thread can not register in the event table. [POS_RET_ERROR_INNER]
 571 ///        - Memory allocate failed in event table when the thread table creation. [POS_RET_ERROR_INNER]
 572 ///        - After register the thread table in event table, the event flag has already been \n
 573 ///          registered. [POS_RET_ERROR_INNER]
 574 ///        - After register the thread table in event table, the event flag register failed. [POS_RET_ERROR_INNER]
 575 ///        - The event table is full when event creation. [POS_RET_ERROR_INNER]
 576 ///        - The memory for event HANDLE allocate failed when event table creation. [POS_RET_ERROR_INNER]
 577 ///        - The thread can not be registered in event table. [POS_RET_ERROR_INNER]
 578 ///        - In event table, to allocate the memory of the thread table creation, but failed. [POS_RET_ERROR_INNER]
 579 ///        - After register the thread in event table, the event flag has already been registered. [POS_RET_ERROR_INNER]
 580 ///        - After register the thread in event table, the event flag register failed. [POS_RET_ERROR_INNER]
 581 ///        - Specified event ID has not been registered in table. [POS_RET_ERROR_INNER]
 582 ///        - Initialize event object failed. [POS_RET_ERROR_INNER]
 583 ///        - The message queue name has not been registered in control table when GPS reset \n
 584 ///          message transfer between processes. [POS_RET_ERROR_INNER]
 585 ///        - Message transfer HANDLE create failed when GPS reset message transfered \n
 586 ///          between processes. [POS_RET_ERROR_INNER]
 587 ///        - Message transfer HANDLE get failed from internal table when GPS reset message \n
 588 ///          transfered between processes. [POS_RET_ERROR_INNER]
 589 ///        - GPS reset message transfer failed between processes. [POS_RET_ERROR_INNER]
 590 ///        - Specified event HANDLE has not been registered in event HANDLE table during  \n
 591 ///          event waiting. [POS_RET_ERROR_INNER]
 592 ///        - The count of thread is reach to max in event management table during event waiting. [POS_RET_ERROR_INNER]
 593 ///        - The EV_FLAG_BIT is not set in flagID during event waiting. [POS_RET_ERROR_INNER]
 594 ///        - The ID of message event queue has not been created during event waiting. [POS_RET_ERROR_INNER]
 595 ///        - The flagID has not been registered during event waiting. [POS_RET_ERROR_INNER]
 596 ///        - The interruption happened during event waiting [POS_RET_ERROR_INNER]
 597 ///        - Whatever error happened during event waiting. [POS_RET_ERROR_INNER]
 598 ///        - The result of sensor data get processing is POS_RET_ERROR_RESOURCE. [POS_RET_ERROR_RESOURCE]
 599 ///        - The result of sensor data get processing is not POS_RET_ERROR_RESOURCE. [POS_RET_ERROR_INNER]
 600 ///
 601 /// \~english @par Detail
 602 ///        - Call this API to reset GPS device.
 603 ///
 604 /// \~english @par
 605 ///        - Please note the following points when use this API.
 606 ///        - This API is only called by Navigation proxy.
 607 ///
 608 /// \~english @par
 609 ///          Notification of message
 610 ///        - The result of communication with GPS device will be sent by system API message with following format. \n
 611 ///          Command ID : CID_POSIF_REQ_GPS_RESET \n
 612 ///          message structure
 613 /// \~english @code
 614 ///   typedef struct
 615 ///   {
 616 ///     TG_GPS_RET_RESET  data;      /* GPS reset status data */
 617 ///   } TG_GPS_RET_RESET_MSG;
 618 /// @endcode
 619 ///        - message data body structure
 620 /// \~english @code
 621 ///   typedef struct {
 622 ///     unsigned long    ret_rst_status;    /* response GPS reset status */
 623 ///   } TG_GPS_RET_RESET;
 624 /// @endcode
 625 ///        - response GPS reset status(ret_rst_status)
 626 ///        - GPS_SENDOK:acknowledge
 627 ///        - GPS_SENDNG:connection error
 628 ///
 629 /// \~english @par Classification
 630 ///        - Public
 631 ///
 632 /// \~english @par Type
 633 ///        - Fire and Forget
 634 ///
 635 /// \~english @see
 636 ///        - None
 637 ////////////////////////////////////////////////////////////////////////////////////////////
 638 POS_RET_API POS_ReqGPSReset(HANDLE hApp, PCSTR ResName, uint8_t mode);
 639
 640 ////////////////////////////////////////////////////////////////////////////////////////////
 641 /// \ingroup tag_Positioning
 642 /// \~english @par Brief
 643 ///        - Register GPS time setting request delivery
 644 ///
 645 /// \~english @param [in] hApp
 646 ///        - HANDLE - App Handle
 647 /// \~english @param [in] notifyName
 648 ///        - PCSTR - Destination thread name
 649 /// \~english @param [in] ucCtrlFlg
 650 ///        - uint8_t - Delivery control flag(register)
 651 ///
 652 /// \~english @par
 653 ///        - Delivery control flag(ucCtrlFlg)
 654 ///        - SENSOR_DELIVERY_REGIST - register
 655 ///
 656 /// \~english @retval POS_RET_NORMAL normal finish
 657 /// \~english @retval POS_RET_ERROR_PARAM parameter error
 658 /// \~english @retval POS_RET_ERROR_BUFFULL the register count is full
 659 /// \~english @retval POS_RET_ERROR_INNER internal error
 660 /// \~english @retval POS_RET_ERROR_NOSUPPORT unsupported
 661 /// \~english @retval POS_RET_ERROR_RESOURCE lack of resource
 662 ///
 663 /// \~english @par Precondition
 664 ///        - The creation/initialization(FrameworkunifiedCreateDispatcherWithoutLoop and etc.) of \n
 665 ///          the Dispatcher for App are completed.
 666 ///        - Availability of positioning service is TRUE.
 667 ///
 668 /// \~english @par changes of internal status
 669 ///        - There is no changes of internal status
 670 ///
 671 /// \~english @par Failure condition
 672 ///        - The parameter hApp is NULL [POS_RET_ERROR_PARAM]
 673 ///        - The parameter notifyName is NULL [POS_RET_ERROR_PARAM]
 674 ///        - The parameter ucCtrlFlg is not register(SENSOR_DELIVERY_REGIST) [POS_RET_ERROR_PARAM]
 675 ///        - The count of message in message queue is reach to max [POS_RET_ERROR_RESOURCE]
 676 ///        - The count of mutex is reach to max [POS_RET_ERROR_RESOURCE]
 677 ///        - The count of item in ProcessName-ProcessNo convert table is reach to max [POS_RET_ERROR_RESOURCE]
 678 ///        - The event is created in same process, but the count of reference is reach to max [POS_RET_ERROR_INNER]
 679 ///        - The event is created in system, but the count of reference is reach to max  [POS_RET_ERROR_INNER]
 680 ///        - Memory allocate falied during the event table creation for event registering. [POS_RET_ERROR_INNER]
 681 ///        - The thread can not register in the event table. [POS_RET_ERROR_INNER]
 682 ///        - Memory allocate failed in event table during the thread table creation. [POS_RET_ERROR_INNER]
 683 ///        - After register the thread table in event table, the event flag has already been \n
 684 ///          registered. [POS_RET_ERROR_INNER]
 685 ///        - After register the thread table in event table, the event flag register failed. [POS_RET_ERROR_INNER]
 686 ///        - The event table is full during event creation. [POS_RET_ERROR_INNER]
 687 ///        - The memory for event HANDLE allocate failed during event table creation. [POS_RET_ERROR_INNER]
 688 ///        - The thread can not be registered in event table. [POS_RET_ERROR_INNER]
 689 ///        - In event table, try to allocate the memory of the thread table creation, but failed. [POS_RET_ERROR_INNER]
 690 ///        - After register the thread in event table, the event flag has already been registered. [POS_RET_ERROR_INNER]
 691 ///        - After register the thread in event table, the event flag register failed. [POS_RET_ERROR_INNER]
 692 ///        - Specified event ID has not been registered in table. [POS_RET_ERROR_INNER]
 693 ///        - Initialize event object failed. [POS_RET_ERROR_INNER]
 694 ///        - ProcessNo has not been registered in message control table when message \n
 695 ///          transfered between processes. [POS_RET_ERROR_INNER]
 696 ///        - Message transfer HANDLE get failed when message transfered between processes. [POS_RET_ERROR_INNER]
 697 ///        - Message transfer failed in process. [POS_RET_ERROR_INNER]
 698 ///        - The destination process name size is larger than 20 characters when message transfer \n
 699 ///          between processes. [POS_RET_ERROR_INNER]
 700 ///        - The message queue name has not been registered in control table when message \n
 701 ///          transfer between processes. [POS_RET_ERROR_INNER]
 702 ///        - Message transfer HANDLE create failed when message transfered between processes. [POS_RET_ERROR_INNER]
 703 ///        - Message transfer HANDLE get failed from internal table when message transfered \n
 704 ///          between processes. [POS_RET_ERROR_INNER]
 705 ///        - Message transfer failed between processes. [POS_RET_ERROR_INNER]
 706 ///        - Specified event HANDLE has not been registered in event HANDLE table during  \n
 707 ///          event waiting. [POS_RET_ERROR_INNER]
 708 ///        - The count of thread arrived max in event management table during event waiting. [POS_RET_ERROR_INNER]
 709 ///        - The EV_FLAG_BIT is not set in flagID during event getting. [POS_RET_ERROR_INNER]
 710 ///        - The ID of message event queue has not been created during event getting. [POS_RET_ERROR_INNER]
 711 ///        - The flagID has not been registered during event getting. [POS_RET_ERROR_INNER]
 712 ///        - The interruption happened during event getting [POS_RET_ERROR_INNER]
 713 ///        - Whatever error happened during event getting. [POS_RET_ERROR_INNER]
 714 ///        - The result from positioning service is SENSOR_RET_ERROR_PARAM. [POS_RET_ERROR_PARAM]
 715 ///        - The result from positioning service is SENSOR_RET_ERROR_BUFFULL. [POS_RET_ERROR_BUFFULL]
 716 ///        - The result from positioning service is SENSOR_RET_ERROR_RESOURCE. [POS_RET_ERROR_RESOURCE]
 717 ///        - The result from positioning service is not SENSOR_RET_ERROR_PARAM or  \n
 718 ///          SENSOR_RET_ERROR_BUFFULL or SENSOR_RET_ERROR_RESOURCE. [POS_RET_ERROR_INNER]
 719 ///
 720 /// \~english @par Detail
 721 ///        - Call this API to register GPS time setting request delivery. \n
 722 ///          This API will finish when get the return value.
 723 ///
 724 ///
 725 /// \~english @par
 726 ///          Please note the following points when use this API.
 727 ///        - Duplication registering
 728 ///        - The same destination thread name has already been registered
 729 ///        - The registered delivery data updated and normal return.(first delivery)
 730 ///        - To one delivery destination, the same data will not be duplication deliveried at same timing.
 731 ///        - After call this API, if the delivery destination thread name has been changed, please call this API again.
 732 ///
 733 /// \~english @par
 734 ///          Notification of message
 735 ///        - After registered successfully, vehicle sensor information will be sent by system \n
 736 ///          API message with following format. \n
 737 ///          Command ID : @ref CID_POSIF_REGISTER_LISTENER_GPS_TIME_SET_REQ \n
 738 ///          time info structure \n
 739 ///          The year, month, date, hour, minute and second should be the format set to GPS
 740 /// \~english @code
 741 ///   typedef struct {
 742 ///     uint16_t  year;     /* A.D.(1~) */
 743 ///     uint8_t   month;    /* month(1~12) */
 744 ///     uint8_t   date;     /* date(1~31) */
 745 ///     uint8_t   hour;     /* hour(0~23) */
 746 ///     uint8_t   minute;   /* minute(0~59) */
 747 ///     uint8_t   second;   /* second(0~59) */
 748 ///     uint8_t   reserved; /* not used */
 749 ///   } POS_DATETIME;
 750 /// @endcode
 751 ///
 752 /// \~english @par Classification
 753 ///        - Public
 754 ///
 755 /// \~english @par Type
 756 ///        - Method
 757 ///
 758 /// \~english @see
 759 ///        - None
 760 ////////////////////////////////////////////////////////////////////////////////////////////
 761 POS_RET_API POS_RegisterListenerGPSTimeSetReq(HANDLE hApp, PCSTR notifyName, uint8_t ucCtrlFlg);
 762
 763 ////////////////////////////////////////////////////////////////////////////////////////////
 764 /// \ingroup tag_Positioning
 765 /// \~english @par Brief
 766 ///        - Temporarily set GPS time from Diag function
 767 ///
 768 /// \~english @param [in] hApp
 769 ///        - HANDLE - App Handle
 770 /// \~english @param [in] pstDateTime
 771 ///        - POS_DATETIME * - pointer of GPS time
 772 ///
 773 /// \~english @par
 774 ///        - POS_DATETIME structure
 775 /// \~english @code
 776 ///   typedef struct {
 777 ///     uint16_t  year;     /* A.D.(1~) */
 778 ///     uint8_t   month;    /* month(1~12) */
 779 ///     uint8_t   date;     /* date(1~31) */
 780 ///     uint8_t   hour;     /* hour(0~23) */
 781 ///     uint8_t   minute;   /* minute(0~59) */
 782 ///     uint8_t   second;   /* second(0~59) */
 783 ///     uint8_t   reserved; /* not used */
 784 ///   } POS_DATETIME;
 785 /// @endcode
 786 ///
 787 /// \~english @retval NAVIINFO_RET_NORMAL normal finish
 788 /// \~english @retval NAVIINFO_RET_ERROR_PARAM parameter error
 789 /// \~english @retval NAVIINFO_RET_ERROR_INNER internal error
 790 /// \~english @retval NAVIINFO_RET_ERROR_NOSUPPORT unsupported
 791 /// \~english @retval NAVIINFO_RET_ERROR_RESOURCE lack of resource
 792 ///
 793 /// \~english @par Precondition
 794 ///        - The creation/initialization(FrameworkunifiedCreateDispatcherWithoutLoop and etc.) \n
 795 ///          of the dispatcher for App are completed.
 796 ///        - Availability of positioning service is TRUE.
 797 ///
 798 /// \~english @par change of internal status
 799 ///        - There is no change of internal status
 800 ///
 801 /// \~english @par Failure condition
 802 ///        - The parameter pstDateTime is NULL [POS_RET_ERROR_PARAM]
 803 ///        - The parameter hApp is NULL [POS_RET_ERROR_PARAM]
 804 ///        - GPS time Data size is larger than 144 [POS_RET_ERROR_PARAM]
 805 ///        - The count of message in message queue is reach to max [POS_RET_ERROR_RESOURCE]
 806 ///        - The count of mutex is reach to max [POS_RET_ERROR_RESOURCE]
 807 ///        - The count of item in ProcessName-ProcessNo convert table is reach to max [POS_RET_ERROR_RESOURCE]
 808 ///        - The message queue name has not been registered in control table. [POS_RET_ERROR_INNER]
 809 ///        - Message transfer HANDLE create failed. [POS_RET_ERROR_INNER]
 810 ///        - Message transfer HANDLE get failed from internal table. [POS_RET_ERROR_INNER]
 811 ///        - GPS time setting message transfer failed. [POS_RET_ERROR_INNER]
 812 ///
 813 /// \~english @par Detail
 814 ///        - Call this API to set GPS time data to vehicle sensor. \n
 815 ///          This API will finish when get the return value.
 816 ///
 817 ///
 818 /// \~english @par
 819 ///          Please note the following points when use this API.
 820 ///        - This API will not notify the result of setting time to GPS device. \n
 821 ///          Return normal only there is no error such as parameter error.
 822 ///        - If want to get the result of setting time to GPS device, use  \n
 823 ///          POS_RegisterListnerGpsTime to get GPS time and judge it.
 824 ///        - This API is only called by Diag service.
 825 ///        - While GPS data is receiving from GPS device, the GPS time set by this API is ignored \n
 826 ///          and it is set actual GPS time notified by positioning_hal.
 827 ///
 828 /// \~english @par Classification
 829 ///        - Public
 830 ///
 831 /// \~english @par Type
 832 ///        - Fire and Forget
 833 ///
 834 /// \~english @see
 835 ///        - POS_GetGPStime
 836 ////////////////////////////////////////////////////////////////////////////////////////////
 837 POS_RET_API POS_SetGPStime(HANDLE hApp, POS_DATETIME* pstDateTime);
 838
 839 ////////////////////////////////////////////////////////////////////////////////////////////
 840 /// \ingroup tag_Positioning
 841 /// \~english @par Brief
 842 ///        - Register GPS time delivery
 843 ///
 844 /// \~english @param [in] hApp
 845 ///        - HANDLE - App Handle
 846 /// \~english @param [in] notifyName
 847 ///        - PCSTR - Destination thread name
 848 /// \~english @param [in] ucCtrlFlg
 849 ///        - uint8_t - Delivery control flag(register)
 850 /// \~english @param [in] ucDeliveryTiming
 851 ///        - uint8_t - Delivery timing(change/update)
 852 ///
 853 /// \~english @par
 854 ///        - Delivery control flag(ucCtrlFlg)
 855 ///        - SENSOR_DELIVERY_REGIST - register
 856 ///        - Register specified data delivery
 857 ///        - Please note that if the same data delivery has been registered for multiple \n
 858 ///          times, the data will also be deliveried for registered multiple times.
 859 ///        - The specified GPS time information will be deliveried at registered time (first delivery).
 860 ///        - Delivery timing(ucDeliveryTiming)
 861 ///        - SENSOR_DELIVERY_TIMING_CHANGE - change  Specified data will be deliveried only when it changed.
 862 ///        - SENSOR_DELIVERY_TIMING_UPDATE - update  Specified data will be deliveried as \n
 863 ///          long as it updated by vehicle sensor.
 864 ///
 865 /// \~english @retval SENSOR_RET_NORMAL normal finish
 866 /// \~english @retval SENSOR_RET_ERROR_CREATE_EVENT event creation error
 867 /// \~english @retval SENSOR_RET_ERROR_PARAM parameter error
 868 /// \~english @retval SENSOR_RET_ERROR_INNER internal error
 869 /// \~english @retval SENSOR_RET_ERROR_NOSUPPORT unsupported
 870 /// \~english @retval SENSOR_RET_ERROR_RESOURCE lack of resource
 871 ///
 872 /// \~english @par Precondition
 873 ///        - The creation/initialization(FrameworkunifiedCreateDispatcherWithoutLoop and etc.) of \n
 874 ///          the Dispatcher for App are completed.
 875 ///        - Availability of positioning service is TRUE.
 876 ///
 877 /// \~english @par changes of internal status
 878 ///        - There is no changes of internal status
 879 ///
 880 /// \~english @par Failure condition
 881 ///        - The parameter hApp is NULL [SENSOR_RET_ERROR_PARAM]
 882 ///        - The parameter notifyName is NULL [SENSOR_RET_ERROR_PARAM]
 883 ///        - The parameter ucCtrlFlg is not register(SENSOR_DELIVERY_REGIST) [SENSOR_RET_ERROR_PARAM]
 884 ///        - The parameter ucDeliveryTiming is neither update(SENSOR_DELIVERY_TIMING_UPDATE) \n
 885 ///          nor change(SENSOR_DELIVERY_TIMING_CHANGE) [SENSOR_RET_ERROR_PARAM]
 886 ///        - The count of message in message queue is reach to max [SENSOR_RET_ERROR_RESOURCE]
 887 ///        - The count of mutex is reach to max [SENSOR_RET_ERROR_RESOURCE]
 888 ///        - The count of item in ProcessName-ProcessNo convert table is reach to max [SENSOR_RET_ERROR_RESOURCE]
 889 ///        - The event is created in same process, but the count of reference is reach to \n
 890 ///          max [SENSOR_RET_ERROR_CREATE_EVENT]
 891 ///        - The event is created in system, but the count of reference is reach to max  [SENSOR_RET_ERROR_CREATE_EVENT]
 892 ///        - Memory allocate falied during the event table creation for event  \n
 893 ///          registering. [SENSOR_RET_ERROR_CREATE_EVENT]
 894 ///        - The thread can not register in the event table. [SENSOR_RET_ERROR_CREATE_EVENT]
 895 ///        - Memory allocate failed in event table during the thread table creation. [SENSOR_RET_ERROR_CREATE_EVENT]
 896 ///        - After register the thread table in event table, the event flag has already been \n
 897 ///          registered. [SENSOR_RET_ERROR_CREATE_EVENT]
 898 ///        - After register the thread table in event table, the event flag register \n
 899 ///          failed. [SENSOR_RET_ERROR_CREATE_EVENT]
 900 ///        - The event table is full during event creation. [SENSOR_RET_ERROR_CREATE_EVENT]
 901 ///        - The memory for event HANDLE allocate failed during event table creation. [SENSOR_RET_ERROR_CREATE_EVENT]
 902 ///        - The thread can not be registered in event table. [SENSOR_RET_ERROR_CREATE_EVENT]
 903 ///        - In event table, try to allocate the memory of the thread table creation, but \n
 904 ///          failed. [SENSOR_RET_ERROR_CREATE_EVENT]
 905 ///        - After register the thread in event table, the event flag has already been  \n
 906 ///          registered. [SENSOR_RET_ERROR_CREATE_EVENT]
 907 ///        - After register the thread in event table, the event flag register failed. [SENSOR_RET_ERROR_CREATE_EVENT]
 908 ///        - Specified event ID has not been registered in table. [SENSOR_RET_ERROR_CREATE_EVENT]
 909 ///        - Initialize event object failed. [SENSOR_RET_ERROR_CREATE_EVENT]
 910 ///        - ProcessNo has not been registered in message control table when message \n
 911 ///          transfered between processes. [SENSOR_RET_ERROR_INNER]
 912 ///        - Message transfer HANDLE get failed when message transfered between processes. [SENSOR_RET_ERROR_INNER]
 913 ///        - Message transfer failed between processes. [SENSOR_RET_ERROR_INNER]
 914 ///        - The destination process name size is larger than 20 characters when message \n
 915 ///          transfer between processes. [SENSOR_RET_ERROR_INNER]
 916 ///        - The message queue name has not been registered in control table when message \n
 917 ///          transfer between processes. [SENSOR_RET_ERROR_INNER]
 918 ///        - Message transfer HANDLE create failed when message transfered between processes. [SENSOR_RET_ERROR_INNER]
 919 ///        - Message transfer HANDLE get failed from internal table when message transfered \n
 920 ///          between processes. [SENSOR_RET_ERROR_INNER]
 921 ///        - Message transfer failed between processes. [SENSOR_RET_ERROR_INNER]
 922 ///        - Specified event HANDLE has not been registered in event HANDLE table during \n
 923 ///          event waiting. [SENSOR_RET_ERROR_INNER]
 924 ///        - The count of thread arrived max in event management table during event waiting. [SENSOR_RET_ERROR_INNER]
 925 ///        - The EV_FLAG_BIT is not set in flagID during event get. [SENSOR_RET_ERROR_INNER]
 926 ///        - The ID of message event queue has not been created during event get. [SENSOR_RET_ERROR_INNER]
 927 ///        - The flagID has not been registered during event get. [SENSOR_RET_ERROR_INNER]
 928 ///        - The interruption happened during event get [SENSOR_RET_ERROR_INNER]
 929 ///        - Whatever error happened during event get. [SENSOR_RET_ERROR_INNER]
 930 ///        - Get event timeout. [SENSOR_RET_ERROR_INNER]
 931 ///        - Error happened during event get. [SENSOR_RET_ERROR_INNER]
 932 ///
 933 /// \~english @par Detail
 934 ///        - Call this API to register GPS time delivery. \n
 935 ///          This API will finish when get the return value.
 936 ///
 937 ///
 938 /// \~english @par
 939 ///          Please note the following points when use this API.
 940 ///        - Duplication registering
 941 ///        - The same destination thread name has already been registered
 942 ///        - The registered delivery data updated and normal return.(first delivery)
 943 ///        - To one delivery destination, the same data will not be duplication deliveried at same timing.
 944 ///        - After call this API, if the delivery destination thread name has changed, please call this API again.
 945 ///
 946 /// \~english @par
 947 ///           Notification of message
 948 ///         - After registered successfully, vehicle sensor will send GPS time data \n
 949 ///           as system API message with following format.
 950 ///         - If the register successed, certainly delivery first data. And then \n
 951 ///           delivery data according to the delivery timing.
 952 ///         - Command ID : CID_VEHICLESENS_VEHICLE_INFO_GPS_TIME\n
 953 ///         - SENSOR_MSG_GPSTIME structure
 954 /// \~english @code
 955 ///   typedef struct {
 956 ///     NAVIINFO_UTCTIME  utc;        /* UTC time */
 957 ///     uint8_t           tdsts;      /* time status */
 958 ///     uint8_t           reserve[3]; /* reserve */
 959 ///   } SENSOR_MSG_GPSTIME;
 960 /// @endcode
 961 ///        - time status(tdsts)
 962 ///        - 0= time has not been adjusted after GPS receiver reset(time input or master reset or CSF start)
 963 ///        - 1= time output from RTC Backup(have time adjustment result)
 964 ///        - 2= time adjustment completed
 965 ///
 966 /// \~english @par
 967 ///        - NAVIINFO_UTCTIME structure
 968 /// \~english @code
 969 ///   typedef struct {
 970 ///     uint16_t  year;     /* A.D.(1~) */
 971 ///     uint8_t   month;    /* month(1~12) */
 972 ///     uint8_t   date;     /* date(1~31) */
 973 ///     uint8_t   hour;     /* hour(0~23) */
 974 ///     uint8_t   minute;   /* minute(0~59) */
 975 ///     uint8_t   second;   /* second(0~59) */
 976 ///     uint8_t   reserved; /* not used */
 977 ///   } POS_DATETIME;
 978 /// @endcode
 979 ///
 980 ///
 981 /// \~english @par Classification
 982 ///        - Public
 983 ///
 984 /// \~english @par Type
 985 ///        - Method
 986 ///
 987 /// \~english @see
 988 ///        - None
 989 ////////////////////////////////////////////////////////////////////////////////////////////
 990 SENSOR_RET_API POS_RegisterListenerGPStime(HANDLE hApp, PCSTR notifyName, uint8_t ucCtrlFlg, uint8_t ucDeliveryTiming);
 991
 992 ////////////////////////////////////////////////////////////////////////////////////////////
 993 /// \ingroup tag_Positioning
 994 /// \~english @par Brief
 995 ///        - Get GPS time
 996 ///
 997 /// \~english @param [in] hApp
 998 ///        - HANDLE - App Handle
 999 /// \~english @param [out] dat
1000 ///        - SENSOR_GPSTIME* - output buffer pointer to store GPS time
1001 ///
1002 /// \~english @par
1003 ///        - SENSOR_GPSTIME structure
1004 /// \~english @code
1005 ///   typedef struct {
1006 ///     NAVIINFO_UTCTIME  utc;        /* UTC time */
1007 ///     uint8_t           tdsts;      /* date amd time status */
1008 ///     uint8_t           reserve[3]; /* reserve */
1009 ///   } SENSOR_GPSTIME;
1010 /// @endcode
1011 ///        - date amd time status(tdsts)
1012 ///        - 0= time has not been adjusted after GPS receiver reset(time input or master reset or CSF start)
1013 ///        - 1= time output from RTC Backup(have time adjustment result)
1014 ///        - 2= time adjustment completed
1015 ///
1016 /// \~english @par
1017 ///        - NAVIINFO_UTCTIME structure
1018 /// \~english @code
1019 ///   typedef struct {
1020 ///     uint16_t  year;     /* A.D.(1~) */
1021 ///     uint8_t   month;    /* month(1~12) */
1022 ///     uint8_t   date;     /* date(1~31) */
1023 ///     uint8_t   hour;     /* hour(0~23) */
1024 ///     uint8_t   minute;   /* minute(0~59) */
1025 ///     uint8_t   second;   /* second(0~59) */
1026 ///     uint8_t   reserved; /* not used */
1027 ///   } NAVIINFO_UTCTIME;
1028 /// @endcode
1029 ///
1030 /// \~english @retval POS_RET_NORMAL normal finish
1031 /// \~english @retval POS_RET_ERROR_PARAM parameter error
1032 /// \~english @retval POS_RET_ERROR_INNER internal error
1033 /// \~english @retval POS_RET_ERROR_NOSUPPORT unsupported
1034 /// \~english @retval POS_RET_ERROR_RESOURCE lack of resource
1035 ///
1036 /// \~english @par Precondition
1037 ///        - The creation/initialization(FrameworkunifiedCreateDispatcherWithoutLoop and etc.) \n
1038 ///          of the Dispatcher for App are completed.
1039 ///        - Availability of positioning service is TRUE.
1040 ///
1041 /// \~english @par changes of internal status
1042 ///        - There is no changes of internal status
1043 ///
1044 /// \~english @par Failure condition
1045 ///        - The parameter hApp is NULL [POS_RET_ERROR_PARAM]
1046 ///        - The parameter dat is NULL [POS_RET_ERROR_PARAM]
1047 ///        - The count of message in message queue is reach to max [POS_RET_ERROR_RESOURCE]
1048 ///        - The count of mutex is reach to max [POS_RET_ERROR_RESOURCE]
1049 ///        - The count of item in ProcessName-ProcessNo convert table is reach to max [POS_RET_ERROR_RESOURCE]
1050 ///        - The event is created in same process, but the count of reference is reach to max [POS_RET_ERROR_INNER]
1051 ///        - The event is created in system, but the count of reference is reach to max  [POS_RET_ERROR_INNER]
1052 ///        - Memory allocate falied during the event table creation for event registering. [POS_RET_ERROR_INNER]
1053 ///        - The thread can not register in the event table. [POS_RET_ERROR_INNER]
1054 ///        - Memory allocate failed in event table during the thread table creation. [POS_RET_ERROR_INNER]
1055 ///        - After register the thread table in event table, the event flag has already  \n
1056 ///          been registered. [POS_RET_ERROR_INNER]
1057 ///        - After register the thread table in event table, the event flag register failed. [POS_RET_ERROR_INNER]
1058 ///        - The event table is full during event creation. [POS_RET_ERROR_INNER]
1059 ///        - The memory for event HANDLE allocate failed during event table creation. [POS_RET_ERROR_INNER]
1060 ///        - The thread can not be registered in event table. [POS_RET_ERROR_INNER]
1061 ///        - In event table, try to allocate the memory of the thread table creation, but failed. [POS_RET_ERROR_INNER]
1062 ///        - After register the thread in event table, the event flag has already been registered. [POS_RET_ERROR_INNER]
1063 ///        - After register the thread in event table, the event flag register failed. [POS_RET_ERROR_INNER]
1064 ///        - Specified event ID has not been registered in table. [POS_RET_ERROR_INNER]
1065 ///        - Initialize event object failed. [POS_RET_ERROR_INNER]
1066 ///        - The memory for storing semaphore control data allocate failed. [POS_RET_ERROR_INNER]
1067 ///        - Specified semaphore ID has not been registered when semaphore lock. [POS_RET_ERROR_INNER]
1068 ///        - Internal mutex HANDLE is NULL when mutex lock. [POS_RET_ERROR_INNER]
1069 ///        - Internal mutex HANDLE has not been registered in mutex table when mutex lock. [POS_RET_ERROR_INNER]
1070 ///        - The owner of specified mutex is not itself when mutex lock. [POS_RET_ERROR_INNER]
1071 ///        - Mutex has been multiple locked [POS_RET_ERROR_INNER]
1072 ///        - The HANDLE is NULL when getting usable share memory address. [POS_RET_ERROR_INNER]
1073 ///        - Can not get usable share memory address. [POS_RET_ERROR_INNER]
1074 ///        - Memory allocate failed for share memory map. [POS_RET_ERROR_INNER]
1075 ///        - Memory allocate failed for share memory management. [POS_RET_ERROR_INNER]
1076 ///        - Can not open share memory. [POS_RET_ERROR_INNER]
1077 ///        - Failed to mapping share memory. [POS_RET_ERROR_INNER]
1078 ///        - No empty field in share memory. [POS_RET_ERROR_INNER]
1079 ///        - Failed to guarantee share memory. [POS_RET_ERROR_INNER]
1080 ///        - ProcessNo has not been registered in message control table when message \n
1081 ///          transfered between processes. [POS_RET_ERROR_INNER]
1082 ///        - Message transfer HANDLE get failed when message transfered between processes. [POS_RET_ERROR_INNER]
1083 ///        - Message transfer failed between processes. [POS_RET_ERROR_INNER]
1084 ///        - The destination process name size is larger than 20 characters when message \n
1085 ///          transfer between processes. [POS_RET_ERROR_INNER]
1086 ///        - The message queue name has not been registered in control table when message \n
1087 ///          transfer between processes. [POS_RET_ERROR_INNER]
1088 ///        - Message transfer HANDLE create failed when message transfered between processes. [POS_RET_ERROR_INNER]
1089 ///        - Message transfer HANDLE get failed from internal table when message transfered \n
1090 ///          between processes. [POS_RET_ERROR_INNER]
1091 ///        - Message transfer failed between processes. [POS_RET_ERROR_INNER]
1092 ///        - Specified event HANDLE has not been registered in event HANDLE table during \n
1093 ///          event waiting. [POS_RET_ERROR_INNER]
1094 ///        - The count of thread arrived max in event management table during event waiting. [POS_RET_ERROR_INNER]
1095 ///        - The EV_FLAG_BIT is not set in flagID during event getting. [POS_RET_ERROR_INNER]
1096 ///        - The ID of message event queue has not been created during event getting. [POS_RET_ERROR_INNER]
1097 ///        - The flagID has not been registered during event getting. [POS_RET_ERROR_INNER]
1098 ///        - The interruption happened during event getting [POS_RET_ERROR_INNER]
1099 ///        - Whatever error happened during event getting. [POS_RET_ERROR_INNER]
1100 ///        - The HANDLE is NULL when getting usable share memory address for accessing \n
1101 ///          received data. [POS_RET_ERROR_INNER]
1102 ///        - Can not get usable share memory address for accessing received data. [POS_RET_ERROR_INNER]
1103 ///        - Memory for share memory map allocate failed for accessing received data. [POS_RET_ERROR_INNER]
1104 ///        - Memory for share memory management allocate failed for accessing received data. [POS_RET_ERROR_INNER]
1105 ///        - Can not open share memory for accessing received data. [POS_RET_ERROR_INNER]
1106 ///        - Failed to mapping share memory for accessing received data. [POS_RET_ERROR_INNER]
1107 ///        - The size of data stored in share memory is larger than the size of received data. [POS_RET_ERROR_INNER]
1108 ///        - The result of sensor data getting process is POS_RET_ERROR_RESOURCE. [POS_RET_ERROR_RESOURCE]
1109 ///        - The result of sensor data getting process is not POS_RET_ERROR_RESOURCE. [POS_RET_ERROR_INNER]
1110 ///
1111 /// \~english @par Detail
1112 ///        - Call this API to get GPS time from vehicle sensor.
1113 ///
1114 /// \~english @par
1115 ///        - Please note the following points when use this API.
1116 ///
1117 ///
1118 /// \~english @par Classification
1119 ///        - Public
1120 ///
1121 /// \~english @par Type
1122 ///        - Sync
1123 ///
1124 /// \~english @see
1125 ///        - POS_SetGPStime
1126 ////////////////////////////////////////////////////////////////////////////////////////////
1127 POS_RET_API POS_GetGPStime(HANDLE hApp, SENSOR_GPSTIME* dat);
1128
1129 #ifdef __cplusplus
1130 }
1131 #endif
1132 /** @}*/  // end of positioning
1133 /** @}*/  // end of vehicle_service
1134 /** @}*/  // end of BaseSystem
1135 #endif  // POSITIONING_CLIENT_INCLUDE_VEHICLE_SERVICE_POS_GPS_API_H_