Routino SVN Repository Browser

Check out the latest version of Routino: svn co http://routino.org/svn/trunk routino

ViewVC logotype

Annotation of /trunk/doc/html/library.html

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1770 - (hide annotations) (download) (as text)
Sat Aug 8 13:40:55 2015 UTC (9 years, 7 months ago) by amb
Original Path: branches/libroutino/doc/html/library.html
File MIME type: text/html
File size: 37286 byte(s)
Add some missing API changes.

1 amb 1760 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
2     <html>
3    
4     <head>
5     <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
6     <meta name="viewport" content="width=device-width, initial-scale=1">
7    
8     <title>Routino : Library</title>
9    
10     <!--
11     Routino documentation - library
12    
13     Part of the Routino routing software.
14    
15     This file Copyright 2015 Andrew M. Bishop
16    
17     This program is free software: you can redistribute it and/or modify
18     it under the terms of the GNU Affero General Public License as published by
19     the Free Software Foundation, either version 3 of the License, or
20     (at your option) any later version.
21    
22     This program is distributed in the hope that it will be useful,
23     but WITHOUT ANY WARRANTY; without even the implied warranty of
24     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
25     GNU Affero General Public License for more details.
26    
27     You should have received a copy of the GNU Affero General Public License
28     along with this program. If not, see http://www.gnu.org/licenses/.
29     -->
30    
31     <link href="style.css" type="text/css" rel="stylesheet">
32    
33     <style type="text/css">
34    
35     /* Pre-processor definitions */
36    
37     SPAN.cxref-define-comment
38     {
39     font-style: normal;
40     }
41    
42     SPAN.cxref-define
43     {
44     font-family: monospace;
45     font-weight: bold;
46     font-style: normal;
47    
48     padding-top: 5px;
49     }
50    
51     /* Type definitions */
52    
53     SPAN.cxref-type-comment
54     {
55     font-style: normal;
56     }
57    
58     SPAN.cxref-type
59     {
60     font-family: monospace;
61     font-weight: bold;
62     font-style: normal;
63     }
64    
65     /* Variable definitions */
66    
67     SPAN.cxref-variable-comment
68     {
69     font-style: normal;
70     }
71    
72     SPAN.cxref-variable
73     {
74     font-family: monospace;
75     font-weight: bold;
76     font-style: normal;
77     }
78    
79     /* Function definitions */
80    
81     SPAN.cxref-function-comment
82     {
83     font-style: normal;
84     }
85    
86     SPAN.cxref-function
87     {
88     font-family: monospace;
89     font-weight: bold;
90     font-style: normal;
91     }
92    
93     </style>
94    
95     </head>
96    
97     <body>
98    
99     <!-- Header Start -->
100    
101     <div class="header">
102    
103     <h1>Routino : Library</h1>
104    
105     </div>
106    
107     <!-- Header End -->
108    
109     <!-- Content Start -->
110    
111     <div class="content">
112    
113     <h2 id="H_1_1">Library Usage</h2>
114    
115     This page describes the <tt>libroutino</tt> shared library that can be
116     compiled from the Routino source code and used in other programs.
117    
118     <h3 id="H_1_1_1">Compilation</h3>
119    
120     The <tt>libroutino</tt> shared library is compiled by default when the
121     Routino source code is compiled. There are two versions; a normal
122     version and a 'slim' version that uses less memory but is slower. The
123     names of the libraries are <tt>libroutino.so</tt>
124     and <tt>libroutino-slim.so</tt>
125    
126     <h3 id="H_1_1_2">Including</h3>
127    
128     To use the Routino library in another program the source code for that
129     program should include the <tt>routino.h</tt> file. The functions
130     that are available in the library (both versions) are listed in this
131     file along with all of the constants and data types that are required.
132    
133     <h3 id="H_1_1_3">Linking</h3>
134    
135     After compiling the program that uses the library it needs to be
136     linked to the library. For gcc this requires adding
137     <tt>-lroutino</tt> or <tt>-lroutino-slim</tt> to the linker command
138     line, possibly with a <tt>-L...</tt> parameter to specify the location
139     of the library.
140    
141     <h3 id="H_1_1_4">Example Library Interface Code</h3>
142    
143     An example of a program that can link to the <tt>libroutino</tt>
144     library is provided in the Routino source code called
145     <tt>router+lib.c</tt>. This is an almost exact re-implementation of
146     the standard Routino <tt>router</tt> program using the
147     <tt>libroutino</tt> library.
148    
149    
150     <h2 id="H_1_2">Library License</h2>
151    
152     The source code for the <tt>libroutino</tt> and <tt>libroutino-slim</tt>
153     libraries is the
154     <a class="ext" title="Affero GPLv3" href="http://www.gnu.org/licenses/agpl-3.0.html">GNU Affero General Public License v3</a>
155     the same as for the rest of the Routino software.
156    
157     <h3 id="H_1_2_1">Linking with AGPLv3 Source Code</h3>
158    
159     If <tt>libroutino</tt> is linked with other APGLv3 code then the same
160     license applies to the combination as to the two parts.
161    
162     <h3 id="H_1_2_2">Linking with GPLv3 Source Code</h3>
163    
164     The AGPLv3 license is almost identical to the
165     <a class="ext" title="GPLv3" href="http://www.gnu.org/licenses/gpl-3.0.html">GNU General Public License v3</a>
166     except that network interaction with an AGPLv3 program requires the
167     same source code access as distributing compiled GPLv3 programs.
168     This means that <tt>libroutino</tt> can be linked or combined with
169     code that is released under the GPLv3 without changing the license of
170     that code.
171     <p>
172     If there is no network interaction with the resulting program then the
173     Routino source code can be treated as if it was GPLv3 code for the
174     purposes of distribution and use.
175     <p>
176     If there is network interaction with the resulting program then the
177     AGPLv3 license will apply since this is required by section 13 of the
178     GPLv3.
179     <br>
180     The Software Freedom Law Center description of the GPLv3 and AGPLv3
181     licenses describes
182     <a class="ext" title="SFLC" href="http://www.softwarefreedom.org/resources/2014/SFLC-Guide_to_GPL_Compliance_2d_ed.html#section-13-use-with-the-gnu-affero-general-public-license">combining GPLv3 and APGLv3</a>.
183     <br>
184     My understanding is that only when modified Routino code is linked
185     with GPLv3 code does network interaction require the modified Routino
186     code to be released.
187    
188     <h3 id="H_1_2_3">Linking with Other Source Code</h3>
189    
190     Linking <tt>libroutino</tt> with code released under any other license
191     must preserve the terms of the Routino license on the combination if
192     the software is distributed or interacted with over a network.
193    
194    
195     <h2 id="H_1_3">Routino Library API</h2>
196    
197     <h3>Preprocessor Definitions</h3>
198    
199 amb 1765 <p>
200     <span class="cxref-define-comment"> A version number for the Routino API. </span>
201     <br>
202 amb 1768 <span class="cxref-define">#define ROUTINO_API_VERSION 4</span>
203 amb 1765
204 amb 1760 <h4>Error Definitions</h4>
205    
206     <p>
207     <span class="cxref-define-comment"> No error. </span>
208     <br>
209     <span class="cxref-define">#define ROUTINO_ERROR_NONE 0</span>
210     <p>
211     <span class="cxref-define-comment"> A function was called without the database variable set. </span>
212     <br>
213     <span class="cxref-define">#define ROUTINO_ERROR_NO_DATABASE 1</span>
214     <p>
215     <span class="cxref-define-comment"> A function was called without the profile variable set. </span>
216     <br>
217     <span class="cxref-define">#define ROUTINO_ERROR_NO_PROFILE 2</span>
218     <p>
219     <span class="cxref-define-comment"> A function was called without the translation variable set. </span>
220     <br>
221     <span class="cxref-define">#define ROUTINO_ERROR_NO_TRANSLATION 3</span>
222     <p>
223     <span class="cxref-define-comment"> The specified database to load did not exist. </span>
224     <br>
225     <span class="cxref-define">#define ROUTINO_ERROR_NO_DATABASE_FILES 11</span>
226     <p>
227     <span class="cxref-define-comment"> The specified database could not be loaded. </span>
228     <br>
229     <span class="cxref-define">#define ROUTINO_ERROR_BAD_DATABASE_FILES 12</span>
230     <p>
231     <span class="cxref-define-comment"> The specified profiles XML file did not exist. </span>
232     <br>
233     <span class="cxref-define">#define ROUTINO_ERROR_NO_PROFILES_XML 13</span>
234     <p>
235     <span class="cxref-define-comment"> The specified profiles XML file could not be loaded. </span>
236     <br>
237     <span class="cxref-define">#define ROUTINO_ERROR_BAD_PROFILES_XML 14</span>
238     <p>
239     <span class="cxref-define-comment"> The specified translations XML file did not exist. </span>
240     <br>
241     <span class="cxref-define">#define ROUTINO_ERROR_NO_TRANSLATIONS_XML 15</span>
242     <p>
243     <span class="cxref-define-comment"> The specified translations XML file could not be loaded. </span>
244     <br>
245     <span class="cxref-define">#define ROUTINO_ERROR_BAD_TRANSLATIONS_XML 16</span>
246     <p>
247     <span class="cxref-define-comment"> The requested profile name does not exist in the loaded XML file. </span>
248     <br>
249     <span class="cxref-define">#define ROUTINO_ERROR_NO_SUCH_PROFILE 21</span>
250     <p>
251     <span class="cxref-define-comment"> The requested translation language does not exist in the loaded XML file. </span>
252     <br>
253     <span class="cxref-define">#define ROUTINO_ERROR_NO_SUCH_TRANSLATION 22</span>
254     <p>
255     <span class="cxref-define-comment"> There is no highway near the coordinates to place a waypoint. </span>
256     <br>
257     <span class="cxref-define">#define ROUTINO_ERROR_NO_NEARBY_HIGHWAY 31</span>
258     <p>
259     <span class="cxref-define-comment"> The profile and database do not work together. </span>
260     <br>
261     <span class="cxref-define">#define ROUTINO_ERROR_PROFILE_DATABASE_ERR 41</span>
262     <p>
263     <span class="cxref-define-comment"> The profile being used has not been validated. </span>
264     <br>
265     <span class="cxref-define">#define ROUTINO_ERROR_NOTVALID_PROFILE 42</span>
266     <p>
267     <span class="cxref-define-comment"> The user specified profile contained invalid data. </span>
268     <br>
269     <span class="cxref-define">#define ROUTINO_ERROR_BAD_USER_PROFILE 43</span>
270     <p>
271     <span class="cxref-define-comment"> The routing options specified are not consistent with each other. </span>
272     <br>
273     <span class="cxref-define">#define ROUTINO_ERROR_BAD_OPTIONS 51</span>
274     <p>
275 amb 1765 <span class="cxref-define-comment"> There is a mismatch between the library and caller API version. </span>
276     <br>
277     <span class="cxref-define">#define ROUTINO_ERROR_WRONG_API_VERSION 61</span>
278     <p>
279 amb 1767 <span class="cxref-define-comment"> The progress function returned false. </span>
280     <br>
281     <span class="cxref-define">#define ROUTINO_ERROR_PROGRESS_ABORTED 71</span>
282     <p>
283 amb 1760 <span class="cxref-define-comment"> A route could not be found to waypoint 1. </span>
284     <br>
285     <span class="cxref-define">#define ROUTINO_ERROR_NO_ROUTE_1 1001</span>
286     <p>
287     <span class="cxref-define-comment"> A route could not be found to waypoint 2. </span>
288     <br>
289     <span class="cxref-define">#define ROUTINO_ERROR_NO_ROUTE_2 1002</span>
290     <p>
291     <span class="cxref-define-comment"> A route could not be found to waypoint 3. </span>
292     <br>
293     <span class="cxref-define">#define ROUTINO_ERROR_NO_ROUTE_3 1003</span>
294    
295     <h4>Routino Option Definitions</h4>
296    
297     <p>
298     <span class="cxref-define-comment"> Calculate the shortest route. </span>
299     <br>
300     <span class="cxref-define">#define ROUTINO_ROUTE_SHORTEST 0</span>
301     <p>
302     <span class="cxref-define-comment"> Calculate the quickest route. </span>
303     <br>
304     <span class="cxref-define">#define ROUTINO_ROUTE_QUICKEST 1</span>
305     <p>
306     <span class="cxref-define-comment"> Output an HTML route file. </span>
307     <br>
308     <span class="cxref-define">#define ROUTINO_ROUTE_FILE_HTML 2</span>
309     <p>
310     <span class="cxref-define-comment"> Output a GPX track file. </span>
311     <br>
312     <span class="cxref-define">#define ROUTINO_ROUTE_FILE_GPX_TRACK 4</span>
313     <p>
314     <span class="cxref-define-comment"> Output a GPX route file. </span>
315     <br>
316     <span class="cxref-define">#define ROUTINO_ROUTE_FILE_GPX_ROUTE 8</span>
317     <p>
318     <span class="cxref-define-comment"> Output a text file with important junctions. </span>
319     <br>
320     <span class="cxref-define">#define ROUTINO_ROUTE_FILE_TEXT 16</span>
321     <p>
322     <span class="cxref-define-comment"> Output a text file with all nodes and segments. </span>
323     <br>
324     <span class="cxref-define">#define ROUTINO_ROUTE_FILE_TEXT_ALL 32</span>
325     <p>
326     <span class="cxref-define-comment"> Output a single file type to stdout. </span>
327     <br>
328     <span class="cxref-define">#define ROUTINO_ROUTE_FILE_STDOUT 64</span>
329     <p>
330 amb 1768 <span class="cxref-define-comment"> Output a linked list of of waypoints containing the HTML file information but as plain text. </span>
331     <br>
332     <span class="cxref-define">#define ROUTINO_ROUTE_LIST_HTML 128</span>
333     <p>
334 amb 1760 <span class="cxref-define-comment"> Output a linked list of of waypoints containing the text file information. </span>
335     <br>
336 amb 1768 <span class="cxref-define">#define ROUTINO_ROUTE_LIST_TEXT 256</span>
337 amb 1760 <p>
338     <span class="cxref-define-comment"> Output a linked list of of waypoints containing the text all file information. </span>
339     <br>
340 amb 1768 <span class="cxref-define">#define ROUTINO_ROUTE_LIST_TEXT_ALL 512</span>
341 amb 1760
342     <h4>Linked List Output Point Definitions</h4>
343    
344     <p>
345     <span class="cxref-define-comment"> An unimportant, intermediate, node. </span>
346     <br>
347     <span class="cxref-define">#define ROUTINO_POINT_UNIMPORTANT 0</span>
348     <p>
349     <span class="cxref-define-comment"> A roundabout exit that is not taken. </span>
350     <br>
351     <span class="cxref-define">#define ROUTINO_POINT_RB_NOT_EXIT 1</span>
352     <p>
353     <span class="cxref-define-comment"> An un-interesting junction where the route continues without comment. </span>
354     <br>
355     <span class="cxref-define">#define ROUTINO_POINT_JUNCT_CONT 2</span>
356     <p>
357     <span class="cxref-define-comment"> The highway changes type but nothing else happens. </span>
358     <br>
359     <span class="cxref-define">#define ROUTINO_POINT_CHANGE 3</span>
360     <p>
361     <span class="cxref-define-comment"> An interesting junction to be described. </span>
362     <br>
363     <span class="cxref-define">#define ROUTINO_POINT_JUNCT_IMPORT 4</span>
364     <p>
365     <span class="cxref-define-comment"> The entrance to a roundabout. </span>
366     <br>
367     <span class="cxref-define">#define ROUTINO_POINT_RB_ENTRY 5</span>
368     <p>
369     <span class="cxref-define-comment"> The exit from a roundabout. </span>
370     <br>
371     <span class="cxref-define">#define ROUTINO_POINT_RB_EXIT 6</span>
372     <p>
373     <span class="cxref-define-comment"> The location of a mini-roundabout. </span>
374     <br>
375     <span class="cxref-define">#define ROUTINO_POINT_MINI_RB 7</span>
376     <p>
377     <span class="cxref-define-comment"> The location of a U-turn. </span>
378     <br>
379     <span class="cxref-define">#define ROUTINO_POINT_UTURN 8</span>
380     <p>
381     <span class="cxref-define-comment"> A waypoint. </span>
382     <br>
383     <span class="cxref-define">#define ROUTINO_POINT_WAYPOINT 9</span>
384    
385     <h4>Profile Definitions</h4>
386    
387     <p>
388     <span class="cxref-define-comment"> A Motorway highway. </span>
389     <br>
390     <span class="cxref-define">#define ROUTINO_HIGHWAY_MOTORWAY 1</span>
391     <p>
392     <span class="cxref-define-comment"> A Trunk highway. </span>
393     <br>
394     <span class="cxref-define">#define ROUTINO_HIGHWAY_TRUNK 2</span>
395     <p>
396     <span class="cxref-define-comment"> A Primary highway. </span>
397     <br>
398     <span class="cxref-define">#define ROUTINO_HIGHWAY_PRIMARY 3</span>
399     <p>
400     <span class="cxref-define-comment"> A Secondary highway. </span>
401     <br>
402     <span class="cxref-define">#define ROUTINO_HIGHWAY_SECONDARY 4</span>
403     <p>
404     <span class="cxref-define-comment"> A Tertiary highway. </span>
405     <br>
406     <span class="cxref-define">#define ROUTINO_HIGHWAY_TERTIARY 5</span>
407     <p>
408     <span class="cxref-define-comment"> A Unclassified highway. </span>
409     <br>
410     <span class="cxref-define">#define ROUTINO_HIGHWAY_UNCLASSIFIED 6</span>
411     <p>
412     <span class="cxref-define-comment"> A Residential highway. </span>
413     <br>
414     <span class="cxref-define">#define ROUTINO_HIGHWAY_RESIDENTIAL 7</span>
415     <p>
416     <span class="cxref-define-comment"> A Service highway. </span>
417     <br>
418     <span class="cxref-define">#define ROUTINO_HIGHWAY_SERVICE 8</span>
419     <p>
420     <span class="cxref-define-comment"> A Track highway. </span>
421     <br>
422     <span class="cxref-define">#define ROUTINO_HIGHWAY_TRACK 9</span>
423     <p>
424     <span class="cxref-define-comment"> A Cycleway highway. </span>
425     <br>
426     <span class="cxref-define">#define ROUTINO_HIGHWAY_CYCLEWAY 10</span>
427     <p>
428     <span class="cxref-define-comment"> A Path highway. </span>
429     <br>
430     <span class="cxref-define">#define ROUTINO_HIGHWAY_PATH 11</span>
431     <p>
432     <span class="cxref-define-comment"> A Steps highway. </span>
433     <br>
434     <span class="cxref-define">#define ROUTINO_HIGHWAY_STEPS 12</span>
435     <p>
436     <span class="cxref-define-comment"> A Ferry highway. </span>
437     <br>
438     <span class="cxref-define">#define ROUTINO_HIGHWAY_FERRY 13</span>
439     <p>
440     <span class="cxref-define-comment"> A Paved highway. </span>
441     <br>
442     <span class="cxref-define">#define ROUTINO_PROPERTY_PAVED 1</span>
443     <p>
444     <span class="cxref-define-comment"> A Multilane highway. </span>
445     <br>
446     <span class="cxref-define">#define ROUTINO_PROPERTY_MULTILANE 2</span>
447     <p>
448     <span class="cxref-define-comment"> A Bridge highway. </span>
449     <br>
450     <span class="cxref-define">#define ROUTINO_PROPERTY_BRIDGE 3</span>
451     <p>
452     <span class="cxref-define-comment"> A Tunnel highway. </span>
453     <br>
454     <span class="cxref-define">#define ROUTINO_PROPERTY_TUNNEL 4</span>
455     <p>
456     <span class="cxref-define-comment"> A Footroute highway. </span>
457     <br>
458     <span class="cxref-define">#define ROUTINO_PROPERTY_FOOTROUTE 5</span>
459     <p>
460     <span class="cxref-define-comment"> A Bicycleroute highway. </span>
461     <br>
462     <span class="cxref-define">#define ROUTINO_PROPERTY_BICYCLEROUTE 6</span>
463    
464 amb 1765
465 amb 1760 <h3>Type Definitions</h3>
466    
467     <h4><a name="type-Routino_Database">Typedef Routino_Database</a></h4>
468    
469     <p>
470     <span class="cxref-type-comment"> A data structure to hold a Routino database loaded from a file (the contents are private). </span>
471     <br>
472     <span class="cxref-type">typedef struct _Routino_Database Routino_Database</span>
473    
474     <h4><a name="type-Routino_Waypoint">Typedef Routino_Waypoint</a></h4>
475    
476     <p>
477     <span class="cxref-type-comment"> A data structure to hold a Routino waypoint found within the database (the contents are private). </span>
478     <br>
479     <span class="cxref-type">typedef struct _Routino_Waypoint Routino_Waypoint</span>
480    
481     <h4><a name="type-Routino_Profile">Typedef Routino_Profile</a></h4>
482    
483     <p>
484     <span class="cxref-type-comment"> A data structure to hold a Routino routing profile (the contents are private). </span>
485     <br>
486     <span class="cxref-type">typedef struct _Routino_Profile Routino_Profile</span>
487    
488     <h4><a name="type-Routino_Translation">Typedef Routino_Translation</a></h4>
489    
490     <p>
491     <span class="cxref-type-comment"> A data structure to hold a Routino translation (the contents are private). </span>
492     <br>
493     <span class="cxref-type">typedef struct _Routino_Translation Routino_Translation</span>
494    
495     <h4><a name="type-Routino_UserProfile">Typedef Routino_UserProfile</a></h4>
496    
497     <p>
498     <span class="cxref-type-comment"> A data structure to hold a routing profile that can be defined by the user. </span>
499     <br>
500     <span class="cxref-type">typedef struct _Routino_UserProfile Routino_UserProfile</span>
501     <br>
502     <table class="noborder-left">
503     <tr>
504     <td><span class="cxref-type">struct _Routino_UserProfile</span>
505     <td>&nbsp;
506     </tr>
507     <tr>
508     <td>&nbsp;&nbsp;&nbsp;<span class="cxref-type">{</span>
509     <td>&nbsp;
510     </tr>
511     <tr>
512     <td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
513     <span class="cxref-type">int transport;</span>
514     <td><span class="cxref-type-comment"> The type of transport. </span>
515     </tr>
516     <tr>
517     <td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
518     <span class="cxref-type">float highway[14];</span>
519     <td><span class="cxref-type-comment"> A floating point preference for travel on the highway (range 0 to 1). </span>
520     </tr>
521     <tr>
522     <td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
523     <span class="cxref-type">float speed[14];</span>
524     <td><span class="cxref-type-comment"> The maximum speed on each type of highway (km/hour). </span>
525     </tr>
526     <tr>
527     <td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
528     <span class="cxref-type">float props[7];</span>
529     <td><span class="cxref-type-comment"> A floating point preference for ways with this attribute (range 0 to 1). </span>
530     </tr>
531     <tr>
532     <td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
533     <span class="cxref-type">int oneway;</span>
534     <td><span class="cxref-type-comment"> A flag to indicate if one-way restrictions apply. </span>
535     </tr>
536     <tr>
537     <td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
538     <span class="cxref-type">int turns;</span>
539     <td><span class="cxref-type-comment"> A flag to indicate if turn restrictions apply. </span>
540     </tr>
541     <tr>
542     <td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
543     <span class="cxref-type">float weight;</span>
544     <td><span class="cxref-type-comment"> The weight of the vehicle (in tonnes). </span>
545     </tr>
546     <tr>
547     <td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
548     <span class="cxref-type">float height;</span>
549     <td><span class="cxref-type-comment"> The height of the vehicle (in metres). </span>
550     </tr>
551     <tr>
552     <td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
553     <span class="cxref-type">float width;</span>
554     <td><span class="cxref-type-comment"> The width of vehicle (in metres). </span>
555     </tr>
556     <tr>
557     <td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
558     <span class="cxref-type">float length;</span>
559     <td><span class="cxref-type-comment"> The length of vehicle (in metres). </span>
560     </tr>
561     <tr>
562     <td>&nbsp;&nbsp;&nbsp;<span class="cxref-type">}</span>
563     <td>&nbsp;
564     </tr>
565     </table>
566    
567     <h4><a name="type-Routino_Output">Typedef Routino_Output</a></h4>
568    
569     <p>
570     <span class="cxref-type-comment"> Forward declaration of the Routino_Output data type. </span>
571     <br>
572     <span class="cxref-type">typedef struct _Routino_Output Routino_Output</span>
573    
574     <h4><a name="type-struct-_Routino_Output">Type struct _Routino_Output</a></h4>
575    
576     <p>
577     <span class="cxref-type-comment"> A linked list output of the calculated route whose contents depend on the ROUTINO_ROUTE_LIST_* options selected. </span>
578     <br>
579     <span class="cxref-type">struct _Routino_Output</span>
580     <br>
581     <table class="noborder-left">
582     <tr>
583     <td><span class="cxref-type">struct _Routino_Output</span>
584     <td>&nbsp;
585     </tr>
586     <tr>
587     <td>&nbsp;&nbsp;&nbsp;<span class="cxref-type">{</span>
588     <td>&nbsp;
589     </tr>
590     <tr>
591     <td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
592     <span class="cxref-type">Routino_Output* next;</span>
593     <td><span class="cxref-type-comment"> A pointer to the next route section. </span>
594     </tr>
595     <tr>
596     <td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
597     <span class="cxref-type">float lon;</span>
598     <td><span class="cxref-type-comment"> The longitude of the point (radians). </span>
599     </tr>
600     <tr>
601     <td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
602     <span class="cxref-type">float lat;</span>
603     <td><span class="cxref-type-comment"> The latitude of the point (radians). </span>
604     </tr>
605     <tr>
606     <td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
607     <span class="cxref-type">float dist;</span>
608     <td><span class="cxref-type-comment"> The total distance travelled (metres). </span>
609     </tr>
610     <tr>
611     <td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
612     <span class="cxref-type">float time;</span>
613     <td><span class="cxref-type-comment"> The total journey time (seconds). </span>
614     </tr>
615     <tr>
616     <td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
617 amb 1766 <span class="cxref-type">float speed;</span>
618 amb 1770 <td><span class="cxref-type-comment"> The speed (km/hr) for this section of the route (ROUTINO_ROUTE_LIST_TEXT_ALL format only). </span>
619 amb 1766 </tr>
620     <tr>
621     <td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
622 amb 1760 <span class="cxref-type">int type;</span>
623     <td><span class="cxref-type-comment"> The type of point (one of the ROUTINO_POINT_* values). </span>
624     </tr>
625     <tr>
626     <td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
627     <span class="cxref-type">int turn;</span>
628 amb 1770 <td><span class="cxref-type-comment"> The amount to turn (degrees) for the next section of the route (ROUTINO_ROUTE_LIST_TEXT or ROUTINO_ROUTE_LIST_HTML format). </span>
629 amb 1760 </tr>
630     <tr>
631     <td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
632     <span class="cxref-type">int bearing;</span>
633     <td><span class="cxref-type-comment"> The compass direction (degrees) for the next section of the route. </span>
634     </tr>
635     <tr>
636     <td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
637 amb 1766 <span class="cxref-type">char* name;</span>
638 amb 1770 <td><span class="cxref-type-comment"> 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). </span>
639 amb 1760 </tr>
640     <tr>
641 amb 1770 <td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
642     <span class="cxref-type">char* desc1;</span>
643     <td><span class="cxref-type-comment"> The first part of the description of the next section of route (ROUTINO_ROUTE_LIST_HTML format only). </span>
644     </tr>
645     <tr>
646     <td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
647     <span class="cxref-type">char* desc2;</span>
648     <td><span class="cxref-type-comment"> The second part of the description of the next section of route (ROUTINO_ROUTE_LIST_HTML format only). </span>
649     </tr>
650     <tr>
651 amb 1760 <td>&nbsp;&nbsp;&nbsp;<span class="cxref-type">}</span>
652     <td>&nbsp;
653     </tr>
654     </table>
655    
656 amb 1767 <h4><a name="type-Routino_ProgressFunc">Typedef Routino_ProgressFunc</a></h4>
657 amb 1760
658 amb 1767 <p>
659     <span class="cxref-type-comment"> A type of function that can be used as a callback to indicate routing progress, if it returns false the router stops. </span>
660     <br>
661     <span class="cxref-type">typedef int (*Routino_ProgressFunc)(double complete)</span>
662    
663 amb 1760 <h3>Variable Definitions</h3>
664    
665 amb 1765 <h4><a name="var-Routino_APIVersion">Global Variable Routino_APIVersion</a></h4>
666    
667     <p>
668     <span class="cxref-variable-comment"> Contains the libroutino API version number. </span>
669     <br>
670     <span class="cxref-variable">int Routino_APIVersion</span>
671    
672 amb 1760 <h4><a name="var-Routino_errno">Global Variable Routino_errno</a></h4>
673    
674     <p>
675     <span class="cxref-variable-comment"> Contains the error number of the most recent Routino function (one of the ROUTINO_ERROR_* values). </span>
676     <br>
677     <span class="cxref-variable">int Routino_errno</span>
678    
679    
680     <h3>Function Definitions</h3>
681    
682     <h4><a name="func-Routino_CalculateRoute">Global Function Routino_CalculateRoute()</a></h4>
683    
684     <p>
685     <span class="cxref-function-comment"> Calculate a route using a loaded database, chosen profile, chosen translation and set of waypoints.</span>
686     <br>
687 amb 1767 <span class="cxref-function">Routino_Output* Routino_CalculateRoute ( Routino_Database* database, Routino_Profile* profile, Routino_Translation* translation, Routino_Waypoint** waypoints, int nwaypoints, int options, Routino_ProgressFunc progress )</span>
688 amb 1760 <br>
689     <dl>
690     <dt><span class="cxref-function">Routino_Output* Routino_CalculateRoute</span>
691     <dd><span class="cxref-function-comment">Returns the head of a linked list of route data (if requested) or NULL.</span>
692     <dt><span class="cxref-function">Routino_Database* database</span>
693     <dd><span class="cxref-function-comment">The loaded database to use.</span>
694     <dt><span class="cxref-function">Routino_Profile* profile</span>
695     <dd><span class="cxref-function-comment">The chosen routing profile to use.</span>
696     <dt><span class="cxref-function">Routino_Translation* translation</span>
697     <dd><span class="cxref-function-comment">The chosen translation information to use.</span>
698     <dt><span class="cxref-function">Routino_Waypoint** waypoints</span>
699     <dd><span class="cxref-function-comment">The set of waypoints.</span>
700     <dt><span class="cxref-function">int nwaypoints</span>
701     <dd><span class="cxref-function-comment">The number of waypoints.</span>
702     <dt><span class="cxref-function">int options</span>
703     <dd><span class="cxref-function-comment">The set of routing options (ROUTINO_ROUTE_*) ORed together.</span>
704 amb 1767 <dt><span class="cxref-function">Routino_ProgressFunc progress</span>
705     <dd><span class="cxref-function-comment">A function to be called occasionally to report progress or NULL.</span>
706 amb 1760 </dl>
707    
708 amb 1765 <h4><a name="func-Routino_Check_API_Version">Global Function Routino_Check_API_Version()</a></h4>
709    
710     <p>
711     <span class="cxref-function-comment"> Check the version of the library used by the caller against the library version</span>
712     <br>
713     <span class="cxref-function">int Routino_Check_API_Version ( int caller_version )</span>
714     <br>
715     <dl>
716     <dt><span class="cxref-function">int Routino_Check_API_Version</span>
717     <dd><span class="cxref-function-comment">Returns ROUTINO_ERROR_NONE if OK or ROUTINO_ERROR_WRONG_VERSION if there is an error.</span>
718     <dt><span class="cxref-function">int caller_version</span>
719     <dd><span class="cxref-function-comment">The version of the API used in the caller.</span>
720     </dl>
721     <br>
722     <span class="cxref-function-comment"> This function should not be called directly, use the macro Routino_CheckAPIVersion() which takes no arguments.</span>
723    
724     <p>
725     <span class="cxref-define-comment"> A wrapper function to simplify the API version check. </span>
726     <br>
727     <span class="cxref-define">#define Routino_CheckAPIVersion()</span>
728    
729 amb 1760 <h4><a name="func-Routino_CreateProfileFromUserProfile">Global Function Routino_CreateProfileFromUserProfile()</a></h4>
730    
731     <p>
732     <span class="cxref-function-comment"> Create a fully formed Routino Profile from a Routino User Profile.</span>
733     <br>
734     <span class="cxref-function">Routino_Profile* Routino_CreateProfileFromUserProfile ( Routino_UserProfile* profile )</span>
735     <br>
736     <dl>
737     <dt><span class="cxref-function">Routino_Profile* Routino_CreateProfileFromUserProfile</span>
738     <dd><span class="cxref-function-comment">Returns an allocated Routino Profile.</span>
739     <dt><span class="cxref-function">Routino_UserProfile* profile</span>
740     <dd><span class="cxref-function-comment">The user specified profile to convert (not modified by this).</span>
741     </dl>
742    
743     <h4><a name="func-Routino_CreateUserProfileFromProfile">Global Function Routino_CreateUserProfileFromProfile()</a></h4>
744    
745     <p>
746     <span class="cxref-function-comment"> Create a Routino User Profile from a Routino Profile loaded from an XML file.</span>
747     <br>
748     <span class="cxref-function">Routino_UserProfile* Routino_CreateUserProfileFromProfile ( Routino_Profile* profile )</span>
749     <br>
750     <dl>
751     <dt><span class="cxref-function">Routino_UserProfile* Routino_CreateUserProfileFromProfile</span>
752     <dd><span class="cxref-function-comment">Returns an allocated Routino User Profile.</span>
753     <dt><span class="cxref-function">Routino_Profile* profile</span>
754     <dd><span class="cxref-function-comment">The Routino Profile to convert (not modified by this).</span>
755     </dl>
756    
757     <h4><a name="func-Routino_DeleteRoute">Global Function Routino_DeleteRoute()</a></h4>
758    
759     <p>
760     <span class="cxref-function-comment"> Delete the linked list created by Routino_CalculateRoute.</span>
761     <br>
762     <span class="cxref-function">void Routino_DeleteRoute ( Routino_Output* output )</span>
763     <br>
764     <dl>
765     <dt><span class="cxref-function">Routino_Output* output</span>
766     <dd><span class="cxref-function-comment">The output to be deleted.</span>
767     </dl>
768    
769     <h4><a name="func-Routino_FindWaypoint">Global Function Routino_FindWaypoint()</a></h4>
770    
771     <p>
772     <span class="cxref-function-comment"> Finds the nearest point in the database to the specified latitude and longitude.</span>
773     <br>
774     <span class="cxref-function">Routino_Waypoint* Routino_FindWaypoint ( Routino_Database* database, Routino_Profile* profile, double latitude, double longitude )</span>
775     <br>
776     <dl>
777     <dt><span class="cxref-function">Routino_Waypoint* Routino_FindWaypoint</span>
778     <dd><span class="cxref-function-comment">Returns a pointer to a newly allocated Routino waypoint or NULL if none could be found.</span>
779     <dt><span class="cxref-function">Routino_Database* database</span>
780     <dd><span class="cxref-function-comment">The Routino database to use.</span>
781     <dt><span class="cxref-function">Routino_Profile* profile</span>
782     <dd><span class="cxref-function-comment">The Routino profile to use.</span>
783     <dt><span class="cxref-function">double latitude</span>
784     <dd><span class="cxref-function-comment">The latitude in degrees of the point.</span>
785     <dt><span class="cxref-function">double longitude</span>
786     <dd><span class="cxref-function-comment">The longitude in degrees of the point.</span>
787     </dl>
788    
789     <h4><a name="func-Routino_FreeXMLProfiles">Global Function Routino_FreeXMLProfiles()</a></h4>
790    
791     <p>
792     <span class="cxref-function-comment"> Free the internal memory that was allocated for the Routino profiles loaded from the XML file.</span>
793     <br>
794     <span class="cxref-function">void Routino_FreeXMLProfiles ( void )</span>
795    
796     <h4><a name="func-Routino_FreeXMLTranslations">Global Function Routino_FreeXMLTranslations()</a></h4>
797    
798     <p>
799     <span class="cxref-function-comment"> Free the internal memory that was allocated for the Routino translations loaded from the XML file.</span>
800     <br>
801     <span class="cxref-function">void Routino_FreeXMLTranslations ( void )</span>
802    
803     <h4><a name="func-Routino_GetProfile">Global Function Routino_GetProfile()</a></h4>
804    
805     <p>
806     <span class="cxref-function-comment"> 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.</span>
807     <br>
808     <span class="cxref-function">Routino_Profile* Routino_GetProfile ( const char* name )</span>
809     <br>
810     <dl>
811     <dt><span class="cxref-function">Routino_Profile* Routino_GetProfile</span>
812     <dd><span class="cxref-function-comment">Returns a pointer to an internal data structure - do not free.</span>
813     <dt><span class="cxref-function">const char* name</span>
814     <dd><span class="cxref-function-comment">The name of the profile to select.</span>
815     </dl>
816    
817     <h4><a name="func-Routino_GetProfileNames">Global Function Routino_GetProfileNames()</a></h4>
818    
819     <p>
820     <span class="cxref-function-comment"> Return a list of the profile names that have been loaded from the XML file.</span>
821     <br>
822     <span class="cxref-function">char** Routino_GetProfileNames ( void )</span>
823     <br>
824     <dl>
825     <dt><span class="cxref-function">char** Routino_GetProfileNames</span>
826     <dd><span class="cxref-function-comment">Returns a NULL terminated list of strings - all allocated.</span>
827     </dl>
828    
829     <h4><a name="func-Routino_GetTranslation">Global Function Routino_GetTranslation()</a></h4>
830    
831     <p>
832     <span class="cxref-function-comment"> 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.</span>
833     <br>
834     <span class="cxref-function">Routino_Translation* Routino_GetTranslation ( const char* language )</span>
835     <br>
836     <dl>
837     <dt><span class="cxref-function">Routino_Translation* Routino_GetTranslation</span>
838     <dd><span class="cxref-function-comment">Returns a pointer to an internal data structure - do not free.</span>
839     <dt><span class="cxref-function">const char* language</span>
840     <dd><span class="cxref-function-comment">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.</span>
841     </dl>
842    
843     <h4><a name="func-Routino_GetTranslationLanguages">Global Function Routino_GetTranslationLanguages()</a></h4>
844    
845     <p>
846     <span class="cxref-function-comment"> Return a list of the translation languages that have been loaded from the XML file.</span>
847     <br>
848     <span class="cxref-function">char** Routino_GetTranslationLanguages ( void )</span>
849     <br>
850     <dl>
851     <dt><span class="cxref-function">char** Routino_GetTranslationLanguages</span>
852     <dd><span class="cxref-function-comment">Returns a NULL terminated list of strings - all allocated.</span>
853     </dl>
854    
855     <h4><a name="func-Routino_LoadDatabase">Global Function Routino_LoadDatabase()</a></h4>
856    
857     <p>
858     <span class="cxref-function-comment"> Load a database of files for Routino to use for routing.</span>
859     <br>
860     <span class="cxref-function">Routino_Database* Routino_LoadDatabase ( const char* dirname, const char* prefix )</span>
861     <br>
862     <dl>
863     <dt><span class="cxref-function">Routino_Database* Routino_LoadDatabase</span>
864     <dd><span class="cxref-function-comment">Returns a pointer to the database.</span>
865     <dt><span class="cxref-function">const char* dirname</span>
866     <dd><span class="cxref-function-comment">The pathname of the directory containing the database files.</span>
867     <dt><span class="cxref-function">const char* prefix</span>
868     <dd><span class="cxref-function-comment">The prefix of the database files.</span>
869     </dl>
870    
871     <h4><a name="func-Routino_ParseXMLProfiles">Global Function Routino_ParseXMLProfiles()</a></h4>
872    
873     <p>
874     <span class="cxref-function-comment"> Parse a Routino XML file containing profiles, must be called before selecting a profile.</span>
875     <br>
876     <span class="cxref-function">int Routino_ParseXMLProfiles ( const char* filename )</span>
877     <br>
878     <dl>
879     <dt><span class="cxref-function">int Routino_ParseXMLProfiles</span>
880     <dd><span class="cxref-function-comment">Returns non-zero in case of an error or zero if there was no error.</span>
881     <dt><span class="cxref-function">const char* filename</span>
882     <dd><span class="cxref-function-comment">The full pathname of the file to read.</span>
883     </dl>
884    
885     <h4><a name="func-Routino_ParseXMLTranslations">Global Function Routino_ParseXMLTranslations()</a></h4>
886    
887     <p>
888     <span class="cxref-function-comment"> Parse a Routino XML file containing translations, must be called before selecting a translation.</span>
889     <br>
890     <span class="cxref-function">int Routino_ParseXMLTranslations ( const char* filename )</span>
891     <br>
892     <dl>
893     <dt><span class="cxref-function">int Routino_ParseXMLTranslations</span>
894     <dd><span class="cxref-function-comment">Returns non-zero in case of an error or zero if there was no error.</span>
895     <dt><span class="cxref-function">const char* filename</span>
896     <dd><span class="cxref-function-comment">The full pathname of the file to read.</span>
897     </dl>
898    
899     <h4><a name="func-Routino_UnloadDatabase">Global Function Routino_UnloadDatabase()</a></h4>
900    
901     <p>
902     <span class="cxref-function-comment"> Close the database files that were opened by a call to Routino_LoadDatabase().</span>
903     <br>
904     <span class="cxref-function">void Routino_UnloadDatabase ( Routino_Database* database )</span>
905     <br>
906     <dl>
907     <dt><span class="cxref-function">Routino_Database* database</span>
908     <dd><span class="cxref-function-comment">The database to close.</span>
909     </dl>
910    
911     <h4><a name="func-Routino_ValidateProfile">Global Function Routino_ValidateProfile()</a></h4>
912    
913     <p>
914     <span class="cxref-function-comment"> Validates that a selected routing profile is valid for use with the selected routing database.</span>
915     <br>
916     <span class="cxref-function">int Routino_ValidateProfile ( Routino_Database* database, Routino_Profile* profile )</span>
917     <br>
918     <dl>
919     <dt><span class="cxref-function">int Routino_ValidateProfile</span>
920     <dd><span class="cxref-function-comment">Returns zero if OK or something else in case of an error.</span>
921     <dt><span class="cxref-function">Routino_Database* database</span>
922     <dd><span class="cxref-function-comment">The Routino database to use.</span>
923     <dt><span class="cxref-function">Routino_Profile* profile</span>
924     <dd><span class="cxref-function-comment">The Routino profile to validate.</span>
925     </dl>
926    
927    
928     </div>
929    
930     <!-- Content End -->
931    
932     <!-- Footer Start -->
933    
934     <div class="footer">
935    
936     <address>
937     &copy; Andrew M. Bishop - <a href="http://www.routino.org/">http://www.routino.org/</a>
938     </address>
939    
940     </div>
941    
942     <!-- Footer End -->
943    
944     </body>
945    
946     </html>