trunk/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 5

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_LIST_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_LIST_TEXT or ROUTINO_ROUTE_LIST_HTML
                   format).
         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_LIST_TEXT or ROUTINO_ROUTE_LIST_HTML
                     format) or previous section of the route
                     (ROUTINO_ROUTE_LIST_TEXT_ALL format).
         char* desc1; The first part of the description of the next
                      section of route (ROUTINO_ROUTE_LIST_HTML format only).
         char* desc2; The second part of the description of the next
                      section of route (ROUTINO_ROUTE_LIST_HTML format only).
         char* desc3; The third part of the description, the total
                      distance and time (ROUTINO_ROUTE_LIST_HTML format only).
      }

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	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	A version number for the Routino API.
95	#define ROUTINO_API_VERSION 5
96
97	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	There is a mismatch between the library and caller API version.
152	#define ROUTINO_ERROR_WRONG_API_VERSION 61
153
154	The progress function returned false.
155	#define ROUTINO_ERROR_PROGRESS_ABORTED 71
156
157	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	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	Output a linked list of of waypoints containing the text file
197	information.
198	#define ROUTINO_ROUTE_LIST_TEXT 256
199
200	Output a linked list of of waypoints containing the text all file
201	information.
202	#define ROUTINO_ROUTE_LIST_TEXT_ALL 512
203
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
303	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
310	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
317	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
324	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
331	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
353	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
360	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	float speed; The speed (km/hr) for this section of the route
368	(ROUTINO_ROUTE_LIST_TEXT_ALL format only).
369	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_LIST_TEXT or ROUTINO_ROUTE_LIST_HTML
372	format).
373	int bearing; The compass direction (degrees) for the next section
374	of the route.
375	char* name; The name of the next section of the route
376	(ROUTINO_ROUTE_LIST_TEXT or ROUTINO_ROUTE_LIST_HTML
377	format) or previous section of the route
378	(ROUTINO_ROUTE_LIST_TEXT_ALL format).
379	char* desc1; The first part of the description of the next
380	section of route (ROUTINO_ROUTE_LIST_HTML format only).
381	char* desc2; The second part of the description of the next
382	section of route (ROUTINO_ROUTE_LIST_HTML format only).
383	char* desc3; The third part of the description, the total
384	distance and time (ROUTINO_ROUTE_LIST_HTML format only).
385	}
386
387	Typedef Routino_ProgressFunc
388
389	A type of function that can be used as a callback to indicate routing
390	progress, if it returns false the router stops.
391
392	typedef int (*Routino_ProgressFunc)(double complete)
393
394	Variable Definitions
395	- - - - - - - - - -
396
397	Global Variable Routino_APIVersion
398
399	Contains the libroutino API version number.
400
401	int Routino_APIVersion
402
403	Global Variable Routino_errno
404
405	Contains the error number of the most recent Routino function (one of
406	the ROUTINO_ERROR_* values).
407
408	int Routino_errno
409
410	Function Definitions
411	- - - - - - - - - -
412
413	Global Function Routino_CalculateRoute()
414
415	Calculate a route using a loaded database, chosen profile, chosen
416	translation and set of waypoints.
417
418	Routino_Output* Routino_CalculateRoute ( Routino_Database* database,
419	Routino_Profile* profile, Routino_Translation* translation,
420	Routino_Waypoint** waypoints, int nwaypoints, int options,
421	Routino_ProgressFunc progress )
422
423	Routino_Output* Routino_CalculateRoute
424	Returns the head of a linked list of route data (if requested)
425	or NULL.
426
427	Routino_Database* database
428	The loaded database to use.
429
430	Routino_Profile* profile
431	The chosen routing profile to use.
432
433	Routino_Translation* translation
434	The chosen translation information to use.
435
436	Routino_Waypoint** waypoints
437	The set of waypoints.
438
439	int nwaypoints
440	The number of waypoints.
441
442	int options
443	The set of routing options (ROUTINO_ROUTE_*) ORed together.
444
445	Routino_ProgressFunc progress
446	A function to be called occasionally to report progress or NULL.
447
448	Global Function Routino_Check_API_Version()
449
450	Check the version of the library used by the caller against the library
451	version
452
453	int Routino_Check_API_Version ( int caller_version )
454
455	int Routino_Check_API_Version
456	Returns ROUTINO_ERROR_NONE if OK or ROUTINO_ERROR_WRONG_VERSION
457	if there is an error.
458
459	int caller_version
460	The version of the API used in the caller.
461
462	This function should not be called directly, use the macro
463	Routino_CheckAPIVersion() which takes no arguments.
464
465	A wrapper function to simplify the API version check.
466	#define Routino_CheckAPIVersion()
467
468	Global Function Routino_CreateProfileFromUserProfile()
469
470	Create a fully formed Routino Profile from a Routino User Profile.
471
472	Routino_Profile* Routino_CreateProfileFromUserProfile (
473	Routino_UserProfile* profile )
474
475	Routino_Profile* Routino_CreateProfileFromUserProfile
476	Returns an allocated Routino Profile.
477
478	Routino_UserProfile* profile
479	The user specified profile to convert (not modified by this).
480
481	Global Function Routino_CreateUserProfileFromProfile()
482
483	Create a Routino User Profile from a Routino Profile loaded from an XML
484	file.
485
486	Routino_UserProfile* Routino_CreateUserProfileFromProfile (
487	Routino_Profile* profile )
488
489	Routino_UserProfile* Routino_CreateUserProfileFromProfile
490	Returns an allocated Routino User Profile.
491
492	Routino_Profile* profile
493	The Routino Profile to convert (not modified by this).
494
495	Global Function Routino_DeleteRoute()
496
497	Delete the linked list created by Routino_CalculateRoute.
498
499	void Routino_DeleteRoute ( Routino_Output* output )
500
501	Routino_Output* output
502	The output to be deleted.
503
504	Global Function Routino_FindWaypoint()
505
506	Finds the nearest point in the database to the specified latitude and
507	longitude.
508
509	Routino_Waypoint* Routino_FindWaypoint ( Routino_Database* database,
510	Routino_Profile* profile, double latitude, double longitude )
511
512	Routino_Waypoint* Routino_FindWaypoint
513	Returns a pointer to a newly allocated Routino waypoint or NULL
514	if none could be found.
515
516	Routino_Database* database
517	The Routino database to use.
518
519	Routino_Profile* profile
520	The Routino profile to use.
521
522	double latitude
523	The latitude in degrees of the point.
524
525	double longitude
526	The longitude in degrees of the point.
527
528	Global Function Routino_FreeXMLProfiles()
529
530	Free the internal memory that was allocated for the Routino profiles
531	loaded from the XML file.
532
533	void Routino_FreeXMLProfiles ( void )
534
535	Global Function Routino_FreeXMLTranslations()
536
537	Free the internal memory that was allocated for the Routino
538	translations loaded from the XML file.
539
540	void Routino_FreeXMLTranslations ( void )
541
542	Global Function Routino_GetProfile()
543
544	Select a specific routing profile from the set of Routino profiles that
545	have been loaded from the XML file or NULL in case of an error.
546
547	Routino_Profile* Routino_GetProfile ( const char* name )
548
549	Routino_Profile* Routino_GetProfile
550	Returns a pointer to an internal data structure - do not free.
551
552	const char* name
553	The name of the profile to select.
554
555	Global Function Routino_GetProfileNames()
556
557	Return a list of the profile names that have been loaded from the XML
558	file.
559
560	char** Routino_GetProfileNames ( void )
561
562	char** Routino_GetProfileNames
563	Returns a NULL terminated list of strings - all allocated.
564
565	Global Function Routino_GetTranslation()
566
567	Select a specific translation from the set of Routino translations that
568	have been loaded from the XML file or NULL in case of an error.
569
570	Routino_Translation* Routino_GetTranslation ( const char* language )
571
572	Routino_Translation* Routino_GetTranslation
573	Returns a pointer to an internal data structure - do not free.
574
575	const char* language
576	The language to select (as a country code, e.g. 'en', 'de') or
577	an empty string for the first in the file or NULL for the
578	built-in English version.
579
580	Global Function Routino_GetTranslationLanguages()
581
582	Return a list of the translation languages that have been loaded from
583	the XML file.
584
585	char** Routino_GetTranslationLanguages ( void )
586
587	char** Routino_GetTranslationLanguages
588	Returns a NULL terminated list of strings - all allocated.
589
590	Global Function Routino_LoadDatabase()
591
592	Load a database of files for Routino to use for routing.
593
594	Routino_Database* Routino_LoadDatabase ( const char* dirname, const
595	char* prefix )
596
597	Routino_Database* Routino_LoadDatabase
598	Returns a pointer to the database.
599
600	const char* dirname
601	The pathname of the directory containing the database files.
602
603	const char* prefix
604	The prefix of the database files.
605
606	Global Function Routino_ParseXMLProfiles()
607
608	Parse a Routino XML file containing profiles, must be called before
609	selecting a profile.
610
611	int Routino_ParseXMLProfiles ( const char* filename )
612
613	int Routino_ParseXMLProfiles
614	Returns non-zero in case of an error or zero if there was no
615	error.
616
617	const char* filename
618	The full pathname of the file to read.
619
620	Global Function Routino_ParseXMLTranslations()
621
622	Parse a Routino XML file containing translations, must be called before
623	selecting a translation.
624
625	int Routino_ParseXMLTranslations ( const char* filename )
626
627	int Routino_ParseXMLTranslations
628	Returns non-zero in case of an error or zero if there was no
629	error.
630
631	const char* filename
632	The full pathname of the file to read.
633
634	Global Function Routino_UnloadDatabase()
635
636	Close the database files that were opened by a call to
637	Routino_LoadDatabase().
638
639	void Routino_UnloadDatabase ( Routino_Database* database )
640
641	Routino_Database* database
642	The database to close.
643
644	Global Function Routino_ValidateProfile()
645
646	Validates that a selected routing profile is valid for use with the
647	selected routing database.
648
649	int Routino_ValidateProfile ( Routino_Database* database,
650	Routino_Profile* profile )
651
652	int Routino_ValidateProfile
653	Returns zero if OK or something else in case of an error.
654
655	Routino_Database* database
656	The Routino database to use.
657
658	Routino_Profile* profile
659	The Routino profile to validate.
660
661	--------
662
663	Copyright 2015 Andrew M. Bishop.