/*
 * Copyright (C) 2016 The Android Open Source Project
 *
 * 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.
 */

package android.hardware.gnss@1.0;

/**
 * Interface for passing GNSS configuration info from platform to HAL.
 */
interface IGnssConfiguration {
    /**
     * Enum which holds the bit masks for SUPL_MODE configuration parameter.
     */
    enum SuplMode : uint8_t {
        /** Mobile Station Based */
        MSB = 0x01,

        /** Mobile Station Assisted */
        MSA = 0x02
    };

    /**
     * Enum which holds the bit masks for GPS_LOCK configuration parameter.
     */
    enum GpsLock : uint8_t {
        /** Lock Mobile Originated GPS functionalitues. */
        MO    =  0x01,

        /** Lock Network initiated GPS functionalities. */
        NI    =  0x02
    };

    /**
     * Enum that hold the bit masks for various LTE Positioning Profile settings (LPP_PROFILE
     * configuration parameter). If none of the bits in the enum are set, the default setting is
     * Radio Resource Location Protocol(RRLP).
     */
    enum LppProfile : uint8_t {
        /** Enable LTE Positioning Protocol user plane */
        USER_PLANE          = 0x01,

        /** Enable LTE Positioning Protocol Control plane */
        CONTROL_PLANE       = 0x02
    };

    /**
     * Enum which holds the bit masks for A_GLONASS_POS_PROTOCOL_SELECT
     * configuration parameter.
     */
    enum GlonassPosProtocol : uint8_t {
        /** Radio Resource Control(RRC) control-plane. */
        RRC_CPLANE                  = 0x01,

        /** Radio Resource Location user-plane. */
        RRLP_CPLANE                 = 0x02,

        /** LTE Positioning Protocol User plane */
        LPP_UPLANE                  = 0x04
    };

    /**
     * IMPORTANT: GNSS HAL must expect the below methods to be called multiple
     * times. They can be called even when GnssLocationProvider is already
     * constructed and enabled. GNSS HAL must maintain the existing requests
     * for various callbacks regardless the change in configuration data.
     */

     /**
      * This method enables or disables NI emergency SUPL restrictions.
      *
      * @param enabled True if the device must only accept NI Emergency SUPL requests when the
      *                     device is truly in emergency mode (e.g. the user has dialed 911, 112,
      *                     etc...)
      *                False if the device must accept NI Emergency SUPL any time they are
      *                      received
      *
      * @return success True if operation was successful.
      */
     setSuplEs(bool enabled) generates (bool success);

     /**
      * This method sets the SUPL version requested by Carrier. The GNSS HAL
      * must use this version of the SUPL protocol if supported.
      *
      * @param version SUPL version requested by carrier. This is a bit mask
      * with bits 0:7 representing a service indicator field, bits 8:15
      * representing the minor version and bits 16:23 representing the
      * major version.
      *
      * @return success True if operation was successful.
      */
     setSuplVersion(uint32_t version) generates (bool success);

     /**
      * This method sets the SUPL mode.
      *
      * @param mode Bit mask that specifies the SUPL mode which is set with the SuplMode enum.
      *
      * @return success True if operation was successful.
      */
     setSuplMode(bitfield<SuplMode> mode) generates (bool success);

     /**
      * This setting configures how GPS functionalities should be locked when
      * user turns off GPS On setting.
      *
      * @param lock Bitmask that specifies the GPS functionalities to be be
      * locked as per the GpsLock enum.
      *
      * @return success True if operation was successful.
      */
     setGpsLock(bitfield<GpsLock> lock) generates (bool success);

     /**
      * This method sets the LTE Positioning Profile configuration.
      *
      * @param lppProfile Bitmask that specifies the LTE Positioning Profile
      * configuration to be set as per the LppProfile enum.
      *
      * @return success True if operation was successful.
      */
     setLppProfile(bitfield<LppProfile> lppProfile) generates (bool success);

     /**
      * This method selects positioning protocol on A-Glonass system.
      *
      * @param protocol Bitmask that specifies the positioning protocol to be
      * set as per GlonassPosProtocol enum.
      *
      * @return success True if operation was successful.
      */
     setGlonassPositioningProtocol(bitfield<GlonassPosProtocol> protocol) generates (bool success);

     /**
      * This method configures which PDN to use.
      *
      * @param enable Use emergency PDN if true and regular PDN if false.
      * @return success True if operation was successful.
      */
     setEmergencySuplPdn(bool enable) generates (bool success);
};