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