/*
 * Copyright (c) 2022 Qualcomm Technologies, Inc.
 * All Rights Reserved.
 * Confidential and Proprietary - Qualcomm Technologies, Inc.
 */

/**
 * This interface is used by clients to get notification from TZ.
 * Clients should pass this interface object to TZ by using \link IPeripheralState \endlink
 * method @ref registerCallBack.
 */

/** @cond */
interface IPeripheralStateCB {
/** @endcond */

  /**
   * @addtogroup IPeripheralStateCB
   * @{
   */
  /* Error Codes */
  error ERROR_EMERGENCYCALL;

  /**
   * To receive notification of peripheral state clients will use this interface.
   * Peripheral Access Control service uses this method to notify state change
   * of Peripheral registering this interface as callback.
   *
   * @param[in]  uint8 various state values are defined in \link IPeripheralState \endlink
   *
   * @return
   * Object_OK on success.\n
   * IPeripheralStateCB_ERROR_EMERGENCYCALL if modem/gnss are in emergency call.\n
   */

  method notifyPeripheralStateChange(in uint8 state);

  /** @} */
};


/** @cond */
interface IPeripheralState {
  /** @endcond */

  /**
   * @addtogroup IPeripheralState
   * @{
   */

  /* These constants define the possible peripheral states */

  /** When peripheral is in secure state we use this value */
  const uint8 STATE_SECURE            = 0x01;
  /** When peripheral is in non secure state we use this value */
  const uint8 STATE_NONSECURE         = 0x02;
  /** During EMERGENCY CALLs MODEM will use this state to notify TZ service */
  const uint8 STATE_EMERGENCYCALL     = 0x03;
  /** Pre-change state notification for some peripherals */
  const uint8 STATE_PRE_CHANGE        = 0x04;
  /** Post-change state notification for some peripherals */
  const uint8 STATE_POST_CHANGE       = 0x05;

  /* Error Codes for each methods */
  error ERROR_PERIPHERAL_NOT_FOUND;

  /**
   * This method will register a callback object for given peripheral which will be
   * used to get the secure events notification.
   *
   * @param[in]  uint32 valid peripheral values are defined in \link CPeripheralAccessControl \endlink
   * @param[in]  interface \link IPeripheralStateCB \endlink object
   *
   * @return
   * Object_OK on success.\n
   * IPeripheralState_ERROR_PERIPHERAL_NOT_FOUND on faliure if invalid peripheral is given as input.\n
   */

  method registerCallBack(in uint32 peripheral, in IPeripheralStateCB periStateCB);

  /**
   * This method will provide state of the peripheral requested.
   *
   * @param[in]  uint32 valid peripheral values are defined in \link CPeripheralAccessControl \endlink
   * @param[in]  uint8 various state values are defined in \link IPeripheralState \endlink
   *
   *
   * @return
   * Object_OK on success.\n
   * IPeripheralState_ERROR_PERIPHERAL_NOT_FOUND on failure if peripheral is not valid.\n
   */

  method getPeripheralState(in uint32 peripheral, out uint8 state);

  /** @} */
};
