GPSLIB v1.03a

GPSLIB v1.03a

Welcome to GPSLIB, a simple SDK (software development kit) which can be used to add GPS support to your 32 bit Windows applications.

Features

History

Installation & Redistribution

Usage

API Reference

Structures used by GPSLIB

Shareware Notice

Planned Enhancements

Contacting the Author

Features

Can be used by any development environment which supports calling Windows DLLs including VB, VBA, C, C++, Fortran and Delphi.
Fully supports the UNICODE programming model.
Provides a control panel applet which is used to add, configure and remove GPS receivers on the client's computer.
Simple API which is similar to function calls in the Win32 SDK API, meaning that it should be familiar to Windows developers.

History

V1.0 (13 January 1998)

Initial public release.

V1.01 (20 January 1998)

A number of problems were discovered when GPSLIB was being used in a UNICODE build (i.e it didn't work <g>). These problems have now been fixed.
Mak file now includes all the possible build options for all the GPSLIB components.
Mak file no longer hard codes output to "d:\winnt\system32". (This was due to the way I have my development system set up).
Some of the other options in the mak file such as output directories have been tidied up
Now includes Ascii release binaries in distribution.
Minor updates to the documentation.

V1.02 (26 August 1998)

Small change to stdafx.h to include afxcview.h in gps32exe
The GpsShowControlPanel function now actually works
Minor tweaks to the GPS Mak files
Removed a number of unused symbols
Change ID of a number of GPS32EXE menu items to avoid conflict with new VC 6 defines.
Updated all Version Infos to 1.02
Removed a level 4 warning from the Test app.
Removed unused toolbar from GPS CPL file
GPS cpl file now uses standard F2 accelerator for Rename
GPS32EXE toolbar is now shown flat
Number of extra TRACE statements have been added to aid in debugging.

V1.03 (13 June 1999)

Fixed a problem with the calling convention of the exported functions in the DLL. This was discovered when being called from Visual Basic. Because of this change the dll you must link to now is called gps103(u).dll.
Now ships with a gps.bas file which allows you to start using GPSLIB straight away.
Also includes a small VB 6 project to test some of the GPS functions.
Updated all copyrights and version info strings.
Updated text in the about dialog for GPSLIB

21 June 1999

Extended VB sample which ships with GPSLIB.
Updated gps.bas file which was previously causing a crash when being used by VB.

27 September 2001

Fixed a problem where the background serial port thread caused heavy CPU utilization.
Updated the project settings so that all binaries get build to the Bin directory and all Lib files get created in a Lib directory
Updated the version info's in all the binaries
Updated the copyright message in the code modules

v1.03a (21 August 2002)

Fixed a synchronisation problem between the worker thread and the GpsGetPosition method. Thanks to Bill Oatman for spotting this problem.

Installation & Redistribution

GPSLIB is for Win32 development only. To help keep the download size to a minimum, there is no install program. All you need to do is unzip the "gpslib.zip" file into a directory on your hard disk.

When it comes time to distribute your applications you will need to ship the relevant GPSLIB dll and control panel applet.

Usage

To start developing client applications using GPSLIB, all you will need to do is to link to the relevant GPSLIB DLL and then call the functions you want.

Notes for users of VC 5.0 / 6.0

Before you start using GPSLIB you will need to modify your include and lib directories to include the relevant GPSLIB directories.
If you want to rebuild any of the GPSLIB components then open up gps32.dsw file as a project workspace. This is a VC 5 workspace file which if you open it in VC 6 will automatically be upgraded to the new workspace format.
The binary modules of the GPSLIB components are not included in this distribution to help keep the download size to a minimum. If you want to use these versions, then you will need to build them using the supplied workspace file.

Depending on your build configuration you will need to link to a different version of the GPSLIB DLL.

Build Configuration	GPSLIB DLL to link to
Ascii Debug	GPS103D.DLL
Ascii Release	GPS103.DLL
Unicode Debug	GPS103UD.DLL
Unicode Release	GPS103U.DLL

The control panel applet consists of the two files. Namely a .cpl and .exe file.

Build Configuration	Control Panel dll	Control Panel Exe
Ascii Debug	GPS103D.CPL	GPS103D.EXE
Ascii Release	GPS103.CPL	GPS103.EXE
Unicode Debug	GPS103UD.CPL	GPS103UD.EXE
Unicode Release	GPS103U.CPL	GPS103U.EXE

These two files which form the GPS control panel applet should be installed into the system directory (system32 directory under Windows NT) of client machines. You can install the GPSLIB dll in the system or application directory of client machines.

Please note that you are only allowed to redistribute the release mode components of GPSLIB.

The debug versions are only relevant to client applications developed in C or C++ which can take advantage of the debugging information contained in these DLLs. This allows you to step directly into the GPSLIB source code when you are debugging your client applications from inside IDE's such as Microsoft's "Developer Studio".

API Reference

The GPSLIB DLLs provided export a number of functions as listed below:

GpsShowControlPanel
GpsCreateEntry
GpsGetNumDevices
GpsEnumDevices
GpsDeleteEntry
GpsRenameEntry
GpsPropertiesDlg
GpsOpen
GpsClose
GpsGetPosition
GpsGetVersion
GpsDeviceNameAlreadyExists
GpsShowAboutBox
GpsGetDevice
GpsSetDevice

GpsShowControlPanel

BOOL GpsShowControlPanel();

Return Value

TRUE if the applet was successfully displayed otherwise FALSE.

Parameters

None.

Remarks

Brings up the GPS Receivers Control Panel Applet. This allows you to install, configure and remove GPS Receivers on your system.

GpsCreateEntry

BOOL GpsCreateEntry(HWND hWnd);

Return Value

TRUE if a new GPS receiver was installed otherwise FALSE.

Parameters

hWnd The parent window to be used for user interface elements which are displayed by this functions.

Remarks

This brings up a standard wizard based dialog to allow the user to install a GPS receiver on their computer.

See Also

GpsDeleteEntry, GpsGetDevice

GpsGetNumDevices

DWORD GpsGetNumDevices();

Return Value

The number of currently installed GPS Receivers.

Parameters

None.

Remarks

Simple function to return the number of installed GPS devices.

See Also

GpsEnumDevices, GpsGetDevice

GpsEnumDevices

DWORD GpsEnumDevices(LPGPSDEVINFO lpGpsDevInfo, DWORD dwRequestedDevices);

Return Value

The number of GPS devices successfully enumerated.

Parameters

IpGpsDevInfo Pointer to an array of GPSDEVINFO structures which will be filled in upon return from this function.

dwRequestedDevices The number of devices to enumerate.

Remarks

This allow you to retrieve the configuration parameters for any installed GPS device. To enumerate all the currently installed GPS devices, you would set dwRequestedDevices to the return value from GpsGetNumDevices.

GpsDeleteEntry

BOOL GpsDeleteEntry(LPCTSTR lpszEntry);

Return Value

TRUE if the GPS device was successfully removed, otherwise FALSE.

Parameters

lpszEntry The name of the GPS device to remove.

Remarks

Removes an installed GPS device.

See Also

GpsCreateEntry

GpsRenameEntry

BOOL GpsRenameEntry(LPCTSTR lpszOldEntry, LPCTSTR lpszNewEntry);

Return Value

TRUE if the GPS device was successfully renamed, otherwise FALSE.

Parameters

lpszOldEntry The current name of the GPS device.
lpszNewEntry The new name of the GPS device.

Remarks

Renames an already installed GPS receiver.

See Also

GpsCreateEntry, GpsDeleteEntry

GpsPropertiesDlg

BOOL GpsPropertiesDlg(HWND hWnd, LPCTSTR lpszEntry);

Return Value

TRUE if the properties dialog was successfully displayed and the user closed the dialog by using the "OK" button.

Parameters

hWnd The parent window to use to display the properties dialog.
lpszEntry The name of the GPS device to show properties for.

Remarks

Displays the properties dialog associated with an installed GPS receiver. Internally if the dialog is closed using the "OK" button, it's associated properties will be updated and saved.

See Also

GpsCreateEntry, GpsDeleteEntry

GpsOpen

HGPS GpsOpen(LPCTSTR lpszEntry);

Return Value

An abstract HANDLE type (HGPS) which represents an open connection to a GPS receiver. Upon return an invalid handle value is represented by the standard Win32 value INVALID_HANDLE_VALUE

Parameters

lpszEntry The name of the GPS device to open a connection to. If lpszEntry is set to NULL, then the default GPS receiver will be opened.

Remarks

This is the main function a client application would use to retrieve GPS fix. Client applications should also provide a mechanism to bring up the control panel applet by calling GpsShowControlPanel.

GpsClose

BOOL GpsClose(HGPS hEntry);

Return Value

TRUE if the connection to the open GPS receiver was successfully closed.

Parameters

hEntry The handle to the open GPS receiver to close.

Remarks

This function would normally be called just prior to exiting your client GPS application.

See Also

GpsOpen

GpsGetPosition

BOOL GpsGetPosition(HGPS hEntry, LPGPSPOSITION lpPosition);

Return Value

TRUE if the GPS fix for the open GPS connection was retrieved successfully.

Parameters

hEntry The handle to the open GPS connection to retrieve a GPS fix for.
lpPosition A pointer to a GPSPOSITION structure which will be filled in upon successful return from this function.

Remarks

This function should be called periodically by client applications after a successful call to the function GpsOpen. A suggested update period is between 1 - 5 seconds depending on the requirements of the client application. Upon successful return the lpPosition can be used by the client application for whatever purpose required, e.g. In an atlas type program the information could be used to plot the users position and track over a map on the screen.

See Also

GpsOpen, GpsClose, GPSPOSITION

GpsGetVersion

DWORD GpsGetVersion();

Return Value

The current version of GPSLIB encoded as a DWORD.

Parameters

None.

Remarks

Returns the version number of the GPSLIB dll. Currently 0x101 is returned which corresponds to v1.01 of GPSLIB

GpsDeviceNameAlreadyExists

BOOL GpsDeviceNameAlreadyExists(LPCTSTR lpszEntry);

Return Value

TRUE if a the named GPS device is already installed, otherwise FALSE.

Parameters

lpszEntry The name of the GPS device to determine if it is installed.

Remarks

Simple function which internally uses GpsEnumDevices to determine if the named GPS device is already installed. It is used by the control panel applet to ensure uniqueness of the names assigned to devices.

See Also

GpsEnumDevices

GpsShowAboutBox

void GpsShowAboutBox(HWND hWnd);

Return Value

None.

Parameters

hWnd The parent window to use to display the about box.

Remarks

Simple function which displays an "About Box" with version number and copyright information of GPSLIB. It is used by the control panel applet for its "about box".

See Also

GpsGetVersion

GpsGetDevice

BOOL GpsGetDevice(LPCTSTR lpszEntry, LPGPSDEVINFO lpDevice);

Return Value

TRUE if the device was found successfully otherwise FALSE.

Parameters

lpszEntry The name of the GPS device to retrieve settings for.
IpGpsDevInfo Pointer to a GPSDEVINFO structure which will be filled in upon return from this function.

Remarks

Retrieves the settings for a specified GPS device given its name. If lpszEntry is set to NULL, then the settings for the default GPS receiver will be retrieved.

GpsSetDevice

BOOL GpsSetDevice(LPCTSTR lpszEntry, LPCGPSDEVINFO lpGpsDevInfo);

Return Value

TRUE if the device settings were successfully updated otherwise FALSE.

Parameters

lpszEntry The name of the GPS device to update settings for.
IpGpsDevInfo Pointer to a constant GPSDEVINFO structure which contains the parameters to update.

Remarks

Updates the settings for a specified GPS device given its name. You would normally call GpsGetDevice prior to calling this function to ensure that lpGpsDevInfo contains valid members.

Structures used by GPSLIB

GPSDEVINFO Structure

typedef struct tagGPSDEVINFO
{
    TCHAR szDeviceName[ GPS_MaxDeviceName + 1 ];
    BOOL bDefaultReceiver;
    WORD wCommPort;
    DWORD dwCommBaudRate;
    WORD wCommDataBits;
    WORD wCommParity;
    WORD wCommStopBits;
} GPSDEVINFO;

The GPSDEVINFO structure represents a GPS receivers device properties.

Members

szDeviceName	The name of the GPS Device
bDefaultReceiver	TRUE if this device is the default receiver else FALSE
wCommPort	The serial communications port this GPS receiver is connected to
dwCommBaudRate	The baud rate used to connect to this device.
wCommDataBits	Data bits of the comms port used to connect to this device
wCommParity	Enum of the type of parity used to connect to this device. This member is one of the following enums: GpsParityNone GpsParityOdd GpsParityEven GpsParityMark GpsParitySpace
wCommStopBits	Enum of the stop bits used to connect to this device. This member is one of the following enums: GpsStopBits1 GpsStopBits1Point5 GpsStopBits2

See Also

GpsEnumDevices

GPSPOSITION Structure

typedef struct tagGPSPOSITION
{
    BOOL bNorthing;
    DWORD dwLatitude;
    BOOL bEasting;
    DWORD dwLongitude;
    DWORD dwBearing;
    DWORD dwSpeed;
    WORD wFixYear;
    WORD wFixMonth;
    WORD wFixDay;
    WORD wFixHour;
    WORD wFixMinute;
    WORD wFixSecond;
    WORD nSatellites;
    DWORD dwAntennaAltitude;
    WORD wQualityIndicator;
} GPSPOSITION;

Members

bNorthing	TRUE if reported position is north of the equator else FALSE.
dwLatitude	Latitude of the reported position in hundredths of seconds of a degree. This value along with bNorthing is retrieved from the NMEA command "GPRMC"
bEasting	TRUE if reported position is east of the Greenwich Prime Meridian else FALSE
dwLongitude	Longitude in hundredths of seconds of a degree. This value along with bEasting is retrieved from the NMEA command "GPRMC"
dwBearing	The bearing in hundredths of degrees East of North. This value is retrieved from the NMEA command "GPRMC". This corresponds to the compass direction in which the receiver is traveling.
dwSpeed	Speed in Centimeters / Hour. This value is retrieved from the NMEA command "GPRMC". This corresponds to the speed at which the receiver is traveling.
wFixYear	The year in which the GPS location fix was taken. This value is retrieved from the NMEA command "GPRMC"
wFixMonth	The month in which the GPS location fix was taken. This value is retrieved from the NMEA command "GPRMC"
wFixDay	The day in which the GPS location fix was taken. This value is retrieved from the NMEA command "GPRMC"
wFixHour	The hour in which the GPS location fix was taken. This value is retrieved from the NMEA command "GPRMC"
wFixMinute	The minute in which the GPS location fix was taken. This value is retrieved from the NMEA command "GPRMC"
wFixSecond	The second in which the GPS location fix was taken. This value is retrieved from the NMEA command "GPRMC"
nSatellites	The number of satellites in view. This value is retrieved from the NMEA command "GPGGA"
dwAntennaAltitude	Altitude of the receiver in Centimeters above mean sea level. This value is retrieved from the NMEA command "GPGGA"
wQualityIndicator	Enum of the GPS Quality Indicator. This value is retrieved from the NMEA command "GPGGA". This member is one of the following enums: GpsQualityFixNotAvailable GpsQualityFix GpsQualityDifferentialFix

SHAREWARE NOTICE:

GPSLIB is shareware and this trial version is a fully functional evaluation copy. This means that you are free to evaluate GPSLIB for up to 30 days. After this period if you are still using GPSLIB and/or wish to include it in a project of yours, then you are legally obliged to register GPSLIB with the author. Registration will entitle you to comprehensive email support from the author. The cost is $20 US dollars. I do not support online registration for this product yet so you must register via normal post. Remember to include your email address in your letter so that I can quickly confirm receipt of your registration. Payment should be made by cheque and be made out to:

PJ Naughter,
Clonganny,
Ballygarrett,
Gorey,
Co. Wexford.

Ireland

The registration fee is very small and its a great incentive for me to keep improving GPSLIB. Once I have received the registration you are entitled to unlimited email support for GPSLIB.

PLANNED ENHANCEMENTS

Provide an MFC wrapper class to provide a C++ interface to GPSLIB.
Remove dependency of GPSLIB control panel applet upon MFC. This should help reduce the size of it significantly.
Rebase the GPSLIB DLLs to improve the load time of client applications.
Provide support for multiple client applications using the same GPS device at the same time. An interesting technical challenge which will require development of a framework similar to the way TAPI is implemented.
If you have any other suggested improvements for GPSLIB, please let me know so that I can incorporate them into the next release of GPSLIB.

CONTACTING THE AUTHOR

PJ Naughter
Email: pjna@naughter.com
Web: http://www.naughter.com
21 August 2002