#ifndef AEEPOSDET_H
#define AEEPOSDET_H /* #ifndef AEEPOSDET_H */
/*============================================================================

FILE:  AEEPosDet.h

SERVICES:
        Posision determination APIs

GENERAL DESCRIPTION:
        IPosDet Interface exports the serving basestation information and gpsOne
        based position determination services.

REVISION HISTORY:

============================================================================

               Copyright © 1999-2002 QUALCOMM Incorporated
                       All Rights Reserved.
                   QUALCOMM Proprietary/GTDR

============================================================================*/

#include "AEE.h"
#include "AEENet.h"

/* Sector Based position determination info */
typedef struct AEESectorInfo
{
   uint16 wSysID;             /* System Identification */
   uint16 wNetID;             /* Network Identification */
   uint16 wBaseID;            /* Base Station Identification */
   uint16 wBaseClass;         /* Base Station Class */
   uint16 wBestPN;            /* Best Pilot */
   uint16 wPacketZoneID;      /* Packet Data Service Zone Identifier */
   uint16 wMobileCountryCode; /* Mobile country code */
   int32 dwBaseLatitude;      /* Base Station Latitude */
   int32 dwBaseLongitude;     /* Base Station Longitude */
} AEESectorInfo;
typedef  uint16      AEEGPSMode;

#define  AEEGPS_MODE_ONE_SHOT             0x0001
#define  AEEGPS_MODE_DLOAD_FIRST          0x0002
#define  AEEGPS_MODE_TRACK_LOCAL          0x0004
#define  AEEGPS_MODE_TRACK_NETWORK        0x0008
#define  AEEGPS_MODE_TRACK_OPTIMAL        0x0009
#define  AEEGPS_MODE_TRACK_STANDALONE     0x000A
#define  AEEGPS_MODE_DEFAULT              AEEGPS_MODE_ONE_SHOT

typedef uint8        AEEGPSOpt;

#define  AEEGPS_OPT_NONE         0x00
#define  AEEGPS_OPT_SPEED        0x01
#define  AEEGPS_OPT_ACCURACY     0x02
#define  AEEGPS_OPT_PAYLOAD      0x03
#define  AEEGPS_OPT_DEFAULT      AEEGPS_OPT_NONE

typedef uint32        AEEGPSSvrType;

#define  AEEGPS_SERVER_DEFAULT   0
#define  AEEGPS_SERVER_IP        0x00000001
#define  AEEGPS_SERVER_DBURST    0x00000002

typedef struct _AEEGPSIPServer {
   INAddr      addr;
   INPort      port;
   uint16      reserved;
} AEEGPSIPServer;

typedef struct _AEEGPSServer{
   AEEGPSSvrType  svrType;
   union {
      AEEGPSIPServer ipsvr;
   } svr;
} AEEGPSServer;

typedef uint8     AEEGPSQos;

typedef struct _AEEGPSConfig {
   AEEGPSMode        mode;      //Operation type requested
   uint16            nFixes;    //Estimated number of fixes
   uint16            nInterval; //Estimated interval between fixes (seconds)
   AEEGPSOpt         optim;     //Optimization (speed/accuracy)
   AEEGPSQos         qos;       //Quality of Service
   AEEGPSServer      server;    //Server type
} AEEGPSConfig;

typedef  uint8    AEEGPSReq;

#define  AEEGPS_GETINFO_NONE       0x00      /* Acceptable with AEEGPS_MODE_DLOAD_FIRST */
#define  AEEGPS_GETINFO_LOCATION   0x01
#define  AEEGPS_GETINFO_VELOCITY   0x02
#define  AEEGPS_GETINFO_ALTITUDE   0x04

typedef  uint8    AEEGPSAccuracy;

#define  AEEGPS_ACCURACY_LEVEL1    1
#define  AEEGPS_ACCURACY_LEVEL2    2
#define  AEEGPS_ACCURACY_LEVEL3    3
#define  AEEGPS_ACCURACY_LEVEL4    4
#define  AEEGPS_ACCURACY_LEVEL5    5
#define  AEEGPS_ACCURACY_LEVEL6    6
#define  AEEGPS_ACCURACY_LOWEST    AEEGPS_ACCURACY_LEVEL1
#define  AEEGPS_ACCURACY_HIGHEST   AEEGPS_ACCURACY_LEVEL6


#define  AEEGPS_VALID_LAT     0x0001
#define  AEEGPS_VALID_LON     0x0002
#define  AEEGPS_VALID_ALT     0x0004
#define  AEEGPS_VALID_HEAD    0x0008
#define  AEEGPS_VALID_HVEL    0x0010
#define  AEEGPS_VALID_VVEL    0x0020
#define  AEEGPS_VALID_HUNC    0x0040
#define  AEEGPS_VALID_AUNC    0x0080
#define  AEEGPS_VALID_PUNC    0x0100
#define  AEEGPS_VALID_VUNC    0x0200

#define  AEEGPS_VALID_MASK    ( (AEEGPS_VALID_LAT) | (AEEGPS_VALID_LON) \
                              | (AEEGPS_VALID_ALT) | (AEEGPS_VALID_HEAD) \
                              | (AEEGPS_VALID_HVEL) | (AEEGPS_VALID_VVEL) \
                              | (AEEGPS_VALID_HUNC) | (AEEGPS_VALID_AUNC) \
                              | (AEEGPS_VALID_PUNC) | (AEEGPS_VALID_VUNC) )

#define  AEEGPS_ERR_NO_ERR              0
#define  AEEGPS_ERR_BASE                0x00100000
#define  AEEGPS_ERR_GENERAL_FAILURE    (AEEGPS_ERR_BASE + 1)
#define  AEEGPS_ERR_TIMEOUT            (AEEGPS_ERR_BASE + 2)
#define  AEEGPS_ERR_ACCURACY_UNAVAIL   (AEEGPS_ERR_BASE + 3)
#define  AEEGPS_ERR_INFO_UNAVAIL       (AEEGPS_ERR_BASE + 4)
#define  AEEGPS_ERR_PRIVACY_REFUSED    (AEEGPS_ERR_BASE + 5)
#define  AEEGPS_ERR_SRV_UNREACHABLE    (AEEGPS_ERR_BASE + 6)
#define  AEEGPS_ERR_LINK_FAILED        (AEEGPS_ERR_BASE + 7)
#define  AEEGPS_ERR_REJECTED           (AEEGPS_ERR_BASE + 8)
#define  AEEGPS_ERR_OUTOF_RESOURCES    (AEEGPS_ERR_BASE + 9)
#define  AEEGPS_ERR_STALE_BS_INFO      (AEEGPS_ERR_BASE + 10)
#define  AEEGPS_ERR_RECEIVER_BUSY      (AEEGPS_ERR_BASE + 11)



typedef struct _AEEGPSInfo {
   uint32             dwTimeStamp;          // Time, seconds since 1/6/1980
   uint32             status;               // Response status;
   int32              dwLat;                // Lat, 180/2^25 degrees, WGS-84 ellipsoid
   int32              dwLon;                // Lon, 360/2^26 degrees, WGS-84 ellipsoid
   int16              wAltitude;            // Alt, meters, WGS-84 ellipsoid
   uint16             wHeading;             // Heading, 360/2^10 degrees
   uint16             wVelocityHor;         // Horizontal velocity, 0.25 meters/second
   int8               bVelocityVer;         // Vertical velocity, 0.5 meters/second
   AEEGPSAccuracy     accuracy;             // Accuracy of the data
   uint16             fValid;               // Flags indicating valid fields in the struct.
   uint8              bHorUnc;              // Horizontal uncertainity
   uint8              bHorUncAngle;         // Hor. Uncertainity at angle
   uint8              bHorUncPerp;          // Hor. uncertainty perpendicular
   uint16             wVerUnc;              // Vertical uncertainity.
} AEEGPSInfo;

typedef struct _AEEPositionInfoEx {
   uint32               dwSize;
   flg                  fLatitude:1;
   flg                  fLongitude:1;
   flg                  fAltitude:1;
   flg                  fHeading:1;
   flg                  fHorVelocity:1;
   flg                  fVerVelocity:1;
   flg                  fHorUnc:1;           /* valid : HorUncAngle, HorUnc, HorUncPerp */
   flg                  fAltitudeUnc:1;

   double               Latitude;            /* in degrees */
   double               Longitude;           /* in degrees */
   int                  nAltitude;           /* in meters */
   double               Heading;             /* degress from true North. */
   double               HorVelocity;         /* meters/second. */
   double               VerVelocity;         /* meters/second. */

   double               HorUncAngle;         /* Angle of axis with respect
                                             ** to true North for position
                                             ** uncertainity. */
   double               HorUnc;              /* Uncertainity along the axis
                                             ** specified with the HorUncAngle. */
   double               HorUncPerp;          /* Uncertainity along the axis
                                             ** axis perpendicular to HorUncAngle. */

   double               AltitudeUnc;         /* Uncertainity in altitude */

} AEEPositionInfoEx;

typedef  uint8    AEEOrientationReq;
#define  AEEORIENTATION_REQ_AZIMUTH   0x01

typedef struct _AEEOrientationAzimuthInfo {
  uint16             wSize;           // sizeof( AEEOrientationAzimuthInfo ) in bytes.
  uint16             wAzimuth;        // Angle 0 - 359 degress and 59 arcminutes.
                                      // bits 0-5 contain arcminutes
                                      // bits 6-15 contain degrees.
                                      // This is the heading angle in the local
                                      // horizontal plane measured clockwise from
                                      // true North.
  uint32             dwTimeStamp;     // Time, seconds since 1/6/1980
} AEEOrientationAzimuthInfo;

typedef struct IPosDet IPosDet;

AEEINTERFACE(IPosDet) {
   DECLARE_IQIBASE(IPosDet);
   int (*GetSectorInfo)(IPosDet *, AEESectorInfo *);
   int (*SetGPSConfig)(IPosDet *, AEEGPSConfig *);
   int (*GetGPSConfig)(IPosDet *, AEEGPSConfig *);
   int (*GetGPSInfo)(IPosDet *, AEEGPSReq, AEEGPSAccuracy, AEEGPSInfo *, AEECallback *);
   /* AEECLSID_POSDET_20 end */
   int (*GetOrientation)(IPosDet *, AEEOrientationReq, void *, AEECallback *);
   int (*GetSectorInfoEx)(IPosDet *, AEESectorInfo *, uint16 wSize);
   /* AEECLSID_POSDET_21 end */
   int (*ExtractPositionInfo)(IPosDet *, AEEGPSInfo *, AEEPositionInfoEx *);
};

#define IPOSDET_AddRef(p)                AEEGETPVTBL((p),IPosDet)->AddRef((p))
#define IPOSDET_Release(p)               AEEGETPVTBL((p),IPosDet)->Release((p))
#define IPOSDET_QueryInterface(p,id,pp)  AEEGETPVTBL((p),IPosDet)->QueryInterface((p),(id),(pp))
#define IPOSDET_SetGPSConfig(p,pc)       AEEGETPVTBL((p),IPosDet)->SetGPSConfig((p),(pc))
#define IPOSDET_GetGPSConfig(p,pc)       AEEGETPVTBL((p),IPosDet)->GetGPSConfig((p),(pc))
#define IPOSDET_GetGPSInfo(p,r,a,pi,pcb) AEEGETPVTBL((p),IPosDet)->GetGPSInfo((p),(r),(a),(pi),(pcb))

static __inline int IPOSDET_GetSectorInfo(IPosDet *p, AEESectorInfo *pi)
{
   IPosDet *pNew;
   int     nErr = EUNSUPPORTED;

   if( SUCCESS == IPOSDET_QueryInterface(p, AEECLSID_POSDET, (void **)&pNew)) {
     nErr = AEEGETPVTBL(pNew,IPosDet)->GetSectorInfoEx(pNew, pi, sizeof(AEESectorInfo));
     IPOSDET_Release(pNew);
   }
   else if( SUCCESS == IPOSDET_QueryInterface(p, AEECLSID_POSDET_20, (void **)&pNew)
            || SUCCESS == IPOSDET_QueryInterface(p, AEECLSID_POSDET_11, (void **)&pNew) ) {
     nErr = AEEGETPVTBL(pNew,IPosDet)->GetSectorInfo(pNew, pi);
     IPOSDET_Release(pNew);
   }
   return nErr;
}

static __inline int IPOSDET_GetOrientation(IPosDet *p, AEEOrientationReq r, void *pi, AEECallback *pcb)
{
   IPosDet *pNew;
   int      nErr = EUNSUPPORTED;

   if (SUCCESS == IPOSDET_QueryInterface(p, AEECLSID_POSDET, (void **)&pNew)) {
      nErr = AEEGETPVTBL(pNew,IPosDet)->GetOrientation(pNew,r,pi,pcb);
      IPOSDET_Release(pNew);
   }
   return nErr;
}

static __inline int IPOSDET_ExtractPositionInfo(IPosDet *p, AEEGPSInfo *pi, AEEPositionInfoEx *po)
{
   IPosDet *pNew;
   int      nErr = EUNSUPPORTED;

   if (SUCCESS == IPOSDET_QueryInterface(p, AEECLSID_POSDET, (void **)&pNew)) {
      nErr = AEEGETPVTBL(pNew,IPosDet)->ExtractPositionInfo(pNew,pi,po);
      IPOSDET_Release(pNew);
   }
   return nErr;
}

/*=====================================================================
  DATA STRUCTURES DOCUMENTATION
=======================================================================

AEESectorInfo

Description:
This structure is used to obtain sector based position location information from the system.

Definition:

typedef struct _AEESectorInfo
{
   uint16 wSysID;
   uint16 wNetID;
   uint16 wBaseID;
   uint16 wBaseClass;
   uint16 wBestPN;
   uint16 wBestPN;
   uint16 wPacketZoneID;
   uint16 wMobileCountryCode;
   uint32 dwBaseLatitude;
   uint32 dwBaseLongitude;
}AEESectorInfo;

Members:

   wSysID:               System Identification
   wNetID:               Network Identification
   wBaseStationID:            Base Station Identification
   wBaseStationClass:         Base Station Class
   wBestPN:              Best Pilot
   wPacketZoneID:        Packet Data Service Zone Identifier
   wMobileCountryCode:   Mobile country code
   dwBaseLatitude:       Base Station Latitude in the units of 0.25second, expressed
                         as a two's complement signed number with positive numbers
                         signifying North latitudes.
   dwBaseLongitude:      Base Station Longitude in the units of 0.25second, expressed
                         as a two's complement signed number with positive numbers
                         signifying East longitude.

Comments:
   For dwBaseLatitude and dwBaseLongitude, a floating point division with 14400 transforms
   them into degress.

See Also:
   IPOSDET_GetSectorInfo()

=======================================================================

AEEGPSMode

Description:
   This structure is used to specify the mode of operation of the GPS
   system on the device.

Definition:
   typedef  uint16      AEEGPSMode;
   
Values:
Supported values:
   AEEGPS_MODE_ONE_SHOT       : One-time request. This option is the default.
   AEEGPS_MODE_DLOAD_FIRST    : In addition to honoring the request of AEEGPSReq,
                                downloads ephemeris and almanac data from the
                                location server. Device will use the duration computed
                                with (nFixes * nInterval) and automatically refresh
                                the data from location server when it becomes invalid.
                                Device will make use of this data in computing
                                position locally. Application can take advantage of
                                this by changing the mode to AEEGPS_MODE_TRACK_LOCAL
                                for subsequent position location requests.
   AEEGPS_MODE_TRACK_LOCAL    : Compute the position locally on the mobile device.
                                Network traffic in this mode is minimal when
                                performing multiple GetGPSInfo requests. This mode uses
                                aiding satellite data (ephemeris data and almanac) downloaded
                                from location server. If the aiding data in the device
                                is unavailable or becomes invalid, device seeks that
                                information from the location server (same as
                                AEEGPS_MODE_DLOAD_FIRST) automatically.
   AEEGPS_MODE_TRACK_NETWORK  : Compute the position using location server. Communicates
                                with the server using TCP/IP.
   AEEGPS_MODE_TRACK_OPTIMAL  : Track optimally, uses the type of optimization
                                suggested AEEGPSOpt. AEEGPS_OPT_NONE is not acceptable value
                                for this mode which will result in EBADPARM.
   AEEGPS_MODE_TRACK_STANDALONE : Mobile device autonomously performs position determination.
                                This mode differs from AEEGPS_MODE_TRACK_LOCAL, in that
                                device seeks the GPS satellite ephemeris and almanac data from
                                Position location server using wireless TCP/IP communication.
                                In this method device obtains GPS satellite ephemeris and
                                almanac data by decoding GPS signals (like a conventional
                                GPS receiver).

Comments:
   Not all devices with PosDet capability are capable of AEEGPS_MODE_TRACK_LOCAL or
   AEEGPS_MODE_DLOAD_FIRST. Setting the mode on such devices will result in EUNSUPPORTED.

See Also:
   AEEGPSConfig
   IPOSDET_SetGPSConfig()
   IPOSDET_GetGPSInfo()

=======================================================================

AEEGPSOpt

Description:
   This data type is used to specify the optimization desired from the
   position determination subsystem.

Definition:
   typedef  uint8      AEEGPSOpt;

Supported values:
   AEEGPS_OPT_NONE        : Does not apply any optimization methods.
   AEEGPS_OPT_SPEED       : Optimize the GPS fix for time.
   AEEGPS_OPT_ACCURACY    : Optimize the GPS fix for accuracy. This option may require
                            longer time and network connectivity/more Data burst messages.
   AEEGPS_OPT_PAYLOAD     : Optimize the method of computing fix so it will result in
                            none or minimum data exchange with the remote location server.
   AEEGPS_OPT_DEFAULT     : This is set to AEEGPS_OPT_NONE.


Comments:
   None

See Also:
   AEEGPSConfig
   IPOSDET_SetGPSConfig()
   IPOSDET_GetGPSInfo()

=======================================================================

AEEGPSSvrType

Description:
   This data type is used to specify the server type to be used for GPS services.

Definition:
   typedef  uint32      AEEGPSSvrType;

Supported values:
   AEEGPS_SERVER_DEFAULT  : Use the default(preferred) server and the mode of
                            transport specified by the carrier/OEM.
   AEEGPS_SERVER_IP       : Use an IP-based location Server. (See also AEEGPSIPServer)
   AEEGPS_SERVER_DBURST   : Use data burst messages as the transport to/from the
                            location server. ( This server type may not be supported in
                            all the mobile networks. Using this server type in such
                            event causes EUNSUPPORTED with IPOSDET_SetGPSConfig )

Comments:
   None

See Also:
   AEEGPSServer

=======================================================================

AEEGPSIPServer

Description:
   This structure specifies the IP Server to be used (To be used when
   AEEGPS_SERVER_IP is specified as the server type).

Definition:
   typedef struct _AEEGPSIPServer {
      INAddr      addr;
      INPort      port;
      uint16      reserved;
   } AEEGPSIPServer;

Members:
   addr     :  32-bit IP address of the server in network byte order
   port     :  port to connect. In network byte order.

Comments:
   None

See Also:
   INAddr
   INPort
   AEEGPSServer

=======================================================================

AEEGPSServer

Description:
   This structure specifies the Server type and specifications for the
   server to be used for GPS-based position determination.

Definition:
   typedef struct _AEEGPSServer{
      AEEGPSSvrType  svrType;
      union {
         AEEGPSIPServer ipsvr;
      } svr;
   } AEEGPSServer;

Members:
   svr     :  specifications for the server to be used.


Comments:
   A valid value for ipsvr is required when server type AEEGPS_SERVER_IP is specified.

See Also:
   AEEGPSConfig
   AEEGPSSvrType
   AEEGPSIPServer

=======================================================================

AEEGPSConfig

Description:
   This structure is used to configure the GPS engine provided by this interface.

Definition:
   typedef struct _AEEGPSConfig {
      AEEGPSMode        mode;
      uint16            nFixes;
      uint16            nInterval;
      AEEGPSOpt         optim;
      AEEGPSQos         qos;
      AEEGPSServer      server;
   } AEEGPSConfig;

Members:
   mode:      The mode of operation to be configured for this interface
              Possible options are:
~
              AEEGPS_MODE_ONE_SHOT:    Only one position determination
                                       request to be made. This option
                                       may not be optimal for repeated
                                       position determination requests.

              AEEGPS_MODE_DLOAD_FIRST: This mode is suited for applications
                                       that would do repeated position
                                       determination requests, and would
                                       prefer the results to be computed
                                       locally on the mobile device after
                                       initial data is downloaded from
                                       the server.

              AEEGPS_MODE_TRACK_LOCAL: This mode is suited for applications
                                       intending to perform tracking, and
                                       require frequent fast location/velocity/
                                       altitude information. This mode also
                                       requires minimizal requests to the network
                                       for position determination information.

              AEEGPS_MODE_TRACK_NETWORK: This mode is suited for applications
                                        requiring tracking that would prefer
                                        getting accurate position determination
                                        information from the network.

              AEEGPS_MODE_TRACK_OPTIMAL: Track optimally, uses the type of
                                       optimization suggested AEEGPSOpt.
                                       AEEGPS_OPT_NONE is not acceptable value
                                       for this mode which will result in
                                       EBADPARM.

              AEEGPS_MODE_TRACK_STANDALONE : This mode is suited for applications
                                       intending to perform position fixes even
                                       when Terrestrial wireless service is
                                       unavailable.

              AEEGPS_MODE_DEFAULT:     The default mode of operation, which is
                                       set to AEEGPS_MODE_ONE_SHOT
*

   nFixes:    Estimated number of position determination requests that would
              be made using this interface.

   nInterval: Estimated interval between fixes (in seconds).

   optim:     The optimization required for this interface. Possible values
              are:
~
              AEEGPS_OPT_NONE      : No optimization.~
              AEEGPS_OPT_SPEED     : Optimize for speed~
              AEEGPS_OPT_ACCURACY  : Optimize for accuracy.~
              AEEGPS_OPT_PAYLOAD   : Optimize for least data exchange with
                                     location server.~
              AEEGPS_OPT_DEFAULT   : Default. Set for no optimization.~
*

   qos:       Quality of Service. Values between 0-255 are valid, 255 providing
              the highest quality of service. This option may be ignored on
              certain mobile devices.

   server:    Server configuration. This structure specifies the server type
              and configuration. Possible server types are:
~
              AEEGPS_SERVER_DEFAULT~
              AEEGPS_SERVER_IP~
              AEEGPS_SERVER_DBURST ~
*
              Effective BREW3.0.3, application using server type other than 
              AEEGPS_SERVER_DEFAULT must have privilege to the group id 
              AEECLSID_LOCATIONSERVER.

              If the server type is AEEGPS_SERVER_IP, the IP Address and port
              of the Position Determination server must be specified. If the port
              number is specified as 0, connection will be attempted on a default
              port for the service.

Comments:
   None

See Also:
   IPOSDET_SetGPSConfig()

=======================================================================

AEEGPSInfo

Description:
   This structure is used to obtain GPS based position location information from the
   system. The parameters returned are as per the TIA/EIA IS-801 standard.

Definition:
   typedef struct _AEEGPSInfo {
      uint32             dwTimeStamp;
      uint32             status;
      int32              dwLat;
      int32              dwLon;
      int16              wAltitude;
      uint16             wHeading;
      uint16             wVelocityHor;
      int8               bVelocityVer;
      AEEGPSAccuracy     accuracy;
      uint16             fValid;
      uint8              bHorUnc;
      uint8              bHorUncAngle;
      uint8              bHorUncPerp;
      uint16             wVerUnc;
   } AEEGPSInfo;

Members:
   dwTimeStamp:          Time (in seconds since 1/6/1980) of this measurement
   status:               Response Status
   dwLat:                Latitude, 180/2^25 degrees, WGS-84 ellipsoid
   dwLon:                Longitude, 360/2^26 degrees, WGS-84 ellipsoid
   wAltitude:            Altitude, meters, WGS-84 ellipsoid
   wHeading:             Heading, 360/2^10 degrees
   wVelocityHor:         Horizontal velocity, 0.25 meters/second
   bVelocityVer:         Vertical velocity, 0.5 meters/second
   accuracy:             Accuracy of the data.
   fValid:               Flags indicating valid fields in the struct.
   bHorUnc:              Horizontal uncertainity
   bHorUncAngle:         Horizontal uncertainity at angle
   bHorUncPerp:          Horizontal uncertainty perpendicular
   bVerUnc:              Vertical uncertainity

Comments:
   fValid indicates the fields set in the AEEGPSInfo structure. The following
   flags are available.
~
         AEEGPS_VALID_LAT   :    Valid latitude  ~
         AEEGPS_VALID_LON   :    Valid longitude  ~
         AEEGPS_VALID_ALT   :    Valid altitude ~
         AEEGPS_VALID_HEAD  :    Valid heading  ~
         AEEGPS_VALID_HVEL  :    Valid horizontal velocity~
         AEEGPS_VALID_VVEL  :    Valid vertical velocity~
         AEEGPS_VALID_HUNC  :    Valid horizontal uncertainity  ~
         AEEGPS_VALID_AUNC  :    Valid Horizontal uncertainity at angle~
         AEEGPS_VALID_PUNC  :    Valid horizontal uncertainity (orthogonal)~
         AEEGPS_VALID_VUNC  :    Valid Vertical uncertainity~
*

   The accuracy is specified by 6 levels starting from AEEGPS_ACCURACY_LEVEL1 to
   AEEGPS_ACCURACY_LEVEL6

   status may contain following information indicating the Success or Failure
   of the GetGpsInfo request :
~
     AEEGPS_ERR_NO_ERR : Indicates that request is completely answered.~
     AEEGPS_ERR_GENERAL_FAILURE : Indicates that position request failed. This is a general
   system failure for position request.~
     AEEGPS_ERR_TIMEOUT : Request timedout.~
     AEEGPS_ERR_INFO_UNAVAIL : Indicates that either partial or no information is
   available for the request. Check the fValid field to retrieve any partial information
   available.~
     AEEGPS_ERR_PRIVACY_REFUSED : Indicates that the request is refused to protect
   the device's privacy. This occurs when the Privacy enforced on the device decided to
   reject the position requests of the application.~
    AEEGPS_ERR_SRV_UNREACHABLE : When device fails to connect/communicate with the location
   server. The reasons could be that the IP address (set by application using
   IPOSDET_SetGPSConfig() or the default value provisioned into the device) is either
   incorrect or unavailable.~
    AEEGPS_ERR_LINK_FAILED : When the communication link setup to handle the position request
   is disrupted. The reasons could be another entity ( either user or a high priority program )
   preempt the session causing the link for current request to fail. Or the wireless link
   failed. This is likely a temporary failure application may re-try.~
    AEEGPS_ERR_REJECTED : One or more entities in the system rejected the position request.~
    AEEGPS_ERR_OUTOF_RESOURCES : When system does not have sufficient resources to handle the
   position request. Resource contention could be coming from one or more of the reasons such
   as another position session, out of tcp sockets, a voice call or any other traffic call
   locking up resources, etc. This error most likely requires user intervention in order for
   the re-tries to succeed.~
    AEEGPS_ERR_RECEIVER_BUSY : When device' radio receiver is temporarily unavailable for position 
   determination.~
*

See Also:
   IPOSDET_GetGPSInfo()
   WGS84_TO_DEGREES()
   IPOSDET_ExtractPositionInfo()

=======================================================================

AEEPositionInfoEx

Description:
   This structure is used to obtain position location information from the
   GPS based position location AEEGPSInfo.

Definition:
typedef struct _AEEPositionInfoEx {
   uint32               dwSize;
   flg                  fLatitude:1;
   flg                  fLongitude:1;
   flg                  fAltitude:1;
   flg                  fHeading:1;
   flg                  fHorVelocity:1;
   flg                  fVerVelocity:1;
   flg                  fHorUnc:1;
   flg                  fAltitudeUnc:1;

   double               Latitude;
   double               Longitude;
   int                  nAltitude;
   double               Heading;
   double               HorVelocity;
   double               VerVelocity;
   double               HorUncAngle;
   double               HorUnc;
   double               HorUncPerp;
   double               AltitudeUnc;

} AEEPositionInfoEx;

Members:

   dwSize:              The sizeof the AEEPositionInfoEx structure.
   fLatitude:           Latitude member of the structure is valid.
   fLongitude:          Longitude member of the AEEPositionInfoEx is valid.
   fAltitude:           nAltitude member is valid.
   fHeading:            the member Heading is valid.
   fHorVelocity:        the member HorVelocity is valid.
   fVerVelocity:        the member VerVelocity is valid.
   fHorUnc:             Horizontal uncertainity members (HorUncAngle,
                        HorUnc and HorUncPerp) are valid.
   fAltitudeUnc:        the member AltitudeUnc is valid.

   Latitude:            latitude in degrees w.r.t WGS-84 ellipsoid.
   Longitude:           longitude in degrees w.r.t WGS-84 ellipsoid.
   nAltitude:           altitude in meters w.r.t WGS-84 ellipsoid.
   Heading:             heading direction in degrees from true North.
   HorVelocity:         horizontal velocity in meters/second.
   VerVelocity:         vertical velocity in meters/second.

   HorUncAngle:         one of the data members describing uncertainity in position.
                        This describes an axis in horizontal plane, in degrees
                        from true North.
   HorUnc:              one of the data members describing uncertainity in position.
                        This describes the uncertainity in meters along the axis(specified
                        bye HorUncAngle) in horizontal plane.
   HorUncPerp:          one of the data members describing uncertainity in position.
                        This describes the uncertainity in meters along the axis perpendicular
                        to the one specified by HorUncAngle.

   AltitudeUnc:         meters of uncertainity in the altitude.

Comments:

   The uncertainity in position parameters : HorUncAngle, HorUnc and HorUncPerp - describe an ellipse in
   the horizontal plane.

See Also:
   IPOSDET_ExtractPositionInfo()

=============================================================================

AEEOrientationReq

Description:

Definition:
    typedef uint8 AEEOrientationReq;
    #define AEEORIENTATION_REQ_AZIMUTH 0x01

Members:
    None

Comments:
    None

See Also:
    None

=======================================================================

AEEOrientationAzimuthInfo

Description:
   This structure is used to obtain the azimuth of the device. This is the response
   from the device for the request AEEORIENTATION_REQ_AZIMUTH.

Definition:
   typedef struct _AEEOrientationAzimuthInfo {
      uint16             wSize;
      uint16             wAzimuth;
      uint32             dwTimeStamp;
   } AEEOrientationAzimuthInfo;

Members:
   wSize:                size of the data structure AEEOrientationAzimuthInfo.
   wAzimuth:             Angle 0 - 359 degress and 59 arcminutes.
                         bits 0-5 contain arcminutes
                         bits 6-15 contain degrees.
                         This is the heading angle in the local horizontal plane
                         measured clockwise from true North
   dwTimeStamp:          Time (in seconds since 1/6/1980) of this measurement

Comments:
   None

See Also:
   IPOSDET_GetOrientation()

=========================================================================
=========================================================================
INTERFACES   DOCUMENTATION
=========================================================================
IPosdet Interface

Description:

This interface provides services for position determination using sector
information or GPS information. In order to use the sector-based postion
determination methods such as IPOSDET_GetSectorInfo(), SectorInfo privileges
are required. Similarily, for GPS based position determination methods such
as IPOSDET_SetGPSConfig(), IPOSDET_GetGPSConfig(), and IPOSDET_GetGPSInfo(),
Position Determination Privieleges are required.

IPOSDET_GetGPSInfo() is an asynchronous method which uses AEECallback. Care
must be taken to ensure that the callbacks and information structures passed
to these methods by reference remain in scope till the callback returns.

BREW SDK users can set the GPS emulation in the Tools->GPS Emulation menu to
use a pre-recorded NMEA file as GPS input, or connect an NMEA-output capable
GPS device. An offline utlity called NMEALogger.exe can be used to record an
NMEA file from data coming from a GPS device connected to the serial port of
the desktop/laptop. This NMEA file can be used later as GPS input. See SDK
User's Guide and SDK Utilities Guide for details.

The following header file is required:

AEEPosDet.h

=======================================================================

IPOSDET_AddRef()

Description:
   This function increments the reference count of the IPosDet Interface object, allowing
   the object to be shared by multiple callers. The object is freed when the reference
   count reaches 0 (zero).

Prototype:
   uint32 IPOSDET_AddRef(IPosDet * pIPosDet)

Parameters:
   pIPosDet: [in]. Pointer to the IPosDet Interface object.

Return Value:
   Incremented reference count for the object.

Comments:
   A valid object returns a positive reference count.

Side Effects:
   None

Version:
   Introduced BREW Client 1.1

See Also:
   IPOSDET_Release()

=======================================================================

IPOSDET_Release()

Description:
   This function decrements the reference count of the IPosDet Interface object. The
   object is freed from memory and is no longer valid when the reference count reaches
   0 (zero).

Prototype:
   uint32 IPOSDET_Release(IPosDet * pIPosDet)

Parameters:
   pIPosDet: [in]. Pointer to the IPosDet Interface object.

Return Value:
   Decremented reference count for the object.
   0 (zero), If the object has been freed and is no longer valid.

Comments:
   None

Side Effects:
   None

Version:
   Introduced BREW Client 1.1

See Also:
   IPOSDET_AddRef()

=======================================================================

IPOSDET_QueryInterface()

Description:
   This function asks an object for another API contract from the object in question.

Prototype:

   int IPOSDET_QueryInterface
   (
   IPosDet * pIPosDet,
   AEECLSID idReq,
   void ** ppo
   )

Parameters:
   pIPosDet: [in] Pointer to the IPosDet Interface object.
   idReq:    [in] Requested class ID exposed by the object
   ppo:      [out] Returned object.  Filled by this method

Return Value:
   SUCCESS - Interface found~
   ENOMEMORY - Insufficient memory~
   ECLASSNOTSUPPORT - Requested interface is unsupported~

Comments:
   The pointer in *ppo is set to the new interface (with refcount positive), or NULL if the
   ClassID is not supported by the object. ppo MUST not be NULL.

Side Effects:
   None

Version:
   Introduced BREW Client 1.1

See Also:
   None

=======================================================================

IPOSDET_GetSectorInfo()

Description:
   This function returns information for sector based position
   location. It returns information about the SystemID, NetworkID,
   BaseStationID, BaseStationClass and best Pilot.  Inorder to invoke
   this function, the caller (app) must have the PL_SECTORINFO privilege
   level. Without this privilege level,this function will fail.

Prototype:
   int   IPOSDET_GetSectorInfo(IPosDet *pif, AEESectorInfo *pSecInfo)

Parameters:
   pif:      [in]. Pointer to IPosDet object.
   pSecInfo: [out]. This must be a value ptr to the
              AEESectorInfo structure.
              On return, the members of this
              struct contain sector information.

Return Value:
   AEE_SUCCESS: if the function succeeded~
   EPRIVLEVEL: if the caller does not have sufficient privilege levels
              (PL_SECTORINFO) to invoke this function~
   EBADPARM: if pSecInfo is NULL~
   EUNSUPPORTED: if this function is not supported. ~
   EFAILED: General Failure~

Comments:
   None

Side Effects:
   None

Version:
   Introduced BREW Client 1.1

See Also:
   AEESectorInfo

=======================================================================

IPOSDET_SetGPSConfig()

Description:
   This function sets the GPS configuration to be used by the GPS engine.

Prototype:
   int IPOSDET_SetGPSConfig(IPosDet *pIPosDet, AEEGPSConfig *pConfig);

Parameters:
   pIPosDet : [in]. The interface pointer.
   pConfig  : [in]. Pointer to GPS configuration. See AEEGPSConfig for details.


Return Value:
   SUCCESS   : The function succeeded~
   EPRIVLEVEL: if the caller does not have sufficient privilege levels
               (PL_POS_LOCATION) to invoke this function~
   EBADPARM  : if pConfig is NULL or the data passed in the *pConfig is invalid.
               (checks validity of mode, server.svrType, optim)~
   EUNSUPPORTED: if this configuration is not supported on the system.~


Comments:
   Until this function is called, the position determination engine will be
   configured with default settings. Default settings can be obtained using
   IPOSDET_GetGPSConfig. Only the position determination requests following
   a call to IPOSDET_SetGPSConfig() will use the new configuration.

Side Effects:
   None

Version:
   Introduced BREW Client 2.0

See Also:
   AEEGPSConfig
   IPOSDET_GetGPSConfig()

=======================================================================

IPOSDET_GetGPSConfig()

Description:
    This function gets the current GPS configuration of the GPS engine.

Prototype:
   int IPOSDET_GetGPSConfig(IPosDet *pIPosDet, AEEGPSConfig *pConfig);

Parameters:
   pif           : [in]. Pointer to IPosDet Object.
   pConfig       : [out]. Pointer to GPS configuration. See AEEGPSConfig for details.


Return Value:
   SUCCESS        : if the function succeeded~
   EPRIVLEVEL     : if the caller does not have sufficient privilege levels
                    (PL_POS_LOCATION) to invoke this function~
   EBADPARM       : if pConfig is NULL~
   EUNSUPPORTED   : if this function is not supported. ~

Comments:
   None

Side Effects:
   None

Version:
   Introduced BREW Client 2.0

See Also:
   AEEGPSConfig
   IPOSDET_SetGPSConfig()

=======================================================================

IPOSDET_GetGPSInfo()

Description:
   This function returns information for GPS based position location. It returns
   latitude, longitude, altitude information, as well as vector information such as
   horizontal and vertical velocity, heading, and the uncertainity of the horizontal
   information. This is an asynchronous call, and the callback specified by pcb is
   called on completion. If the position request is not satisfactorily answered, the
   status member of AEEGPSInfo will be non-zero with the one of AEEGPS_ERR_* values.

   This function enforces the privacy policies recommended by the network operator.
   Privacy implementation on the device may prompt the user using a dialog.
   Applications invoking this function must be prepared to surrender the screen for
   the dialog prompted to user. Application after invoking this function must suspend
   any paint to the screen on the event EVT_DIALOG_START and must redraw on the event
   EVT_DIALOG_END.


Prototype:
   int IPOSDET_GetGPSInfo(IPosDet *pif, AEEGPSReq req, AEEGPSAccuracy accuracy,
                          AEEGPSInfo *pGPSInfo, AEECallback *pcb );

Parameters:
   pif      : [in]. Pointer to IPosDet object.
   req      : [in]. Request type (AEEGPS_GETINFO_LOCATION, AEEGPS_GETINFO_VELOCITY,
              AEEGPS_GETINFO_ALTITUDE,AEEGPS_GETINFO_NONE).
              The flags(exlcuding AEEGPS_GETINFO_NONE) can be combined to get more
              than one type of information. The flag AEEGPS_GETINFO_NONE is applicable
              only when the configured mode is of type AEEGPS_MODE_DLOAD_FIRST.
   accuracy : [in]. Desired level of accuracy for this request.
   pGPSInfo : [out]. On input, this must be a valid ptr to the
              AEEGPSInfo structure. On callback, the members of this
              struct contain GPS information. The caller must ensure
              that this structure is valid till the callback
              specified by pcb gets called.
   pcb      : [in]. Callback function which gets called on completion of position
              determination.


Return Value:
   SUCCESS        : if the function succeeded~
   EPRIVLEVEL     : if the caller does not have sufficient privilege levels
                    (PL_POS_LOCATION) to invoke this function~
   EBADPARM       : if pGPSInfo or pcb is NULL~
   EUNSUPPORTED   : if this function is not supported. ~
   EFAILED        : general failure~


Comments:
   On succeess, the request is being processed and a response will be notified
   asynchronously using the callback. Application may invoke CALLBACK_Cancel() on
   the pcb to cancel the request.

Side Effects:
   None

Version:
   Introduced BREW Client 2.0

See Also:
   AEEGPSReq
   AEEGPSAccuracy
   AEEGPSInfo
   AEECallback

=======================================================================

IPOSDET_GetOrientation()

Description:
   This function returns device's orientation in the horizontal plane.
   This is an asynchronous call, and the callback specified by pcb is
   called on completion.

Prototype:
   int IPOSDET_GetOrientation( IPosDet *pif, AEEOrientationReq req, void *pOrInfo,
                               AEECallback *pcb );

Parameters:
   pif      : [in]. Pointer to the IPosDet object.
   req      : [in]. The requested information. (Possible values include
              AEEORIENTATION_REQ_AZIMUTH)
   pOrInfo  : [out]. On input, this must be a valid ptr to the
              valid memory with the first two bytes (wSize) indicating
              the space available in bytes. The space should be a minimum
              of that required to place the response corresponding the request.
              On callback, the members of this struct contain Orientation
              information corresponding to the request. The caller must ensure
              that this memory is valid till the callback specified by pcb
              gets called.
   pcb      : [in]. Callback function which gets called on completion of the
              request.

Return Value:
   SUCCESS        : if the function succeeded~
   EPRIVLEVEL     : if the caller does not have sufficient privilege levels
                    (PL_POS_LOCATION) to invoke this function~
   EBADPARM       : if pOrInfo or pcb is NULL~
   EUNSUPPORTED   : if this function is not supported ~
   EFAILED        : general failure~


Comments:
   If successfully accepted, caller may cancel the request by invoking
   CALLBACK_Cancel() on the pcb.

Side Effects:
   None

Version:
   Introduced BREW Client 2.1

See Also:
   AEEOrientationReq
   AEEOrientationAzimuthInfo

=======================================================================

IPOSDET_ExtractPositionInfo()

Description:
   Given the position in AEEGPSInfo, this function generates the position
   information in the format specified by AEEPositionInfoEx.

Prototype:
   int IPOSDET_ExtractPositionInfo( IPosDet *pif, AEEGPSInfo *pi, AEEPositionInfoEx *po );

Parameters:
   pif      : [in]. Pointer to the IPosDet object.
   pi       : [in]. Pointer to AEEGPSInfo data.
   po       : [out]. Output buffer for position information.

Return Value:
   SUCCESS        : if the function succeeded~
   EPRIVLEVEL     : if the caller does not have sufficient privilege levels
                    (PL_POS_LOCATION) to invoke this function~
   EBADPARM       : if pi or po is NULL. or the buffer provided by po is not
                    sufficient~
   EUNSUPPORTED   : if this function is not supported~
   EFAILED        : general failure~


Comments:
   None

Side Effects:
   None

Version:
   Introduced BREW Client 3.0

See Also:
   AEEGPSInfo
   AEEPositionInfoEx

=======================================================================*/

#endif /* #ifndef AEEPOSDET_H */


