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

Merge pull request #701 from N0NB/doxygen_work 

Doxygen work
Hamlib-4.2
Nate Bargmann 2021-05-16 21:26:14 -05:00 zatwierdzone przez GitHub
rodzic 47cf245826 b679b0c753
commit fbd07524e2
Nie znaleziono w bazie danych klucza dla tego podpisu
ID klucza GPG: 4AEE18F83AFDEB23
4 zmienionych plików z 304 dodań i 185 usunięć
Pokaż statystyki Ściągnij plik aktualizacji Ściągnij plik porównania Expand all files Collapse all files

17
NEWS
Wyświetl plik

@ -7,14 +7,14 @@ Copyright (C) 2000-2021 Michael Black W9MDB, and others
Please send Hamlib bug reports to hamlib-developer@lists.sourceforge.net
Version 4.2
* 2021-04-27
* 2021-05-17
* New rig_get_mode_bandwidths -- returns token set for bandwidths for given mode
Rig command: \get_mode_bandwidths CW
Mode=CW
Normal=500Hz
Narrow=50Hz
Wide=2400Hz
* New rig_get_info -- returns token set for all vfos where order does not matter
* New rig_get_info -- returns token set for all vfos where order does not matter
This is a string return to allow for easy future expansion without changing the API
New tokens may be introduced and can be skipped if not used by clients
Rig command: \get_rig_info
@ -37,13 +37,18 @@ Version 4.2
* USRP lib and gnuradio are deprecated and will be removed in 5.0
* Added Radan rotator
* Added Malachite SDR
* Added Malachite SDR
* Major rework for PRM80
* Add twiddle_timeout and twiddle_rit --set-conf options
rigctld --set-conf=twiddle_timeout=5,twiddle_rit=1
rigctld --set-conf=twiddle_timeout=5,twiddle_rit=1
This will set the twiddle timeout to 5 seconds and turn on twiddle_rit
For twiddle timeout VFOB will not be polled for 5 seconds after VFO twiddling is detected
rigctld --twiddle is deprecated and will be removed in 5.0 along with get_twiddle and set_twiddle
For twiddle timeout VFOB will not be polled for 5 seconds after VFO twiddling
is detected
* rigctld --twiddle is deprecated and will be removed in 5.0 along with
get_twiddle and set_twiddle
* Rework Doxygen manual including default layout for Doxygen 1.9.1. So far
the amplifier, rotator, and utilities API sections have been updated. The
rig (radio) section remains to be updated.
Version 4.1
2021-01-31

18
README.freqranges
Wyświetl plik

@ -1,9 +1,15 @@
Frequency ranges are being changed to reflect rig capabilities instead of region restrictions
As of 2020-05-05 the behavior is:
#1 Any range which shows ITU# or TBD has not been modified to this convention
#2 Ranges on the backends are being change to USA/EUR/KOR/TPE/ITR per the IC-9700 convention. So if you see one of those monikers on a rig's freq range it should accurately reflect the rig's capabilities.
Frequency ranges are being changed to reflect rig capabilities instead of
region restrictions
Note that most rigs will have just USA or USA/EUR models. Not too many rigs have more than 2 models but it appears at least Icom is headed that way.
As of 2020-05-05 the behavior is:
#1 Any range which shows ITU# or TBD has not been modified to this convention
#2 Ranges on the backends are being change to USA/EUR/KOR/TPE/ITR per the
IC-9700 convention. So if you see one of those monikers on a rig's freq
range it should accurately reflect the rig's capabilities.
Note that most rigs will have just USA or USA/EUR models. Not too many rigs
have more than 2 models but it appears at least Icom is headed that way.
USA - United States of America
EUR - Europe
@ -12,5 +18,3 @@ TPE - Japan
ITR - ??
AUS - Australia
CHN - China

70
doc/index.doxygen
Wyświetl plik

@ -1,10 +1,5 @@
/*! \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
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
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.
\section txtfil Distributed information files
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 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 COPYING;
\subpage COPYING.LIB;
@ -44,10 +45,20 @@ Other files: \subpage INSTALL;
\section slic Documentation License
\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
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.
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)
\verbinclude README
*/
/*! \page Rdmebeta README.betatester
\verbinclude README.betatester
*/
/*! \page Rdmedevel README.developer
\verbinclude README.developer
*/
/*! \page Rdmewin Cross-compiling Hamlib on Linux for MS Windows
This page contains the `scripts/README.build-Windows` instructions and the
`scripts/build-w32.sh` file that describe cross-compiling Hamlib for MS
Windows 32 bit on Debian GNU/Linux.
`scripts/build-w32.sh` and `scripts/build-w64.h` files that describe
cross-compiling Hamlib for MS Windows 32 and 64 bit versions on Debian
GNU/Linux.
\tableofcontents
\section Build README.build-Windows
\verbinclude README.build-Windows
\subsection W32 The build-w32.sh script
\verbinclude build-w32.sh
\include{lineno} build-w32.sh
\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
\verbinclude INSTALL
*/
/*! \page AUTHORS AUTHORS
\verbinclude AUTHORS
*/
/*! \page COPYING COPYING
\verbinclude COPYING
*/
/*! \page COPYING.LIB COPYING.LIB
\verbinclude COPYING.LIB
*/
/*! \page LICENSE LICENSE
\verbinclude LICENSE
*/
/*! \page NEWS NEWS
\verbinclude NEWS
*/
/*! \page PLAN PLAN
\verbinclude PLAN
*/
/*! \page THANKS THANKS
\verbinclude THANKS
*/
/* Defined API groups--sections included with addtogroup in sources. */
/*! Define groups for Doxygen
* \defgroup rig Rig (transceiver) 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
* 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
* routines.
/**
* \addtogroup utilities
* @{
*/
/**
* \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
# include "config.h"
#endif
@ -67,74 +90,93 @@
#include <hamlib/rotator.h>
#ifndef DOC_HIDDEN
/** \brief Standard definition of a radian. */
#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
/* The following is contributed by Dave Hines M1CXW
*
* begin dph
*/
/*
* These are the constants used when converting between Maidenhead grid
* locators and longitude/latitude values. MAX_LOCATOR_PAIRS is the maximum
* number of locator character pairs to convert. This number MUST NOT exceed
* the number of pairs of values in loc_char_range[].
* Setting 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
* Beware that there seems to be no universally accepted standard for 10 & 12
* character locators.
/* At this time documenting a single static variable as in loc_char_range[]
* below is not supported by Doxygen. Hide this section until support exists
* or a work-around becomes available.
*/
#ifndef DOC_HIDDEN
/**
* \brief Constants used when converting between Maidenhead grid
* locators and longitude/latitude values.
*
* The ranges of characters which will be accepted by locator2longlat, and
* generated by longlat2locator, are specified by the loc_char_range[] array.
* This array may be changed without requiring any other code changes.
* \ref MAX_LOCATOR_PAIRS is the maximum number of locator character pairs to
* convert. This number MUST NOT exceed the number of pairs of values in
* 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:
* 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:
* const static int loc_char_range[] = { 18, 10, 24, 10, 25, 10 };
*
* 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
* \code const static int loc_char_range[] = { 18, 10, 24, 10, 25, 10 };\endcode
*/
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 MIN_LOCATOR_PAIRS 1
/* end dph */
#endif /* !DOC_HIDDEN */
/**
* \brief Convert DMS to decimal degrees
* \param degrees Degrees, whole degrees
* \param minutes Minutes, whole minutes
* \param seconds Seconds, decimal seconds
* \param sw South or West
* \brief Convert Degrees Minutes Seconds (DMS) notation to decimal degrees
* (D.DDD) angle.
*
* Convert degree/minute/second angle to decimal degrees angle.
* \a degrees >360, \a minutes > 60, and \a seconds > 60.0 are allowed,
* but resulting angle won't be normalized.
* \param degrees Degrees, whole degrees.
* \param minutes Minutes, whole minutes.
* \param seconds Seconds, decimal seconds.
* \param sw South or West.
*
* When the variable 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).
* Convert a Degrees Minutes Seconds (DMS) notation value to a decimal degrees
* (D.DDD) angle value.
*
* \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()
*/
@ -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
* \param degrees Degrees, whole degrees
* \param minutes Minutes, decimal minutes
* \param sw South or West
* \brief Convert degrees decimal minutes (D M.MMM) notation to decimal
* degrees (D.DDD) angle.
*
* Convert a degrees, decimal minutes notation common on
* many GPS units to its decimal degrees value.
* \param degrees Degrees, whole degrees.
* \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
* resulting angle won't be normalized.
* Convert a degrees decimal minutes (D M.MMM) notation common on many GPS
* units to a decimal degrees (D.DDD) angle value.
*
* When the variable 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).
* \note For the parameters \a degrees > 360, \a minutes > 60.0, \a seconds >
* 60.0 are allowed, but the resulting angle will not be normalized.
*
* \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()
*/
@ -223,29 +267,33 @@ double HAMLIB_API dmmm2dec(int degrees, double minutes, double seconds, int sw)
/**
* \brief Convert decimal degrees angle into DMS notation
* \param dec Decimal degrees
* \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
* \brief Convert a decimal degrees (D.DDD) angle into Degrees Minutes
* Seconds (DMS) notation.
*
* Convert decimal degrees angle into its degree/minute/second
* notation.
* \param dec Decimal degrees (D.DDD).
* \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
* within these limits and the sign set appropriately.
* Convert decimal degrees angle (D.DDD) into its Degree Minute Second (DMS)
* notation.
*
* Upon return dec2dms guarantees 0 >= \a degrees <= 180,
* 0 >= \a minutes < 60, and 0.0 >= \a seconds < 60.0.
* When \a dec < -180 or \a dec > 180, the angle will be normalized within
* these limits and the sign set appropriately.
*
* When \a dec is < 0.0 \a sw will be set to 1. When \a dec is
* >= 0.0 \a sw will be set to 0. This flag allows the application
* to determine whether the DMS angle should be treated as negative
* (south or west).
* Upon return, guarantees 0 >= \a degrees <= 180, 0 >= \a minutes < 60, and
* 0.0 >= \a seconds < 60.0.
*
* \retval -RIG_EINVAL if any of the pointers are NULL.
* \retval RIG_OK if conversion went OK.
* When \a dec is < 0.0 \a sw will be set to 1. When \a dec is >= 0.0 \a sw
* 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()
*/
@ -317,28 +365,33 @@ int HAMLIB_API dec2dms(double dec,
/**
* \brief Convert a decimal angle into D M.MMM notation
* \param dec Decimal degrees
* \param degrees Pointer for the calculated whole Degrees
* \param minutes Pointer for the calculated decimal Minutes
* \param sw Pointer for the calculated SW flag
* \brief Convert a decimal degrees (D.DDD) angle into degrees decimal minutes
* (D M.MMM) notation.
*
* Convert a decimal angle into its degree, decimal minute
* notation common on many GPS units.
* \param dec Decimal degrees angle.
* \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
* within these limits and the sign set apropriately.
* Convert a decimal angle into its degree, decimal minute
* notation common on many GPS units.
*
* Upon return dec2dmmm guarantees 0 >= \a degrees <= 180,
* 0.0 >= \a minutes < 60.0.
* When passed a value < -180 or > 180, the value will be normalized
* 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
* >= 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).
* Upon return dec2dmmm guarantees 0 >= \a degrees <= 180,
* 0.0 >= \a minutes < 60.0.
*
* \retval -RIG_EINVAL if any of the pointers are NULL.
* \retval RIG_OK if conversion went OK.
* When \a dec is < 0.0 \a sw will be set to 1. When \a dec is
* >= 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()
*/
@ -369,23 +422,27 @@ int HAMLIB_API dec2dmmm(double dec, int *degrees, double *minutes, int *sw)
/**
* \brief Convert Maidenhead grid locator 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
* \brief Convert QRA locator (Maidenhead grid square) to Longitude/Latitude.
*
* Convert Maidenhead grid locator to Longitude/Latitude (decimal degrees).
* The locator should be in 2 through 12 chars long format.
* \a locator2longlat is case insensitive, however it checks for
* locator validity.
* \param longitude Pointer for the calculated Longitude.
* \param latitude Pointer for the calculated Latitude.
* \param locator The QRA locator--2 through 12 characters + nul string.
*
* Decimal long/lat is computed to center of grid square, i.e. given
* EM19 will return coordinates equivalent to the southwest corner
* of EM19mm.
* Convert a QRA locator string to Longitude/Latitude in decimal degrees
* (D.DDD). The locator should be 2 through 12 chars long format.
* \a locator2longlat is case insensitive, however it checks for locator
* validity.
*
* \retval -RIG_EINVAL if locator exceeds RR99xx99xx99 or exceeds length
* limit--currently 1 to 6 lon/lat pairs.
* \retval RIG_OK if conversion went OK.
* Decimal long/lat is computed to center of grid square, i.e. given
* `EM19` will return coordinates equivalent to the southwest corner
* 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
* 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
* \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
* \brief Convert longitude/latitude to QRA locator (Maidenhead grid square).
*
* Convert longitude/latitude (decimal degrees) to Maidenhead grid locator.
* \a locator must point to an array at least \a pair_count * 2 char + '\\0'.
* \param longitude Longitude, decimal degrees.
* \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
* length limit. Currently 1 to 6 lon/lat pairs.
* \retval RIG_OK if conversion went OK.
* Convert longitude/latitude given in decimal degrees (D.DDD) to a QRA
* locator (Maidenhead grid square). \a locator must point to an array length
* 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 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
* supported.
* that ranges from aa to xx. At some point both conventions should be
* supported.
*
* \sa locator2longlat()
*/
@ -531,26 +594,28 @@ int HAMLIB_API longlat2locator(double longitude,
/**
* \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
* for 12 character locators. Antipodal points, which are easily
* calculated, are considered equidistant and the bearing is
* simply resolved to be true north (0.0°).
* Calculate the distance and bearing (QRB) between \a lon1, \a lat1 and
* \a lon2, \a lat2.
*
* \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.
* \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()
*/
@ -664,12 +729,13 @@ int HAMLIB_API qrb(double lon1,
/**
* \brief Calculate the long path distance between two points.
* \param distance The shortpath distance
*
* Calculate the long path (respective of the short path)
* of a given distance.
* \param distance The shortpath distance in kilometers.
*
* \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()
*/
@ -683,13 +749,13 @@ double HAMLIB_API distance_long_path(double distance)
/**
* \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)
* of a given bearing.
* \param azimuth The shortpath bearing--0.0 to 360.0 degrees.
*
* \return the azimuth in decimal degrees for the opposite path or
* -RIG_EINVAL upon input error (outside the range of 0.0 to 360.0).
* Calculate the long path (opposite of the short path) of a given bearing.
*
* \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()
*/