/*
* @copyright Copyright (c) 2016-2020 TOYOTA MOTOR CORPORATION.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/**
* @file ss_power_service_if.h
* @brief \~english This file supports the Power Service client interface.
*/
/**
* @file
*/
/** @addtogroup BaseSystem
* @{
*/
/** @addtogroup system_service
* @ingroup BaseSystem
* @{
*/
/** @addtogroup power_service
* @ingroup system_service
* @{
*/
#ifndef POWER_SERVICE_CLIENT_INCLUDE_SYSTEM_SERVICE_SS_POWER_SERVICE_IF_H_ // NOLINT (build/header_guard)
#define POWER_SERVICE_CLIENT_INCLUDE_SYSTEM_SERVICE_SS_POWER_SERVICE_IF_H_
#include "system_service/ss_power_service.h"
#include "system_service/ss_power_service_protocol.h"
////////////////////////////////////////////////////////////////////////////////////////////
/// \ingroup OpenPowerService
/// \~english @par Summary
/// Obtain a handle for using the PowerService.
/// \~english @param [in] f_hApp
/// HANDLE - Application handle
/// \~english @retval Handle Success
/// \~english @retval NULL Failed
/// \~english @par Classification
/// Public
/// \~english @par Type
/// Sync only(None communication)
/// \~english @par Detail
/// - The API creates a communication resource between
/// the user service and the PowerService
/// and returns a handle for using the PowerService.\n
/// \n
/// - Include ss_power_service_ifc.h
/// - Library libSS_PowerServiceIf.so
/// \~english @see
/// None
////////////////////////////////////////////////////////////////////////////////////////////
HANDLE OpenPowerService(HANDLE f_hApp);
////////////////////////////////////////////////////////////////////////////////////////////
/// \ingroup ClosePowerService
/// \~english @par Summary
/// Free a handle for using PowerService.
/// \~english @param [in] f_hApp
/// HANDLE - Application handle
/// \~english @param [in] f_hService
/// HANDLE - PowerService handle
/// \~english @retval eFrameworkunifiedStatusOK Success
/// \~english @retval eFrameworkunifiedStatusInvldHandle Invalid handle
/// \~english @retval eFrameworkunifiedStatusFail Failed
/// \~english @par Classification
/// Public
/// \~english @par Type
/// Sync only
/// \~english @par Detail
/// - The API terminates the communication resource between
/// the user service and the PowerServiceand frees the given handle. \n
/// \n
/// - Include ss_power_service_ifc.h
/// - Library libSS_PowerServiceIf.so
/// \~english @see
/// None
////////////////////////////////////////////////////////////////////////////////////////////
EFrameworkunifiedStatus ClosePowerService(HANDLE f_hApp, HANDLE f_hService);
////////////////////////////////////////////////////////////////////////////////////////////
/// \ingroup PwrServiceOpenSessionRequest
/// \~english @par Summary
/// Make the PowerService available.
/// \~english @param [in] f_hService
/// HANDLE - PowerService handle
/// \~english @param [in] f_eSessionType
/// EPWR_SESSION_TYPE - Session type
/// \~english @retval eFrameworkunifiedStatusOK Success
/// \~english @retval eFrameworkunifiedStatusInvldHandle Invalid handle
/// \~english @retval eFrameworkunifiedStatusInvldParam Invalid parameter
/// \~english @retval eFrameworkunifiedStatusFail Failed
/// \~english @par Classification
/// Public
/// \~english @par Type
/// Fire and Forget x Method
/// \~english @par Detail
/// - The API opens a session between the user service
/// and the PowerService and makes the PowerService available. \n
/// \n
/// - Include ss_power_service_ifc.h
/// - Library libSS_PowerServiceIf.so
/// \~english @see
/// None
////////////////////////////////////////////////////////////////////////////////////////////
EFrameworkunifiedStatus PwrServiceOpenSessionRequest(HANDLE f_hService,
EPWR_SESSION_TYPE f_eSessionType);
////////////////////////////////////////////////////////////////////////////////////////////
/// \ingroup PwrServiceCloseSessionRequest
/// \~english @par Summary
/// End using the PowerService.
/// \~english @param [in] f_hService
/// HANDLE - PowerService handle
/// \~english @param [in] f_hSession
/// HANDLE - Session type
/// \~english @retval eFrameworkunifiedStatusOK Success
/// \~english @retval eFrameworkunifiedStatusInvldHandle Invalid handle
/// \~english @retval eFrameworkunifiedStatusFail Failed
/// \~english @par Classification
/// Public
/// \~english @par Type
/// Fire and Forget x Method
/// \~english @par Detail
/// - The API closes the session between the user service
/// and the PowerService and terminatesthe PowerSerivce use. \n
/// \n
/// - Include ss_power_service_ifc.h
/// - Library libSS_PowerServiceIf.so
/// \~english @see
/// None
////////////////////////////////////////////////////////////////////////////////////////////
EFrameworkunifiedStatus PwrServiceCloseSessionRequest(HANDLE f_hService, HANDLE f_hSession);
////////////////////////////////////////////////////////////////////////////////////////////
/// \ingroup PwrServiceDecodeOpenSessionResponse
/// \~english @par Summary
/// Obtain a handle for OpenSessionRequest response message.
/// \~english @param [in] f_hApp
/// HANDLE - Application handle
/// \~english @param [in] f_hSession
/// HANDLE& - Address of storing session handle
/// \~english @retval eFrameworkunifiedStatusOK Success
/// \~english @retval eFrameworkunifiedStatusInvldHandle Invalid handle
/// \~english @retval eFrameworkunifiedStatusNullPointer NULL Pointer
/// \~english @par Classification
/// Public
/// \~english @par Type
/// Sync only(None communication)
/// \~english @par Detail
/// - The API obtains a handle for OpenSessionRequest
/// response message using the given application handle.\n
/// \n
/// - Include ss_power_service_ifc.h
/// - Library libSS_PowerServiceIf.so
/// \~english @see
/// None
////////////////////////////////////////////////////////////////////////////////////////////
EFrameworkunifiedStatus PwrServiceDecodeOpenSessionResponse(HANDLE f_hApp,
HANDLE& f_hSession); // NOLINT (runtime/references)
////////////////////////////////////////////////////////////////////////////////////////////
/// \ingroup PwrServiceSetVoltageState
/// \~english @par Summary
/// Set power supply state.
/// \~english @param [in] f_hSession
/// HANDLE - Session handle
/// \~english @param [in] f_eVoltage_state
/// EPWR_VOLTAGE_STATE_TYPE - Power supply status value
/// \~english @par
/// - Power supply status value
///
/// Name | Value |
/// epsvsINVALID | 0xFF |
/// epsvsNORMAL | 0x20 |
/// epsvsLVI1 | 0x22 |
/// epsvsLVI2 | 0x24 |
///
/// \~english @retval eFrameworkunifiedStatusOK Success
/// \~english @retval eFrameworkunifiedStatusInvldHandle Invalid handle
/// \~english @retval eFrameworkunifiedStatusInvldParam Invalid parameter
/// \~english @retval eFrameworkunifiedStatusFail Failed
/// \~english @par Classification
/// Public
/// \~english @par Type
/// Method only
/// \~english @par Detail
/// - The API sets power supply state to the PowerService. \n
/// \n
/// - Include ss_power_service_ifc.h
/// - Library libSS_PowerServiceIf.so
/// \~english @see
/// None
////////////////////////////////////////////////////////////////////////////////////////////
EFrameworkunifiedStatus PwrServiceSetVoltageState(HANDLE f_hSession,
EPWR_VOLTAGE_STATE_TYPE f_eVoltage_state);
////////////////////////////////////////////////////////////////////////////////////////////
/// \ingroup PwrServiceSetCrankState
/// \~english @par Summary
/// Set crank state.
/// \~english @param [in] f_hSession
/// HANDLE - Session handle
/// \~english @param [in] f_eCrank_state
/// EPWR_CRANK_STATE_TYPE - Crank state value
/// \~english @par
/// - Crank state value
///
/// Name | Value |
/// epscsINVALID | 0xFF |
/// epscsENTRY | 0xA0 |
/// epscsEXIT | 0xA2 |
///
/// \~english @retval eFrameworkunifiedStatusOK Success
/// \~english @retval eFrameworkunifiedStatusInvldHandle Invalid handle
/// \~english @retval eFrameworkunifiedStatusInvldParam Invalid parameter
/// \~english @retval eFrameworkunifiedStatusFail Failed
/// \~english @par Classification
/// Public
/// \~english @par Type
/// Fire and Forget only
/// \~english @par Detail
/// - The API sets crank state to the PowerService.\n
/// \n
/// - Include ss_power_service_ifc.h
/// - Library libSS_PowerServiceIf.so
/// \~english @see
/// None
////////////////////////////////////////////////////////////////////////////////////////////
EFrameworkunifiedStatus PwrServiceSetCrankState(HANDLE f_hSession,
EPWR_CRANK_STATE_TYPE f_eCrank_state);
////////////////////////////////////////////////////////////////////////////////////////////
/// \ingroup PwrServiceSystemModeInfoRequest
/// \~english @par Summary
/// Request to obtain the system mode information.
/// \~english @param [in] f_hSession
/// HANDLE - Session handle
/// \~english @retval eFrameworkunifiedStatusOK Success
/// \~english @retval eFrameworkunifiedStatusInvldHandle Invalid handle
/// \~english @retval eFrameworkunifiedStatusFail Failed
/// \~english @par Classification
/// Public
/// \~english @par Type
/// Method x Method
/// \~english @par Detail
/// - The API requests the PowerService to obtain
/// the system mode information.\n
/// \n
/// - Include ss_power_service_ifc.h
/// - Library libSS_PowerServiceIf.so
/// \~english @see
/// None
////////////////////////////////////////////////////////////////////////////////////////////
EFrameworkunifiedStatus PwrServiceSystemModeInfoRequest(HANDLE f_hSession);
////////////////////////////////////////////////////////////////////////////////////////////
/// \ingroup PwrServiceSendInitCompReport
/// \~english @par Summary
/// Send an initialize complete response.
/// \~english @param [in] f_hSession
/// HANDLE - Session handle
/// \~english @retval eFrameworkunifiedStatusOK Success
/// \~english @retval eFrameworkunifiedStatusInvldHandle Invalid handle
/// \~english @retval eFrameworkunifiedStatusFail Failed
/// \~english @par Classification
/// Public
/// \~english @par Type
/// Fire and Forgeat x Fire and Forget
/// \~english @par Detail
/// - The API sends an initialize complete response to the PowerService.\n
/// \n
/// - Include ss_power_service_ifc.h
/// - Library libSS_PowerServiceIf.so
/// \~english @see
/// None
////////////////////////////////////////////////////////////////////////////////////////////
EFrameworkunifiedStatus PwrServiceSendInitCompReport(HANDLE f_hSession);
////////////////////////////////////////////////////////////////////////////////////////////
/// \ingroup PwrServiceSendSetShutdownPopupRequest
/// \~english @par Summary
/// Obtain shutdown state.
/// \~english @param [in] f_hSession
/// HANDLE - Session handle
/// \~english @param [in] f_eShutdownPopup
/// EPWR_SHUTDOWN_POPUP_TYPE - Shutdown state
/// \~english @retval eFrameworkunifiedStatusOK Success
/// \~english @retval eFrameworkunifiedStatusInvldHandle Invalid handle
/// \~english @retval eFrameworkunifiedStatusInvldParam Invalid parameter
/// \~english @retval eFrameworkunifiedStatusFail Failed
/// \~english @par Classification
/// Public
/// \~english @par Type
/// Method only
/// \~english @par Detail
/// - The API obtains the shutdown state from the PowerService. \n
/// \n
/// - Include ss_power_service_ifc.h
/// - Library libSS_PowerServiceIf.so
/// \~english @see
/// None
////////////////////////////////////////////////////////////////////////////////////////////
EFrameworkunifiedStatus PwrServiceSendSetShutdownPopupRequest(HANDLE f_hSession,
EPWR_SHUTDOWN_POPUP_TYPE f_eShutdownPopup);
////////////////////////////////////////////////////////////////////////////////////////////
/// \ingroup PwrServiceSendStartupConfirmationMsgRequest
/// \~english @par Summary
/// Send startup confirmation request.
/// \~english @param [in] f_hSession
/// HANDLE - Session handle
/// \~english @param [in] f_eState
/// EPWR_SC_MSG_STRUCT
/// - Address of the structure for startup confirmation request message
/// \~english @par
/// - Structure for startup confirmation request message
/// \~english @code
/// typedef struct {
/// EPWR_SC__CWORD56__BOOT_MODE_TYPE _CWORD56_BootMode;
/// EPWR_SC_WAKEUP_TYPE wakeupType;
/// EPWR_SC_COLD_START_REQ_TYPE coldStartRequest;
/// EPWR_SC_SECURITY_STATUS securityStatus;
/// UI_32 HWVersion;
/// UI_32 matchedHardwareType;
/// UI_32 softwareType;
/// UI_32 imageType;
/// UI_32 majorVersion;
/// UI_32 minorVersion;
/// UI_32 SWVersionYear;
/// UI_32 SWVersionWeek;
/// UI_32 SWVersionPatchLevel;
/// } StartupConfirmationMsgStrut, EPWR_SC_MSG_STRUCT;
/// @endcode\n
/// \n
/// - EPWR_SC__CWORD56__BOOT_MODE_TYPE
///
/// Name | Value |
/// eps_CWORD56_bmINVALID | 0xFF |
/// eps_CWORD56_bmAPPLICATION_MODE | 0x00 |
/// eps_CWORD56_bmPROGRAMMING_MODE | 0x08 |
///
\n
/// \n
/// - EPWR_SC_WAKEUP_TYPE
///
/// Name | Value |
/// epsstINVALID | 0xFF |
/// epsstWARMSTART | 0x00 |
/// epsstCOLDSTART | 0x01 |
///
\n
/// \n
/// - EPWR_SC_COLD_START_REQ_TYPE
///
/// Name | Value |
/// epsscrtINVALID | 0xFF |
/// epsscrtNOT_REQUIRED | 0x00 |
/// epsscrtREQUIRED | 0x01 |
///
\n
/// \n
/// - EPWR_SC_SECURITY_STATUS
///
/// Name | Value |
/// epsssINVALID | 0xFF |
/// epsssUNLOCK | 0x00 |
/// epsssLOCK | 0x01 |
///
\n
/// \n
/// \~english @retval eFrameworkunifiedStatusOK Success
/// \~english @retval eFrameworkunifiedStatusInvldHandle Invalid handle
/// \~english @retval eFrameworkunifiedStatusFail Failed
/// \~english @par Classification
/// Public
/// \~english @par Type
/// Fire and Forget x Fire and Forget
/// \~english @par Detail
/// - The API sends a startup confirmation request to the PowerService.\n
/// \n
/// - Include ss_power_service_ifc.h
/// - Library libSS_PowerServiceIf.so
/// \~english @see
/// None
////////////////////////////////////////////////////////////////////////////////////////////
EFrameworkunifiedStatus PwrServiceSendStartupConfirmationMsgRequest(HANDLE f_hSession
, EPWR_SC_MSG_STRUCT f_eState);
////////////////////////////////////////////////////////////////////////////////////////////
/// \ingroup PwrServiceSendPowerRequest
/// \~english @par Brief
/// Send power request.
/// \~english @param [in] f_hSession
/// HANDLE - Session handle
/// \~english @param [in] f_eState
/// \ref PowerRequestMsgStrutWithUMCR "EPWR_POWER_REQUEST_MSG_STRUCT_WITH_UMCR&" - Address of the structure for power request message
/// \~english @par
/// \n
/// Of the eight elements of the \ref PowerRequestMsgStrutWithUMCR "EPWR_POWER_REQUEST_MSG_STRUCT_WITH_UMCR" structure, five elements set fixed values.\n
/// startupType = \ref epsprm_CWORD102_si_CWORD102__STARTUP_NORMAL\n
/// openingType = \ref epsprmotTIMING_TYPE_1\n
/// lastUserMode = \ref epsumON\n
/// manResetInfo = \ref epsprmriNORMAL\n
/// lastSystemRetentionReq = \ref epsprlsrrLAST_SYSTEM_OFF\n
/// \n
/// For the following, set different values at system startup and shutdown.\n
/// (Element name) = (Startup settings or Shutdown settings)\n
/// startupReason = (\ref epswfIGN_ACC or \ref epswfINVALID)\n
/// userMode = (\ref epsumON or \ref epsumOFF)\n
/// \n
/// For the following, set different values at power state transition.\n
///
/// Element name | Power state | Value |
/// userModeChangeReason |
Not Available | \ref epsumcrNOT_AVAILABLE |
/// | \ref epsumcrON_KEY |
/// Parking(+B) | \ref epsumcrPARKING_B |
/// Pre-boot(+BA) | \ref epsumcrPRE_BA |
/// Normal-boot | \ref epsumcrNORMAL |
/// Background-boot(+BA) | \ref epsumcrBACKGROUND_BA |
///
/// \n
/// \~english @retval eFrameworkunifiedStatusOK Success
/// \~english @retval eFrameworkunifiedStatusInvldHandle Invalid handle
/// \~english @retval eFrameworkunifiedStatusFail Failed
/// \~english @par Prerequisite
/// None
/// \~english @par Change of internal state
/// None
/// \~english @par Conditions of processing failure
/// - When the session handle (f_hSession) specified by the argument is NULL. [eFrameworkunifiedStatusInvldHandle]
/// - The process fails for some reason. [eFrameworkunifiedStatusFail]
/// \~english @par Classification
/// Public
/// \~english @par Type
/// Method only
/// \~english @par Detail
/// - The API send a power request to the PowerService.\n
/// \n
/// - Include ss_power_service_ifc.h
/// - Library libSS_PowerServiceIf.so
/// \~english @see
/// None
////////////////////////////////////////////////////////////////////////////////////////////
EFrameworkunifiedStatus PwrServiceSendPowerRequest(HANDLE f_hSession,
EPWR_POWER_REQUEST_MSG_STRUCT_WITH_UMCR& f_eState);
////////////////////////////////////////////////////////////////////////////////////////////
/// \ingroup PwrServiceSendShutdownRequest
/// \~english @par Summary
/// Send shutdown request.
/// \~english @param [in] f_hSession
/// HANDLE - Session handle
/// \~english @param [in] f_eState
/// EPWR_SHUTDOWN_REQUEST_MSG_STRUCT&
/// - Address of the structure for shutdown request message
/// \~english @par
/// - Structure for shutdown request message
/// \~english @code
/// typedef struct {
/// EPWR_ONS_TYPE ONS_Type;
/// EPWR_SHUTDOWN_TRIGGER_TYPE shutdownTrigger;
/// EPWR_USER_MODE_TYPE lastUserMode;
/// EPWR_TRANSPORT_MODE_TYPE transportMode;
/// EPWR_PROD_MODE_TYPE productionMode;
/// EPWR_LHC_TYPE limpHomeCutoffRequest;
/// } ShutdownRequestMsgStrut, EPWR_SHUTDOWN_REQUEST_MSG_STRUCT
/// @endcode\n
/// \n
/// - EPWR_ONS_TYPE
///
/// Name | Value |
/// epssdmonsINVALID | 0xFF |
/// epssdmonsNO_ONS | 0x00 |
/// epssdmonsONS | 0x01 |
///
\n
/// \n
/// - EPWR_SHUTDOWN_TRIGGER_TYPE
///
/// Name | Value |
/// epssdmsdtINVALID | 0xFF |
/// epssdmsdtTESTACC_OFF | 0x00 |
/// epssdmsdtON_KEY | 0x01 |
/// epssdmsdtIGN_LOCK | 0x02 |
/// epssdmsdtPWR_SAVE | 0x03 |
/// epssdmsdtTMP_STARTUP | 0x04 |
/// epssdmsdtDIAG_DEACTIVATION | 0x05 |
/// epssdmsdtABNORMAL_VOLTAGE | 0x06 |
/// epssdmsdtABNORMAL_TEMP | 0x07 |
/// epssdmsdtBATTERYCUTOFF | 0x08 |
/// epssdmsdtLIMPHOME | 0x09 |
/// epssdmsdtHU_CAN_ERROR | 0x0A |
/// epssdmsdtBODY_CAN_ERROR | 0x0B |
/// epssdmsdtTRANSPORT_MODE | 0x0C |
/// epssdmsdtPRODUCTION_MODE | 0x0D |
/// epssdmsdtIGN_OFF | 0x0E |
/// epssdmsdtGENERIC_ERROR_RESET | 0x0F |
/// epssdmsdtFATAL_ERROR_RESET | 0x10 |
/// epssdmsdtUSER_DATA_RESET | 0x11 |
/// epssdmsdtFACTORY_DATA_RESET | 0x12 |
/// epssdmsdtFAST_SLEEP_MODE | 0x13 |
/// epssdmsdtNORMAL_RESET | 0x14 |
/// epssdmsdtPROGUPDATE_RESET | 0x15 |
///
\n
/// \n
/// - EPWR_USER_MODE_TYPE
///
/// Name | Value |
/// epsumINVALID | 0xFF |
/// epsumOFF | 0x00 |
/// epsumON | 0x01 |
///
\n
/// \n
/// - EPWR_TRANSPORT_MODE_TYPE
///
/// Name | Value |
/// epstmINVALID | 0xFF |
/// epstmDISABLED | 0x00 |
/// epstmENABLED | 0x01 |
///
\n
/// \n
/// - EPWR_PROD_MODE_TYPE
///
/// Name | Value |
/// epspmINVALID | 0xFF |
/// epspmDISABLED | 0x00 |
/// epspmENABLED | 0x01 |
///
\n
/// \n
/// - EPWR_LHC_TYPE
///
/// Name | Value |
/// epslhcINVALID | 0xFF |
/// epslhcDISABLED | 0x00 |
/// epslhcENABLED | 0x01 |
///
\n
/// \n
/// \~english @retval eFrameworkunifiedStatusOK Success
/// \~english @retval eFrameworkunifiedStatusInvldHandle Invalid handle
/// \~english @retval eFrameworkunifiedStatusFail Failed
/// \~english @par Classification
/// Public
/// \~english @par Type
/// Method x Method
/// \~english @par Detail
/// - The API sends shutdown request to the PowerService.\n
/// \n
/// - Include ss_power_service_ifc.h
/// - Library libSS_PowerServiceIf.so
/// \~english @see
/// None
////////////////////////////////////////////////////////////////////////////////////////////
EFrameworkunifiedStatus PwrServiceSendShutdownRequest(
HANDLE f_hSession
, EPWR_SHUTDOWN_REQUEST_MSG_STRUCT &f_eState); // NOLINT (runtime/references)
////////////////////////////////////////////////////////////////////////////////////////////
/// \ingroup PwrServiceSendHeartBeatRequest
/// \~english @par Summary
/// Send a request for HeartBeat monitoring start.
/// \~english @param [in] f_hSession
/// HANDLE - Session handle
/// \~english @param [in] f_eHbReqMsg
/// EPWR_HB_REQ_MSG_STRUCT*
/// - Address of the structure for HeartBeat monitoring start request message
/// \~english @par
/// - Structure for HeartBeat monitoring start request message
/// \~english @code
/// typedef struct {
/// UI_8 IntervalSec;
/// } EPWR_HB_REQ_MSG_STRUCT;
/// @endcode\n
/// \n
/// \~english @retval eFrameworkunifiedStatusOK Success
/// \~english @retval eFrameworkunifiedStatusInvldHandle Invalid handle
/// \~english @retval eFrameworkunifiedStatusFail Failed
/// \~english @par Classification
/// Public
/// \~english @par Type
/// Method x Method
/// \~english @par Detail
/// - The API sends HeartBeat monitoring start\n
/// request to the PowerService\n
/// - Include ss_power_service_ifc.h
/// - Library libSS_PowerServiceIf.so
/// \~english @see
/// None
////////////////////////////////////////////////////////////////////////////////////////////
EFrameworkunifiedStatus PwrServiceSendHeartBeatRequest(
HANDLE f_hSession,
EPWR_HB_REQ_MSG_STRUCT *f_eHbReqMsg);
#endif // POWER_SERVICE_CLIENT_INCLUDE_SYSTEM_SERVICE_SS_POWER_SERVICE_IF_H_ // NOLINT (build/header_guard)
/** @}*/ // end of PowerService
/** @}*/ // end of SystemService
/** @}*/ // end of BaseSystem