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

include "IGPSession.idl"

/** @cond */
interface IAppController {
/** @endcond */

  /** @cond */
  /**
   * CallBack object UIDs.
   */
  const uint32 CBO_INTERFACE_WAIT = 1; /**< IWait interface */
  /** @endcond */

  /** @cond */
  /**
   * Error codes
   */
  error ERROR_APP_SUSPENDED;           /**< App suspended/terminated, cannot receive commands */
  error ERROR_APP_BLOCKED_ON_LISTENER; /**< App blocked on a listener call */
  error ERROR_APP_UNLOADED;            /**< App has been unloaded */
  error ERROR_APP_IN_USE;              /**< App busy processing another command */
  error ERROR_NOT_SUPPORTED;           /**< App or commonlib doesn't support this feature */
  error ERROR_CBO_UNKNOWN;             /**< Unknown callback object */
  error ERROR_APP_UNLOAD_NOT_ALLOWED;  /**< App cannot be unloaded*/
  /** @endcond */

  /**
   * @addtogroup IAppController
   * @{
   */

  /**
    Opens a session with the trusted application.

    This method is part of the GP interface for the TA.

    The caller/implementer (depending on parameter type) manually marshals the
    content of four input/output buffers.

    @param[in]  cancelCode         Optional code to use for cancellations.
    @param[in]  connectionMethod   What CA identity credentials to use.
    @param[in]  connectionData     Optional connection group identifier.
    @param[in]  paramTypes         Parameter types, 1 byte per parameter.
    @param[in]  exParamTypes       Extended information for parameters, 1 byte per parameter.
    @param[in]  i1                 First input buffer.
    @param[in]  i2                 Second input buffer.
    @param[in]  i3                 Third input buffer.
    @param[in]  i4                 Fourth input buffer.
    @param[out] o1                 First output buffer.
    @param[out] o2                 Second output buffer.
    @param[out] o3                 Third output buffer.
    @param[out] o4                 Fourth output buffer.
    @param[in]  imem1              First optional memory region.
    @param[in]  imem2              Second optional memory region.
    @param[in]  imem3              Third optional memory region.
    @param[in]  imem4              Fourth optional memory region.
    @param[out] memrefOutSz1       Desired output size for memref 1, if larger than size provided.
    @param[out] memrefOutSz2       Desired output size for memref 2, if larger than size provided.
    @param[out] memrefOutSz3       Desired output size for memref 3, if larger than size provided.
    @param[out] memrefOutSz4       Desired output size for memref 4, if larger than size provided.
    @param[out] session            Newly opened session.
    @param[out] retValue           GP return value.
    @param[out] retOrigin          Where the GP return value originated.

    @return  Object_OK if successful.
   */
  method openSession(in uint32 cancelCode,
                     in uint32 connectionMethod,
                     in uint32 connectionData,
                     in uint32 paramTypes,
                     in uint32 exParamTypes,
                     in buffer i1,
                     in buffer i2,
                     in buffer i3,
                     in buffer i4,
                     out buffer o1,
                     out buffer o2,
                     out buffer o3,
                     out buffer o4,
                     in interface imem1,
                     in interface imem2,
                     in interface imem3,
                     in interface imem4,
                     out uint32 memrefOutSz1,
                     out uint32 memrefOutSz2,
                     out uint32 memrefOutSz3,
                     out uint32 memrefOutSz4,
                     out IGPSession session,
                     out uint32 retValue,
                     out uint32 retOrigin);

  /**
    Unloads the trusted application.

    This function fails if the application is currently busy. The caller is
    expected to try again at a later time.

    @return  Object_OK if successful.
   */
  method unload();

  /**
    Gets the object implementing app-provided functionalities.

    @param[out] obj          Returned object.

    @return  Object_OK on success.
   */
  method getAppObject(out interface obj);

  /**
    Installs a CallBack Object provided by the client.

    @param[in] uid           UID of service class to register.
    @param[in] obj           Object implementing the interface.

    @return  Object_OK on success.
   */
  method installCBO(in uint32 uid, in interface obj);

  /** @} */ /* end_addtogroup IAppController */

};