libroutino/doc/LIBRARY.txt

                           Routino : Library
                           =================


Library Usage
-------------

   This page describes the libroutino shared library that can be compiled
   from the Routino source code and used in other programs.

Compilation
- - - - - -

   The libroutino shared library is compiled by default when the Routino
   source code is compiled. There are two versions; a normal version and a
   'slim' version that uses less memory but is slower. The names of the
   libraries are libroutino.so and libroutino-slim.so

Including
- - - - -

   To use the Routino library in another program the source code for that
   program should include the routino.h file. The functions that are
   available in the library (both versions) are listed in this file along
   with all of the constants and data types that are required.

Linking
- - - -

   After compiling the program that uses the library it needs to be linked
   to the library. For gcc this requires adding -lroutino or
   -lroutino-slim to the linker command line, possibly with a -L...
   parameter to specify the location of the library.

Example Library Interface Code
- - - - - - - - - - - - - - -

   An example of a program that can link to the libroutino library is
   provided in the Routino source code called router+lib.c. This is an
   almost exact re-implementation of the standard Routino router program
   using the libroutino library.


Library License
---------------

   The source code for the libroutino and libroutino-slim libraries is the
   GNU Affero General Public License v3 the same as for the rest of the
   Routino software.

Linking with AGPLv3 Source Code
- - - - - - - - - - - - - - - -

   If libroutino is linked with other APGLv3 code then the same license
   applies to the combination as to the two parts.

Linking with GPLv3 Source Code
- - - - - - - - - - - - - - -

   The AGPLv3 license is almost identical to the GNU General Public
   License v3 except that network interaction with an AGPLv3 program
   requires the same source code access as distributing compiled GPLv3
   programs. This means that libroutino can be linked or combined with
   code that is released under the GPLv3 without changing the license of
   that code.

   If there is no network interaction with the resulting program then the
   Routino source code can be treated as if it was GPLv3 code for the
   purposes of distribution and use.

   If there is network interaction with the resulting program then the
   AGPLv3 license will apply since this is required by section 13 of the
   GPLv3.
   The Software Freedom Law Center description of the GPLv3 and AGPLv3
   licenses describes combining GPLv3 and APGLv3.
   My understanding is that only when modified Routino code is linked with
   GPLv3 code does network interaction require the modified Routino code
   to be released.

Linking with Other Source Code
- - - - - - - - - - - - - - -

   Linking libroutino with code released under any other license must
   preserve the terms of the Routino license on the combination if the
   software is distributed or interacted with over a network.


Routino Library API
-------------------

Preprocessor Definitions
- - - - - - - - - - - -

   A version number for the Routino API.
   #define ROUTINO_API_VERSION 4

Error Definitions

   No error.
   #define ROUTINO_ERROR_NONE 0

   A function was called without the database variable set.
   #define ROUTINO_ERROR_NO_DATABASE 1

   A function was called without the profile variable set.
   #define ROUTINO_ERROR_NO_PROFILE 2

   A function was called without the translation variable set.
   #define ROUTINO_ERROR_NO_TRANSLATION 3

   The specified database to load did not exist.
   #define ROUTINO_ERROR_NO_DATABASE_FILES 11

   The specified database could not be loaded.
   #define ROUTINO_ERROR_BAD_DATABASE_FILES 12

   The specified profiles XML file did not exist.
   #define ROUTINO_ERROR_NO_PROFILES_XML 13

   The specified profiles XML file could not be loaded.
   #define ROUTINO_ERROR_BAD_PROFILES_XML 14

   The specified translations XML file did not exist.
   #define ROUTINO_ERROR_NO_TRANSLATIONS_XML 15

   The specified translations XML file could not be loaded.
   #define ROUTINO_ERROR_BAD_TRANSLATIONS_XML 16

   The requested profile name does not exist in the loaded XML file.
   #define ROUTINO_ERROR_NO_SUCH_PROFILE 21

   The requested translation language does not exist in the loaded XML
   file.
   #define ROUTINO_ERROR_NO_SUCH_TRANSLATION 22

   There is no highway near the coordinates to place a waypoint.
   #define ROUTINO_ERROR_NO_NEARBY_HIGHWAY 31

   The profile and database do not work together.
   #define ROUTINO_ERROR_PROFILE_DATABASE_ERR 41

   The profile being used has not been validated.
   #define ROUTINO_ERROR_NOTVALID_PROFILE 42

   The user specified profile contained invalid data.
   #define ROUTINO_ERROR_BAD_USER_PROFILE 43

   The routing options specified are not consistent with each other.
   #define ROUTINO_ERROR_BAD_OPTIONS 51

   There is a mismatch between the library and caller API version.
   #define ROUTINO_ERROR_WRONG_API_VERSION 61

   The progress function returned false.
   #define ROUTINO_ERROR_PROGRESS_ABORTED 71

   A route could not be found to waypoint 1.
   #define ROUTINO_ERROR_NO_ROUTE_1 1001

   A route could not be found to waypoint 2.
   #define ROUTINO_ERROR_NO_ROUTE_2 1002

   A route could not be found to waypoint 3.
   #define ROUTINO_ERROR_NO_ROUTE_3 1003

Routino Option Definitions

   Calculate the shortest route.
   #define ROUTINO_ROUTE_SHORTEST 0

   Calculate the quickest route.
   #define ROUTINO_ROUTE_QUICKEST 1

   Output an HTML route file.
   #define ROUTINO_ROUTE_FILE_HTML 2

   Output a GPX track file.
   #define ROUTINO_ROUTE_FILE_GPX_TRACK 4

   Output a GPX route file.
   #define ROUTINO_ROUTE_FILE_GPX_ROUTE 8

   Output a text file with important junctions.
   #define ROUTINO_ROUTE_FILE_TEXT 16

   Output a text file with all nodes and segments.
   #define ROUTINO_ROUTE_FILE_TEXT_ALL 32

   Output a single file type to stdout.
   #define ROUTINO_ROUTE_FILE_STDOUT 64

   Output a linked list of of waypoints containing the HTML file
   information but as plain text.
   #define ROUTINO_ROUTE_LIST_HTML 128

   Output a linked list of of waypoints containing the text file
   information.
   #define ROUTINO_ROUTE_LIST_TEXT 256

   Output a linked list of of waypoints containing the text all file
   information.
   #define ROUTINO_ROUTE_LIST_TEXT_ALL 512

Linked List Output Point Definitions

   An unimportant, intermediate, node.
   #define ROUTINO_POINT_UNIMPORTANT 0

   A roundabout exit that is not taken.
   #define ROUTINO_POINT_RB_NOT_EXIT 1

   An un-interesting junction where the route continues without comment.
   #define ROUTINO_POINT_JUNCT_CONT 2

   The highway changes type but nothing else happens.
   #define ROUTINO_POINT_CHANGE 3

   An interesting junction to be described.
   #define ROUTINO_POINT_JUNCT_IMPORT 4

   The entrance to a roundabout.
   #define ROUTINO_POINT_RB_ENTRY 5

   The exit from a roundabout.
   #define ROUTINO_POINT_RB_EXIT 6

   The location of a mini-roundabout.
   #define ROUTINO_POINT_MINI_RB 7

   The location of a U-turn.
   #define ROUTINO_POINT_UTURN 8

   A waypoint.
   #define ROUTINO_POINT_WAYPOINT 9

Profile Definitions

   A Motorway highway.
   #define ROUTINO_HIGHWAY_MOTORWAY 1

   A Trunk highway.
   #define ROUTINO_HIGHWAY_TRUNK 2

   A Primary highway.
   #define ROUTINO_HIGHWAY_PRIMARY 3

   A Secondary highway.
   #define ROUTINO_HIGHWAY_SECONDARY 4

   A Tertiary highway.
   #define ROUTINO_HIGHWAY_TERTIARY 5

   A Unclassified highway.
   #define ROUTINO_HIGHWAY_UNCLASSIFIED 6

   A Residential highway.
   #define ROUTINO_HIGHWAY_RESIDENTIAL 7

   A Service highway.
   #define ROUTINO_HIGHWAY_SERVICE 8

   A Track highway.
   #define ROUTINO_HIGHWAY_TRACK 9

   A Cycleway highway.
   #define ROUTINO_HIGHWAY_CYCLEWAY 10

   A Path highway.
   #define ROUTINO_HIGHWAY_PATH 11

   A Steps highway.
   #define ROUTINO_HIGHWAY_STEPS 12

   A Ferry highway.
   #define ROUTINO_HIGHWAY_FERRY 13

   A Paved highway.
   #define ROUTINO_PROPERTY_PAVED 1

   A Multilane highway.
   #define ROUTINO_PROPERTY_MULTILANE 2

   A Bridge highway.
   #define ROUTINO_PROPERTY_BRIDGE 3

   A Tunnel highway.
   #define ROUTINO_PROPERTY_TUNNEL 4

   A Footroute highway.
   #define ROUTINO_PROPERTY_FOOTROUTE 5

   A Bicycleroute highway.
   #define ROUTINO_PROPERTY_BICYCLEROUTE 6

Type Definitions
- - - - - - - -

Typedef Routino_Database

   A data structure to hold a Routino database loaded from a file (the
   contents are private).

   typedef struct _Routino_Database Routino_Database

Typedef Routino_Waypoint

   A data structure to hold a Routino waypoint found within the database
   (the contents are private).

   typedef struct _Routino_Waypoint Routino_Waypoint

Typedef Routino_Profile

   A data structure to hold a Routino routing profile (the contents are
   private).

   typedef struct _Routino_Profile Routino_Profile

Typedef Routino_Translation

   A data structure to hold a Routino translation (the contents are
   private).

   typedef struct _Routino_Translation Routino_Translation

Typedef Routino_UserProfile

   A data structure to hold a routing profile that can be defined by the
   user.

   typedef struct _Routino_UserProfile Routino_UserProfile
   struct _Routino_UserProfile
      {
         int transport; The type of transport.
         float highway[14]; A floating point preference for travel on the
                            highway (range 0 to 1).
         float speed[14]; The maximum speed on each type of highway
                          (km/hour).
         float props[7]; A floating point preference for ways with this
                         attribute (range 0 to 1).
         int oneway; A flag to indicate if one-way restrictions apply.
         int turns; A flag to indicate if turn restrictions apply.
         float weight; The weight of the vehicle (in tonnes).
         float height; The height of the vehicle (in metres).
         float width; The width of vehicle (in metres).
         float length; The length of vehicle (in metres).
      }

Typedef Routino_Output

   Forward declaration of the Routino_Output data type.

   typedef struct _Routino_Output Routino_Output

Type struct _Routino_Output

   A linked list output of the calculated route whose contents depend on
   the ROUTINO_ROUTE_LIST_* options selected.

   struct _Routino_Output
      {
         Routino_Output* next; A pointer to the next route section.
         float lon; The longitude of the point (radians).
         float lat; The latitude of the point (radians).
         float dist; The total distance travelled (metres).
         float time; The total journey time (seconds).
         float speed; The speed (km/hr) for this section of the route
                      (ROUTINO_ROUTE_TEXT_ALL format only).
         int type; The type of point (one of the ROUTINO_POINT_* values).
         int turn; The amount to turn (degrees) for the next section of
                   the route (ROUTINO_ROUTE_TEXT format only).
         int bearing; The compass direction (degrees) for the next section
                      of the route.
         char* name; The name of the next section of the route
                       (ROUTINO_ROUTE_TEXT format) or previous section
                       of the route (ROUTINO_ROUTE_TEXT_ALL format).
      }

Typedef Routino_ProgressFunc

   A type of function that can be used as a callback to indicate routing
   progress, if it returns false the router stops.

   typedef int (*Routino_ProgressFunc)(double complete)

Variable Definitions
- - - - - - - - - -

Global Variable Routino_APIVersion

   Contains the libroutino API version number.

   int Routino_APIVersion

Global Variable Routino_errno

   Contains the error number of the most recent Routino function (one of
   the ROUTINO_ERROR_* values).

   int Routino_errno

Function Definitions
- - - - - - - - - -

Global Function Routino_CalculateRoute()

   Calculate a route using a loaded database, chosen profile, chosen
   translation and set of waypoints.

   Routino_Output* Routino_CalculateRoute ( Routino_Database* database,
   Routino_Profile* profile, Routino_Translation* translation,
   Routino_Waypoint** waypoints, int nwaypoints, int options,
   Routino_ProgressFunc progress )

   Routino_Output* Routino_CalculateRoute
          Returns the head of a linked list of route data (if requested)
          or NULL.

   Routino_Database* database
          The loaded database to use.

   Routino_Profile* profile
          The chosen routing profile to use.

   Routino_Translation* translation
          The chosen translation information to use.

   Routino_Waypoint** waypoints
          The set of waypoints.

   int nwaypoints
          The number of waypoints.

   int options
          The set of routing options (ROUTINO_ROUTE_*) ORed together.

   Routino_ProgressFunc progress
          A function to be called occasionally to report progress or NULL.

Global Function Routino_Check_API_Version()

   Check the version of the library used by the caller against the library
   version

   int Routino_Check_API_Version ( int caller_version )

   int Routino_Check_API_Version
          Returns ROUTINO_ERROR_NONE if OK or ROUTINO_ERROR_WRONG_VERSION
          if there is an error.

   int caller_version
          The version of the API used in the caller.

   This function should not be called directly, use the macro
   Routino_CheckAPIVersion() which takes no arguments.

   A wrapper function to simplify the API version check.
   #define Routino_CheckAPIVersion()

Global Function Routino_CreateProfileFromUserProfile()

   Create a fully formed Routino Profile from a Routino User Profile.

   Routino_Profile* Routino_CreateProfileFromUserProfile (
   Routino_UserProfile* profile )

   Routino_Profile* Routino_CreateProfileFromUserProfile
          Returns an allocated Routino Profile.

   Routino_UserProfile* profile
          The user specified profile to convert (not modified by this).

Global Function Routino_CreateUserProfileFromProfile()

   Create a Routino User Profile from a Routino Profile loaded from an XML
   file.

   Routino_UserProfile* Routino_CreateUserProfileFromProfile (
   Routino_Profile* profile )

   Routino_UserProfile* Routino_CreateUserProfileFromProfile
          Returns an allocated Routino User Profile.

   Routino_Profile* profile
          The Routino Profile to convert (not modified by this).

Global Function Routino_DeleteRoute()

   Delete the linked list created by Routino_CalculateRoute.

   void Routino_DeleteRoute ( Routino_Output* output )

   Routino_Output* output
          The output to be deleted.

Global Function Routino_FindWaypoint()

   Finds the nearest point in the database to the specified latitude and
   longitude.

   Routino_Waypoint* Routino_FindWaypoint ( Routino_Database* database,
   Routino_Profile* profile, double latitude, double longitude )

   Routino_Waypoint* Routino_FindWaypoint
          Returns a pointer to a newly allocated Routino waypoint or NULL
          if none could be found.

   Routino_Database* database
          The Routino database to use.

   Routino_Profile* profile
          The Routino profile to use.

   double latitude
          The latitude in degrees of the point.

   double longitude
          The longitude in degrees of the point.

Global Function Routino_FreeXMLProfiles()

   Free the internal memory that was allocated for the Routino profiles
   loaded from the XML file.

   void Routino_FreeXMLProfiles ( void )

Global Function Routino_FreeXMLTranslations()

   Free the internal memory that was allocated for the Routino
   translations loaded from the XML file.

   void Routino_FreeXMLTranslations ( void )

Global Function Routino_GetProfile()

   Select a specific routing profile from the set of Routino profiles that
   have been loaded from the XML file or NULL in case of an error.

   Routino_Profile* Routino_GetProfile ( const char* name )

   Routino_Profile* Routino_GetProfile
          Returns a pointer to an internal data structure - do not free.

   const char* name
          The name of the profile to select.

Global Function Routino_GetProfileNames()

   Return a list of the profile names that have been loaded from the XML
   file.

   char** Routino_GetProfileNames ( void )

   char** Routino_GetProfileNames
          Returns a NULL terminated list of strings - all allocated.

Global Function Routino_GetTranslation()

   Select a specific translation from the set of Routino translations that
   have been loaded from the XML file or NULL in case of an error.

   Routino_Translation* Routino_GetTranslation ( const char* language )

   Routino_Translation* Routino_GetTranslation
          Returns a pointer to an internal data structure - do not free.

   const char* language
          The language to select (as a country code, e.g. 'en', 'de') or
          an empty string for the first in the file or NULL for the
          built-in English version.

Global Function Routino_GetTranslationLanguages()

   Return a list of the translation languages that have been loaded from
   the XML file.

   char** Routino_GetTranslationLanguages ( void )

   char** Routino_GetTranslationLanguages
          Returns a NULL terminated list of strings - all allocated.

Global Function Routino_LoadDatabase()

   Load a database of files for Routino to use for routing.

   Routino_Database* Routino_LoadDatabase ( const char* dirname, const
   char* prefix )

   Routino_Database* Routino_LoadDatabase
          Returns a pointer to the database.

   const char* dirname
          The pathname of the directory containing the database files.

   const char* prefix
          The prefix of the database files.

Global Function Routino_ParseXMLProfiles()

   Parse a Routino XML file containing profiles, must be called before
   selecting a profile.

   int Routino_ParseXMLProfiles ( const char* filename )

   int Routino_ParseXMLProfiles
          Returns non-zero in case of an error or zero if there was no
          error.

   const char* filename
          The full pathname of the file to read.

Global Function Routino_ParseXMLTranslations()

   Parse a Routino XML file containing translations, must be called before
   selecting a translation.

   int Routino_ParseXMLTranslations ( const char* filename )

   int Routino_ParseXMLTranslations
          Returns non-zero in case of an error or zero if there was no
          error.

   const char* filename
          The full pathname of the file to read.

Global Function Routino_UnloadDatabase()

   Close the database files that were opened by a call to
   Routino_LoadDatabase().

   void Routino_UnloadDatabase ( Routino_Database* database )

   Routino_Database* database
          The database to close.

Global Function Routino_ValidateProfile()

   Validates that a selected routing profile is valid for use with the
   selected routing database.

   int Routino_ValidateProfile ( Routino_Database* database,
   Routino_Profile* profile )

   int Routino_ValidateProfile
          Returns zero if OK or something else in case of an error.

   Routino_Database* database
          The Routino database to use.

   Routino_Profile* profile
          The Routino profile to validate.

--------

Copyright 2015 Andrew M. Bishop.
1	amb	1760	Routino : Library
2			=================
3
4
5			Library Usage
6			-------------
7
8			This page describes the libroutino shared library that can be compiled
9			from the Routino source code and used in other programs.
10
11			Compilation
12			- - - - - -
13
14			The libroutino shared library is compiled by default when the Routino
15			source code is compiled. There are two versions; a normal version and a
16			'slim' version that uses less memory but is slower. The names of the
17			libraries are libroutino.so and libroutino-slim.so
18
19			Including
20			- - - - -
21
22			To use the Routino library in another program the source code for that
23			program should include the routino.h file. The functions that are
24			available in the library (both versions) are listed in this file along
25			with all of the constants and data types that are required.
26
27			Linking
28			- - - -
29
30			After compiling the program that uses the library it needs to be linked
31			to the library. For gcc this requires adding -lroutino or
32			-lroutino-slim to the linker command line, possibly with a -L...
33			parameter to specify the location of the library.
34
35			Example Library Interface Code
36			- - - - - - - - - - - - - - -
37
38			An example of a program that can link to the libroutino library is
39			provided in the Routino source code called router+lib.c. This is an
40			almost exact re-implementation of the standard Routino router program
41			using the libroutino library.
42
43
44			Library License
45			---------------
46
47			The source code for the libroutino and libroutino-slim libraries is the
48			GNU Affero General Public License v3 the same as for the rest of the
49			Routino software.
50
51			Linking with AGPLv3 Source Code
52			- - - - - - - - - - - - - - - -
53
54			If libroutino is linked with other APGLv3 code then the same license
55			applies to the combination as to the two parts.
56
57			Linking with GPLv3 Source Code
58			- - - - - - - - - - - - - - -
59
60			The AGPLv3 license is almost identical to the GNU General Public
61			License v3 except that network interaction with an AGPLv3 program
62			requires the same source code access as distributing compiled GPLv3
63			programs. This means that libroutino can be linked or combined with
64			code that is released under the GPLv3 without changing the license of
65			that code.
66
67			If there is no network interaction with the resulting program then the
68			Routino source code can be treated as if it was GPLv3 code for the
69			purposes of distribution and use.
70
71			If there is network interaction with the resulting program then the
72			AGPLv3 license will apply since this is required by section 13 of the
73			GPLv3.
74			The Software Freedom Law Center description of the GPLv3 and AGPLv3
75			licenses describes combining GPLv3 and APGLv3.
76			My understanding is that only when modified Routino code is linked with
77			GPLv3 code does network interaction require the modified Routino code
78			to be released.
79
80			Linking with Other Source Code
81			- - - - - - - - - - - - - - -
82
83			Linking libroutino with code released under any other license must
84			preserve the terms of the Routino license on the combination if the
85			software is distributed or interacted with over a network.
86
87
88			Routino Library API
89			-------------------
90
91			Preprocessor Definitions
92			- - - - - - - - - - - -
93
94	amb	1767	A version number for the Routino API.
95	amb	1768	#define ROUTINO_API_VERSION 4
96	amb	1767
97	amb	1760	Error Definitions
98
99			No error.
100			#define ROUTINO_ERROR_NONE 0
101
102			A function was called without the database variable set.
103			#define ROUTINO_ERROR_NO_DATABASE 1
104
105			A function was called without the profile variable set.
106			#define ROUTINO_ERROR_NO_PROFILE 2
107
108			A function was called without the translation variable set.
109			#define ROUTINO_ERROR_NO_TRANSLATION 3
110
111			The specified database to load did not exist.
112			#define ROUTINO_ERROR_NO_DATABASE_FILES 11
113
114			The specified database could not be loaded.
115			#define ROUTINO_ERROR_BAD_DATABASE_FILES 12
116
117			The specified profiles XML file did not exist.
118			#define ROUTINO_ERROR_NO_PROFILES_XML 13
119
120			The specified profiles XML file could not be loaded.
121			#define ROUTINO_ERROR_BAD_PROFILES_XML 14
122
123			The specified translations XML file did not exist.
124			#define ROUTINO_ERROR_NO_TRANSLATIONS_XML 15
125
126			The specified translations XML file could not be loaded.
127			#define ROUTINO_ERROR_BAD_TRANSLATIONS_XML 16
128
129			The requested profile name does not exist in the loaded XML file.
130			#define ROUTINO_ERROR_NO_SUCH_PROFILE 21
131
132			The requested translation language does not exist in the loaded XML
133			file.
134			#define ROUTINO_ERROR_NO_SUCH_TRANSLATION 22
135
136			There is no highway near the coordinates to place a waypoint.
137			#define ROUTINO_ERROR_NO_NEARBY_HIGHWAY 31
138
139			The profile and database do not work together.
140			#define ROUTINO_ERROR_PROFILE_DATABASE_ERR 41
141
142			The profile being used has not been validated.
143			#define ROUTINO_ERROR_NOTVALID_PROFILE 42
144
145			The user specified profile contained invalid data.
146			#define ROUTINO_ERROR_BAD_USER_PROFILE 43
147
148			The routing options specified are not consistent with each other.
149			#define ROUTINO_ERROR_BAD_OPTIONS 51
150
151	amb	1765	There is a mismatch between the library and caller API version.
152			#define ROUTINO_ERROR_WRONG_API_VERSION 61
153
154	amb	1767	The progress function returned false.
155			#define ROUTINO_ERROR_PROGRESS_ABORTED 71
156
157	amb	1760	A route could not be found to waypoint 1.
158			#define ROUTINO_ERROR_NO_ROUTE_1 1001
159
160			A route could not be found to waypoint 2.
161			#define ROUTINO_ERROR_NO_ROUTE_2 1002
162
163			A route could not be found to waypoint 3.
164			#define ROUTINO_ERROR_NO_ROUTE_3 1003
165
166			Routino Option Definitions
167
168			Calculate the shortest route.
169			#define ROUTINO_ROUTE_SHORTEST 0
170
171			Calculate the quickest route.
172			#define ROUTINO_ROUTE_QUICKEST 1
173
174			Output an HTML route file.
175			#define ROUTINO_ROUTE_FILE_HTML 2
176
177			Output a GPX track file.
178			#define ROUTINO_ROUTE_FILE_GPX_TRACK 4
179
180			Output a GPX route file.
181			#define ROUTINO_ROUTE_FILE_GPX_ROUTE 8
182
183			Output a text file with important junctions.
184			#define ROUTINO_ROUTE_FILE_TEXT 16
185
186			Output a text file with all nodes and segments.
187			#define ROUTINO_ROUTE_FILE_TEXT_ALL 32
188
189			Output a single file type to stdout.
190			#define ROUTINO_ROUTE_FILE_STDOUT 64
191
192	amb	1768	Output a linked list of of waypoints containing the HTML file
193			information but as plain text.
194			#define ROUTINO_ROUTE_LIST_HTML 128
195
196	amb	1760	Output a linked list of of waypoints containing the text file
197			information.
198	amb	1768	#define ROUTINO_ROUTE_LIST_TEXT 256
199	amb	1760
200			Output a linked list of of waypoints containing the text all file
201			information.
202	amb	1768	#define ROUTINO_ROUTE_LIST_TEXT_ALL 512
203	amb	1760
204			Linked List Output Point Definitions
205
206			An unimportant, intermediate, node.
207			#define ROUTINO_POINT_UNIMPORTANT 0
208
209			A roundabout exit that is not taken.
210			#define ROUTINO_POINT_RB_NOT_EXIT 1
211
212			An un-interesting junction where the route continues without comment.
213			#define ROUTINO_POINT_JUNCT_CONT 2
214
215			The highway changes type but nothing else happens.
216			#define ROUTINO_POINT_CHANGE 3
217
218			An interesting junction to be described.
219			#define ROUTINO_POINT_JUNCT_IMPORT 4
220
221			The entrance to a roundabout.
222			#define ROUTINO_POINT_RB_ENTRY 5
223
224			The exit from a roundabout.
225			#define ROUTINO_POINT_RB_EXIT 6
226
227			The location of a mini-roundabout.
228			#define ROUTINO_POINT_MINI_RB 7
229
230			The location of a U-turn.
231			#define ROUTINO_POINT_UTURN 8
232
233			A waypoint.
234			#define ROUTINO_POINT_WAYPOINT 9
235
236			Profile Definitions
237
238			A Motorway highway.
239			#define ROUTINO_HIGHWAY_MOTORWAY 1
240
241			A Trunk highway.
242			#define ROUTINO_HIGHWAY_TRUNK 2
243
244			A Primary highway.
245			#define ROUTINO_HIGHWAY_PRIMARY 3
246
247			A Secondary highway.
248			#define ROUTINO_HIGHWAY_SECONDARY 4
249
250			A Tertiary highway.
251			#define ROUTINO_HIGHWAY_TERTIARY 5
252
253			A Unclassified highway.
254			#define ROUTINO_HIGHWAY_UNCLASSIFIED 6
255
256			A Residential highway.
257			#define ROUTINO_HIGHWAY_RESIDENTIAL 7
258
259			A Service highway.
260			#define ROUTINO_HIGHWAY_SERVICE 8
261
262			A Track highway.
263			#define ROUTINO_HIGHWAY_TRACK 9
264
265			A Cycleway highway.
266			#define ROUTINO_HIGHWAY_CYCLEWAY 10
267
268			A Path highway.
269			#define ROUTINO_HIGHWAY_PATH 11
270
271			A Steps highway.
272			#define ROUTINO_HIGHWAY_STEPS 12
273
274			A Ferry highway.
275			#define ROUTINO_HIGHWAY_FERRY 13
276
277			A Paved highway.
278			#define ROUTINO_PROPERTY_PAVED 1
279
280			A Multilane highway.
281			#define ROUTINO_PROPERTY_MULTILANE 2
282
283			A Bridge highway.
284			#define ROUTINO_PROPERTY_BRIDGE 3
285
286			A Tunnel highway.
287			#define ROUTINO_PROPERTY_TUNNEL 4
288
289			A Footroute highway.
290			#define ROUTINO_PROPERTY_FOOTROUTE 5
291
292			A Bicycleroute highway.
293			#define ROUTINO_PROPERTY_BICYCLEROUTE 6
294
295			Type Definitions
296			- - - - - - - -
297
298			Typedef Routino_Database
299
300			A data structure to hold a Routino database loaded from a file (the
301			contents are private).
302	amb	1765
303	amb	1760	typedef struct _Routino_Database Routino_Database
304
305			Typedef Routino_Waypoint
306
307			A data structure to hold a Routino waypoint found within the database
308			(the contents are private).
309	amb	1765
310	amb	1760	typedef struct _Routino_Waypoint Routino_Waypoint
311
312			Typedef Routino_Profile
313
314			A data structure to hold a Routino routing profile (the contents are
315			private).
316	amb	1765
317	amb	1760	typedef struct _Routino_Profile Routino_Profile
318
319			Typedef Routino_Translation
320
321			A data structure to hold a Routino translation (the contents are
322			private).
323	amb	1765
324	amb	1760	typedef struct _Routino_Translation Routino_Translation
325
326			Typedef Routino_UserProfile
327
328			A data structure to hold a routing profile that can be defined by the
329			user.
330	amb	1765
331	amb	1760	typedef struct _Routino_UserProfile Routino_UserProfile
332			struct _Routino_UserProfile
333			{
334			int transport; The type of transport.
335			float highway[14]; A floating point preference for travel on the
336			highway (range 0 to 1).
337			float speed[14]; The maximum speed on each type of highway
338			(km/hour).
339			float props[7]; A floating point preference for ways with this
340			attribute (range 0 to 1).
341			int oneway; A flag to indicate if one-way restrictions apply.
342			int turns; A flag to indicate if turn restrictions apply.
343			float weight; The weight of the vehicle (in tonnes).
344			float height; The height of the vehicle (in metres).
345			float width; The width of vehicle (in metres).
346			float length; The length of vehicle (in metres).
347			}
348
349			Typedef Routino_Output
350
351			Forward declaration of the Routino_Output data type.
352	amb	1765
353	amb	1760	typedef struct _Routino_Output Routino_Output
354
355			Type struct _Routino_Output
356
357			A linked list output of the calculated route whose contents depend on
358			the ROUTINO_ROUTE_LIST_* options selected.
359	amb	1765
360	amb	1760	struct _Routino_Output
361			{
362			Routino_Output* next; A pointer to the next route section.
363			float lon; The longitude of the point (radians).
364			float lat; The latitude of the point (radians).
365			float dist; The total distance travelled (metres).
366			float time; The total journey time (seconds).
367	amb	1766	float speed; The speed (km/hr) for this section of the route
368			(ROUTINO_ROUTE_TEXT_ALL format only).
369	amb	1760	int type; The type of point (one of the ROUTINO_POINT_* values).
370			int turn; The amount to turn (degrees) for the next section of
371			the route (ROUTINO_ROUTE_TEXT format only).
372			int bearing; The compass direction (degrees) for the next section
373			of the route.
374	amb	1766	char* name; The name of the next section of the route
375	amb	1760	(ROUTINO_ROUTE_TEXT format) or previous section
376			of the route (ROUTINO_ROUTE_TEXT_ALL format).
377			}
378
379	amb	1767	Typedef Routino_ProgressFunc
380
381			A type of function that can be used as a callback to indicate routing
382			progress, if it returns false the router stops.
383
384			typedef int (*Routino_ProgressFunc)(double complete)
385
386	amb	1760	Variable Definitions
387			- - - - - - - - - -
388
389	amb	1765	Global Variable Routino_APIVersion
390
391			Contains the libroutino API version number.
392
393			int Routino_APIVersion
394
395	amb	1760	Global Variable Routino_errno
396
397			Contains the error number of the most recent Routino function (one of
398			the ROUTINO_ERROR_* values).
399	amb	1765
400	amb	1760	int Routino_errno
401
402			Function Definitions
403			- - - - - - - - - -
404
405			Global Function Routino_CalculateRoute()
406
407			Calculate a route using a loaded database, chosen profile, chosen
408			translation and set of waypoints.
409
410			Routino_Output* Routino_CalculateRoute ( Routino_Database* database,
411			Routino_Profile* profile, Routino_Translation* translation,
412	amb	1767	Routino_Waypoint** waypoints, int nwaypoints, int options,
413			Routino_ProgressFunc progress )
414	amb	1760
415			Routino_Output* Routino_CalculateRoute
416			Returns the head of a linked list of route data (if requested)
417			or NULL.
418
419			Routino_Database* database
420			The loaded database to use.
421
422			Routino_Profile* profile
423			The chosen routing profile to use.
424
425			Routino_Translation* translation
426			The chosen translation information to use.
427
428			Routino_Waypoint** waypoints
429			The set of waypoints.
430
431			int nwaypoints
432			The number of waypoints.
433
434			int options
435			The set of routing options (ROUTINO_ROUTE_*) ORed together.
436
437	amb	1767	Routino_ProgressFunc progress
438			A function to be called occasionally to report progress or NULL.
439
440	amb	1765	Global Function Routino_Check_API_Version()
441
442			Check the version of the library used by the caller against the library
443			version
444
445			int Routino_Check_API_Version ( int caller_version )
446
447			int Routino_Check_API_Version
448			Returns ROUTINO_ERROR_NONE if OK or ROUTINO_ERROR_WRONG_VERSION
449			if there is an error.
450
451			int caller_version
452			The version of the API used in the caller.
453
454			This function should not be called directly, use the macro
455			Routino_CheckAPIVersion() which takes no arguments.
456
457			A wrapper function to simplify the API version check.
458			#define Routino_CheckAPIVersion()
459
460	amb	1760	Global Function Routino_CreateProfileFromUserProfile()
461
462			Create a fully formed Routino Profile from a Routino User Profile.
463
464			Routino_Profile* Routino_CreateProfileFromUserProfile (
465			Routino_UserProfile* profile )
466
467			Routino_Profile* Routino_CreateProfileFromUserProfile
468			Returns an allocated Routino Profile.
469
470			Routino_UserProfile* profile
471			The user specified profile to convert (not modified by this).
472
473			Global Function Routino_CreateUserProfileFromProfile()
474
475			Create a Routino User Profile from a Routino Profile loaded from an XML
476			file.
477
478			Routino_UserProfile* Routino_CreateUserProfileFromProfile (
479			Routino_Profile* profile )
480
481			Routino_UserProfile* Routino_CreateUserProfileFromProfile
482			Returns an allocated Routino User Profile.
483
484			Routino_Profile* profile
485			The Routino Profile to convert (not modified by this).
486
487			Global Function Routino_DeleteRoute()
488
489			Delete the linked list created by Routino_CalculateRoute.
490
491			void Routino_DeleteRoute ( Routino_Output* output )
492
493			Routino_Output* output
494			The output to be deleted.
495
496			Global Function Routino_FindWaypoint()
497
498			Finds the nearest point in the database to the specified latitude and
499			longitude.
500
501			Routino_Waypoint* Routino_FindWaypoint ( Routino_Database* database,
502			Routino_Profile* profile, double latitude, double longitude )
503
504			Routino_Waypoint* Routino_FindWaypoint
505			Returns a pointer to a newly allocated Routino waypoint or NULL
506			if none could be found.
507
508			Routino_Database* database
509			The Routino database to use.
510
511			Routino_Profile* profile
512			The Routino profile to use.
513
514			double latitude
515			The latitude in degrees of the point.
516
517			double longitude
518			The longitude in degrees of the point.
519
520			Global Function Routino_FreeXMLProfiles()
521
522			Free the internal memory that was allocated for the Routino profiles
523			loaded from the XML file.
524
525			void Routino_FreeXMLProfiles ( void )
526
527			Global Function Routino_FreeXMLTranslations()
528
529			Free the internal memory that was allocated for the Routino
530			translations loaded from the XML file.
531
532			void Routino_FreeXMLTranslations ( void )
533
534			Global Function Routino_GetProfile()
535
536			Select a specific routing profile from the set of Routino profiles that
537			have been loaded from the XML file or NULL in case of an error.
538
539			Routino_Profile* Routino_GetProfile ( const char* name )
540
541			Routino_Profile* Routino_GetProfile
542			Returns a pointer to an internal data structure - do not free.
543
544			const char* name
545			The name of the profile to select.
546
547			Global Function Routino_GetProfileNames()
548
549			Return a list of the profile names that have been loaded from the XML
550			file.
551
552			char** Routino_GetProfileNames ( void )
553
554			char** Routino_GetProfileNames
555			Returns a NULL terminated list of strings - all allocated.
556
557			Global Function Routino_GetTranslation()
558
559			Select a specific translation from the set of Routino translations that
560			have been loaded from the XML file or NULL in case of an error.
561
562			Routino_Translation* Routino_GetTranslation ( const char* language )
563
564			Routino_Translation* Routino_GetTranslation
565			Returns a pointer to an internal data structure - do not free.
566
567			const char* language
568			The language to select (as a country code, e.g. 'en', 'de') or
569			an empty string for the first in the file or NULL for the
570			built-in English version.
571
572			Global Function Routino_GetTranslationLanguages()
573
574			Return a list of the translation languages that have been loaded from
575			the XML file.
576
577			char** Routino_GetTranslationLanguages ( void )
578
579			char** Routino_GetTranslationLanguages
580			Returns a NULL terminated list of strings - all allocated.
581
582			Global Function Routino_LoadDatabase()
583
584			Load a database of files for Routino to use for routing.
585
586			Routino_Database* Routino_LoadDatabase ( const char* dirname, const
587			char* prefix )
588
589			Routino_Database* Routino_LoadDatabase
590			Returns a pointer to the database.
591
592			const char* dirname
593			The pathname of the directory containing the database files.
594
595			const char* prefix
596			The prefix of the database files.
597
598			Global Function Routino_ParseXMLProfiles()
599
600			Parse a Routino XML file containing profiles, must be called before
601			selecting a profile.
602
603			int Routino_ParseXMLProfiles ( const char* filename )
604
605			int Routino_ParseXMLProfiles
606			Returns non-zero in case of an error or zero if there was no
607			error.
608
609			const char* filename
610			The full pathname of the file to read.
611
612			Global Function Routino_ParseXMLTranslations()
613
614			Parse a Routino XML file containing translations, must be called before
615			selecting a translation.
616
617			int Routino_ParseXMLTranslations ( const char* filename )
618
619			int Routino_ParseXMLTranslations
620			Returns non-zero in case of an error or zero if there was no
621			error.
622
623			const char* filename
624			The full pathname of the file to read.
625
626			Global Function Routino_UnloadDatabase()
627
628			Close the database files that were opened by a call to
629			Routino_LoadDatabase().
630
631			void Routino_UnloadDatabase ( Routino_Database* database )
632
633			Routino_Database* database
634			The database to close.
635
636			Global Function Routino_ValidateProfile()
637
638			Validates that a selected routing profile is valid for use with the
639			selected routing database.
640
641			int Routino_ValidateProfile ( Routino_Database* database,
642			Routino_Profile* profile )
643
644			int Routino_ValidateProfile
645			Returns zero if OK or something else in case of an error.
646
647			Routino_Database* database
648			The Routino database to use.
649
650			Routino_Profile* profile
651			The Routino profile to validate.
652
653			--------
654
655			Copyright 2015 Andrew M. Bishop.