File: LIBRARY.txt

package info (click to toggle)
routino 3.2-5
  • links: PTS, VCS
  • area: main
  • in suites: buster
  • size: 8,376 kB
  • sloc: ansic: 22,337; xml: 5,520; perl: 2,485; makefile: 753; sh: 661
file content (695 lines) | stat: -rw-r--r-- 21,230 bytes parent folder | download | duplicates (5)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
                           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 8

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 points containing the HTML file information but
   as plain text.
   #define ROUTINO_ROUTE_LIST_HTML 128

   Output a linked list of points containing the HTML file information as
   plain text and with all points.
   #define ROUTINO_ROUTE_LIST_HTML_ALL 256

   Output a linked list of points containing the text file information.
   #define ROUTINO_ROUTE_LIST_TEXT 512

   Output a linked list of points containing the text all file
   information.
   #define ROUTINO_ROUTE_LIST_TEXT_ALL 1024

   Route between the points in a loop returning to the first point.
   #define ROUTINO_ROUTE_LOOP 2048

   Route between the points in reverse order.
   #define ROUTINO_ROUTE_REVERSE 4096

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 (kilometres) up to the
                     point.
         float time; The total journey time (seconds) up to the point.
         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
                   or ROUTINO_ROUTE_LIST_HTML_ALL 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
                     or ROUTINO_ROUTE_LIST_HTML_ALL 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 or
                      ROUTINO_ROUTE_LIST_HTML format).
         char* desc2; The second part of the description of the next
                      section of route (ROUTINO_ROUTE_LIST_HTML or
                      ROUTINO_ROUTE_LIST_HTML format).
         char* desc3; The third part of the description, the total
                      distance and time at the end of the next section of
                      route (ROUTINO_ROUTE_LIST_HTML or
                      ROUTINO_ROUTE_LIST_HTML 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.

   const int Routino_APIVersion

Global Variable Routino_Version

   Contains the Routino version number.

   const char* Routino_Version

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_GetTranslationLanguageFullNames()

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

   char** Routino_GetTranslationLanguageFullNames ( void )

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

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.