xplane-sys 4.0.109

#ifndef _XPLMNavigation_h_
#define _XPLMNavigation_h_

/***************************************************************************
 * XPLMNavigation
 ***************************************************************************/
/*
 * The XPLM Navigation APIs give you some access to the navigation databases
 * inside X-Plane.  X-Plane stores all navigation information in RAM, so by
 * using these APIs you can gain access to most information without having to
 * go to disk or parse the files yourself.
 *
 * You can also use this API to program the FMS.  You must use the navigation
 * APIs to find the nav-aids you want to program into the FMS, since the FMS
 * is powered internally by X-Plane's navigation database.
 *
 */

#include "XPLMDefs.h"

#ifdef __cplusplus
extern "C" {
#endif

/***************************************************************************
 * NAVIGATION DATABASE ACCESS
 ***************************************************************************/

/*
 * XPLMNavType
 *
 * These enumerations define the different types of navaids.  They are each
 * defined with a separate bit so that they may be bit-wise added together to
 * form sets of nav-aid types.
 *
 * NOTE: xplm_Nav_LatLon is a specific lat-lon coordinate entered into the
 * FMS. It will not exist in the database, and cannot be programmed into the
 * FMS. Querying the FMS for navaids will return it.  Use
 * XPLMSetFMSEntryLatLon to set a lat/lon waypoint.
 *
 */
XPLM_MAYBE_TYPEDEF enum XPLM_ENUM {
    xplm_Nav_Unknown = 0,

    xplm_Nav_Airport = 1,

    xplm_Nav_NDB = 2,

    xplm_Nav_VOR = 4,

    xplm_Nav_ILS = 8,

    xplm_Nav_Localizer = 16,

    xplm_Nav_GlideSlope = 32,

    xplm_Nav_OuterMarker = 64,

    xplm_Nav_MiddleMarker = 128,

    xplm_Nav_InnerMarker = 256,

    xplm_Nav_Fix = 512,

    xplm_Nav_DME = 1024,

    xplm_Nav_LatLon = 2048,

} XPLM_ENUM_NAME(XPLMNavType);
XPLM_ENUM_C(XPLMNavType)

/*
 * XPLMNavRef
 *
 * XPLMNavRef is an iterator into the navigation database.  The navigation
 * database is essentially an array, but it is not necessarily densely
 * populated. The only assumption you can safely make is that like-typed
 * nav-aids are grouped together.
 *
 * Use XPLMNavRef to refer to a nav-aid.
 *
 * XPLM_NAV_NOT_FOUND is returned by functions that return an XPLMNavRef when
 * the iterator must be invalid.
 *
 */
typedef int XPLMNavRef;

#define XPLM_NAV_NOT_FOUND -1

/*
 * XPLMGetFirstNavAid
 *
 * This returns the very first navaid in the database.  Use this to traverse
 * the entire database.  Returns XPLM_NAV_NOT_FOUND if the nav database is
 * empty.
 *
 */
XPLM_API XPLMNavRef XPLMGetFirstNavAid(void);

/*
 * XPLMGetNextNavAid
 *
 * Given a valid navaid ref, this routine returns the next navaid.  It returns
 * XPLM_NAV_NOT_FOUND if the navaid passed in was invalid or if the navaid
 * passed in was the last one in the database.  Use this routine to iterate
 * across all like-typed navaids or the entire database.
 *
 */
XPLM_API XPLMNavRef XPLMGetNextNavAid(XPLMNavRef inNavAidRef);

/*
 * XPLMFindFirstNavAidOfType
 *
 * This routine returns the ref of the first navaid of the given type in the
 * database or XPLM_NAV_NOT_FOUND if there are no navaids of that type in the
 * database.  You must pass exactly one navaid type to this routine.
 *
 */
XPLM_API XPLMNavRef XPLMFindFirstNavAidOfType(XPLMNavType inType);

/*
 * XPLMFindLastNavAidOfType
 *
 * This routine returns the ref of the last navaid of the given type in the
 * database or XPLM_NAV_NOT_FOUND if there are no navaids of that type in the
 * database.  You must pass exactly one navaid type to this routine.
 *
 */
XPLM_API XPLMNavRef XPLMFindLastNavAidOfType(XPLMNavType inType);

/*
 * XPLMFindNavAid
 *
 * This routine provides a number of searching capabilities for the nav
 * database. XPLMFindNavAid will search through every navaid whose type is
 * within inType (multiple types may be added together) and return any navaids
 * found based on the following rules:
 *
 * * If inLat and inLon are not NULL, the navaid nearest to that lat/lon will
 *   be returned, otherwise the last navaid found will be returned.
 *
 * * If inFrequency is not NULL, then any navaids considered must match this
 *   frequency.  Note that this will screen out radio beacons that do not have
 *   frequency data published (like inner markers) but not fixes and airports.
 *
 * * If inNameFragment is not NULL, only navaids that contain the fragment in
 *   their name will be returned.
 *
 * * If inIDFragment is not NULL, only navaids that contain the fragment in
 *   their IDs will be returned.
 *
 * This routine provides a simple way to do a number of useful searches:
 * * Find the nearest navaid on this frequency.
 * * Find the nearest airport.
 * * Find the VOR whose ID is "KBOS".
 * * Find the nearest airport whose name contains "Chicago".
 *
 */
XPLM_API XPLMNavRef XPLMFindNavAid(const char* inNameFragment, /* Can be NULL */
                                   const char* inIDFragment,   /* Can be NULL */
                                   float* inLat,               /* Can be NULL */
                                   float* inLon,               /* Can be NULL */
                                   int* inFrequency,           /* Can be NULL */
                                   XPLMNavType inType);

/*
 * XPLMGetNavAidInfo
 *
 * This routine returns information about a navaid.  Any non-null field is
 * filled out with information if it is available.
 *
 * Frequencies are in the nav.dat convention as described in the X-Plane nav
 * database FAQ: NDB frequencies are exact, all others are multiplied by 100.
 *
 * The buffer for IDs should be at least 6 chars and the buffer for names
 * should be at least 41 chars, but since these values are likely to go up, I
 * recommend passing at least 32 chars for IDs and 256 chars for names when
 * possible.
 *
 * The outReg parameter tells if the navaid is within the local "region" of
 * loaded DSFs.  (This information may not be particularly useful to plugins.)
 * The parameter is a single byte value 1 for true or 0 for false, not a C
 * string.
 *
 */
XPLM_API void XPLMGetNavAidInfo(XPLMNavRef inRef,
                                XPLMNavType* outType, /* Can be NULL */
                                float* outLatitude,   /* Can be NULL */
                                float* outLongitude,  /* Can be NULL */
                                float* outHeight,     /* Can be NULL */
                                int* outFrequency,    /* Can be NULL */
                                float* outHeading,    /* Can be NULL */
                                char* outID,          /* Can be NULL */
                                char* outName,        /* Can be NULL */
                                char* outReg);        /* Can be NULL */

/***************************************************************************
 * FLIGHT MANAGEMENT COMPUTER
 ***************************************************************************/
/*
 * Note: the FMS works based on an array of entries.  Indices into the array
 * are zero-based.  Each entry is a navaid plus an altitude.  The FMS tracks
 * the currently displayed entry and the entry that it is flying to.
 *
 * The FMS must be programmed with contiguous entries, so clearing an entry at
 * the end shortens the effective flight plan.  There is a max of 100
 * waypoints in the flight plan.
 *
 */

/*
 * XPLMCountFMSEntries
 *
 * This routine returns the number of entries in the FMS.
 *
 */
XPLM_API int XPLMCountFMSEntries(void);

/*
 * XPLMGetDisplayedFMSEntry
 *
 * This routine returns the index of the entry the pilot is viewing.
 *
 */
XPLM_API int XPLMGetDisplayedFMSEntry(void);

/*
 * XPLMGetDestinationFMSEntry
 *
 * This routine returns the index of the entry the FMS is flying to.
 *
 */
XPLM_API int XPLMGetDestinationFMSEntry(void);

/*
 * XPLMSetDisplayedFMSEntry
 *
 * This routine changes which entry the FMS is showing to the index specified.
 *
 */
XPLM_API void XPLMSetDisplayedFMSEntry(int inIndex);

/*
 * XPLMSetDestinationFMSEntry
 *
 * This routine changes which entry the FMS is flying the aircraft toward.
 *
 */
XPLM_API void XPLMSetDestinationFMSEntry(int inIndex);

/*
 * XPLMGetFMSEntryInfo
 *
 * This routine returns information about a given FMS entry. If the entry is
 * an airport or navaid, a reference to a nav entry can be returned allowing
 * you to find additional information (such as a frequency, ILS heading, name,
 * etc.). Note that this reference can be XPLM_NAV_NOT_FOUND until the
 * information has been looked up asynchronously, so after flightplan changes,
 * it might take up to a second for this field to become populated. The other
 * information is available immediately. For a lat/lon entry, the lat/lon is
 * returned by this routine but the navaid cannot be looked up (and the
 * reference will be XPLM_NAV_NOT_FOUND). FMS name entry buffers should be at
 * least 256 chars in length.
 *
 * WARNING: Due to a bug in X-Plane prior to 11.31, the navaid reference will
 * not be set to XPLM_NAV_NOT_FOUND while no data is available, and instead
 * just remain the value of the variable that you passed the pointer to.
 * Therefore, always initialize the variable to XPLM_NAV_NOT_FOUND before
 * passing the pointer to this function.
 *
 */
XPLM_API void XPLMGetFMSEntryInfo(int inIndex,
                                  XPLMNavType* outType, /* Can be NULL */
                                  char* outID,          /* Can be NULL */
                                  XPLMNavRef* outRef,   /* Can be NULL */
                                  int* outAltitude,     /* Can be NULL */
                                  float* outLat,        /* Can be NULL */
                                  float* outLon);       /* Can be NULL */

/*
 * XPLMSetFMSEntryInfo
 *
 * This routine changes an entry in the FMS to have the destination navaid
 * passed in and the altitude specified.  Use this only for airports, fixes,
 * and radio-beacon navaids.  Currently of radio beacons, the FMS can only
 * support VORs and NDBs. Use the routines below to clear or fly to a lat/lon.
 *
 */
XPLM_API void XPLMSetFMSEntryInfo(int inIndex, XPLMNavRef inRef,
                                  int inAltitude);

/*
 * XPLMSetFMSEntryLatLon
 *
 * This routine changes the entry in the FMS to a lat/lon entry with the given
 * coordinates.
 *
 */
XPLM_API void XPLMSetFMSEntryLatLon(int inIndex, float inLat, float inLon,
                                    int inAltitude);

/*
 * XPLMClearFMSEntry
 *
 * This routine clears the given entry, potentially shortening the flight
 * plan.
 *
 */
XPLM_API void XPLMClearFMSEntry(int inIndex);

/***************************************************************************
 * GPS RECEIVER
 ***************************************************************************/
/*
 * These APIs let you read data from the GPS unit.
 *
 */

/*
 * XPLMGetGPSDestinationType
 *
 * This routine returns the type of the currently selected GPS destination,
 * one of fix, airport, VOR or NDB.
 *
 */
XPLM_API XPLMNavType XPLMGetGPSDestinationType(void);

/*
 * XPLMGetGPSDestination
 *
 * This routine returns the current GPS destination.
 *
 */
XPLM_API XPLMNavRef XPLMGetGPSDestination(void);

#ifdef __cplusplus
}
#endif

#endif