Appendix F: GPS Receiver's DLL Interface Prototypes

StartGps

Parameters
int FAR PASCAL _loadds StartGps(double old_lat, double old_lon,GpsCommParms com_p, GpsCommParms dgps_param,LPCSTR library,INIINFO ini_info,double UserLat,double UserLon, Environment Env)
Previous GPS Latitude (double) [degrees]
Previous GPS Longitude (double) [degrees]
GPS receivers comm port parameters (GpsCommParms)
DGPS receivers comm port parameters (GpsCommParms)
GPS DLL's language specific string library (LPCSTR)
Information on a third parties GPS DLL INI file which we are interfacing with. (INIINFO)
A user specific Latitude offset (double) [degrees]
A user specific Longitude offset (double) [degrees]
Receivers INI specific Environment settings (Environment)

Return Codes
ERR_LANGUAGE_DLL - Was unable to load the gps language specifice DLL.
ERR_INITALIZED - StartGPS was previously called
ERR_REGISTER_WINDOW - Third party DLL unable to launch (eg: goldcards tgpsdll.dll)
ERR_MALLOC_COMM_BUF - Unable to set buffer size for comm port communication
ERR_OPEN_COMM_PORT - could not take control of the comm port set in the GPS comm port settings
ERR_NO_GPS - No GPS receiver found

Functionality
StartGps firstly initializes all internal variables, sets up the comm ports for the GPS & DGPS receivers for communication. Then opens up the language specific DLL.

StopGps
Parameters
void FAR PASCAL _loadds StopGps( void)
none

Returns
nothing

Functionality
StopGps shuts down the comm port, closes language library, closes any window which was opened for a specific GPS receiver, and resets the DLL to un-initialized.

GpsID
Parameters
int FAR PASCAL _loadds GpsID (void)
none

Returns
TRUE or FALSE (int)

Functionality
GpsID returns TRUE if we are communicating with the GPS receiver. (I.e. We got at least 3 messages from the receiver.) Otherwise it returns FALSE

PollGps
Parameters
void FAR PASCAL _loadds PollGps (void)
none

Returns
nothing

Functionality
PollGps sends GPS specific codes to the GPS receiver, so that the receiver will return the specified data, used in HandleGps . This routine should be called once a second.

HandleGps
Parameters
void FAR PASCAL _loadds HandleGps (void)
none

Returns
nothing

Functionality
HandleGps gets the information from the GPS receiver which was asked for via PollGps , this should be called right after PollGps . All packets from the receiver are processed here and the appropriate data is processed and saved.

GpsPosition
Parameters
int FAR PASCAL _loadds GpsPosition( double *lat, double *lon, int Modify)
Latitude (double *) [degrees]
Longitude (double *) [degrees]
Modify (int) [TRUE / FALSE]

Returns
Sets Latitude & Longitude
GPS_SAME - Latitude & Longitude has not changed since the previous call to this function.
GPS_DIFFERENT - Latitude & Longitude has changed since the previous call to this function.

Functionality
GpsPosition returns the Latitude / Longitude, and the return code is GPS_DIFFERENT if there has been a change in position since the last time you called this routine. If Modify is TRUE the old position will be replaced by the current position.

GpsAccuracy
Parameters
int FAR PASCAL _loadds GpsAccuracy( char *accuracy,int detail ,int *Valid_Position, int Modify)
Current GPS Accuracy (char *) [LANGUAGE SPECIFIC]
Detail Level (int) [EXPERT / NOVICE]
Valid Position fix (int *) [TRUE / FALSE]
Modify old accuracy (int) [TRUE / FALSE]

Returns
Sets accuracy with a character string containing the accuracy of the GPS receiver, which will depend apon what detail is set to.
GPS_SAME - The accuracy has not changed since the previous call to this function.
GPS_DIFFERENT - The accuracy has changed since the previous call to this function.

Functionality
GpsAccuracy sets accuracy to a text string of what the GPS accuracy is and is dependent apon detail . If detail is set to Expert then accuracy will be set to (GPS-2D, GPS-3D, DGPS-2D,DGPS-3D). If detail is set to Novice then accuracy will be set to (POOR, FAIR, GOOD, EXCELLENT). These character strings are in the G_(language).DLL for example G_AMERIC.DLL. If Modify is TRUE the old accuracy will be replaced by the current accuracy.
NOTE : The return code GPS_SAME or GPS_DIFFERENT depends upon the accuracy not the string sent back through accuracy . So if you call GpsAccuracy with detail set to Novice for the first time it will return GPS_DIFFERENT and accuracy will be set to "FAIR", and if you call it again with detail set to EXPERT it will return GPS_SAME and accuracy will be set to "GPS 3D". The accuracy hasn't changed but the definition of what accuracy is has.

GpsStatus
Parameters
int FAR PASCAL _loadds GpsStatus(char far *status, int Modify)
Current GPS status (char *) [Language Specific]
Modify old status with new status [TRUE / FALSE]

Returns
Sets status with a character string containing the status of the GPS receiver.
GPS_SAME - The status has not changed since the previous call to this function.
GPS_DIFFERENT - The status has changed since the previous call to this function.

Functionality
GpsStatus sets status to a text string of what the GPS status is. These character strings are in the G_(language).DLL for example G_SA_001.DLL, where 001 is the country code for the language contained within. If Modify is TRUE the oldstatus will be replaced by the current status. The type of messages sent back through status depends upon what the receiver is doing, ie (Position Fixes, acquiring satellites, Downloading Almanac, 1 usable satellites, etc.)

GpsStatusAcc
Parameters
int FAR PASCAL _loadds GpsStatusAcc( int far *stat, int far *acc)
Current GPS status (int *)
Current GPS accuracy (int *)

Returns
stat will be set to the current non-language specific status
acc will be set to the current non-language specific accuracy
Currently they always return GPS_DIFFERENT. (April 19, 1996)

Functionality
This function is similar to both GpsStatus and GpsAccuracy but returns a numerical representation of the GPS status and accuracy, definitions found in strider.h.

GpsSatellites
Parameters
int FAR PASCAL _loadds GpsSatellites(Satellites *sats, int Modify)
Sats structure to put current viewed satellites (Satellites *)
Modify old structure with new satellite information [TRUE / FALSE]

Returns
a filled in Satellite structure with the updated satellite information (ID, SNR, Azimuth, and Elevation) & the # of satellites tracked.
GPS_SAME - The satellite info has not changed since the previous call to this function.
GPS_DIFFERENT - The satellite info has changed since the previous call to this function.

Functionality
GpsSatellites returns a structure of the # satellites being tracked, their ID's, Signal to Noise ratio (SNR), Elevation, and Azimuth (if these are available from the specific receiver). If these are not available a hard coded N/A will be in these variables.
ID
The satellites ID is the number associated with that particular satellite given to it by the US DoD. This is a number between 1-32.
SNR
The satellites SNR determines how strong a signal we are receiving from a given satellite, and therefore how accurate of a position fix we are getting from this satellite. SNR can range between 0 and 25, where an SNR below 0 represents a satellite we were tracking but lost and in this case SNR for this satellite will be LOST . The satellite information are returned in order of the satellites SNR .
Elevation
The satellites Elevation is measured in degrees from sea level, where 90 degrees is straight overhead.
Azimuth
The satellites Azimuth is measured in degrees from true north, this means if you are facing north and the Azimuth is 0 the satellite is right in front of you.

GpsErrors
Parameters
int FAR PASCAL _loadds GpsErrors(Errors *err)
err structure to put any GPS error messages(Errors *)

Returns
a filled in Error structure with the updated GPS error information if any.
GPS_SAME - No Errors have occurred
GPS_DIFFERENT - A GPS Error has occurred.

Functionality
returns a structure of the different types of GPS errors Possible Errors are : Antenna fault , Battery backup , Clock Fault , Almanac Bad

GpsTime
Parameters
int FAR PASCAL _loadds GpsTime (double *time)
The GPS time in seconds since Sunday (double *)

Returns
the number of seconds since midnight Saturday in GMT
GPS_SAME - Current time is the same as the last time this function was called.
GPS_DIFFERENT - GPS time has changed.

Functionality
GpsTime returns the GPS time as the # of seconds since Sunday in GMT time, it will returns 0 if no time is available.

Units
time is the number of seconds since midnight Saturday in GMT time.

GpsDate
Parameters
int FAR PASCAL _loadds GpsDate (Dates *date)
date structure to put the current date in(Dates *)

Returns
a filled in Dates structure with the updated GPS date.
GPS_SAME - date has not changed since the last function call.
GPS_DIFFERENT - date has changed.

Functionality
GpsDate sets a Dates structure with the current date information provided by the GPS receiver.
NOTE : This date is based apon GMT time, therefore checks must be made to make sure the correct date will be displayed depending upon the Time Zone the person is in.

GpsHSpeed
Parameters
int FAR PASCAL _loadds GpsHSpeed (double *hspeed)
hspeed is the current GPS horizontal speed in meters/second (double *)

Returns
the GPS heading (horizontal) speed in meters/second
GPS_SAME - no change in hspeed
GPS_DIFFERENT - new GPS speed.

Functionality
GpsHSpeed returns the current GPS Heading Speed. (ie how fast we are travelling). In (meters / second) this can be changed in Strider to what the user wants as indicated in the INI file.

Units
hspeed is the horizontal or heading speed of the GPS receiver in meters per second.

GpsHeading
Parameters
int FAR PASCAL _loadds GpsHeading (double *heading)
heading is the current GPS heading in degrees (double *)

Returns
the GPS heading in degrees
GPS_SAME - no change in heading
GPS_DIFFERENT - new GPS direction.

Functionality
GpsHeading returns the current GPS Heading, this is instantaneous, and may be inaccurate.

Units
heading is in degrees from true north.

GpsAltitude
Parameters
int FAR PASCAL _loadds GpsAltitude(double *alt)
alt is the current GPS altitude in meters (double *)

Returns
the GPS alitude in Meters
GPS_SAME - no change in altitude
GPS_DIFFERENT - New altitude information.

Functionality
GpsAltitude returns the current GPS Altitude in Meters.
NOTE : if we are in D/GPS 2D this value is very inaccurate.

Units
alt is in meters above sea level.

GpsGetName
Parameters
void FAR PASCAL _loadds GpsGetName(char *name)
name is the name of the GPS receiver & DLL (char *) [LANGUAGE INDEPENDENT]

Returns
the name of the GPS receiver's DLL set in name

GpsRevision
Parameters
void FAR PASCAL _loadds GpsRevision(Revisions *Rev)
Rev Contains the version information for the DLL & the GPS receivers version information & DGPS receivers version information. (Revisions *) [LANGUAGE Specific]

Returns
the version of the GPS receiver's DLL
the GPS receiver's Navigation version information
the GPS receiver Signal processor's version information
the GPS receiver's third parties DLL version information
the DGPS receiver's version information

Functionality
GpsRevision returns the version information of the DLL and the GPS receiver connected to it, which is provided by the GPS if available. The Format of the DLL's version information is X.x.Yy, Date, where X is the Major revision, and x is the minor revision of gpsdll.c (the common GPS routines. Y is the major revision and y is a letter denoting the minor revision of the GPS specific DLL routines found in (tsip.c taip.c allstar.c goldcard.c etc.). The date is the last day gpsdll.c was modified.