kopia lustrzana https://github.com/Hamlib/Hamlib
Update Doxygen comments and main page
Nate Bargmann
rodzic
47cf245826
commit
0ed6b11088
|
|
@ -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
384
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
|
||||
*
|
||||
* 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()
|
||||
*/
|
||||
|
|
|
|||
Ładowanie…
Reference in New Issue