/**
 * \ingroup loc
 *
 * \file    qaGobiApiLoc.h
 *
 * \brief   Location API function prototypes
 */

/*
 * Copyright: © 2011-2015 Sierra Wireless, Inc. all rights reserved
 */
#ifndef __GOBI_API_LOC_H__
#define __GOBI_API_LOC_H__

#ifdef __cplusplus
extern "C" {
#endif

/**
 *  This structure contains the Parameter for RegisterEvents
 *
 *  \param  pEventRegMask
 *          - Specifies the events that the control point is interested
 *          in receiving.
 *          -Values
 *             - 0x00000001 - to receive position report event
 *                            indications
 *             - 0x00000002 - to receive satellite report event
 *                            indications
 *             - 0x00000004 - to receive NMEA reports for position
 *                            and satellites in view
 *             - 0x00000008 - to receive NI Notify/Verify request
 *                            event indications
 *             - 0x00000010 - to receive time injection request
 *                            event indications.
 *             - 0x00000020 - to receive predicted orbits request
 *                            event indications.
 *             - 0x00000040 - to receive position injection request
 *                            event indications.
 *             - 0x00000080 - to receive fix session status report
 *                            event indications.
 *             - 0x00000200 - to receive Wi-Fi position request
 *                            event indications.
 *             - 0x00000400 - to receive notifications from the
 *                            location engine indicating its readiness
 *                            to accept data from the sensors
 *             - 0x00000800 - to receive time sync requests from
 *                            the GPS engine. Time sync enables the
 *                            GPS engine to synchronize its clock
 *                            with the sensor processor’s clock.
 *             - 0x00001000 - to receive Stationary Position Indicator (SPI)
 *                            streaming report indications.
 *             - 0x00002000 - to receive location server requests.
 *                            These requests are generated when
 *                            the service wishes to establish a
 *                            connection with a location server.
 *             - 0x00004000 - to receive notifications related
 *                            to network-initiated Geofences. These
 *                            events notify the client when a network-initiated
 *                            Geofence is added, deleted, or edited.
 *             - 0x00008000 - to receive Geofence alerts. These alerts
 *                            are generated to inform the client of
 *                            the changes that may affect a Geofence,
 *                            e.g., if GPS is turned off or if the
 *                            network is unavailable.
 *             - 0x00010000 - to receive notifications when a Geofence
 *                            is breached. These events are generated
 *                            when a UE enters or leaves the perimeter
 *                            of a Geofence. This breach report is for
 *                            a single Geofence.
 *             - 0x00020000 - to register for pedometer control requests
 *                            from the location engine. The location
 *                            engine sends this event to control the
 *                            injection of pedometer reports.
 *             - 0x00040000 - to register for motion data control requests
 *                            from the location engine. The location
 *                            engine sends this event to control the
 *                            injection of motion data.
 *             - 0x00080000 - to receive notification when a batch is full.
 *                            The location engine sends this event to
 *                            notify of Batch Full for ongoing batching
 *                            session.
 *             - 0x00100000 - to receive position report indications
 *                            along with an ongoing batching session.
 *                            The location engine sends this event to
 *                            notify the batched position report while
 *                            a batching session is ongoing.
 *             - 0x00200000 - to receive Wi-Fi Access Point (AP) data
 *                            inject request event indications.
 *             - 0x00400000 - to receive notifications when a Geofence
 *                            is breached. These events are generated
 *                            when a UE enters or leaves the perimeter
 *                            of a Geofence. This breach notification
 *                            is for multiple Geofences. Breaches from
 *                            multiple Geofences are all batched and
 *                            sent in the same notification.
 *             - 0x00800000 - to receive notifications from the location
 *                            engine indicating its readiness to accept
 *                            vehicle data (vehicle accelerometer,
 *                            vehicle angular rate, vehicle odometry, etc.).
 *             - 0x01000000 - to receive system clock and satellite
 *                            measurement report events (system clock,
 *                            SV time, Doppler, etc.).
 *             - 0x02000000 - to receive satellite position reports
 *                            as polynomials.
 *
 */

typedef struct
{
	ULONGLONG eventRegister;
} LOCEventRegisterReqResp;

/**
 *  This structure contains the Parameter External Power Source State.
 *
 *  \param  pLOCEventRegisterReqResp
 *          - Specifies the Power state; injected by the control
 *            point.
 *          - Values
 *             - 0 - Device is not connected to an external power
 *                   source
 *             - 1 - Device is connected to an external power source
 *             - 2 - Unknown external power state
 */

typedef struct
{
	ULONG extPowerState;
} LOCExtPowerStateReqResp;

/**
 * This structure contains the Application Information
 *
 * \param appProviderLength
 *        - Length of the Application Provider
 *
 * \param pAppProvider
 *        - Application Provider
 *        - Depends upon the Length of application Provider
 *
 * \param appNameLength
 *        - Length of Application Name
 *
 * \param pAppName
 *        - Application Name
 *        - Depends upon the Length of application Name
 *
 * \param appVersionValid
 *        - Specifies whether the application version string contains a
 *        valid value
 *
 *        - 0x00 (FALSE) – Application version string is invalid
 *        - 0x01 (TRUE) – Application version string is valid
 *
 * \param appVersionLength
 *        - Length of Application Version
 *
 * \param pAppVersion
 *        - Application Version
 *        - Depends upon the Length of application Version
 *
 */

struct LocApplicationInfo
{
    BYTE appProviderLength;
    CHAR *pAppProvider;
    BYTE appNameLength;
    CHAR *pAppName;
    BYTE appVersionValid;
    CHAR appVersionLength;
    CHAR *pAppVersion;
};

/**
 * This structure contains the LOC Start Request
 *
 * \param SessionId
 *        - ID of the session as identified by the control point.
 *        - Range: 0 to 255
 *
 * \param pRecurrenceType
 *        - Specifies the type of session in which the control point
 *        is interested.
 *        - Defaults to SINGLE.
 *        -Values
 *           - 1 - Request periodic position fixes
 *           - 2 - Request a single position fix
 *
 * \param pHorizontalAccuracyLvl
 *        - Specifies the horizontal accuracy level required by the
 *        control point.
 *        - Defaults to LOW
 *        - Values
 *           - 1 - Low accuracy
 *           - 2 - Medium accuracy
 *           - 3 - High accuracy
 *
 * \param pIntermediateReportState
 *        - Specifies if the control point is interested
 *        in receiving intermediate reports.
 *        - ON by default.
 *        - Values
 *          - 1 - Intermediate reports are turned on
 *          - 2 - Intermediate reports are turned off
 *
 * \param appVersionValid
 *        - Specifies whether the application version string contains a
 *        valid value
 *
 *        - 0x00 (FALSE) – Application version string is invalid
 *        - 0x01 (TRUE) – Application version string is valid
 *
 * \param LocApplicationInfo
 *        - LOC Application Parameters
 *        - See \ref LocApplicationInfo for more information
 *
 * \param pConfigAltitudeAssumed
 *        - Configuration for Altitude Assumed Info in GNSS SV
 *        Info Event
 *        - Defaults to ENABLED.
 *        - Values
 *          - 1 - Enable Altitude Assumed information in GNSS SV
 *          Info Event
 *          - 2 - Disable Altitude Assumed information in GNSS SV
 *          Info Event
 *
 */

typedef struct
{
     BYTE    SessionId;
     ULONG   *pRecurrenceType;
     ULONG   *pHorizontalAccuracyLvl;
     ULONG   *pIntermediateReportState;
     ULONG   *pMinIntervalTime;
     struct   LocApplicationInfo *pApplicationInfo;
     ULONG   *pConfigAltitudeAssumed;
} LOCStartReqResp;

/**
 * This structure contains the LOC Stop Request
 *
 * \param sessionId
 *        - ID of the session as identified by the control point.
 *        - Range: 0 to 255
 */
typedef struct
{
     BYTE     sessionId;
}LOCStopReqResp;



/**
 * This structure contains the Delete SV Info
 *
 * \param id
 *        - SV ID of the satellite whose data is to be
 *          deleted
 *        - Range:
 *           - For GPS: 1 to 32
 *           - For SBAS: 33 to 64
 *           - For GLONASS: 65 to 96
 *
 * \param system
 *        - Indicates to which constellation this SV belongs
 *        - Valid values:
 *           - eQMI_LOC_SV_SYSTEM_GPS (1) - GPS satellite
 *           - eQMI_LOC_SV_SYSTEM_GALILEO (2) - GALILEO satellite
 *           - eQMI_LOC_SV_SYSTEM_SBAS (3) - SBAS satellite
 *           - eQMI_LOC_SV_SYSTEM_COMPASS (4) - COMPASS satellite
 *           - eQMI_LOC_SV_SYSTEM_GLONASS (5) - GLONASS satellite
 *           - eQMI_LOC_SV_SYSTEM_BDS (6) - BDS satellite
 *
 * \param mask
 *        - Indicates if the ephemeris or almanac for a satellite
 *          is to be deleted
 *        - Valid values:
 *           - 0x01 - DELETE_EPHEMERIS
 *           - 0x02 - DELETE_ALMANAC
 *
 */
typedef struct
{
    WORD    id;
    ULONG   system;
    BYTE    mask;
}SV;


/**
 * This structure contains the elements of Delete SV Info
 *
 * \param len
 *        - Number of sets of the following elements in struct SV:
 *           - gnssSvId
 *           - system
 *           - deleteSvInfoMask
 *
 * \param pSV
 *        - Pointer to struct SV. See \ref SV for more information
 *
 */

typedef struct
{
    BYTE    len;
    SV      *pSV;
}SVInfo;

/**
 * This structure contains the GNSS data
 *
 * \param mask
 *        - Mask for the GNSS data that is to be deleted
 *        - Valid values:
 *           - QMI_LOC_MASK_DELETE_GPS_SVDIR (0x00000001) - Mask to
 *             delete GPS SVDIR
 *           - QMI_LOC_MASK_DELETE_GPS_SVSTEER (0x00000002) - Mask to
 *             delete GPS SVSTEER 
 *           - QMI_LOC_MASK_DELETE_GPS_TIME (0x00000004) - Mask to
 *             delete GPS time
 *           - QMI_LOC_MASK_DELETE_GPS_ALM_CORR (0x00000008) - Mask to
 *             delete almanac correlation
 *           - QMI_LOC_MASK_DELETE_GLO_SVDIR (0x00000010) - Mask to
 *             delete GLONASS SVDIR
 *           - QMI_LOC_MASK_DELETE_GLO_SVSTEER (0x00000020) - Mask to
 *             delete GLONASS SVSTEER
 *           - QMI_LOC_MASK_DELETE_GLO_TIME (0x00000040) - Mask to
 *             delete GLONASS time
 *           - QMI_LOC_MASK_DELETE_GLO_ALM_CORR (0x00000080) - Mask to
 *             delete GLONASS almanac correlation
 *           - QMI_LOC_MASK_DELETE_SBAS_SVDIR (0x00000100) - Mask to
 *             delete SBAS SVDIR
 *           - QMI_LOC_MASK_DELETE_SBAS_SVSTEER (0x00000200) - Mask to
 *             delete SBAS SVSTEER
 *           - QMI_LOC_MASK_DELETE_POSITION (0x00000400) - Mask to
 *             delete position estimate
 *           - QMI_LOC_MASK_DELETE_TIME (0x00000800) - Mask to
 *             delete time estimate
 *           - QMI_LOC_MASK_DELETE_IONO (0x00001000) - Mask to
 *             delete IONO
 *           - QMI_LOC_MASK_DELETE_UTC (0x00002000) - Mask to
 *             delete UTC estimate
 *           - QMI_LOC_MASK_DELETE_HEALTH (0x00004000) - Mask to
 *             delete SV health record
 *           - QMI_LOC_MASK_DELETE_SADATA (0x00008000) - Mask to
 *             delete SADATA
 *           - QMI_LOC_MASK_DELETE_RTI (0x00010000) - Mask to
 *             delete RTI
 *           - QMI_LOC_MASK_DELETE_SV_NO_EXIST (0x00020000) - Mask to
 *             delete SV_NO_EXIST
 *           - QMI_LOC_MASK_DELETE_FREQ_BIAS_EST (0x00040000) - Mask to
 *             delete frequency bias estimate
 *           - QMI_LOC_MASK_DELETE_BDS_SVDIR (0x00080000) - Mask to
 *             delete BDS SVDIR
 *           - QMI_LOC_MASK_DELETE_BDS_SVSTEER (0x00100000) - Mask to
 *             delete BDS SVSTEER
 *           - QMI_LOC_MASK_DELETE_BDS_TIME (0x00200000) - Mask to
 *             delete BDS time
 *           - QMI_LOC_MASK_DELETE_BDS_ALM_CORR (0x00400000) - Mask to
 *             delete BDS almanac correlation
 *           - QMI_LOC_MASK_DELETE_GNSS_SV_BLACKLIST_GPS (0x00800000) -
 *             Mask to delete GNSS SV blacklist GPS
 *           - QMI_LOC_MASK_DELETE_GNSS_SV_BLACKLIST_GLO (0x01000000) -
 *             Mask to delete GNSS SV blacklist GLO
 *           - QMI_LOC_MASK_DELETE_GNSS_SV_BLACKLIST_BDS (0x02000000) -
 *             Mask to delete GNSS SV blacklist BDS
 *
 */
typedef struct
{
    ULONGLONG   mask;
}GnssData;

/**
 * This structure contains the cell database
 *
 * \param mask
 *        - Mask for the cell database assistance data that is to be deleted
 *        - Valid values:
 *           - 0x00000001 - DELETE_CELLDB_POS
 *           - 0x00000002 - DELETE_CELLDB_LATEST_GPS_POS
 *           - 0x00000004 - DELETE_CELLDB_OTA_POS
 *           - 0x00000008 - DELETE_CELLDB_EXT_REF_POS
 *           - 0x00000010 - DELETE_CELLDB_TIMETAG
 *           - 0x00000020 - DELETE_CELLDB_CELLID
 *           - 0x00000040 - DELETE_CELLDB_CACHED_CELLID
 *           - 0x00000080 - DELETE_CELLDB_LAST_SRV_CELL
 *           - 0x00000100 - DELETE_CELLDB_CUR_SRV_CELL
 *           - 0x00000200 - DELETE_CELLDB_NEIGHBOR_INFO
 *
 */
typedef struct
{
    ULONG   mask;
}CellDb;

/**
 * This structure contains the clock Info
 *
 * \param mask
 *        - Mask for the clock information assistance data that is to be deleted
 *        - Valid bitmasks:
 *           - QMI_LOC_MASK_DELETE_CLOCK_INFO_TIME_EST (0x00000001) - Mask to
 *             delete time estimate from clock information
 *           - QMI_LOC_MASK_DELETE_CLOCK_INFO_FREQ_EST (0x00000002) - Mask to
 *             delete frequency estimate from clock information
 *           - QMI_LOC_MASK_DELETE_CLOCK_INFO_WEEK_NUMBER (0x00000004) - Mask to
 *             delete week number from clock information
 *           - QMI_LOC_MASK_DELETE_CLOCK_INFO_RTC_TIME (0x00000008) - Mask to
 *             delete RTC time from clock information
 *           - QMI_LOC_MASK_DELETE_CLOCK_INFO_TIME_TRANSFER (0x00000010) - Mask to
 *             delete time transfer from clock information
 *           - QMI_LOC_MASK_DELETE_CLOCK_INFO_GPSTIME_EST (0x00000020) - Mask to
 *             delete GPS time estimate from clock information
 *           - QMI_LOC_MASK_DELETE_CLOCK_INFO_GLOTIME_EST (0x00000040) - Mask to
 *             delete GLONASS time estimate from clock information
 *           - QMI_LOC_MASK_DELETE_CLOCK_INFO_GLODAY_NUMBER (0x00000080) - Mask to
 *             delete GLONASS day number from clock information
 *           - QMI_LOC_MASK_DELETE_CLOCK_INFO_GLO4YEAR_NUMBER (0x00000100) - Mask to
 *             delete GLONASS four year number from clock information
 *           - QMI_LOC_MASK_DELETE_CLOCK_INFO_GLO_RF_GRP_DELAY (0x00000200) - Mask to
 *             delete GLONASS RF GRP delay from clock information
 *           - QMI_LOC_MASK_DELETE_CLOCK_INFO_DISABLE_TT (0x00000400) - Mask to
 *             delete disable TT from clock information
 *           - QMI_LOC_MASK_DELETE_CLOCK_INFO_GG_LEAPSEC (0x00000800) - Mask to
 *             delete a BDS time estimate from the clock information
 *           - QMI_LOC_MASK_DELETE_CLOCK_INFO_GG_GGTB (0x00001000) - Mask to
 *             delete a BDS time estimate from the clock information
 *           - QMI_LOC_MASK_DELETE_CLOCK_INFO_BDSTIME_EST (0x00002000) - Mask to
 *             delete a BDS time estimate from the clock information
 *           - QMI_LOC_MASK_DELETE_CLOCK_INFO_GB_GBTB (0x00004000) - Mask to delete
 *             Glonass-to-BDS time bias-related information from the clock information
 *           - QMI_LOC_MASK_DELETE_CLOCK_INFO_BG_BGTB (0x00008000) - Mask to delete
 *             BDS-to-GLONASS time bias-related information from the clock information
 *           - QMI_LOC_MASK_DELETE_CLOCK_INFO_BDSWEEK_NUMBER (0x00010000) - Mask to
 *             delete the BDS week number from the clock information
 *           - QMI_LOC_MASK_DELETE_CLOCK_INFO_BDS_RF_GRP_DELAY (0x00020000) - Mask to
 *             delete the BDS RF GRP delay from the clock information
 *
 */

typedef struct
{
    ULONG   mask;
}ClkInfo;

/**
 * This structure contains the BDS SV Info
 *
 * \param id
 *        - SV ID of the satellite whose data is to be deleted.
 *           - Range for BDS: 201 to 237
 *
 * \param mask
 *        - Indicates if the ephemeris or almanac for a satellite is to be deleted
 *        - Valid values:
 *           - QMI_LOC_MASK_DELETE_EPHEMERIS (0x01) - Delete ephemeris for the satellite
 *           - QMI_LOC_MASK_DELETE_ALMANAC (0x02) - Delete almanac for the satellite
 *
*/
typedef struct
{
    WORD    id;
    BYTE    mask;
}BdsSV;

/**
 * This structure contains the number of sets of the BDS SVN Info
 *
 * \param len
 *        - Number of sets of the following elements:
 *           - gnssSvId
 *           - deleteSvInfoMask
 *
 * \param pSV
 *        - Pointer to struct BdsSV. See \ref BdsSV for more information
 *
*/
typedef struct
{
    BYTE    len;
    BdsSV   *pSV;
}BdsSVInfo;



/**
 * This structure contains LOC delete assist data request
 *
 * \param pSVInfo
 *        - Pointer to struct SVInfo. See \ref SVInfo for more information
 *
 * \param pGnssData
 *        - Pointer to struct GnssData. See \ref GnssData for more information
 *
 * \param pCellDb
 *        - Pointer to struct CellDb. See \ref CellDb for more information
 *
 * \param pClkInfo
 *        - Pointer to struct ClkInfo. See \ref ClkInfo for more information
 *
 * \param pBdsSVInfo
 *        - Pointer to struct BdsSVInfo. See \ref BdsSVInfo for more information
 *
 */

typedef struct
{
    SVInfo *pSVInfo;
    GnssData *pGnssData;
    CellDb *pCellDb;
    ClkInfo *pClkInfo;
    BdsSVInfo *pBdsSVInfo;
}LocDelAssDataReq;

/**
 *  Used by the control point to register for events from the location subsystem.
 *
 *  \param  pLOCEventRegisterReqResp[IN]
 *          - See \ref LOCEventRegisterReqResp for more information
 *
 *  \return eQCWWAN_ERR_NONE on success, eQCWWAN_xxx error value otherwise
 *
 *  \sa     See qmerrno.h for eQCWWAN_xxx error values
 *
 *  \note   Timeout: 5 seconds
 *
 */

ULONG SLQSLOCEventRegister (
        LOCEventRegisterReqResp *pLOCEventRegisterReqResp );
/**
 *  Used by the control point to set the current external power configuration.
 *
 *  \param  pLOCExtPowerStateReqResp[IN]
 *          - See \ref LOCExtPowerStateReqResp for more information
 *
 *  \return eQCWWAN_ERR_NONE on success, eQCWWAN_xxx error value otherwise
 *
 *  \sa     See qmerrno.h for eQCWWAN_xxx error values
 *
 *  \note   Timeout: 5 seconds
 *
 */

ULONG SLQSLOCSetExtPowerState(
		LOCExtPowerStateReqResp *pLOCExtPowerStateReqResp);

/**
 *  Used by the control point to initiate a GPS session.
 *
 *  \param  pLOCStartReqResp[IN]
 *          - See \ref LOCStartReqResp for more information
 *
 *  \return eQCWWAN_ERR_NONE on success, eQCWWAN_xxx error value otherwise
 *
 *  \sa     See qmerrno.h for eQCWWAN_xxx error values
 *
 *  \note   Timeout: 5 seconds
 *
 */

ULONG SLQSLOCStart(LOCStartReqResp *pLOCStartReqResp);
/**
 *  Used by the control point to stop a GPS session.
 *
 *  \param  pLOCStopReqResp[IN]
 *          - See \ref LOCStopReqResp for more information
 *
 *  \return eQCWWAN_ERR_NONE on success, eQCWWAN_xxx error value otherwise
 *
 *  \sa     See qmerrno.h for eQCWWAN_xxx error values
 *
 *  \note   Timeout: 5 seconds
 *
 */

ULONG SLQSLOCStop(LOCStopReqResp *pLOCStopReqResp);

/**
 *  Used by the control point to tells the engine to use the specified operation mode
 *  while making the position fixes
 *
 *  \param  mode[IN]
 *          - Valid values:
 *             - eQMI_LOC_OPER_MODE_DEFAULT (1) - Use the default engine mode
 *             - eQMI_LOC_OPER_MODE_MSB (2) - Use the MS-based mode
 *             - eQMI_LOC_OPER_MODE_MSA (3) - Use the MS-assisted mode
 *             - eQMI_LOC_OPER_MODE_STANDALONE (4) - Use Standalone mode
 *             - eQMI_LOC_OPER_MODE_CELL_ID (5) - Use cell ID; this mode is
 *               only valid for GSM/UMTS networks
 *             - eQMI_LOC_OPER_MODE_WWAN (6) - Use WWAN measurements to calculate
 *               the position; if this mode is set, AFLT will be used for 1X
 *               networks and OTDOA will be used for LTE networks
 *
 *  \return eQCWWAN_ERR_NONE on success, eQCWWAN_xxx error value otherwise
 *
 *  \sa     See qmerrno.h for eQCWWAN_xxx error values
 *
 *  \note   Timeout: 5 seconds
 *
 */
ULONG SLQSLOCSetOpMode(ULONG mode);

/**
 *  Used by the control point to delete the location engine assistance data
 *
 *  \param  request[IN]
 *          - Input a NULL pointer to delete all assistance data. Otherwise, specify optional fields
 *            to be deleted. See \ref LocDelAssDataReq for more information
 *
 *  \return eQCWWAN_ERR_NONE on success, eQCWWAN_xxx error value otherwise
 *
 *  \sa     See qmerrno.h for eQCWWAN_xxx error values
 *
 *  \note   Timeout: 5 seconds
 *
 */

ULONG SLQSLOCDelAssData(LocDelAssDataReq request);

#ifdef __cplusplus
} /* extern "C" { */
#endif

#endif /* __GOBI_API_LOC_H__ */
