mirror
/
Hamlib
kopia lustrzana https://github.com/Hamlib/Hamlib
1
0
Forkuj 0
Kod Zgłoszenia Projekty Wydania Wiki Aktywność

Update Doxygen comments and main page

pull/701/head
Nate Bargmann 2021-05-16 21:10:31 -05:00
rodzic 47cf245826
commit 0ed6b11088
Nie znaleziono w bazie danych klucza dla tego podpisu
ID klucza GPG: F72625E2EDBED598
2 zmienionych plików z 282 dodań i 172 usunięć
Pokaż statystyki Ściągnij plik aktualizacji Ściągnij plik porównania Expand all files Collapse all files

70
doc/index.doxygen
Wyświetl plik

@ -1,10 +1,5 @@
/*! \mainpage Hamlib API Reference /*! \mainpage Hamlib API Reference
\section auth Authors
Stéphane Fillod, F8CFE, and Frank Singleton, VK3FCS and the Hamlib Group
\n Documentation revisions by Martin Ewing, AA6E, Nate Bargmann, N0NB, Michael Black, W9MDB
\section s1 Preface \section s1 Preface
This document describes the Hamlib library Application Programming Interface This document describes the Hamlib library Application Programming Interface
@ -14,18 +9,24 @@ We attempt to document the complete API of the core modules of Hamlib, i.e.
the API seen by end-user application developers. You may navigate the the API seen by end-user application developers. You may navigate the
documentation through the tabs at the top of this page. documentation through the tabs at the top of this page.
\note This documentation is a work in progress.
Please report any problems to hamlib-developer@lists.sourceforge.net. Please report any problems to hamlib-developer@lists.sourceforge.net.
\section txtfil Distributed information files \section txtfil Distributed information files
These text files are distributed with the Hamlib package. These text files are distributed with the Hamlib package.
Readme files: \subpage Rdme "General"; \li Readme files: \subpage Rdme "General";
\subpage Rdmebeta "Beta Tester"; \subpage Rdmebeta "Beta Tester";
\subpage Rdmedevel "Developer"; \subpage Rdmedevel "Developer";
\subpage Rdmewin "MS Windows" \subpage Rdmewin "MS Windows";
\subpage Rdmeosx "Mac OS X";
\subpage Rdmefrq "Frequency range changes";
\subpage Rdmemulti "Multicast support";
\subpage Security "Security policy";
Other files: \subpage INSTALL; \li Other files: \subpage INSTALL;
\subpage AUTHORS; \subpage AUTHORS;
\subpage COPYING; \subpage COPYING;
\subpage COPYING.LIB; \subpage COPYING.LIB;
@ -44,10 +45,20 @@ Other files: \subpage INSTALL;
\section slic Documentation License \section slic Documentation License
\li \subpage doclicense \li \subpage doclicense
\section auth Authors
\li Stéphane Fillod, F8CFE, and Frank Singleton, VK3FCS and the Hamlib Group
\li Documentation revisions by Martin Ewing, AA6E, Nate Bargmann, N0NB,
Michael Black, W9MDB and many others.
*/ */
/* Subpage definitions follow. */
/*! \page doclicense License for Documentation /*! \page doclicense License for Documentation
This documentation is free; you can redistribute it without This documentation is free; you can redistribute it without
any restrictions. The modification or derived work must retain any restrictions. The modification or derived work must retain
copyright and list all authors. copyright and list all authors.
This documentation is distributed in the hope that it will be This documentation is distributed in the hope that it will be
@ -58,48 +69,81 @@ of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
/*! \page Rdme README (general) /*! \page Rdme README (general)
\verbinclude README \verbinclude README
*/ */
/*! \page Rdmebeta README.betatester /*! \page Rdmebeta README.betatester
\verbinclude README.betatester \verbinclude README.betatester
*/ */
/*! \page Rdmedevel README.developer /*! \page Rdmedevel README.developer
\verbinclude README.developer \verbinclude README.developer
*/ */
/*! \page Rdmewin Cross-compiling Hamlib on Linux for MS Windows /*! \page Rdmewin Cross-compiling Hamlib on Linux for MS Windows
This page contains the `scripts/README.build-Windows` instructions and the This page contains the `scripts/README.build-Windows` instructions and the
`scripts/build-w32.sh` file that describe cross-compiling Hamlib for MS `scripts/build-w32.sh` and `scripts/build-w64.h` files that describe
Windows 32 bit on Debian GNU/Linux. cross-compiling Hamlib for MS Windows 32 and 64 bit versions on Debian
GNU/Linux.
\tableofcontents
\section Build README.build-Windows \section Build README.build-Windows
\verbinclude README.build-Windows \verbinclude README.build-Windows
\subsection W32 The build-w32.sh script \subsection W32 The build-w32.sh script
\verbinclude build-w32.sh \include{lineno} build-w32.sh
\subsection W64 The build-w64.sh script \subsection W64 The build-w64.sh script
\verbinclude build-w64.sh \include{lineno} build-w64.sh
*/ */
/*! \page Rdmeosx README.osx
\verbinclude README.osx
*/
/*! \page Rdmefrq README.freqranges
\verbinclude README.freqranges
*/
/*! \page Rdmemulti README.multicast
\verbinclude README.multicast
*/
/* FIXME: figure out how to include Markdown for HTML output. */
/*! \page Security SECURITY.md
\include SECURITY.md
*/
/*! \page INSTALL INSTALL /*! \page INSTALL INSTALL
\verbinclude INSTALL \verbinclude INSTALL
*/ */
/*! \page AUTHORS AUTHORS /*! \page AUTHORS AUTHORS
\verbinclude AUTHORS \verbinclude AUTHORS
*/ */
/*! \page COPYING COPYING /*! \page COPYING COPYING
\verbinclude COPYING \verbinclude COPYING
*/ */
/*! \page COPYING.LIB COPYING.LIB /*! \page COPYING.LIB COPYING.LIB
\verbinclude COPYING.LIB \verbinclude COPYING.LIB
*/ */
/*! \page LICENSE LICENSE /*! \page LICENSE LICENSE
\verbinclude LICENSE \verbinclude LICENSE
*/ */
/*! \page NEWS NEWS /*! \page NEWS NEWS
\verbinclude NEWS \verbinclude NEWS
*/ */
/*! \page PLAN PLAN /*! \page PLAN PLAN
\verbinclude PLAN \verbinclude PLAN
*/ */
/*! \page THANKS THANKS /*! \page THANKS THANKS
\verbinclude THANKS \verbinclude THANKS
*/ */
/* Defined API groups--sections included with addtogroup in sources. */
/*! Define groups for Doxygen /*! Define groups for Doxygen
* \defgroup rig Rig (transceiver) API * \defgroup rig Rig (transceiver) API
* \defgroup rig_internal Rig (transceiver) Internal API * \defgroup rig_internal Rig (transceiver) Internal API

384
src/locator.c
Wyświetl plik

@ -1,17 +1,3 @@
/**
* \addtogroup utilities
* @{
*/
/**
* \file src/locator.c
* \brief locator and bearing conversion interface
* \author Stephane Fillod and the Hamlib Group
* \date 2000-2010
*
* Hamlib Interface - locator, bearing, and conversion calls
*/
/* /*
* Hamlib Interface - locator and bearing conversion calls * Hamlib Interface - locator and bearing conversion calls
* Copyright (c) 2001-2010 by Stephane Fillod * Copyright (c) 2001-2010 by Stephane Fillod
@ -47,12 +33,49 @@
* *
*/ */
/*! \page hamlib Hamlib general purpose API
* /**
* Here are grouped some often used functions, like locator conversion * \addtogroup utilities
* routines. * @{
*/ */
/**
* \file src/locator.c
*
* \brief QRA locator (Maidenhead grid square) and latitude/longitude bearing
* conversion interface.
*
* \author Stephane Fillod
* \author Nate Bargmann
* \author Dave Hines
* \author The Hamlib Group
* \date 2000-2020
*/
/**
* \page hamlib Hamlib general purpose API
*
* Hamlib function call interface for determining QRA locator (Maidenhead grid
* square), bearing, and conversion between QRA locator and latitude/longitude
* formats.
*
* \par Sources used in writing these routines
*
* \parblock
* Code to determine bearing and range was taken from the Great Circle,
* by Steven R. Sampson, N5OWK.<br />
* Ref: "Air Navigation", Air Force Manual 51-40, 1 February 1987<br />
* Ref: "ARRL Satellite Experimenters Handbook", August 1990
*
* Code to calculate distance and azimuth between two QRA locators, taken from
* wwl, by IK0ZSN, Mirko Caserta.
*
* New bearing code added by N0NB was found at:
* http://williams.best.vwh.net/avform.htm#Crs
* \endparblock
*/
#ifdef HAVE_CONFIG_H #ifdef HAVE_CONFIG_H
# include "config.h" # include "config.h"
#endif #endif
@ -67,74 +90,93 @@
#include <hamlib/rotator.h> #include <hamlib/rotator.h>
#ifndef DOC_HIDDEN /** \brief Standard definition of a radian. */
#define RADIAN (180.0 / M_PI) #define RADIAN (180.0 / M_PI)
/* arc length for 1 degree, 60 Nautical Miles */ /** \brief arc length for 1 degree in kilometers, i.e. 60 Nautical Miles */
#define ARC_IN_KM 111.2 #define ARC_IN_KM 111.2
/* The following is contributed by Dave Hines M1CXW /* The following is contributed by Dave Hines M1CXW
* *
* begin dph * begin dph
*/ */
/*
* These are the constants used when converting between Maidenhead grid /* At this time documenting a single static variable as in loc_char_range[]
* locators and longitude/latitude values. MAX_LOCATOR_PAIRS is the maximum * below is not supported by Doxygen. Hide this section until support exists
* number of locator character pairs to convert. This number MUST NOT exceed * or a work-around becomes available.
* the number of pairs of values in loc_char_range[]. */
* Setting MAX_LOCATOR_PAIRS to 3 will convert the currently defined 6 #ifndef DOC_HIDDEN
* character locators. A value of 4 will convert the extended 8 character
* locators described in section 3L of "The IARU region 1 VHF managers /**
* handbook". Values of 5 and 6 will extent the format even more, to the * \brief Constants used when converting between Maidenhead grid
* longest definition I have seen for locators, see * locators and longitude/latitude values.
* http://www.btinternet.com/~g8yoa/geog/non-ra.html
* Beware that there seems to be no universally accepted standard for 10 & 12
* character locators.
* *
* The ranges of characters which will be accepted by locator2longlat, and * \ref MAX_LOCATOR_PAIRS is the maximum number of locator character pairs to
* generated by longlat2locator, are specified by the loc_char_range[] array. * convert. This number MUST NOT exceed the number of pairs of values in
* This array may be changed without requiring any other code changes. * loc_char_range[]. Setting \ref MAX_LOCATOR_PAIRS to 3 will convert the
* currently defined 6 character locators. A value of 4 will convert the
* extended 8 character locators described in section 3L of "The IARU region 1
* VHF managers handbook". Values of 5 and 6 will extent the format even
* more, to the longest definition I have seen for locators, see
* http://www.btinternet.com/~g8yoa/geog/non-ra.html (currently a dead
* link. -N0NB). Be aware that there seems to be no universally accepted
* standard for 10 & 12 character locators.
*
* The ranges of characters which will be accepted by locator2longlat(), and
* generated by longlat2locator(), are specified by the \ref loc_char_range[]
* array. This array may be changed without requiring any other code changes.
* *
* For the fifth pair to range from aa to xx use: * For the fifth pair to range from aa to xx use:
* const static int loc_char_range[] = { 18, 10, 24, 10, 24, 10 }; * \code const static int loc_char_range[] = { 18, 10, 24, 10, 24, 10 };\endcode
* *
* For the fifth pair to range from aa to yy use: * For the fifth pair to range from aa to yy use:
* const static int loc_char_range[] = { 18, 10, 24, 10, 25, 10 }; * \code const static int loc_char_range[] = { 18, 10, 24, 10, 25, 10 };\endcode
*
* MAX_LOCATOR_PAIRS now sets the limit locator2longlat() will convert and
* sets the maximum length longlat2locator() will generate. Each function
* properly handles any value from 1 to 6 so MAX_LOCATOR_PAIRS should be
* left at 6. MIN_LOCATOR_PAIRS sets a floor on the shortest locator that
* should be handled. -N0NB
*/ */
const static int loc_char_range[] = { 18, 10, 24, 10, 24, 10 }; const static int loc_char_range[] = { 18, 10, 24, 10, 24, 10 };
#endif /* !DOC_HIDDEN */
/** \def MAX_LOCATOR_PAIRS
*
* \brief Longest locator to process, e.g. AA00AA00AA00.
*
* Sets the limit locator2longlat() will convert and sets the maximum length
* longlat2locator() will generate. Each function properly handles any value
* from `1` to `6` so \ref MAX_LOCATOR_PAIRS should be left at `6`.
*
* \def MIN_LOCATOR_PAIRS
*
* \brief Shortest locator to process, e.g. AA.
*
* Sets a floor on the shortest locator that should be handled.
*/
#define MAX_LOCATOR_PAIRS 6 #define MAX_LOCATOR_PAIRS 6
#define MIN_LOCATOR_PAIRS 1 #define MIN_LOCATOR_PAIRS 1
/* end dph */ /* end dph */
#endif /* !DOC_HIDDEN */
/** /**
* \brief Convert DMS to decimal degrees * \brief Convert Degrees Minutes Seconds (DMS) notation to decimal degrees
* \param degrees Degrees, whole degrees * (D.DDD) angle.
* \param minutes Minutes, whole minutes
* \param seconds Seconds, decimal seconds
* \param sw South or West
* *
* Convert degree/minute/second angle to decimal degrees angle. * \param degrees Degrees, whole degrees.
* \a degrees >360, \a minutes > 60, and \a seconds > 60.0 are allowed, * \param minutes Minutes, whole minutes.
* but resulting angle won't be normalized. * \param seconds Seconds, decimal seconds.
* \param sw South or West.
* *
* When the variable sw is passed a value of 1, the returned decimal * Convert a Degrees Minutes Seconds (DMS) notation value to a decimal degrees
* degrees value will be negative (south or west). When passed a * (D.DDD) angle value.
* value of 0 the returned decimal degrees value will be positive
* (north or east).
* *
* \return The angle in decimal degrees. * \note For the parameters \a degrees >360, \a minutes > 60, and \a seconds >
* 60.0 are allowed, but the resulting angle will not be normalized.
*
* When the variable \a sw is passed a value of 1, the returned decimal
* degrees value will be negative (*South* or *West*). When passed a value of 0
* the returned decimal degrees value will be positive (*North* or *East*).
*
* \return The signed angle in decimal degrees (D.DDD).
* *
* \sa dec2dms() * \sa dec2dms()
*/ */
@ -173,23 +215,25 @@ double HAMLIB_API dms2dec(int degrees, int minutes, double seconds, int sw)
/** /**
* \brief Convert D M.MMM notation to decimal degrees * \brief Convert degrees decimal minutes (D M.MMM) notation to decimal
* \param degrees Degrees, whole degrees * degrees (D.DDD) angle.
* \param minutes Minutes, decimal minutes
* \param sw South or West
* *
* Convert a degrees, decimal minutes notation common on * \param degrees Degrees, whole degrees.
* many GPS units to its decimal degrees value. * \param minutes Minutes, decimal minutes.
* \param seconds Seconds, decimal seconds.
* \param sw South or West.
* *
* \a degrees > 360, \a minutes > 60.0 are allowed, but * Convert a degrees decimal minutes (D M.MMM) notation common on many GPS
* resulting angle won't be normalized. * units to a decimal degrees (D.DDD) angle value.
* *
* When the variable sw is passed a value of 1, the returned decimal * \note For the parameters \a degrees > 360, \a minutes > 60.0, \a seconds >
* degrees value will be negative (south or west). When passed a * 60.0 are allowed, but the resulting angle will not be normalized.
* value of 0 the returned decimal degrees value will be positive
* (north or east).
* *
* \return The angle in decimal degrees. * When the variable \a sw is passed a value of 1, the returned decimal
* degrees value will be negative (*South* or *West*). When passed a value of
* 0 the returned decimal degrees value will be positive (*North* or *East*).
*
* \return The signed angle in decimal degrees (D.DDD).
* *
* \sa dec2dmmm() * \sa dec2dmmm()
*/ */
@ -223,29 +267,33 @@ double HAMLIB_API dmmm2dec(int degrees, double minutes, double seconds, int sw)
/** /**
* \brief Convert decimal degrees angle into DMS notation * \brief Convert a decimal degrees (D.DDD) angle into Degrees Minutes
* \param dec Decimal degrees * Seconds (DMS) notation.
* \param degrees Pointer for the calculated whole Degrees
* \param minutes Pointer for the calculated whole Minutes
* \param seconds Pointer for the calculated decimal Seconds
* \param sw Pointer for the calculated SW flag
* *
* Convert decimal degrees angle into its degree/minute/second * \param dec Decimal degrees (D.DDD).
* notation. * \param degrees Pointer for the calculated whole Degrees.
* \param minutes Pointer for the calculated whole Minutes.
* \param seconds Pointer for the calculated decimal Seconds.
* \param sw Pointer for the calculated SW (South/West) flag.
* *
* When \a dec < -180 or \a dec > 180, the angle will be normalized * Convert decimal degrees angle (D.DDD) into its Degree Minute Second (DMS)
* within these limits and the sign set appropriately. * notation.
* *
* Upon return dec2dms guarantees 0 >= \a degrees <= 180, * When \a dec < -180 or \a dec > 180, the angle will be normalized within
* 0 >= \a minutes < 60, and 0.0 >= \a seconds < 60.0. * these limits and the sign set appropriately.
* *
* When \a dec is < 0.0 \a sw will be set to 1. When \a dec is * Upon return, guarantees 0 >= \a degrees <= 180, 0 >= \a minutes < 60, and
* >= 0.0 \a sw will be set to 0. This flag allows the application * 0.0 >= \a seconds < 60.0.
* to determine whether the DMS angle should be treated as negative
* (south or west).
* *
* \retval -RIG_EINVAL if any of the pointers are NULL. * When \a dec is < 0.0 \a sw will be set to 1. When \a dec is >= 0.0 \a sw
* \retval RIG_OK if conversion went OK. * will be set to 0. This flag allows the application to determine whether
* the DMS angle should be treated as negative (*South* or *West*).
*
* \return RIG_OK if the operation has been successful, otherwise a **negative
* value** if an error occurred (in which case, cause is set appropriately).
*
* \retval RIG_OK The conversion was successful.
* \retval RIG_EINVAL Either of the pointers are NULL.
* *
* \sa dms2dec() * \sa dms2dec()
*/ */
@ -317,28 +365,33 @@ int HAMLIB_API dec2dms(double dec,
/** /**
* \brief Convert a decimal angle into D M.MMM notation * \brief Convert a decimal degrees (D.DDD) angle into degrees decimal minutes
* \param dec Decimal degrees * (D M.MMM) notation.
* \param degrees Pointer for the calculated whole Degrees
* \param minutes Pointer for the calculated decimal Minutes
* \param sw Pointer for the calculated SW flag
* *
* Convert a decimal angle into its degree, decimal minute * \param dec Decimal degrees angle.
* notation common on many GPS units. * \param degrees Pointer for the calculated whole Degrees.
* \param minutes Pointer for the calculated decimal Minutes.
* \param sw Pointer for the calculated SW flag.
* *
* When passed a value < -180 or > 180, the value will be normalized * Convert a decimal angle into its degree, decimal minute
* within these limits and the sign set apropriately. * notation common on many GPS units.
* *
* Upon return dec2dmmm guarantees 0 >= \a degrees <= 180, * When passed a value < -180 or > 180, the value will be normalized
* 0.0 >= \a minutes < 60.0. * within these limits and the sign set apropriately.
* *
* When \a dec is < 0.0 \a sw will be set to 1. When \a dec is * Upon return dec2dmmm guarantees 0 >= \a degrees <= 180,
* >= 0.0 \a sw will be set to 0. This flag allows the application * 0.0 >= \a minutes < 60.0.
* to determine whether the D M.MMM angle should be treated as negative
* (south or west).
* *
* \retval -RIG_EINVAL if any of the pointers are NULL. * When \a dec is < 0.0 \a sw will be set to 1. When \a dec is
* \retval RIG_OK if conversion went OK. * >= 0.0 \a sw will be set to 0. This flag allows the application
* to determine whether the D M.MMM angle should be treated as negative
* (south or west).
*
* \return RIG_OK if the operation has been successful, otherwise a **negative
* value** if an error occurred (in which case, cause is set appropriately).
*
* \retval RIG_OK The conversion was successful.
* \retval RIG_EINVAL Either of the pointers are NULL.
* *
* \sa dmmm2dec() * \sa dmmm2dec()
*/ */
@ -369,23 +422,27 @@ int HAMLIB_API dec2dmmm(double dec, int *degrees, double *minutes, int *sw)
/** /**
* \brief Convert Maidenhead grid locator to Longitude/Latitude * \brief Convert QRA locator (Maidenhead grid square) to Longitude/Latitude.
* \param longitude Pointer for the calculated Longitude
* \param latitude Pointer for the calculated Latitude
* \param locator The Maidenhead grid locator--2 through 12 char + nul string
* *
* Convert Maidenhead grid locator to Longitude/Latitude (decimal degrees). * \param longitude Pointer for the calculated Longitude.
* The locator should be in 2 through 12 chars long format. * \param latitude Pointer for the calculated Latitude.
* \a locator2longlat is case insensitive, however it checks for * \param locator The QRA locator--2 through 12 characters + nul string.
* locator validity.
* *
* Decimal long/lat is computed to center of grid square, i.e. given * Convert a QRA locator string to Longitude/Latitude in decimal degrees
* EM19 will return coordinates equivalent to the southwest corner * (D.DDD). The locator should be 2 through 12 chars long format.
* of EM19mm. * \a locator2longlat is case insensitive, however it checks for locator
* validity.
* *
* \retval -RIG_EINVAL if locator exceeds RR99xx99xx99 or exceeds length * Decimal long/lat is computed to center of grid square, i.e. given
* limit--currently 1 to 6 lon/lat pairs. * `EM19` will return coordinates equivalent to the southwest corner
* \retval RIG_OK if conversion went OK. * of `EM19mm`.
*
* \return RIG_OK if the operation has been successful, otherwise a **negative
* value** if an error occurred (in which case, cause is set appropriately).
*
* \retval RIG_OK The conversion was successful.
* \retval RIG_EINVAL The QRA locator exceeds RR99xx99xx99 or exceeds length
* limit--currently 1 to 6 lon/lat pairs--or is otherwise malformed.
* *
* \bug The fifth pair ranges from aa to xx, there is another convention * \bug The fifth pair ranges from aa to xx, there is another convention
* that ranges from aa to yy. At some point both conventions should be * that ranges from aa to yy. At some point both conventions should be
@ -461,23 +518,29 @@ int HAMLIB_API locator2longlat(double *longitude,
/** /**
* \brief Convert longitude/latitude to Maidenhead grid locator * \brief Convert longitude/latitude to QRA locator (Maidenhead grid square).
* \param longitude Longitude, decimal degrees
* \param latitude Latitude, decimal degrees
* \param locator Pointer for the Maidenhead Locator
* \param pair_count Precision expressed as lon/lat pairs in the locator
* *
* Convert longitude/latitude (decimal degrees) to Maidenhead grid locator. * \param longitude Longitude, decimal degrees.
* \a locator must point to an array at least \a pair_count * 2 char + '\\0'. * \param latitude Latitude, decimal degrees.
* \param locator Pointer for the QRA Locator.
* \param pair_count Requested precision expressed as lon/lat pairs in the
* returned QRA locator string.
* *
* \retval -RIG_EINVAL if \a locator is NULL or \a pair_count exceeds * Convert longitude/latitude given in decimal degrees (D.DDD) to a QRA
* length limit. Currently 1 to 6 lon/lat pairs. * locator (Maidenhead grid square). \a locator must point to an array length
* \retval RIG_OK if conversion went OK. * that is at least \a pair_count * 2 char + '\\0'.
*
* \return RIG_OK if the operation has been successful, otherwise a **negative
* value** if an error occurred (in which case, cause is set appropriately).
*
* \retval RIG_OK The conversion was successful.
* \retval RIG_EINVAL if \a locator is NULL or \a pair_count exceeds length
* limit. Currently 1 to 6 lon/lat pairs.
* *
* \bug \a locator is not tested for overflow. * \bug \a locator is not tested for overflow.
* \bug The fifth pair ranges from aa to yy, there is another convention * \bug The fifth pair ranges from aa to yy, there is another convention
* that ranges from aa to xx. At some point both conventions should be * that ranges from aa to xx. At some point both conventions should be
* supported. * supported.
* *
* \sa locator2longlat() * \sa locator2longlat()
*/ */
@ -531,26 +594,28 @@ int HAMLIB_API longlat2locator(double longitude,
/** /**
* \brief Calculate the distance and bearing between two points. * \brief Calculate the distance and bearing between two points.
* \param lon1 The local Longitude, decimal degrees
* \param lat1 The local Latitude, decimal degrees
* \param lon2 The remote Longitude, decimal degrees
* \param lat2 The remote Latitude, decimal degrees
* \param distance Pointer for the distance, km
* \param azimuth Pointer for the bearing, decimal degrees
* *
* Calculate the QRB between \a lon1, \a lat1 and \a lon2, \a lat2. * \param lon1 The local Longitude, decimal degrees.
* \param lat1 The local Latitude, decimal degrees,
* \param lon2 The remote Longitude, decimal degrees.
* \param lat2 The remote Latitude, decimal degrees.
* \param distance Pointer for the distance, km.
* \param azimuth Pointer for the bearing, decimal degrees.
* *
* This version will calculate the QRB to a precision sufficient * Calculate the distance and bearing (QRB) between \a lon1, \a lat1 and
* for 12 character locators. Antipodal points, which are easily * \a lon2, \a lat2.
* calculated, are considered equidistant and the bearing is
* simply resolved to be true north (0.0°).
* *
* \retval -RIG_EINVAL if NULL pointer passed or lat and lon values * This version will calculate the QRB to a precision sufficient for 12
* character locators. Antipodal points, which are easily calculated, are
* considered equidistant and the bearing is simply resolved to be true north,
* e.g. \a azimuth = 0.0.
*
* \return RIG_OK if the operation has been successful, otherwise a **negative
* value** if an error occurred (in which case, cause is set appropriately).
*
* \retval RIG_OK The calculations were successful.
* \retval RIG_EINVAL If a NULL pointer passed or \a lat and \a lon values
* exceed -90 to 90 or -180 to 180. * exceed -90 to 90 or -180 to 180.
* \retval RIG_OK if calculations are successful.
*
* \return The distance in kilometers and azimuth in decimal degrees
* for the short path are stored in \a distance and \a azimuth.
* *
* \sa distance_long_path(), azimuth_long_path() * \sa distance_long_path(), azimuth_long_path()
*/ */
@ -664,12 +729,13 @@ int HAMLIB_API qrb(double lon1,
/** /**
* \brief Calculate the long path distance between two points. * \brief Calculate the long path distance between two points.
* \param distance The shortpath distance
* *
* Calculate the long path (respective of the short path) * \param distance The shortpath distance in kilometers.
* of a given distance.
* *
* \return the distance in kilometers for the opposite path. * Calculate the long path (opposite bearing of the short path) of a given
* distance.
*
* \return The distance in kilometers for the opposite path.
* *
* \sa qrb() * \sa qrb()
*/ */
@ -683,13 +749,13 @@ double HAMLIB_API distance_long_path(double distance)
/** /**
* \brief Calculate the long path bearing between two points. * \brief Calculate the long path bearing between two points.
* \param azimuth The shortpath bearing--0.0 to 360.0 degrees
* *
* Calculate the long path (respective of the short path) * \param azimuth The shortpath bearing--0.0 to 360.0 degrees.
* of a given bearing.
* *
* \return the azimuth in decimal degrees for the opposite path or * Calculate the long path (opposite of the short path) of a given bearing.
* -RIG_EINVAL upon input error (outside the range of 0.0 to 360.0). *
* \return the azimuth in decimal degrees for the opposite path or RIG_EINVAL
* (negated value) upon input error (outside the range of 0.0 to 360.0).
* *
* \sa qrb() * \sa qrb()
*/ */