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

/**
   HLOS defined listener that gets passed into the Secure Channel Passthrough
   interface, and handles indications that are received from modem side.
*/
interface ISCListener {

   /**
      Callback function for raw modem data that comes back to this particular
      client

      @param response[in]      Indication data from the modem. These are
                               asynchronous with inData requests utilizing
                               sendRequest().
    */
    method onResponse(in buffer response);

   /**
      User-defined callback handler to receive Secure Channel error code

      @param error[in]     Error code of Secure Channel failure.
    */
    method onError(in int32 error);
};

/**
   Secure Channel Passthrough Client is a mink object that is connected with
   a particular client/service channel in Secure Channel. The
   ISCPassthroughClient object is returned once a license is passed in, and this
   object will be used to communicate with the modem task.
*/
interface ISCPassthroughClient {

   /**
      Send data packet through Secure Channel.

      @param message[in]   Buffer to be sent via secure channel

      @return Object_OK or ISCPassthrough error code
    */
    method sendRequest(in buffer message);

   /**
      Retrieves cached data from Secure Channel Passthrough

      @param handler[in]        Replacement ISCListener handler if needed

      @param responseCode[out]  Potential error code if Secure Channel failure.
                                Value of 0 if message success.

      @param responseData[out]  Data of secure channel message from modem. It is
                                a zero-length buffer if responseCode is not 0.

      @return Object_OK or ISCPassthrough error code
    */
    method retrieveData(in ISCListener handler,
                        out int32 responseCode,
                        out buffer responseData);
};

/**
   Secure Channel Passthrough is a licensed mechanism for talking to secure
   channel clients. This interface is available to HLOS clients as well.
   A license must be installed through official PFM APIs before this pathway
   will be functional. Each task id connection creates a unique pathway that
   will be verified between the connecting user and the installed licenses.
*/
interface ISCPassthrough {

   /** Connection Tasks */
    const uint32 CONNECTION_QDMA = 1;  /** Qualcomm Device Management &
                                           Analytics modem task */

   /** Errors start at 10! */
    error LICENSE_FEATURE_NOT_AVAIL_ERROR;  /** License feature not found in
                                                installed licenses */
    error TZSC_NOT_AVAILABLE_ERROR;         /** Secure Channel error; is not
                                                available or set up */
    error INVALID_ARGUMENT_ERROR;           /** Invalid argument passed in */

    error HEAP_ALLOCATION_ERROR;            /** Unable to allocate on heap */

    error LICENSE_DECODE_FAILED_ERROR;      /** Unable to decode license */

    error MAX_CLIENTS_CONNECTED_ERROR;      /** Maximum number of clients
                                                allowed */
    error CLIENT_NOT_REGISTERED_ERROR;      /** Secure Channel Client not
                                                registered or available */
    error RNG_NOT_FUNCTIONING_ERROR;        /** Unable to generate random
                                                identifier number */

   /**
      Initial Connection Pathway. connect() is called with a task ID and a
      callback handler, and returns an ISCPassthroughClient that will then
      be used for communication to modem.

      @param connectionTask[in]  Connection Task that client intends to talk to.
                                 License correlating to task must be installed
                                 separately using PFM interfaces.
      @param handler[in]         Handler mink object of client defined
                                 ISCListener. Interface used to receive messages
                                 from the modem.
      @param client[out]         ISCPassthroughClient object of mink connection.
                                 Interface used to communicate to the modem.

      @return Object_OK or ISCPassthrough error code
    */
    method connect(in uint32 connectionTask,
                   in ISCListener handler,
                   out ISCPassthroughClient client);

   /**
      Initial Connection Pathway. connectWithLicense() is called with a license,
      task id, and a callback handler, and returns an ISCPassthroughClient that
      will then be used for communication to modem.

      @param license[in]         License passed in for secure channel
                                 verification. Once accepted, this license will
                                 be installed and used as basis for this
                                 connection.
      @param connectionTask[in]  Connection Task that client intends to talk to.
      @param handler[in]         Handler mink object of client defined
                                 ISCListener. Interface used to receive messages
                                 from the modem.
      @param client[out]         ISCPassthroughClient object of mink connection.
                                 Interface used to communicate to the modem.

      @return Object_OK or ISCPassthrough error code
    */
    method connectWithLicense(in buffer license,
                              in uint32 connectionTask,
                              in ISCListener handler,
                              out ISCPassthroughClient client);
};
