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

/**
   Must add these values to Java SDK under "CellularSecurityValues.java" class
   file. These constants are key for passing information back and forth from
   CCS task in modem
**/
interface CellularValues {
    const uint32 FEATUREID_PM_CONTROL = 607; /** Cellular EFS POLICY Management */
    const uint32 FEATUREID_NUM_LEVELS  = 1;   /** Max feature IDs */
};



/**
   User-defined callback object that receives data from modem. These functions
   cannot be blocked! They must return instantly, so any processing should be
   passed into a handler
*/
interface ICellularSDKListener {

    /**
       Success indication that acts as a receipt of any request; the nonce
       should be used as an identifier of which original request

       @param nonce[in]     The return nonce that is associated with the sent
                            nonce
    */
    method onSuccess(in uint32 nonce);

    /**
       Error indication that indicates any error from any asynchronous point
       throughout the secure channel. Secure Channel is asynchronous and can
       work on different threads, so this is used to get any error down the line
       that may not be indicated on the original thread; the nonce should be
       used as an identifier of which original request.

       @param[in]  nonce   The return nonce that is associated with the sent
                           nonce
       @param[in]  error   Asynchronous error code of secure channel failure
    */
    method onError(in uint32 nonce, in int32 error);
};


/**
   Connection Security is service-based solution for wireless security. This
   particular service in Trustzone allows for secure communication between
   the HLOS client and the modem task, which controls cellular security measures
   and receives indications and reports. Clients can use this pathway in order
   to have an encrypted, secure channel to talk with modem, verifying with
   integrity that the messages have not been modified or read by anything else.
*/
interface IConnectionSecurity {

    /**
       Errors start at 10! Various errors communicating failure points in
       Connection Security
    */

    /** Error attempting to encode */
    error ENCODER_ERROR;

    /* No license features available in certificate at all */
    error LICENSE_FEATURE_NOT_AVAILABLE_ERROR;

    /* Secure Channel is not available for modem communication */
    error TZSC_NOT_AVAILABLE_ERROR;

    /* Invalid license feature length passed in */
    error INVALID_FEATURE_LENGTH;

    /* Unable to open PFM verification */
    error PFM_LICENSE_OPEN_ERROR;

    /* TZ is busy processing other request */
    error TZ_BUSY_ERROR;
   /**
      Initial Connection Pathway. connect() must be called before any other
      method can be called, otherwise other methods will throw an error.

      @param nonce[in]          Nonce for connect() packet
      @param licenseCert[in]    License passed in for feature verification
      @param handler[in]        Callback object defined by HLOS service to
                                receive packets asynchronously from Trustzone
      @param featureList[out]   Enabled FeatureID list in bitmask form:
                                Example: FeatureList[0] = 607
                                         FeatureList[1] = 608

      @return Object_OK (0) or IConnectionSecurity specific error code
    */
    method connect(in uint32 nonce, in buffer licenseCert,
                   in ICellularSDKListener handler, out uint32[] featureList);


    /**
      Sets the Modem Celluar Connection Security EFS Int value
      @param nonce[in]        Nonce for ssgccsSetPolicyMgmtInt() packet
      @param subopcode[in]    Modem subopcode data
      @param subscriber[in]   Modem subscriber ID
      @param val[in]          Modem EFS configuration value

      @return Object_OK (0) or IConnectionSecurity specific error code

    */
    method ssgccsSetPolicyMgmtInt(in uint32 nonce,
                                  in uint16 subopcode,
                                  in uint8 subscriber,
                                  in int32 val);
    /**
      Sets the Modem Celluar Connection Security EFS string configuration
      @param nonce[in]        Nonce for ssgccsSetPolicyMgmtStr() packet
      @param subopcode[in]    Modem subopcode data
      @param subscriber[in]   Modem subscriber ID
      @param val[in]          Modem EFS configuration value

      @return Object_OK (0) or IConnectionSecurity specific error code

    */
    method ssgccsSetPolicyMgmtStr(in uint32 nonce,
                                  in uint16 subopcode,
                                  in uint8 subscriber,
                                  in uint8[] val);


   /**
     Generates policy management Int to save in Connection Security
     cache

     @param nonce[in]      Nonce for generatePolicyMgmtInt() packet
     @param subopcode[in]  subopcode
     @param subscriber[in]  asid

     @return Object_OK (0) or IConnectionSecurity specific error code
   */
    method generatePolicyMgmtInt(in uint32 nonce, in uint16 subopcode, in uint8 subscriber);

    /**
      Generates policy management str to save in Connection Security
      cache

      @param nonce[in]      Nonce for generatePolicyMgmtStr() packet
      @param subopcode[in]  subopcode
      @param subscriber[in]  asid

      @return Object_OK (0) or IConnectionSecurity specific error code
    */
    method generatePolicyMgmtStr(in uint32 nonce, in uint16 subopcode, in uint8 subscriber);


   /**
      Gets the Modem Celluar Connection Security EFS Int value
      @param subopcode[out]    subopcode
      @param subscriber[out]   ASID
      @param val[out]          Modem EFS configuration value
      @param retcode[out]      Modem EFS error code

      @return Object_OK (0) or IConnectionSecurity specific error code

   */
   method ssgccsGetPolicyMgmtInt(out uint16 subopcode, out uint8 subscriber, out int32 val, out int32 retcode);


   /**
      Gets the Modem Celluar Connection Security EFS Str value
      @param subopcode[out]    subopcode
      @param subscriber[out]   ASID
      @param val[out]          Modem EFS configuration value
      @param retcode[out]      Modem EFS error code

    */
   method ssgccsGetPolicyMgmtStr(out uint16 subopcode, out uint8 subscriber, out uint8[] val, out int32 retcode);

};
