#include <stdlib.h>
#include <cairo.h>
#include "geom.h"
#include "types.h"

Include dependency graph for chartdb.h:

Data Structures
struct	chart_prov_info_login_t

struct	chart_bbox_t

struct	chart_georef_t

struct	chart_procs_t

Macros
#define	MAX_CHART_INSETS 16

#define	MAX_CHART_PROCS 24

Enumerations
enum	chart_type_t { CHART_TYPE_UNKNOWN = 0 , CHART_TYPE_APD = 1 << 0 , CHART_TYPE_IAP = 1 << 1 , CHART_TYPE_DP = 1 << 2 , CHART_TYPE_ODP = 1 << 3 , CHART_TYPE_STAR = 1 << 4 , CHART_TYPE_MIN = 1 << 5 , CHART_TYPE_INFO = 1 << 6 , CHART_TYPE_ALL = 0xffffffffu }

enum	chart_view_t { CHART_VIEW_HEADER , CHART_VIEW_PLANVIEW , CHART_VIEW_PROFILE , CHART_VIEW_MINIMUMS , NUM_CHART_VIEWS }

Functions
chartdb_t *	chartdb_init (const char cache_path, const char pdftoppm_path, const char pdfinfo_path, unsigned airac, const char provider_name, const chart_prov_info_login_t *provider_login)

void	chartdb_fini (chartdb_t *cdb)

bool_t	chartdb_test_connection (const char provider_name, const chart_prov_info_login_t creds)

bool_t	chartdb_test_connection2 (const char provider_name, const chart_prov_info_login_t creds, const char *proxy)

void	chartdb_set_load_limit (chartdb_t *cdb, uint64_t bytes)

void	chartdb_purge (chartdb_t *cdb)

void	chartdb_set_proxy (chartdb_t cdb, const char proxy)

size_t	chartdb_get_proxy (chartdb_t cdb, char proxy, size_t cap)

char **	chartdb_get_chart_names (chartdb_t cdb, const char icao, chart_type_t type, size_t *num_charts)

void	chartdb_free_str_list (char **name_list, size_t num)

char *	chartdb_get_chart_codename (chartdb_t cdb, const char icao, const char *chart_name)

chart_type_t	chartdb_get_chart_type (chartdb_t cdb, const char icao, const char *chart_name)

chart_georef_t	chartdb_get_chart_georef (chartdb_t cdb, const char icao, const char *chart_name)

chart_bbox_t	chartdb_get_chart_view (chartdb_t cdb, const char icao, const char *chart_name, chart_view_t view)

chart_procs_t	chartdb_get_chart_procs (chartdb_t cdb, const char icao, const char *chart_name)

bool_t	chartdb_get_chart_surface (chartdb_t cdb, const char icao, const char chart_name, int page, double zoom, bool_t night, cairo_surface_t surf, int num_pages)

bool_t	chartdb_is_ready (chartdb_t *cdb)

bool_t	chartdb_is_arpt_known (chartdb_t cdb, const char icao)

char *	chartdb_get_arpt_name (chartdb_t cdb, const char icao)

char *	chartdb_get_arpt_city (chartdb_t cdb, const char icao)

char *	chartdb_get_arpt_state (chartdb_t cdb, const char icao)

char *	chartdb_get_metar (chartdb_t cdb, const char icao)

char *	chartdb_get_taf (chartdb_t cdb, const char icao)

bool_t	chartdb_pending_ext_account_setup (chartdb_t *cdb)

Detailed Description

This facility provides the ability to load charts from the following online chart providers:

Navigraph - requires a developer API key from Navigraph, as well as a user subscription to the service.
Aeronav - a free service covering all of the United States as well as FAA-governed regions.
Autorouter - a service requiring a free user account, covering most of Europe and some other countries.
See also
chartdb_init()

Definition in file chartdb.h.

Macro Definition Documentation

◆ MAX_CHART_INSETS

#define MAX_CHART_INSETS 16

Definition at line 52 of file chartdb.h.

◆ MAX_CHART_PROCS

#define MAX_CHART_PROCS 24

Definition at line 53 of file chartdb.h.

Enumeration Type Documentation

◆ chart_type_t

enum chart_type_t

Definition at line 57 of file chartdb.h.

◆ chart_view_t

enum chart_view_t

Bounding boxes for various pre-defined chart views. Zero is referenced to the top left. This is meant to define sections of a Jeppesen chart. This info is only available when using the Navigraph chart provider.

Enumerator
CHART_VIEW_HEADER	The "Briefing Strip" part of the chart.
CHART_VIEW_PLANVIEW	The top-down mapping part of the chart.
CHART_VIEW_PROFILE	The side profile of an approach chart.
CHART_VIEW_MINIMUMS	The minimums block of an approach chart.

Definition at line 141 of file chartdb.h.

Function Documentation

◆ chartdb_fini()

void chartdb_fini ( chartdb_t * cdb )

Frees and shuts down a chart database object, previously returned from chartdb_init().

Definition at line 1278 of file chartdb.c.

◆ chartdb_free_str_list()

void chartdb_free_str_list	(	char **	name_list,
		size_t	num
	)

Frees a list of charts returned from chartdb_get_chart_names().

Parameters

name_list	The list of chart names returned from chartdb_get_chart_names().
num	Number of items in the chart ID list.

Definition at line 1471 of file chartdb.c.

◆ chartdb_get_arpt_city()

char * chartdb_get_arpt_city	(	chartdb_t *	cdb,
		const char *	icao
	)

Queries the human-readable city name from the chart database about a particular airport.

Parameters

icao	The ICAO code of the airport for which to retrieve the info.

Returns: The city name associated with the airport, or NULL if unknown. You must free the returned string using lacf_free().

Definition at line 1792 of file chartdb.c.

◆ chartdb_get_arpt_name()

char * chartdb_get_arpt_name	(	chartdb_t *	cdb,
		const char *	icao
	)

Queries the human-readable airport name from the chart database about a particular airport.

Parameters

icao	The ICAO code of the airport for which to retrieve the info.

Returns: The airport name associated with the airport, or NULL unknown. You must free the returned string using lacf_free().

Definition at line 1786 of file chartdb.c.

◆ chartdb_get_arpt_state()

char * chartdb_get_arpt_state	(	chartdb_t *	cdb,
		const char *	icao
	)

Queries the human-readable state name name from the chart database about a particular airport.

Parameters

icao	The ICAO code of the airport for which to retrieve the info.

Returns: The state name associated with the airport, or NULL unknown. You must free the returned string using lacf_free().

Definition at line 1798 of file chartdb.c.

◆ chartdb_get_chart_codename()

char * chartdb_get_chart_codename	(	chartdb_t *	cdb,
		const char *	icao,
		const char *	chart_name
	)

Retrieves the chart code name for a particular chart. The meaning of the code name varies by provider.

for Navigraph, this is the Jeppesen chart index number, e.g. "10-9".
for Aeronav, this is the contents of the "faanfd18" field, identifying the procedure tuple on departure procedures, e.g. "AKUMY4.AKUMY".
for Autorouter, this field is not defined.
Parameters

icao The ICAO code of the airport for which the chart exists.

chart_name The name of the chart as returned from chartdb_get_chart_names().

Returns
A copy of the chart codename, or NULL if no value is defined. You must free the returned string using lacf_free().

Definition at line 1519 of file chartdb.c.

◆ chartdb_get_chart_georef()

chart_georef_t chartdb_get_chart_georef	(	chartdb_t *	cdb,
		const char *	icao,
		const char *	chart_name
	)

Returns: Chart geo-referencing data for the specified chart. The chart MUST exist. If the chart has no geo-referencing data, the returned info structure will have its present field set to B_FALSE.

Parameters

icao	The ICAO code of the airport for which the chart exists.
chart_name	The name of the chart as returned from chartdb_get_chart_names().

Definition at line 1566 of file chartdb.c.

◆ chartdb_get_chart_names()

char ** chartdb_get_chart_names	(	chartdb_t *	cdb,
		const char *	icao,
		chart_type_t	type,
		size_t *	num_charts
	)

Fetches the list of available charts for a given airport from the chart provider.

Parameters

icao	The ICAO code of the airport for which to query the provider.
type	The type of chart to retrieve.
num_charts	Mandatory return argument which will be filled with the number of charts in the returned string list.

Returns: A list of strings containing the unique chart names which match the search criteria. These chart names are used in other chart database queries to retrieve information about a particular chart. The number of charts in this list will be returned in num_charts. If no charts match the search criteria, this function returns NULL and sets num_charts to 0.; You must free the returned list using chartdb_free_str_list().

Definition at line 1406 of file chartdb.c.

◆ chartdb_get_chart_procs()

chart_procs_t chartdb_get_chart_procs	(	chartdb_t *	cdb,
		const char *	icao,
		const char *	chart_name
	)

Returns: Information about associated coded instrument flight procedures corresponding to a particular chart. If no flight procedures are defined for the chart, the retuend chart_procs_t structure will have its n_procs field set to 0.

Parameters

icao	The ICAO code of the airport for which the chart exists.
chart_name	The name of the chart as returned from chartdb_get_chart_names().

Definition at line 1613 of file chartdb.c.

◆ chartdb_get_chart_surface()

bool_t chartdb_get_chart_surface	(	chartdb_t *	cdb,
		const char *	icao,
		const char *	chart_name,
		int	page,
		double	zoom,
		bool_t	night,
		cairo_surface_t **	surf,
		int *	num_pages
	)

Retrieves chart pixel data. Please note that while this function can initiate a background chart download and rasterization, it will never block. If the chart is not yet ready, the function will return B_FALSE to let you know that the chart isn't ready. You should keep retrying for a certain amount of time (e.g. 20 seconds) before giving up and presenting an error message to the user. Charts returned from chartdb_get_chart_names() should exist and be retrievable, so long as there are no network or disk access errors. If any of the page, zoom or night parameters changes, the database will load a new image surface and return that instead. You shouldn't need to cache the returned image data in your application, the chart database takes care of all caching needs automatically.

Parameters

icao	The ICAO code of the airport for which the chart exists.
chart_name	The name of the chart as returned from chartdb_get_chart_names().
page	If the chart is a PDF with multiple pages, this specifies the page number to return (starting at 0 and up to `num_pages` - see below).
zoom	Relative zoom value to use when rasterizing vector image charts (PDFs), in the range of 0.1 - 10. A zoom value of 1.0 corresponds to roughly 72 DPI. This has no effect when dealing with raster charts (Navigraph).
night	Specifies whether to return a day-light or night-light optimized chart. For chart providers which supply different charts for day and night operations (Navigraph), this retrieves the appropriate chart image. Otherwise, the chart database automatically inverts the colors on the chart to reduce the overall brightness of black-on-white charts.
surf	A mandatory return argument which, if this function returns `B_TRUE`, will be filled with a cairo_surface_t image buffer containing the pixel data suitable for compositing into a cairo_t context, or which you can read the raw pixels from. Once created, the surface is immutable, so you can use it for rendering at a later date without having to worry about synchronizing data access. Please note that when you are done with the surface, you MUST release it by calling cairo_surface_destroy(), or using the CAIRO_SURFACE_DESTROY() macro. If this function returns `B_FALSE`, the `surf` pointer will be set to `NULL`.
num_pages	An optional return argument which will be filled with the number of pages available, if this is a multi-page chart. Only PDF charts from Aeronav and Autorouter can be multi-page. Navigraph charts are always single-page.

Returns: B_TRUE if the request succeeded, in which case surf will be filled with a reference to the image surface data.

Definition at line 1636 of file chartdb.c.

◆ chartdb_get_chart_type()

chart_type_t chartdb_get_chart_type	(	chartdb_t *	cdb,
		const char *	icao,
		const char *	chart_name
	)

Returns: The type of the chart. The chart MUST exist.

Parameters

icao	The ICAO code of the airport for which the chart exists.
chart_name	The name of the chart as returned from chartdb_get_chart_names().

Definition at line 1544 of file chartdb.c.

◆ chartdb_get_chart_view()

chart_bbox_t chartdb_get_chart_view	(	chartdb_t *	cdb,
		const char *	icao,
		const char *	chart_name,
		chart_view_t	view
	)

Returns: Chart view information for the specified chart and chart view. If the chart doesn't have the requested view specified, the function returns a chart_bbox_t with both points set to zero.

Parameters

icao	The ICAO code of the airport for which the chart exists.
chart_name	The name of the chart as returned from chartdb_get_chart_names().
view	The chart view which to retrieve.

Definition at line 1589 of file chartdb.c.

◆ chartdb_get_metar()

char * chartdb_get_metar	(	chartdb_t *	cdb,
		const char *	icao
	)

Utility function to retrieve the latest METAR from the aviationweather.gov/metar service. This function doesn't block for the download. Instead, the download is queued on the chart database's background thread and the METAR is returned if/when it becomes available.

Parameters

cdb	The chart database to use for the download. The chart provider of the database doesn't matter. This function always queries the aviationweather.gov service.
icao	The ICAO code of the station for which to download the METAR.

Returns: The raw METAR text data. If the download hasn't succeeded yet (e.g. due to not being available, being in progress, or due to a network error), this function returns NULL instead. You should keep calling this function at regular intervals, to retry the download. Also, regular calls should be being made even if the download succeded, as a new METAR might have been issued in the mean time. The downloader implements an automatic rate limiter to prevent overloading the network server with continuous requests.; The returned string must be freed using lacf_free().

See also: chartdb_get_taf()

Definition at line 1804 of file chartdb.c.

◆ chartdb_get_proxy()

size_t chartdb_get_proxy	(	chartdb_t *	cdb,
		char *	proxy,
		size_t	cap
	)

Retrieves the current network proxy string used by the database.

Parameters

proxy	A writable buffer, which will be filled with the proxy string in use. If no proxy is in use, this will be filled with an empty string.
cap	The capacity of the `proxy` buffer in bytes. The function will never write more than `cap` bytes to the `proxy` buffer and will always properly NUL-terminate the string, even if truncated.

Returns: The size of the proxy string, including the terminating NUL character. If no proxy is in use, this function instead returns 0.

Definition at line 1385 of file chartdb.c.

◆ chartdb_get_taf()

char * chartdb_get_taf	(	chartdb_t *	cdb,
		const char *	icao
	)

Same as chartdb_get_metar(), but retrieves TAF data from the aviationweather.gov/taf service.

See also: chartdb_get_metar()

Definition at line 1810 of file chartdb.c.

◆ chartdb_init()

chartdb_t * chartdb_init	(	const char *	cache_path,
		const char *	pdftoppm_path,
		const char *	pdfinfo_path,
		unsigned	airac,
		const char *	provider_name,
		const chart_prov_info_login_t *	provider_login
	)

Initializes a new chart database for a specific chart provider. After initialization, the database can be accessed to retrieve various charts asynchronously. The chart databases uses a background thread to perform data fetches, and thus is safe to use from your avionics threads without locking issues.

Parameters

cache_path	A path to a suitable cache directory that the database can use to cache frequently accessed charts, or login information. This would typically be something like "<X-Plane>/Output/caches/<your-addon>/chartdb". This directory need not exist, the database will create it when necessary. If you are initializing multiple chart databases from different providers, you may reuse the same cache directory. You may NOT reuse the same cache directory when using multiple chart databases utilizing the same chart provider, as the providers can overwrite each other's on-disk state.
pdftoppm_path	An optional path to a compiled binary of the pdftoppm utility from the Poppler project. This is used to convert PDF charts to bitmap images suitable for display. PDF charts are supplied by the Aeronav and Autorouter chart providers. If you specify `NULL` here, PDF chart support will not be available.
pdfinfo_path	An optional path to a compiled binary of the pdfinfo utility from the Poppler project. This is used to handle PDF charts. PDF charts are supplied by the Aeronav and Autorouter chart providers. If you specify `NULL` here, PDF chart support will not be available.
airac	The AIRAC cycle for which to initialize the provider. This information is used by the Aeronav provider, as charts are tied to a specific AIRAC cycle. Navigraph and Autorouter do not use this.
provider_name	This must be one of: "aeronav.faa.gov" "autorouter.aero" "navigraph.com"
provider_login	When using the Navigraph or Autorouter providers this MUST be a pointer to a chart_prov_info_login_t structure. When using the Aeronav provider, this is optional. You may free the memory associated with this structure after calling chartdb_init().

See also: chart_prov_info_login_t.

Returns: The initialized chart database if successful, or NULL otherwise.

Definition at line 1212 of file chartdb.c.

◆ chartdb_is_arpt_known()

bool_t chartdb_is_arpt_known	(	chartdb_t *	cdb,
		const char *	icao
	)

Queries the database on whether it has charts available for a given airport.

Parameters

icao	The ICAO code of the airport which to check chart availability for.

Returns: B_TRUE if the given airport has at least one chart available, B_FALSE otherwise. If this returns true, you can use chartdb_get_chart_names() to retrieve the list of available charts for this airport.

Definition at line 1761 of file chartdb.c.

◆ chartdb_is_ready()

bool_t chartdb_is_ready ( chartdb_t * cdb )

Queries the chart database whether it's ready to start processing chart requests. Some chart providers need to perform disk or network I/O before they can start to operate.

Returns: B_TRUE if the chart database is ready to start processing chart requests, B_FALSE otherwise. You should postpone reporting issues about starts not being available until this returns B_TRUE.

Definition at line 1751 of file chartdb.c.

◆ chartdb_pending_ext_account_setup()

bool_t chartdb_pending_ext_account_setup ( chartdb_t * cdb )

Queries the chart database whether external account setup is pending. This is specifically used by the Navigraph chart provider, which requires the user to log in and authorize the simulator through an external web browser. While the chart provider should launch the browser automatically, it is helpful to show a popup window in the simulator, letting the user know that they need to perform the authorization step before being able to proceed.

Returns: B_TRUE when the chart provider of the database is awaiting external account setup completion, B_FALSE if it isn't. This will typically only be required once, as the chart provider will cache any access tokens for automatic connection setup in the future.

Definition at line 1914 of file chartdb.c.

◆ chartdb_purge()

void chartdb_purge ( chartdb_t * cdb )

Instructs the chart database to immediately purge its disk cache. You should generally not need to ever do this, as cache management is automatic.

Definition at line 1359 of file chartdb.c.

◆ chartdb_set_load_limit()

void chartdb_set_load_limit	(	chartdb_t *	cdb,
		uint64_t	bytes
	)

Sets the size of the on-disk cache for the chart database. This is only used by the Aeronav and Autorouter providers (Navigraph never caches anything, as the terms of use of the API prohibit disk caching). If not specified, the default value is 1/32 of the machine's physical memory, or 256MB, whichever is lower.

Parameters

bytes The new maximum sizeof the disk cache in bytes.

Definition at line 1349 of file chartdb.c.

◆ chartdb_set_proxy()

void chartdb_set_proxy	(	chartdb_t *	cdb,
		const char *	proxy
	)

Sets the network proxy to use for chart data downloading. By default no proxy is used for chart downloads.

Parameters

proxy The proxy specifier string, or NULL when you wish to switch back to not using a proxy. The format for proxy specification follows the libcurl format (see below).

See also: https://curl.se/libcurl/c/CURLOPT_PROXY.html

Definition at line 1373 of file chartdb.c.

◆ chartdb_test_connection()

bool_t chartdb_test_connection	(	const char *	provider_name,
		const chart_prov_info_login_t *	creds
	)

Front-end to chartdb_test_connection2() with a NULL proxy.

See also: chartdb_test_connection2()

Definition at line 1324 of file chartdb.c.

◆ chartdb_test_connection2()

bool_t chartdb_test_connection2	(	const char *	provider_name,
		const chart_prov_info_login_t *	creds,
		const char *	proxy
	)

Provides a method for testing the connection credentials for a chart provider. Currently this is only used by the Autorouter provider. This way, you can test whether the supplied credentials are correct, before accepting them from the user to save for future use.

Parameters

provider_name	The chart provider to use for the connection test. Currently this must always be "autorouter.aero".
creds	The login credentials to use for the connection test. All fields of the structure must be populated. See chart_prov_info_login_t for more information.
proxy	An optional field specifying a proxy to use for the connection test. See chartdb_set_proxy() for information on the format of the proxy specification expected here.

Definition at line 1331 of file chartdb.c.

Data Structures

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ MAX_CHART_INSETS

◆ MAX_CHART_PROCS

Enumeration Type Documentation

◆ chart_type_t

◆ chart_view_t

Function Documentation

◆ chartdb_fini()

◆ chartdb_free_str_list()

◆ chartdb_get_arpt_city()

◆ chartdb_get_arpt_name()

◆ chartdb_get_arpt_state()

◆ chartdb_get_chart_codename()

◆ chartdb_get_chart_georef()

◆ chartdb_get_chart_names()

◆ chartdb_get_chart_procs()

◆ chartdb_get_chart_surface()

◆ chartdb_get_chart_type()

◆ chartdb_get_chart_view()

◆ chartdb_get_metar()

◆ chartdb_get_proxy()

◆ chartdb_get_taf()

◆ chartdb_init()

◆ chartdb_is_arpt_known()

◆ chartdb_is_ready()

◆ chartdb_pending_ext_account_setup()

◆ chartdb_purge()

◆ chartdb_set_load_limit()

◆ chartdb_set_proxy()

◆ chartdb_test_connection()

◆ chartdb_test_connection2()