[Hamlib-commits] Hamlib -- Ham radio control libraries branch master updated. fbd07524e2291974b32b7
Library to control radio transceivers and receivers
Brought to you by:
n0nb
Menu
▾
▴
[Hamlib-commits] Hamlib -- Ham radio control libraries branch master updated. fbd07524e2291974b32b75241115c35b974b0dba
|
From: Nate B. <n0...@us...> - 2021-05-17 02:27:17
|
This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "Hamlib -- Ham radio control libraries".
The branch, master has been updated
via fbd07524e2291974b32b75241115c35b974b0dba (commit)
via b679b0c75350bafd1404ccdca61ef3845d77abaf (commit)
via 55ec759a75041897bec3dd114dc38b5f2bcc3c39 (commit)
via 0ed6b110889286a7773f893b6d36e02e3fcefceb (commit)
from 47cf24582626e44d028aaa66fe1ebc9b3d6fd760 (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
commit fbd07524e2291974b32b75241115c35b974b0dba
Merge: 47cf2458 b679b0c7
Author: Nate Bargmann <n0...@n0...>
Date: Sun May 16 21:26:14 2021 -0500
Merge pull request #701 from N0NB/doxygen_work
Doxygen work
commit b679b0c75350bafd1404ccdca61ef3845d77abaf
Author: Nate Bargmann <n0...@n0...>
Date: Sun May 16 21:14:04 2021 -0500
Update NEWS for 4.2 release
diff --git a/NEWS b/NEWS
index 683d706c..c82c9727 100644
--- a/NEWS
+++ b/NEWS
@@ -7,14 +7,14 @@ Copyright (C) 2000-2021 Michael Black W9MDB, and others
Please send Hamlib bug reports to ham...@li...
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
commit 55ec759a75041897bec3dd114dc38b5f2bcc3c39
Author: Nate Bargmann <n0...@n0...>
Date: Sun May 16 21:11:10 2021 -0500
Format to break lines before 80 characters
diff --git a/README.freqranges b/README.freqranges
index 6fe68b84..9d5ca122 100644
--- a/README.freqranges
+++ b/README.freqranges
@@ -1,9 +1,15 @@
-Frequency ranges are being changed to reflect rig capabilities instead of region restrictions
+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.
+#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.
+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
-
-
commit 0ed6b110889286a7773f893b6d36e02e3fcefceb
Author: Nate Bargmann <n0...@n0...>
Date: Sun May 16 21:10:31 2021 -0500
Update Doxygen comments and main page
diff --git a/doc/index.doxygen b/doc/index.doxygen
index 366239c1..1d6103f0 100644
--- a/doc/index.doxygen
+++ b/doc/index.doxygen
@@ -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 ham...@li....
\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
diff --git a/src/locator.c b/src/locator.c
index b7679549..07bd653b 100644
--- a/src/locator.c
+++ b/src/locator.c
@@ -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
+
+/**
+ * \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
*
- * Here are grouped some often used functions, like locator conversion
- * 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.
- *
- * 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.
+
+/* 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.
+ *
+ * \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.
+ *
+ * \param degrees Degrees, whole degrees.
+ * \param minutes Minutes, whole minutes.
+ * \param seconds Seconds, decimal seconds.
+ * \param sw South or West.
*
- * 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.
+ * Convert a Degrees Minutes Seconds (DMS) notation value 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, and \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 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.
+ *
+ * \param degrees Degrees, whole degrees.
+ * \param minutes Minutes, decimal minutes.
+ * \param seconds Seconds, decimal seconds.
+ * \param sw South or West.
*
- * Convert a degrees, decimal minutes notation common on
- * many GPS units to its decimal degrees value.
+ * Convert a degrees decimal minutes (D M.MMM) notation common on many GPS
+ * units to a decimal degrees (D.DDD) angle value.
*
- * \a degrees > 360, \a minutes > 60.0 are allowed, but
- * resulting angle won't be normalized.
+ * \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.
*
- * 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).
+ * 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 angle in decimal degrees.
+ * \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.
+ *
+ * \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.
+ *
+ * Convert decimal degrees angle (D.DDD) into its Degree Minute Second (DMS)
+ * notation.
*
- * Convert decimal degrees angle into its degree/minute/second
- * notation.
+ * When \a dec < -180 or \a dec > 180, the angle will be normalized within
+ * these limits and the sign set appropriately.
*
- * When \a dec < -180 or \a dec > 180, the angle will be normalized
- * within these limits and the sign set appropriately.
+ * Upon return, guarantees 0 >= \a degrees <= 180, 0 >= \a minutes < 60, and
+ * 0.0 >= \a seconds < 60.0.
*
- * Upon return dec2dms guarantees 0 >= \a degrees <= 180,
- * 0 >= \a minutes < 60, and 0.0 >= \a seconds < 60.0.
+ * 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*).
*
- * 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_EINVAL if any of the pointers are NULL.
- * \retval RIG_OK if conversion went OK.
+ * \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.
+ *
+ * \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.
+ *
+ * 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.
*
- * 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.
+ * Decimal long/lat is computed to center of grid square, i.e. given
+ * `EM19` will return coordinates equivalent to the southwest corner
+ * of `EM19mm`.
*
- * 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_EINVAL if locator exceeds RR99xx99xx99 or exceeds length
- * limit--currently 1 to 6 lon/lat pairs.
- * \retval RIG_OK if conversion went OK.
+ * \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
- * exceed -90 to 90 or -180 to 180.
- * \retval RIG_OK if calculations are successful.
+ * 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 The distance in kilometers and azimuth in decimal degrees
- * for the short path are stored in \a distance and \a azimuth.
+ * \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.
*
* \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.
+ *
+ * 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 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()
*/
-----------------------------------------------------------------------
Summary of changes:
NEWS | 17 ++-
README.freqranges | 14 +-
doc/index.doxygen | 70 ++++++++--
src/locator.c | 384 ++++++++++++++++++++++++++++++++----------------------
4 files changed, 302 insertions(+), 183 deletions(-)
hooks/post-receive
--
Hamlib -- Ham radio control libraries
|
