Searching, please wait...

libhomeradar

easy collect aircraft information
~50,000,000 registered contacts
303894 unique aircraft records, 28.78% unresolved records
 ACARS DECODER Planespotting Network Kinetic Avionics AirNav Systems Airframes.org Atlas Tracking
libhomeradar - easy collect aircraft informations

libhomeradar is an easy to use library for all type of programming language which can use libraries. libhomeradar can connect to different sources to collect aircraft informations arround the world with extended informations, powerful filtering and structured data access.

libhomeradar is written in C and is available for Linux and Windows (2003, XP, NT, Vista).

Currently libhomeradar works with the Kinetic Avionics SBS-1 base station and the Airnav Systems Radarbox.


Yahoo! My Web  Google Bookmarks  Windows Live  Facebook  Ask  del.icio.us  Furl 
 

Available library functions

This page is a short api reference to the available functions within libhomeradar. You'll find all these functions within the libhomeradar.h headers. To start using libhomeradar, you should also check our page with some examples!

See also:


 

/* =================== */
/* Available functions */
/* =================== */

/* Get version information from the library */
extern char *homeradar_version(void);

/* Initialize libhomeradar 
   limit is the internal limit of the contact queue
   flags is a bitmask for the internal flags of libhomeradar
   error is a pointer of int to return errors
   path is the basepath to the internal databases
*/
extern LHR homeradar_init(const int limit, const int flags, int *error, 
                          const char *path);

/* Load databases from disc */
extern int homeradar_load_databases(LHR handle, const char *path);

/* Unload databases from memory */
extern int homeradar_unload_databases(LHR handle);

/* Modify library settings */
extern int homeradar_config(LHR handle, const int flag, void *set);

/* Insert new host into hostlist of this handle */
extern int homeradar_addhost(LHR handle, const char *host, const int port, 
                             const int radarbox,const int handler, void (*function));

/* Set a different port for this host - Only if not already connected 
   Returns 1 on success or 0 on error
*/
extern int homeradar_setport(LHR handle, const int hostid, const int port);

/* Delete host from the list of active hosts */
extern int homeradar_drophost(LHR handle, const int hostid);

/* Return the name of the host which is identified by hostid */
extern char *homeradar_gethostbyid(LHR handle, const int hostid);

/* Return the hostid for the given hostname. Returns 0 if host was not found */
extern int homeradar_gethostbyname(LHR handle, const char *host);

/* Init callback handler for special events
   Set hostid to LHR_HOSTS_ALL to bind on all hosts */
extern int homeradar_onhandler(LHR handle, const int handler, const int hostid, 
                               void (*function));

/* Connect to the host with the given hostid */
extern int homeradar_connect(LHR handle, const int hostid);

/* Connect to the host with the given hostid */
extern int homeradar_disconnect(LHR handle, const int hostid);

/* There are any outstanding contacts on this host? Return 0 if none 
   Set hostid to 0 if you wish to get all contacts
*/
extern int homeradar_pendingcontacts(LHR handle, const int hostid);

/* Get next contact for this host 
   Set hostid to 0 if you wish to read any contact from the queue
*/
extern LHR_CONTACT *homeradar_getnextcontact(LHR handle, const int hostid);

/* Setup logging of all received messages */
extern int homeradar_textlogging(LHR handle, const int on, const char *path, 
                                 const int newfile);

/* Get list of all configures hosts - returns count in count
   Returns 0 on error and set count to -1 */
extern int homeradar_hostlist(LHR handle, int *count);

/* Get next host out of hostlist */
extern LHR_HOST *homeradar_getnexthost(LHR handle);

/* Free single contact item */
extern void homeradar_freecontact(LHR_CONTACT *C);

/* Free airport structure with the complete tree */
extern void homeradar_freeairport(LHR_AIRPORTS *P);

/* Return some stats about this host */
extern LHR_STATS *homeradar_stats(LHR handle, const int hostid);

/* Try to resolve reg by icao24 code */
extern char *homeradar_getregbyicao24(LHR handle, const char *icao24);

/* Try to resolve flight by flightnumber */
extern char *homeradar_getroute(LHR handle, const char *flight);

/* Get icao24 code for a given reg */
extern char *homeradar_geticao24byreg(LHR handle, const char *reg);

/* Get airline based on flightnumber */
extern char *homeradar_getairline(LHR handle, const char *flightnum);

/* Get full human readable routing for the given flight */
extern LHR_AIRPORTS *homeradar_fullrouting(LHR H, const char *flight);

/* Get type informations based on ICAO24 code or reg */
extern LHR_CONTACT *homeradar_gettype(LHR handle, const char *srch);

/* Return a list of all contacted aircrafts on the given host
   Before the first call 'item' should be set to 0 
   Get the list in a while loop until NULL will be returned
*/
extern char *homeradar_unique_aircrafts(LHR handle, const int hostid, int *item);

/* Remove all entries from the unique aircraft contact list for the given host */
extern int homeradar_clear_list(LHR handle, const int hostid);

/* Resolve airport by iata or icao code 
   Result item must be freed by caller
*/
extern LHR_AP *homeradar_getairport(LHR handle, const char *str);

/* Start or stop a connection which reads data from the socket output
   of another running libhomeradar application.
   Set install to TRUE to create the connection, FALSE will drop the connection
   If install is TRUE, port and ip must be set. There is no default port here!
   The socket on the other system must be created with homeradar_listener()
   Mode can be - LHR_POLL  (Single connection, active connection)
               - LHR_PUSH  (Multiple connections, passive connection)
   Returns TRUE on success or FALSE in case of errors
*/
extern int homeradar_socketinput(LHR handle, const int install, const int mode, 
                                 const int port, const char *host);

/* Install or disable listener for socket output dump
   Set second parameter to FALSE if you wish to disable the listener.
   If the second parameter is TRUE, port and hostname must also be set 
   Use the LHR_ON / LHR_OFF macro for the onoff parameter.
   Add LHR_SBS1COMP to output contacts in SBS1 compatible format
*/
extern int homeradar_listener(LHR handle, const int onoff, const int port, const char *host);

/* Get a short statistic list from all connected clients 
   Returns NULL in case of any errors or if the listener is not running 
   The pointer must be freed by the client program */
extern char *homeradar_listener_stats(LHR handle);

/* Install or disable the item transfer to the collector at collector.libhomeradar.org
   Set second parameter to FALSE if you wish to disable the transfer
   If the second parameter is TRUE, the transfer will be started 
   Returns FALSE on error and TRUE on success
*/
extern int homeradar_public(LHR handle, const int onoff);

/* Get distance in kilometers between fixed point (LAT/LON) and aircraft at (ac_LAT/ac_LON) */
extern double homeradar_distance(const double LAT, const double LON, 
                                 const double ac_LAT, const double ac_LON);

/* Get distance from aircraft to a given airport 
   Airport must be send as IATA or ICAO code and databases must be loaded 
   Function returns -1 on error, 0 if airport coordinates are not available
   and > 0 as distance in kilometers */
extern double homeradar_distance_to_airport(LHR handle, const char *airport, 
                                            const double LAT, const double LON);

/* Get distance in kilometers between two airports 
   This function will return -1 on error, 0 if not all coordinates are known
   or the distance in kilometers */
extern double homeradar_distance_ap2ap(LHR handle, const char *from, const char *to);

/* Destroy current instance of libhomeradar */
extern void homeradar_destroy(LHR handle);

/* Control logfile handling of libhomeradar
   Should be called with the following parameters
   handle - libhomeradar handle
   flag   - logfile flag (see libhomeradar.h)
   param  - needed parameters or null

   Returns TRUE (1) on success or FALSE (0) on error 
*/
extern int homeradar_logcontrol(LHR handle, const int flag, const void *param);

/* ==================== [ FILTER ] ==================== */

/* Create new filterelement and return ID from this filter 
   Set hostid to LHR_HOSTS_ALL to set filter for every host */
extern int homeradar_addfilter(LHR handle, const int flags, const char *filter, 
                               const int hostid);

/* Append rule to a given filter, returns a valid rule id */
extern int homeradar_appendrule(LHR handle, const int filterid, const int flags, 
                                const char *filter);

/* Delete (disable) rule in a given filter */
extern int homeradar_disablerule(LHR handle, const int filterid, const int ruleid);

/* Activate (enable) rule in a given filter */
extern int homeradar_enablerule(LHR handle, const int filterid, const int ruleid);

/* Test filter with the given contact structure */
extern int homeradar_testfilter(LHR handle, const int filterid, const LHR_CONTACT *C);

/* --------------------------------- */
/* Available from libhomeradar 1.002 */
/* --------------------------------- */

/* This function loads the translation table and activate the translation option 
   If on = true, the translation function will be enabled
      on = false, will disable the translation function
   path should be a pointer to the translation.csv file. You need this only
   on the first call to this function or if you wish to change the file.
   This function returns TRUE on success or FALSE on error
*/
extern int homeradar_translate(LHR handle, const int on, const char *path);

/* Activate or deactivate internal webserver to show aircraft positions on Google(TM) maps
   Set onoff to TRUE (1) will enable the server. onoff to FALSE (0) will stop the server
   srv is the hostname on which the server will listen. Set srv to NULL will enable
   the listener on all available ips on your server.
   The default port is 8080. You can change this by setting the port value != 0
   Note for Linux users: If you wish to bind this server on a port below 1024 you'll 
   root access.   
*/
extern int homeradar_webserver(LHR handle, const int onoff, const char *srv, const int port);

/* --------------------------------- */
/* Available from libhomeradar 1.003 */
/* --------------------------------- */

/* Translation test function 
   This function must be called with a flightmask and/or a registration 
   The function will return a complete LHR_CONTACT record with the 
   translated (if) informations or NULL on errors.
   You must call homeradar_freecontact() to free the reserved memory 
   if C != NULL
*/
extern LHR_CONTACT *homeradar_translation_test(LHR handle, const char *registration, 
                                               const char *flightnumber);

/* Fetch latest translation database from web
   First the timestamp of the current DB will be checked. Download only possible every 7 days
   Will return TRUE (1) on update or FALSE (0) if no update nedded or -1 on error */
extern int homeradar_tt_refresh(LHR handle);

/* Register a different function for the logfile output 
   This function returns TRUE on success or FALSE on error
   If register is FALSE the logging to this function will be disabled
   If register is TRUE the logging will be send to the given function
*/
extern int homeradar_register_logfunction(LHR handle, void (*function), const int reg, 
                                          const int flags);

/* --------------------------------- */
/* Available from libhomeradar 1.004 */
/* --------------------------------- */

/* 
   Enable import functions of libhomeradar 
   Without this option none of the following import functions will work
 */
extern void homeradar_enable_import(LHR handle);

/* 
  This import functions reads a normal semicolon separated string
  in libhomeradar format into the internal queue
  Field definition of the string
  
  ICAO24 Address;
  Callsign;
  New Contact; (possible values are 0 or 1)		(*)
  GPS position (LAT);					(*)
  GPS position (LON);					(*)
  Flightlevel;						(*)
  Squawk;						(*)
  Messagetype;						(*)
  Date of contact (format: YYYY/MM/DD);
  Time of contact (format: HH:MM:SS);
  Aircraft registration;
  Aircraft manufacturer;				(**)
  Aircraft model;					(**)
  Aircraft details;					(**)
  Aircraft construction number;				(**)
  Flightnumber;
  Routing;						(*)
  Airline;						(**)
  Airlines IATA code;					(**)
  Airlines ICAO code					(**)

   (*) = can be empty or 0
  (**) = if empty, will be resolved by libhomeradar
*/
extern int homeradar_import_by_string(LHR handle, const char *str);

/*
  ContactImport reads a standard LHR_CONTACT structure and will send
  this structure to the normal working loop of libhomeradar.
  With this function you can bind other sources to libhomeradar

  Function returns TRUE (1) on success, -1 on error or FALSE (0) if 
  the item could not be inserted
*/
extern int homeradar_import_by_struct(LHR handle, const LHR_CONTACT *C);

/* Import data source by given values
   All values must be initialized. If one of the values is NULL, the 
   the import will not start.
   This function returns TRUE (1) on success or FALSE (0) if import failed.
   -1 will returned in case of errors
*/
extern int homeradar_import_by_data(LHR handle, const char *addr, const char *reg, const char *callsign,
                                    const char *flightnumber, const time_t contacted, 
                                    const double LAT, const double LON);

/* Set system to import only - no host is needed 
   Useful if you use libhomeradar as importer function 
   If you have no other input (SBS1 or RB), then you'll
   need this function to handle imported data from the
   import functions above.
*/
extern int homeradar_without_hosts(LHR handle);

/* Enable or disable the item sharing function.
   Set onoff to FALSE if you wish to disable the sharing option
   If the onoff is TRUE, data sharing will be enabled
   If port is 0 the default port 30003 will be used
   Returns FALSE on error and TRUE on success.
   Output is exactly the same as on SBS1 socket
*/
extern int homeradar_share(LHR handle, const int port, const int onoff, const int access);

/* 
   Control access to the data sharing port. 
   By default everyone can connect and fetch data.

   Add IP to the access rules 
   Set access_denied to FALSE if this ip should get access
   Set access_denied to TRUE to reject this ip
   Returns TRUE on success, FALSE on error
*/
extern int homeradar_access_rule(LHR handle, const char *ip, const int access_denied);

/* Enable dump to disc feature of libhomeradar to include
   the collected flights later with the 'homeradar_readfromdisc' function
   Set on to TRUE to enable and to FALSE to disable this option 
   This function returns TRUE on success or FALSE on errors.
*/
extern int homeradar_dump2disc(LHR handle, const char *file, const int on);

/* Read from disc will read a prev. created textfile with the 'homeradar_dump2disc' function
   The parameter 'file' is the complete path (incl. filename) to the dumpfile
   Function returns how many lines are read or -1 on error */
extern int homeradar_readfromdisc(LHR handle, const char *file, const int type, const int hostid);

/* Enable or disable the collection function of unique aircrafts 
   for the given (or all) hosts.
   Set hostid to LHR_HOSTS_ALL to enable/disable this option on every host
   Set on to 1 (TRUE) to enable or to 0 (FALSE) to disable this function
*/
extern void homeradar_unique_acs_option(LHR handle, const int hostid, const int on);