third party rl6 time and distance calculation dll

Document : ThirdPartyRL6TimeAndDistanceCalculationDLL.doc Dated : 08/05/2017

Third Party RL6 Time and Distance

Calculation DLL

Design

Version 1.8


Contents Revision Control ............................................................................................................ 2

Personnel ........................................................................................................................ 4 DPS ............................................................................................................................ 4

Assumptions ................................................................................................................... 4 Project ............................................................................................................................ 5

Overview .................................................................................................................... 5

Flowchart ................................................................................................................... 6 Map Database Functions ............................................................................................ 7

Load Map Database List ........................................................................................ 7 Get Map Database .................................................................................................. 7

Free Map Database List ......................................................................................... 9 Set Map Database .................................................................................................. 9

Initialisation ............................................................................................................. 10

Add Ban ............................................................................................................... 10 Add Ban 2 ............................................................................................................ 10 Add Avoid ............................................................................................................ 11 Add Avoid 2 ......................................................................................................... 11

Set Boundary Rectangle ....................................................................................... 12 Set Boundary Rectangle 2 .................................................................................... 12

Vehicle Customisation ............................................................................................. 14 Add Vehicle Type ................................................................................................ 14 Number of Vehicles ............................................................................................. 15

Get Vehicle Details .............................................................................................. 16

Save Vehicle Type ............................................................................................... 18 Select Current Vehicle ......................................................................................... 20 Delete Vehicle ...................................................................................................... 21

Location Search ....................................................................................................... 23 Find Place............................................................................................................. 23 Get Search Result ................................................................................................. 23

Get Search Result 2 .............................................................................................. 24 Address Search......................................................................................................... 25

Search Address..................................................................................................... 25 Step-In to Search Address .................................................................................... 26 Get Address Search Result................................................................................... 27

Get Address Search Result 2................................................................................ 28 Clear Address Search Results .............................................................................. 29

Point Definition ........................................................................................................ 30 Set Base Node ...................................................................................................... 30

Set Base Node 2 ................................................................................................... 30 Add Calculation Node.......................................................................................... 31 Add Calculation Node 2....................................................................................... 31

Calculation Functions .............................................................................................. 33 Start Calculation................................................................................................... 33

Calculate Route .................................................................................................... 34 Calculate Route 2 ................................................................................................. 35

Route Results ........................................................................................................... 36


Retrieve Results ................................................................................................... 36 Detailed Route Calculation .................................................................................. 36 Detailed Route Calculation 2 ............................................................................... 38 Save Route Report (Itinerary) .............................................................................. 39 Route Itinerary Info.............................................................................................. 40

Route Itinerary Data ............................................................................................. 42 Route Itinerary Data 2 .......................................................................................... 43 Get Road Name .................................................................................................... 43 Get Postcode ........................................................................................................ 44 Get Country .......................................................................................................... 44

Other Future Gazetteer Functions ............................................................................ 45 Get Place Info ...................................................................................................... 45

Get Place Info 2 ................................................................................................... 46

Get Ref-Town Info ............................................................................................... 47 Get Ref-Town Info 2 ............................................................................................ 47 Get District ........................................................................................................... 48

Get Region ........................................................................................................... 49 Get Postcode Info ................................................................................................. 49 Get Postcode Info 2 .............................................................................................. 50

Clean Up Functions.................................................................................................. 51 Clear Nodes .......................................................................................................... 51 Free Resources ..................................................................................................... 51

Release ................................................................................................................. 52

Document : ThirdPartyRL6TimeAndDistanceCalculationDLL.doc Page 2 Dated : 08/05/2017

Revision Control Revision Date By Details

1.0 01/11/07 Nick Cobbett Initial version.

1.1 12/11/07 Nick Cobbett Parameter changes for weight, height then

width.

1.2 10/04/08 Nick Cobbett Added flowchart.

1.3 22/07/08 Nick Cobbett Addition of extra error codes to

start_calculation function.

1.4 05/05/09 Andrew Gibbons Updated documentation for add_vehicle

Addition of extra error codes to

set_base_node, add_calculation_node,

set_vehicle and start_calculation functions

Added release function.

1.5 08/02/10 Andrew Gibbons Development Version Only!

New RL6 COM Object required v1.9.x.x

Modified document to make it aimed for

general purpose third party application.

Added find_places function.

Added get_search_results function.

1.6 03/05/10 Andrew Gibbons Development Version Only!

Saved as Microsoft Word 2007 format (.docx)

Added route_itinerary_info function.

Added route_itinerary_data function.

Added get_road_name function.

Added get_postcode function.

Added get_country function.

1.7 06/03/12 Andrew Gibbons New Release Version!

New RL6 COM Object required v2.2.x.x

renamed to RL6_COM22.DLL.

Updated set_map_database return values.

Added load_map_database_list function.

Added get_map_database function.

Added free_map_database_list function.

Added add_ban2 function.

Added add_avoid2 function.

Added set_boundary2 function.

Added num_vehicles function.

Added get_vehicle function.

Added save_vehicle function.

Added delete_vehicle function.

Added get_search_result2 function.

Added search_address function.

Added sub_search_address function.

Added get_address_search_result function.

Added get_address_search_result2 function.


Added clear_address_search_results function.

Added set_base_node2 function.

Added add_calculation_node2 function.

Added calculate_route2 function.

Added detailed_route_data2 function.

Added save_route_itinerary function.

Added route_itinerary_data2 function.

Added get_place_info function.

Added get_place_info2 function.

Added get_ref_town_info function.

Added get_ref_town_info2 function.

Added get_district function.

Added get_region function.

Added get_postcode_info function.

Added get_postcode_info2 function.

Grouped all vehicle functions together.

1.8 30/10/12 Andrew Gibbons Changed C# declarations of

MarshalAs(UnmanagedType.U8) to

MarshalAs(UnmanagedType.I4) for all signed

integers.

Changed ‘string’ to ‘StringBuilder’ for all C#

function declarations with ‘Out’ strings.

Added ‘,CallingConvention =

CallingConvention.Cdecl’ to all C#

declarations.


Personnel

DPS

Person Role Telephone Mobile E-mail Paul Palmer CEO 0121 585 6633 [email protected]

Hamish Pearson Trainer 0121 585 6633 [email protected]

Support LogiX Support 0121 585 6633 [email protected]

Assumptions • Each transaction will be made up of a series of calls

• Create transaction

• Add delivery point

• Add collection point (a maximum number will need to be agreed)

• Process data

• Iterate through result set

• End transaction (clear data)

• Parameter passing conventions are C standard.

• Where a reference is made to an ‘int’, it refers to a 32-bit integer.

• All ‘out/ref’ strings should be fixed-length ANSI character strings. This

should be achieved in C#/VB/VB.NET using the System.Text.StringBuilder

class. An example can be found in get_map_database function definition.

The maximum string length returned is 255 characters plus the NULL

terminator.


Project This project was to provide a DLL that can be used within a third party and/or cross

platform application (e.g. .Net applications) to produce time and distance calculations.

There were two initial aims for this project:

1) to provide a simple two point time and distance calculation,

2) to build simple or complex single start/end destination time and distance

matrix.

Overview

Provide a set of DLL calls that can be embedded into a .Net framework to calculate

time and distance from set of calculation node points to a given base node point.

Three methods of calculating times and distances will be provided: -

• Bulk to

A many-to-one calculation. Calculate the time and distance from

many points of supply to a single point of demand (base node).

• Bulk from

A one-to-many calculation. Calculate the time and distance from a

single point of supply (base node) to a many points of demand.

• Detailed

A one-to-one calculation. Calculate the times and distances from one

point to another, returning the time and distances for each road

category.

The solution will be built using a series of calls, which can be split into 4 Phases.

• Initialisation

• Point definition

• Route Calculation

• Route Results


Flowchart

The following flowchart is intended as an example of one possible process flow:

Select Map

Set Base Node

Add Calc. Node

More Calculation

Nodes?

Clear Nodes

More Calculations Same

Map?

Y

Y

Y

Free DLL

set_map_database

Op

tio

na

l

Ban Roads

Set Avoid Areas

Set Boundary Rect

Select Vehicle

Create Vehicle

add_ban

add_avoid

set_boundary

add_vehicle

set_vehicle

set_base_node

add_calculation_node

Calculate Results start_calculation

Extract Results

More Results? Y

retrieve_node_data


Map Database Functions

Load Map Database List

Purpose This call is used to retrieve the list of available map databases. This function should

be combined with get_map_database() and free_map_database_list().

Call [DllImport(@"RL6X.dll",EntryPoint="_load_map_database_list",CallingConvention=CallingC

onvention.Cdecl)]

private static extern void load_map_database_list(

[MarshalAs(UnmanagedType.I4)] ref int rpnMapCount,

[MarshalAs(UnmanagedType.U1)] ref byte rpcResult);

Parameters

Type Name Usage

ref int rpnMapCount Returns the total number of map databases available.

ref

byte

rpcResult Always overwrites field:-

0 Unknown error

99 Success

Get Map Database

Purpose This call is used to retrieve the details about a map database. It can also be used to get

the current loaded map database.

Call [DllImport(@"RL6X.dll",EntryPoint="_get_map_database”,CallingConvention=CallingConvent

ion.Cdecl)]

private static extern void get_map_database(

int vnMapItem,

StringBuilder rpzMap,

StringBuilder rpzDescription,

[MarshalAs(UnmanagedType.U1)] ref byte rpcRegistered,


//Note: rpzMap should be a fixed-length string of at least 3 characters

//Note: rpzDescription should be a fixed-length string of at least 30 characters

//Example:

// int nItem = 0;

// StringBuilder sMap = new StringBuilder(3);

// StringBuilder sDesc = new StringBuilder(30);

// var cReg = new byte();

// var cResult = new byte();

// NativeMethods.get_map_database(nItem, sMap, sDesc, ref cReg, ref cResult);

Parameters

Type Name Usage

int vnMapItem Set to one of the following values to retrieve the map details. First

map is 0. Last vehicle is Map_Count-1. Set to -1 to get the current

map.

string rpzMap Map name. Null terminated string.

string rpzDescription Map description. Null terminated string.

ref

byte

rpcRegistered Returns ‘Y’ (89) if registered, ‘N’ (78) if not registered, or 0 if not

found.

ref

byte


0 Unknown error

1 Database not found


99 Success


Free Map Database List

Purpose This call is used to free allocated resources after finished using the map database list.

Call [DllImport(@"RL6X.dll",EntryPoint="_free_map_database_list”,CallingConvention=CallingC

onvention.Cdecl)]

private static extern void free_map_database_list(


Parameters

Type Name Usage

ref

byte


0 Unknown error

99 Success

Set Map Database

Purpose This call can be used to define the map database to be used.

Call [DllImport(@"RL6X.dll",EntryPoint="_set_map_database”,CallingConvention=CallingConvent

ion.Cdecl)]

private static extern void set_map_database(

[MarshalAs(UnmanagedType.LPStr)] string vszGeoPath,


Parameters

Type Name Usage

string vszGeoPath Null terminated string.

This can either be the code for the map database i.e. UKA, or the full

path the GEOY file (including the extension).

ref

byte


0 Unknown error

1 Map not found

2 Invalid map path

3 Error loading map

or no vehicles in map

99 Success


Initialisation

The following functions are to be used after loading the map database. They are used

for putting restriction on the road network to cover closed roads, height/weight/width

restrictions, preferred routes, and congested or banned areas.

Add Ban

Purpose When producing routes, it is possible to apply restrictions to a road section. These

bans can be of a height/weight/width type, or a % speed slow down (0% = a total

ban). The ban will apply to the nearest road section/link to the specified latitude and

longitude.

Call [DllImport(@"RL6X.dll",EntryPoint="_add_ban”,CallingConvention=CallingConvention.Cdecl

)]

private static extern void add_ban(

float vfLat,

float vfLong,

int vnWeight_kg,

int vnHeight_cm,

int vnWidth_cm,

byte vcPercentEfficiency,


Parameters

Type Name Usage

float vfLat Decimal latitude.

float vfLong Decimal longitude.

int vnWeight_kg Vehicle weight in kg. For unrestricted the value should be 0.

int vnHeight_cm Vehicle height in centimetres. For unrestricted the value

should be 0.

int vnWidth_cm Vehicle width in centimetres. For unrestricted the value

should be 0.

byte vcPercentEfficiency Percentage of normal speed. Zero is a complete ban.

ref

byte


0 Invalid data

99 Success

Add Ban 2

Purpose This function is the same as ‘Add Ban’, but uses micro-degrees (degrees x 106)

instead of decimal degrees.

Call [DllImport(@"RL6X.dll",EntryPoint="_add_ban2”,CallingConvention=CallingConvention.Cdec

l)]

private static extern void add_ban2(

int vnPosY,

int vnPosX,

int vnWeight_kg,

int vnHeight_cm,

int vnWidth_cm,




Parameters

Type Name Usage

int vnPosY Latitude in micro-degrees.

int vnPosX Longitude in micro-degrees.

int vnWeight_kg Vehicle weight in kg. For unrestricted the value should be 0.

int vnHeight_cm Vehicle height in centimetres. For unrestricted the value

should be 0.

int vnWidth_cm Vehicle width in centimetres. For unrestricted the value

should be 0.


ref

byte


0 Invalid data

99 Success

Add Avoid

Purpose When producing routes, it is possible to apply percentage speed restrictions to whole

areas.

Call [DllImport(@"RL6X.dll",EntryPoint="_add_avoid”,CallingConvention=CallingConvention.Cde

cl)]

private static extern void add_avoid(

float vfLat,

float vfLong,

int vnRadius,



Parameters

Type Name Usage



int vnRadius Area radius in metres.


ref

byte


0 Invalid data

99 Success

Add Avoid 2

Purpose This function is the same as ‘Add Avoid’, but uses micro-degrees (degrees x 106)


Call [DllImport(@"RL6X.dll",EntryPoint="_add_avoid2”,CallingConvention=CallingConvention.Cd

ecl)]

private static extern void add_avoid2(

int vnPosY,

int vnPosX,


int vnRadius,



Parameters

Type Name Usage



int vnRadius Area radius in metres.


ref

byte


0 Invalid data

99 Success

Set Boundary Rectangle

Purpose To protect the speed of calculation it is possible to define a rectangle, outside of

which points will not be considered for routing.

If left unset the whole map database will be available.

Call [DllImport(@"RL6X.dll",EntryPoint="_set_boundary”,CallingConvention=CallingConvention.

Cdecl)]

private static extern void set_boundary(

float vfLatN,

float vfLongE,

float vfLatS,

float vfLongW,


Parameters

Type Name Usage

float vfLatN Decimal latitude. Most northerly acceptable point.

float vfLongE Decimal longitude. Most easterly acceptable point.

float vfLatS Decimal latitude. Most southerly acceptable point.

float vfLongW Decimal longitude. Most westerly acceptable point.

ref

byte


0 Invalid rectangle

99 Success

Set Boundary Rectangle 2

Purpose This function is the same as ‘Set Boundary Rectangle’, but uses micro-degrees

(degrees x 106) instead of decimal degrees.

Call [DllImport(@"RL6X.dll",EntryPoint="_set_boundary2”,CallingConvention=CallingConvention

.Cdecl)]

private static extern void set_boundary2(

int vnPosN,

int vnPosE,

int vnPosS,

int vnPosW,



Parameters

Type Name Usage

int vnPosN Latitude in micro-degrees. Most northerly acceptable point.

int vnPosE Longitude in micro-degrees. Most easterly acceptable point.

int vnPosS Latitude in micro-degrees. Most southerly acceptable point.

int vnPosW Longitude in micro-degrees. Most westerly acceptable point.

ref

byte


0 Invalid rectangle

99 Success


Vehicle Customisation

The routing engine can work either with a pre-defined vehicle type or with a user

defined type. It is possible to add, edit or delete the vehicle types within memory for

the current instance of the routing engine.

Vehicle types control the speed of travel as well as restrictions such as weight limits

or road categories.

Add Vehicle Type

Purpose This call allows the creation of multiple vehicle types within memory.

Call [DllImport(@"RL6X.dll",EntryPoint="_add_vehicle”,CallingConvention=CallingConvention.C

decl)]

private static extern void add_vehicle(

[MarshalAs(UnmanagedType.LPStr)] string vszName,

int vnWeight_kg,

int vnHeight_cm,

int vnWidth_cm,

byte vcType,

int vnSpeedCity_metres_ph,

int vnSpeedOtherU_metres_ph,

int vnSpeedOtherR_metres_ph,

int vnSpeedPrimaryU_metres_ph,

int vnSpeedPrimaryR_metres_ph,

int vnSpeedDualCwayU_metres_ph,

int vnSpeedDualCwayR_metres_ph,

int vnSpeedMotorwayU_metres_ph,

int vnSpeedMotorwayR_metres_ph,



Parameters

Type Name Usage

string vszName Vehicle’s unique identity.

Null terminated string. Maximum 8 characters.

int vnWeight_kg Vehicle weight in kg. For unrestricted the value

should be 0.

int vnHeight_cm Vehicle height in centimetres. For unrestricted

the value should be 0.

int vnWidth_cm Vehicle width in centimetres. For unrestricted the

value should be 0.

byte vcType Vehicle type bitmap constructed from the

following list

Bit 0 – Car

Bit 1 – Bus

Bit 2 – HGV

Bit 3 – Carpool (High Occupancy Vehicle

(HOV))

Bit 4 – Pedestrian

Bit 5 – Truck

Bit 6 – Though traffic

Bit 7 – Delivery

E.g. Value of 211 = 20+21+24+26+27

int vnSpeedCity_metres_ph City speed in metres per hour

int vnSpeedOtherU_metres_ph Speed on urban unclassified roads in metres per

hour

int vnSpeedOtherR_metres_ph Speed on rural unclassified roads in metres per

hour

int vnSpeedPrimaryU_metres_ph Speed on urban primary roads in metres per hour

int vnSpeedPrimaryR_metres_ph Speed on rural unclassified roads in metres per

hour

int vnSpeedDualCwayU_metres_ph Speed on urban dual carriageways roads in metres

per hour

int vnSpeedDualCwayR_metres_ph Speed on rural dual carriageways roads in metres

per hour

int vnSpeedMotorwayU_metres_ph Speed on urban motorways roads in metres per

hour

int vnSpeedMotorwayR_metres_ph Speed on rural motorways roads in metres per

hour

ref

byte


0 Invalid data

99 Success

Number of Vehicles

Purpose This call returns the current number of vehicles available.


Call [DllImport(@"RL6X.dll",EntryPoint="_num_vehicles”,CallingConvention=CallingConvention.

Cdecl)]

private static extern void num_vehicles(

[MarshalAs(UnmanagedType.I4)] ref int rpnNumVehicles,


Parameters

Type Name Usage

ref int rpnNumVehicles Total number of vehicles available.

ref

byte


0 Invalid data

1 Main class object does not exist

2 Map database not loaded

3 COM object failed to initialise

99 Success

Get Vehicle Details

Purpose This call returns the details for one of the current vehicle types available.

Call [DllImport(@"RL6X.dll",EntryPoint="_get_vehicle”,CallingConvention=CallingConvention.C

decl)]

private static extern void get_vehicle(

[MarshalAs(UnmanagedType.I4)] ref int rpnItem, /* [in,out] */

StringBuilder rpzName,

StringBuilder rpzDescription,

[MarshalAs(UnmanagedType.I4)] ref int rpnWeight_kg,

[MarshalAs(UnmanagedType.I4)] ref int rpnHeight_cm,

[MarshalAs(UnmanagedType.I4)] ref int rpnWidth_cm,

[MarshalAs(UnmanagedType.U1)] ref byte rpcType,

[MarshalAs(UnmanagedType.I4)] ref int rpnSpeedCity_metres_ph,

[MarshalAs(UnmanagedType.I4)] ref int rpnSpeedOtherU_metres_ph,

[MarshalAs(UnmanagedType.I4)] ref int rpnSpeedOtherR_metres_ph,

[MarshalAs(UnmanagedType.I4)] ref int rpnSpeedPrimaryU_metres_ph,

[MarshalAs(UnmanagedType.I4)] ref int rpnSpeedPrimaryR_metres_ph,

[MarshalAs(UnmanagedType.I4)] ref int rpnSpeedDualCwayU_metres_ph,

[MarshalAs(UnmanagedType.I4)] ref int rpnSpeedDualCwayR_metres_ph,

[MarshalAs(UnmanagedType.I4)] ref int rpnSpeedMotorwayU_metres_ph,

[MarshalAs(UnmanagedType.I4)] ref int rpnSpeedMotorwayR_metres_ph,

[MarshalAs(UnmanagedType.R4)] ref float rpfCostPerM,

[MarshalAs(UnmanagedType.R4)] ref float rpfCostPerSec,

[MarshalAs(UnmanagedType.R4)] ref float rpfCostPerDay,

[MarshalAs(UnmanagedType.R4)] ref float rpfCostPerOffDuty,

[MarshalAs(UnmanagedType.I4)] ref int rpnBreakLen,

[MarshalAs(UnmanagedType.I4)] ref int rpnMaxCont,

[MarshalAs(UnmanagedType.I4)] ref int rpnOffLen,

[MarshalAs(UnmanagedType.I4)] ref int rpnDayLen,

[MarshalAs(UnmanagedType.I4)] ref int rpnOffTime,



Parameters

Type Name Usage

ref int rpnItem Set to one of the following values to retrieve the

vehicle details. First vehicle is 0. Last vehicle is

Num_Vehicles-1. Current vehicle is -1. If -1 is

passed in, then the actual current vehicle item

number is returned.

string rpzName Null terminated string.

string rpzDescription Null terminated string.

ref int rpnWeight_kg Returns vehicle weight in kg. For unrestricted the

value should be 0.

ref int rpnHeight_cm Returns vehicle height in centimetres. For

unrestricted the value should be 0.

ref int rpnWidth_cm Returns vehicle width in centimetres. For

unrestricted the value should be 0.

ref

byte

rpcType Returns vehicle type bitmap constructed from the

following list

Bit 0 – Car

Bit 1 – Bus

Bit 2 – HGV


(HOV))


Bit 5 – Truck


Bit 7 – Delivery

E.g. Value of 211 = 20+21+24+26+27


ref int rpnSpeedCity_metres_ph City speed in metres per hour

ref int rpnSpeedOtherU_metres_ph Speed on urban unclassified roads in metres per

hour

ref int rpnSpeedOtherR_metres_ph Speed on rural unclassified roads in metres per

hour

ref int rpnSpeedPrimaryU_metres_ph Speed on urban primary roads in metres per hour

ref int rpnSpeedPrimaryR_metres_ph Speed on rural unclassified roads in metres per

hour

ref int rpnSpeedDualCwayU_metres_ph Speed on urban dual carriageways roads in

metres per hour

ref int rpnSpeedDualCwayR_metres_ph Speed on rural dual carriageways roads in

metres per hour

ref int rpnSpeedMotorwayU_metres_ph Speed on urban motorways roads in metres per

hour

ref int rpnSpeedMotorwayR_metres_ph Speed on rural motorways roads in metres per

hour

ref

float

rpfCostPerM Returns vehicle cost per metre. The default will

be 0.0.

ref

float

rpfCostPerSec Returns vehicle cost per second. The default

will be 0.0.

ref

float

rpfCostPerDay Returns vehicle cost per day. The default will

be 0.0.

ref

float

rpfCostPerOffDuty Returns vehicle cost per off-duty period. The

default will be 0.0.

ref int rpnBreakLen Returns rest-break duration in minutes. The

default value is 0.

ref int rpnMaxCont Returns maximum continuous driving time in

minutes. The default value is 0.

ref int rpnOffLen Returns off-duty period length in minutes. The

default value is 0.

ref int rpnDayLen Returns maximum driving time before taking an

off duty period. The default value is 0.

ref int rpnOffTime Returns latest time for off-duty period to start in

minutes. The default value is 0 (00:00).

Maximum value is 1440 minutes = (24 hours).

ref

byte


0 Invalid data

99 Success

Save Vehicle Type

Purpose This call is used to save/update existing vehicles and also allows the creation of new

vehicles with additional settings than those using in add_vehicle().

Call [DllImport(@"RL6X.dll",EntryPoint="_save_vehicle”,CallingConvention=CallingConvention.

Cdecl)]


private static extern void save_vehicle(

int vnItem,


[MarshalAs(UnmanagedType.LPStr)] string vszDescription,

int vnWeight_kg,

int vnHeight_cm,

int vnWidth_cm,

byte vcType,

int vnSpeedCity_metres_ph,

int vnSpeedOtherU_metres_ph,

int vnSpeedOtherR_metres_ph,

int vnSpeedPrimaryU_metres_ph,

int vnSpeedPrimaryR_metres_ph,

int vnSpeedDualCwayU_metres_ph,

int vnSpeedDualCwayR_metres_ph,

int vnSpeedMotorwayU_metres_ph,

int vnSpeedMotorwayR_metres_ph,

float vfCostPerM,

float vfCostPerSec,

float vfCostPerDay,

float vfCostPerOffDuty,

int vnBreakLen,

int vnMaxCont,

int vnOffLen,

int vnDayLen,

int vnOffTime,


Parameters

Type Name Usage

int vnItem Set to one of the following values. First vehicle is

0. Last vehicle is Num_Vehicles-1. If -1 is

passed in, then a new vehicle is added/created.



string vszDescription Vehicle’s description.


int vnWeight_kg Vehicle weight in kg. For unrestricted the value

should be 0.

int vnHeight_cm Vehicle height in centimetres. For unrestricted

the value should be 0.

int vnWidth_cm Vehicle width in centimetres. For unrestricted the

value should be 0.

byte vcType Vehicle type bitmap constructed from the

following list

Bit 0 – Car

Bit 1 – Bus

Bit 2 – HGV


(HOV))


Bit 5 – Truck


Bit 7 – Delivery

E.g. Value of 211 = 20+21+24+26+27


int vnSpeedCity_metres_ph City speed in metres per hour

int vnSpeedOtherU_metres_ph Speed on urban unclassified roads in metres per

hour

int vnSpeedOtherR_metres_ph Speed on rural unclassified roads in metres per

hour

int vnSpeedPrimaryU_metres_ph Speed on urban primary roads in metres per hour

int vnSpeedPrimaryR_metres_ph Speed on rural unclassified roads in metres per

hour

int vnSpeedDualCwayU_metres_ph Speed on urban dual carriageways roads in metres

per hour

int vnSpeedDualCwayR_metres_ph Speed on rural dual carriageways roads in metres

per hour

int vnSpeedMotorwayU_metres_ph Speed on urban motorways roads in metres per

hour

int vnSpeedMotorwayR_metres_ph Speed on rural motorways roads in metres per

hour

float vfCostPerM Vehicle cost per metre. The default will be 0.0.

float vfCostPerSec Cost per second. The default will be 0.0.

float vfCostPerDay Cost per day. The default will be 0.0.

float vfCostPerOffDuty Cost per off-duty period. The default will be 0.0.

int vnBreakLen Rest-break duration in minutes. The default value

is 0.

int vnMaxCont Maximum continuous driving time in minutes.

The default value is 0.

int vnOffLen Off-duty period length in minutes. The default

value is 0.

int vnDayLen Maximum driving time before taking an off duty

period. The default value is 0.

int vnOffTime Latest time for off-duty period to start in minutes.

The default value is 0 (00:00). Maximum value is

1440 minutes = (24 hours).

ref

byte


0 Invalid data



3 Vehicle already exists

or error saving vehicle details


99 Success

Select Current Vehicle

Purpose This call allows the selection of a pre-defined vehicle type. The named vehicle

should either have been defined using the add_vehicle()/save_vehicle() function, or be

one of the installed vehicles for the chosen map.


Call [DllImport(@"RL6X.dll",EntryPoint="_set_vehicle”,CallingConvention=CallingConvention.C

decl)]

private static extern void set_vehicle(



Parameters

Type Name Usage



ref

byte


0 Invalid data



3 No vehicles found

4 Error selecting vehicle

5 Vehicle not found

99 Success

Delete Vehicle

Purpose This call is used to delete one of the existing vehicles.

Call [DllImport(@"RL6X.dll",EntryPoint="_delete_vehicle”,CallingConvention=CallingConventio

n.Cdecl)]

private static extern void delete_vehicle(

int vnItem,


Parameters

Type Name Usage

int vnItem Set to one of the following values. First vehicle is

0. Last vehicle is Num_Vehicles-1.

ref

byte


0 Invalid data




4 COM object unexpected error

5 Unknown error

6 Invalid index value

7 Vehicle database not open

8 Delete LOGIX vehicle failed

9 Cannot delete last vehicle

10 General failure (vehicle not found)

20 Other unknown failure

99 Success


Location Search

Find Place

Purpose To search for places stored in the map database and retrieve location.

This function precedes the function ‘get_search_result()’.

Call [DllImport(@"RL6X.dll",EntryPoint="_find_place”,CallingConvention=CallingConvention.Cd

ecl)]

private static extern void find_place(

[MarshalAs(UnmanagedType.LPStr)] string vszSearchString,

byte vcPlaces,

byte vcPostCodes,

byte vcUserData,

byte vcRoads,

[MarshalAs(UnmanagedType.I4)] ref int rpnNumPlacesFound,


Parameters

Type Name Usage

string vszSearchString Null terminated string. Lookup string.

byte vcPlaces Include places gazetteer in search. (‘Y’=true; ‘N’=false)

byte vcPostCodes Include post codes gazetteer in search. (‘Y’=true; ‘N’=false)

byte vcUserData Include user gazetteer in search. (‘Y’=true; ‘N’=false)

byte vcRoads Include road names in search. (‘Y’=true; ‘N’=false)

ref int rpnNumPlacesFound Total number of places found (0 = no results found).

ref

byte


0 Invalid data

1 Nothing found

99 Success

Get Search Result

Purpose Get the results from the previously called find_place() returning the latitude,

longitude, place found, postcode/sector and a location string describing the distance

from the nearest reference town.

This function should immediately follow the call to ‘find_place()’.

Call [DllImport(@"RL6X.dll",EntryPoint="_get_search_result”,CallingConvention=CallingConven

tion.Cdecl)]

private static extern void get_search_result(

int vnItemNo,

StringBuilder rpzPlace,

StringBuilder rpzPostcode,

StringBuilder rpzLocation,

[MarshalAs(UnmanagedType.R4)] ref float rpfLat,

[MarshalAs(UnmanagedType.R4)] ref float rpfLong,

[MarshalAs(UnmanagedType.I4)] ref int rpnConfidence,



Parameters

Type Name Usage

int vnItemNo Item number of the search results.

Zero is the first search item result.

ref string rpzPlace Place name found. (Should be no less than 80 bytes in size)

ref string rpzPostcode Postcode found. (Should be no less than 80 bytes in size)


ref float rpfLat Decimal latitude.

ref float rpfLong Decimal longitude.

ref int rpnConfidence DPS reference to place/location found.

ref byte rpcResult Always overwrites field:-

0 Unknown error

1 Nothing found

99 Success

Get Search Result 2

Purpose This function is the same as ‘Get Search Result’, but uses micro-degrees (degrees x

106) instead of decimal degrees.

Call [DllImport(@"RL6X.dll",EntryPoint="_get_search_result2”,CallingConvention=CallingConve

ntion.Cdecl)]

private static extern void get_search_result2(

int vnItemNo,

StringBuilder rpzPlace,


StringBuilder rpzLocation,

[MarshalAs(UnmanagedType.I4)] ref int rpnPosY,

[MarshalAs(UnmanagedType.I4)] ref int rpnPosX,



Parameters

Type Name Usage

int vnItemNo Item number of the search results.

Zero is the first search item result.


ref string rpzPostcode Postcode found. (Should be no less than 80 bytes in size)


ref int rpnPosY Latitude in micro-degrees.

ref int rpnPosX Longitude in micro-degrees.

ref int rpnConfidence DPS reference to place/location found.


0 Unknown error

1 Nothing found

99 Success


Address Search

Search Address

Purpose Search for an address string using one or multiple sources. This function offers more

search options and returns more detailed results than the ‘Locate Address’ and ‘Get

Search Result’ functions.

NOTE: Your system will require correct configuration to use Google or QAS search

functionality.

NOTE: SLL (Street Level Location) or Road Search are not currently supported.

Call [DllImport(@"RL6X.dll",EntryPoint="_search_address”,CallingConvention=CallingConventio

n.Cdecl)]

private static extern void search_address(

[MarshalAs(UnmanagedType.LPStr)] string vszSearchString,

byte vcSearchOptions,

[MarshalAs(UnmanagedType.I4)] ref int rpnGoogleResults,

[MarshalAs(UnmanagedType.I4)] ref int rpnQASResults,

[MarshalAs(UnmanagedType.I4)] ref int rpnSLLResults,

[MarshalAs(UnmanagedType.I4)] ref int rpnMapResults,

[MarshalAs(UnmanagedType.I4)] ref int rpnRoadResults,


Parameters

Type Name Usage

string vszSearchString Null terminated string. Lookup string.

byte vcSearchOptions Bit-field to set the type of search (e.g. Google, QAS, etc.):

Bit 0 - Google Search

Bit 1 - QAS Search

Bit 2 - SLL Search (Not currently operational)

Bit 3 - DPS Address Scan

Bit 4 - Road Search

Default is for DPS address scan only.

ref int rpnGoogleResults Returns number of Google search results, if requested.

ref int rpnQASResults Returns number of QAS search results, if requested.

ref int rpnSLLResults Returns number of SLL search results, if requested.

ref int rpnMapResults Returns number of DPS address search results, if requested.

ref int rpnRoadResults Returns number of Road Map search results, if requested.

ref

byte


0 Unknown error



98 Address not found

99 Successfully found at least one address


Step-In to Search Address

Purpose Search for an address string using just one source and perform a sequence of 'step-in'

actions. This call is used after a call to ‘Search Address’ where the number of results

is already known and at least one of the results has multiple possible results.

NOTE: This functionality is currently only available when using QAS search

functionality.

Call [DllImport(@"RL6X.dll",EntryPoint="_sub_search_address”,CallingConvention=CallingConve

ntion.Cdecl)]

private static extern void sub_search_address(

[MarshalAs(UnmanagedType.LPStr)] string vszOriginalSearchString,

byte vcOriginalSearchOptions,

[MarshalAs(UnmanagedType.U1)] ref byte rpcSearchType); [MarshalAs(UnmanagedType.I4)] ref int vpanItemSelectedArray,

int vnSizeOfArray,

[MarshalAs(UnmanagedType.I4)] ref int rpnNumResults,


Parameters

Type Name Usage

string vszOriginalSearc

hString

Original lookup string used in a call to search_address().

Null terminated string.

byte vcOriginalSearch

Options

Original lookup string used in a call to search_address().

Bit-field to set the type of search (e.g. Google, QAS, etc.):


Bit 1 - QAS Search



Bit 4 - Road Search

Default is for DPS address scan only.

ref

byte

rpcSearchType The selected search type that will be ‘stepped-in’ to. Where

1=Google, 2=QAS, 3=SLL, 4=Map, 5=Road and anything else

(e.g. 0, 6, etc.) is for the first ‘step-in’ to a search result when

multiple search options were used.

ref int vpanItemSelected

Array

A pointer to an array of int values. This is an array of item

numbers from the results

int vnSizeOfArray Total number of items in array.

ref int rpnNumResults Returns number of results found.

ref

byte


0 Unknown error



98 Address not found

99 Success, at least one address found


Get Address Search Result

Purpose Retrieve one result item from the last address search from a particular source.

If 'vcResultType' is 0, then all types will be grouped into one list, therefore

'vnResultItem' is from 0 to 'nGoogleResults + nQASResults + nSLLResults +

nMapResults + nRoadResults' from the search_address() function.

This function offers more search options and returns more detailed results than the

‘Locate Address’ and ‘Get Search Result’ functions.

NOTE: SLL (Street Level Location) or Road Search are not currently supported.

Call [DllImport(@"RL6X.dll",EntryPoint="_get_address_search_result”,CallingConvention=Calli

ngConvention.Cdecl)]

private static extern void get_address_search_result(

byte vcResultType,

int vnResultItem,

StringBuilder rpzAddressString,

int vnAddressStringSize,





Parameters

Type Name Usage

byte vcResultType Bit-field to set the type of search (e.g. Google, QAS, etc.):


Bit 1 - QAS Search



Bit 4 - Road Search

NOTE: At least one bit should be set.

int vnResultItem Item number of search result (starting from 0).

ref string rpzAddressString Full address found (truncated if longer than

vnAddressStringSize).

Each address string is separated by CR LF (‘\r\n’).

int vnAddressStringSize Size of rpzAddressString buffer to store the address found.



ref int rpnConfidence Level of confidence for search result. This varies

depending on result type. See Google API reference for

‘Accuracy’. See QAS match percentage. See DPS

Address Scan confidence.


0 Unknown error



3 Geocoding object does not exist

4 Error retrieving address result

98 Address found, but no co-ordinates returned

99 Success


Get Address Search Result 2

Purpose This function is the same as ‘Get Address Search Result’, but uses micro-degrees

(degrees x 106) instead of decimal degrees.

Call [DllImport(@"RL6X.dll",EntryPoint="_get_address_search_result2”,CallingConvention=Call

ingConvention.Cdecl)]

private static extern void get_address_search_result2(

byte vcResultType,

int vnResultItem,

StringBuilder rpzAddressString,

int vnAddressStringSize,





Parameters

Type Name Usage

byte vcResultType Bit-field to set the type of search (e.g. Google, QAS, etc.):


Bit 1 - QAS Search



Bit 4 - Road Search

NOTE: At least one bit should be set.

int vnResultItem Item number of search result (starting from 0).

ref

string

rpzAddressString Full address found (truncated if longer than

vnAddressStringSize).

Each address string is separated by CR LF (‘\r\n’).

int vnAddressString

Size

Size of rpzAddressString buffer to store the address found.



ref int rpnConfidence Level of confidence for search result. This varies depending on

result type. See Google API reference for ‘Accuracy’. See QAS

match percentage. See DPS Address Scan confidence.

ref

byte


0 Unknown error



3 Geocoding object does not exist

4 Error retrieving address result

98 Address found, but no latitude or longitude returned

99 Success


Clear Address Search Results

Purpose This call is used to free allocated resources after finished using the address search

results.

Call [DllImport(@"RL6X.dll",EntryPoint="_clear_address_search_results”,CallingConvention=Ca

llingConvention.Cdecl)]

private static extern void clear_address_search_results(


Parameters

Type Name Usage

ref

byte


0 Unknown error

99 Success


Point Definition

Set Base Node

Purpose The base node is the node from / to the distances should be calculated. All distances

will be calculated using the base node.

Call [DllImport(@"RL6X.dll",EntryPoint="_set_base_node”,CallingConvention=CallingConvention

.Cdecl)]

private static extern void set_base_node(

float vfLat,

float vfLong,


Parameters

Type Name Usage



ref

byte


0 Unknown error




4 Point not within boundary geo-rectangle

98 Point already existed and was reassigned as the base node

99 Point successfully added

Set Base Node 2

Purpose This function is the same as ‘Set Base Node’, but uses micro-degrees (degrees x 106)


Call [DllImport(@"RL6X.dll",EntryPoint="_set_base_node2”,CallingConvention=CallingConventio

n.Cdecl)]

private static extern void set_base_node2(

int vnPosY,

int vnPosX,


Parameters

Type Name Usage



ref

byte


0 Unknown error








Add Calculation Node

Purpose A calculation node is a node to be reached to/from the base node.

Call [DllImport(@"RL6X.dll",EntryPoint="_add_calculation_node”,CallingConvention=CallingCon

vention.Cdecl)]

private static extern void add_calculation_node(


float vfLat,

float vfLong,


Parameters

Type Name Usage

string vszName Null terminated string.

Nodes unique identifier.



ref

byte


0 Unknown error





97 Point already exists



Add Calculation Node 2

Purpose This function is the same as ‘Add Calculation Node’, but uses micro-degrees (degrees

x 106) instead of decimal degrees.

Call [DllImport(@"RL6X.dll",EntryPoint="_add_calculation_node2”,CallingConvention=CallingCo

nvention.Cdecl)]

private static extern void add_calculation_node2(


int vnPosY,

int vnPosX,


Parameters

Type Name Usage





ref

byte


0 Unknown error






97 Point already exists




Calculation Functions

Start Calculation

Purpose Starts the calculation process.

Call [DllImport(@"RL6X.dll",EntryPoint="_start_calculation”,CallingConvention=CallingConven

tion.Cdecl)]

private static extern void start_calculation(

byte vcDirection,

int vnMaxRunTime_s,


Parameters

Type Name Usage

byte vcDirection 0 From the base to the calculated nodes (Forwards)

1 To the base from the calculated nodes (Reverse)

int vnMaxRunTime_s Maximum run time in seconds. Zero is unlimited.

ref

byte


0 Unknown error


5 Invalid matrix specification

6 No vehicle selected

9 Error loading map

10 Not enough disk space

11 No nodes stored

12 Only one node stored

13 No vehicle/road speed set

14 Error building matrix

96 Completed with error

97 Timed out

98 Cancelled

99 Success

As all time and distance calculations are done in a single action, there are no errors

that can be reported against a node. The engine only knows if it has found or not

found access to a node. Nodes that cannot be accessed are reported as part of the

result data, where the distance is 12345678km or greater.


Calculate Route

Purpose Calculate a simple route from A to B returning the time, distance and the number of

itinerary records generated.

The number of itinerary instructions can be used to retrieve the step-by-step route

data.

Call [DllImport(@"RL6X.dll",EntryPoint="_calculate_route”,CallingConvention=CallingConventi

on.Cdecl)]

private static extern void calculation_route(

float vfStartLat,

float vfStartLong,

float vfEndLat,

float vfEndLong,

[MarshalAs(UnmanagedType.I4)] ref int rpnTotalTime_s,

[MarshalAs(UnmanagedType.I4)] ref int rpnTotalDist_m,

[MarshalAs(UnmanagedType.I4)] ref int rpnItinCount,


Parameters

Type Name Usage

float vfStartLat Starting latitude.

float vfStartLong Starting longitude.

float vfEndLat Finishing latitude.

float vfEndLong Finishing longitude.

ref int rpnTotalTime_s Total journey time in seconds.

ref int rpnTotalDist_m Total journey distance in metres.

ref int rpnItinCount Total number of itinerary instructions for this route.

ref

byte


0 Unknown error

99 Success


Calculate Route 2

Purpose This function is the same as ‘Calculate Route’, but uses micro-degrees (degrees x 106)


Call [DllImport(@"RL6X.dll",EntryPoint="_calculate_route2”,CallingConvention=CallingConvent

ion.Cdecl)]

private static extern void calculation_route2(

int vnStartPosY,

int vnStartPosX,

int vfEndPosY,

int vnEndPosX,



[MarshalAs(UnmanagedType.I4)] ref int rpnItinCount,


Parameters

Type Name Usage

int vnStartPosY Starting latitude in micro-degrees.

int vnStartPosX Starting longitude in micro-degrees.

int vnEndPosY Finishing latitude in micro-degrees.

int vnEndPosX Finishing longitude in micro-degrees.

ref int rpnTotalTime_s Total journey time in seconds.

ref int rpnTotalDist_m Total journey distance in metres.

ref int rpnItinCount Total number of itinerary instructions for this route.

ref

byte


0 Unknown error

99 Success


Route Results

Retrieve Results

Purpose Returns the time and distance calculated to/from the base node. This function can be

used after a call to ‘start_calculation()’ has completed.

Call [DllImport(@"RL6X.dll",EntryPoint="_retrieve_node_data”,CallingConvention=CallingConve

ntion.Cdecl)]

private static extern void retrieve_node_data(


[MarshalAs(UnmanagedType.I4)] ref int rpnTime_s,

[MarshalAs(UnmanagedType.I4)] ref int rpnDist_m,


Parameters

Type Name Usage



ref int rpnTime_s Return value for journey time in seconds.

ref int rpnDist_m Return value for journey distance in metres.

ref

byte


0 Unknown error



3 Point name not found

4 NULL time/distance cell

5 Error retrieving time/distance cell record

6 Unexpected error

98 Success - Point is at, or very close to, the base node (zero time)

99 Success

Nodes that cannot be accessed are reported as part of the result data, where the

distance is 12345678km or greater. The most common reason for nodes to be

inaccessible is that the nearest road is not accessible to the vehicle type, i.e. the node

is in the middle of a pedestrian area, and the vehicle type has not been set to allow

access. The other reason is that the nearest road is a Motorway etc. As the engine is

not allowed to access a motorway part way down a leg, it has to cross the motorway

or other boundary to access a suitable road.

Detailed Route Calculation

Purpose

This function returns a detailed time and distance breakdown of the route calculated

between two points.

Call [DllImport(@"RL6X.dll",EntryPoint="_detailed_route_data”,CallingConvention=CallingConv

ention.Cdecl)]

private static extern void detailed_route_data(

float vfStartLat,

float vfStartLong,

float vfEndLat,


float vfEndLong,

[MarshalAs(UnmanagedType.I4)] ref int rpnTime_Motorway_s,

[MarshalAs(UnmanagedType.I4)] ref int rpnDist_Motorway_m,

[MarshalAs(UnmanagedType.I4)] ref int rpnTime_Primary_s,

[MarshalAs(UnmanagedType.I4)] ref int rpnDist_Primary_m,

[MarshalAs(UnmanagedType.I4)] ref int rpnTime_Secondary_s,

[MarshalAs(UnmanagedType.I4)] ref int rpnDist_Secondary_m,

[MarshalAs(UnmanagedType.I4)] ref int rpnTime_Minor_s,

[MarshalAs(UnmanagedType.I4)] ref int rpnDist_Minor_m,

[MarshalAs(UnmanagedType.I4)] ref int rpnTime_Unclassified_s,

[MarshalAs(UnmanagedType.I4)] ref int rpnDist_Unclassified_m,

[MarshalAs(UnmanagedType.I4)] ref int rpnTime_IntFerry_s,

[MarshalAs(UnmanagedType.I4)] ref int rpnDist_IntFerry_m,

[MarshalAs(UnmanagedType.I4)] ref int rpnTime_DomFerry_s,

[MarshalAs(UnmanagedType.I4)] ref int rpnDist_DomFerry_m,

[MarshalAs(UnmanagedType.I4)] ref int rpnTime_Tunnel_s,

[MarshalAs(UnmanagedType.I4)] ref int rpnDist_Tunnel_m,

[MarshalAs(UnmanagedType.I4)] ref int rpnTime_TollRoads_s,

[MarshalAs(UnmanagedType.I4)] ref int rpnDist_TollRoads_m,




Parameters

Type Name Usage

float vfStartLat Starting latitude.

float vfStartLong Starting longitude.

float vfEndLat Finishing latitude.

float vfEndLong Finishing longitude.

ref int rpnTime_Motorway_s Journey time in seconds on motorways.

ref int rpnDist_Motorway_m Journey distance in metres on motorways.

ref int rpnTime_Primary_s Journey time in seconds on primary roads.

ref int rpnDist_Primary_m Journey distance in metres on primary roads.

ref int rpnTime_Secondary_s Journey time in seconds on secondary roads.

ref int rpnDist_Secondary_m Journey distance in metres on secondary roads.

ref int rpnTime_Mimor_s Journey time in seconds on minor roads.

ref int rpnDist_Minor_m Journey distance in metres on minor roads.

ref int rpnTime_Unclassified_s Journey time in seconds on unclassified roads.

ref int rpnDist_Unclassified_m Journey distance in metres on unclassified roads.

ref int rpnTime_IntFerry_s Journey time in seconds on international ferries roads.

ref int rpnDist_IntFerry_m Journey distance in metres on international ferries roads.

ref int rpnTime_DomFerry_s Journey time in seconds on domestic ferries roads.

ref int rpnDist_DomFerry_m Journey distance in metres on domestic ferries roads.

ref int rpnTime_Tunnel_s Journey time in seconds in tunnels roads.

ref int rpnDist_Tunnel_m Journey distance in metres in tunnels roads.

ref int rpnTime_TollRoads_s Journey time in seconds on toll roads.

ref int rpnDist_TollRoads_m Journey distance in metres on toll roads.

ref int rpnTotalTime_s Journey total time in seconds.

ref int rpnTotalDist_m Journey total distance in metres.

ref

byte


0 Unknown error

99 Success


Detailed Route Calculation 2

This function is the same as ‘Add Calculation Node’, but uses micro-degrees (degrees

x 106) instead of decimal degrees.

Call [DllImport(@"RL6X.dll",EntryPoint="_detailed_route_data2”,CallingConvention=CallingCon

vention.Cdecl)]

private static extern void detailed_route_data2(

int vnStartPosY,

int vnStartPosX,

int vfEndPosY,

int vnEndPosX,

[MarshalAs(UnmanagedType.I4)] ref int rpnTime_Motorway_s,

[MarshalAs(UnmanagedType.I4)] ref int rpnDist_Motorway_m,

[MarshalAs(UnmanagedType.I4)] ref int rpnTime_Primary_s,

[MarshalAs(UnmanagedType.I4)] ref int rpnDist_Primary_m,

[MarshalAs(UnmanagedType.I4)] ref int rpnTime_Secondary_s,

[MarshalAs(UnmanagedType.I4)] ref int rpnDist_Secondary_m,

[MarshalAs(UnmanagedType.I4)] ref int rpnTime_Minor_s,

[MarshalAs(UnmanagedType.I4)] ref int rpnDist_Minor_m,

[MarshalAs(UnmanagedType.I4)] ref int rpnTime_Unclassified_s,

[MarshalAs(UnmanagedType.I4)] ref int rpnDist_Unclassified_m,

[MarshalAs(UnmanagedType.I4)] ref int rpnTime_IntFerry_s,

[MarshalAs(UnmanagedType.I4)] ref int rpnDist_IntFerry_m,

[MarshalAs(UnmanagedType.I4)] ref int rpnTime_DomFerry_s,

[MarshalAs(UnmanagedType.I4)] ref int rpnDist_DomFerry_m,

[MarshalAs(UnmanagedType.I4)] ref int rpnTime_Tunnel_s,

[MarshalAs(UnmanagedType.I4)] ref int rpnDist_Tunnel_m,

[MarshalAs(UnmanagedType.I4)] ref int rpnTime_TollRoads_s,

[MarshalAs(UnmanagedType.I4)] ref int rpnDist_TollRoads_m,




Parameters

Type Name Usage

int vnStartPosY Starting latitude in micro-degrees.

int vnStartPosX Starting longitude in micro-degrees.

int vnEndPosY Finishing latitude in micro-degrees.

int vnEndPosX Finishing longitude in micro-degrees.

ref int rpnTime_Motorway_s Journey time in seconds on motorways.

ref int rpnDist_Motorway_m Journey distance in metres on motorways.

ref int rpnTime_Primary_s Journey time in seconds on primary roads.

ref int rpnDist_Primary_m Journey distance in metres on primary roads.

ref int rpnTime_Secondary_s Journey time in seconds on secondary roads.

ref int rpnDist_Secondary_m Journey distance in metres on secondary roads.

ref int rpnTime_Mimor_s Journey time in seconds on minor roads.

ref int rpnDist_Minor_m Journey distance in metres on minor roads.

ref int rpnTime_Unclassified_s Journey time in seconds on unclassified roads.

ref int rpnDist_Unclassified_m Journey distance in metres on unclassified roads.

ref int rpnTime_IntFerry_s Journey time in seconds on international ferries roads.

ref int rpnDist_IntFerry_m Journey distance in metres on international ferries roads.

ref int rpnTime_DomFerry_s Journey time in seconds on domestic ferries roads.

ref int rpnDist_DomFerry_m Journey distance in metres on domestic ferries roads.

ref int rpnTime_Tunnel_s Journey time in seconds in tunnels roads.

ref int rpnDist_Tunnel_m Journey distance in metres in tunnels roads.

ref int rpnTime_TollRoads_s Journey time in seconds on toll roads.


ref int rpnDist_TollRoads_m Journey distance in metres on toll roads.

ref int rpnTotalTime_s Journey total time in seconds.

ref int rpnTotalDist_m Journey total distance in metres.

ref

byte


0 Unknown error

99 Success

Save Route Report (Itinerary)

Purpose Creates a HTML route report and XML route itinerary for the calculated route

between two points using the calculate_route() function.

NOTE: Must have called 'calculate_route()' before calling this function.

Call [DllImport(@"RL6X.dll",EntryPoint="_route_itinerary_info”,CallingConvention=CallingCon

vention.Cdecl)]

private static extern void route_itinerary_info(

byte vcFlags,

int vnRadius1,

int vnRadius2,

int vnRadius3,

int vnWidth,

int vnHeight,

StringBuilder rpzURL,

int vnURLSize,


Parameters

Type Name Usage

byte vcFlags Bit-field to set the output options:

Bit 0 - Quickest route

Bit 1 - Shortest route

Bit 2 - Cheapest route

Bit 3 - Output NMEA file

Bit 4 - Include XML detailed itinerary

Bit 5 - Draw entire route map

Bit 6 - Draw sub maps

NOTE: Quickest route is the default.

int vnRadius1 Radius in km for the first sub map’s start and end locations.

This can be 0 to not draw this sub map.

int vnRadius2 Radius in km for the second sub map’s start and end locations.


int vnRadius3 Radius in km for the third sub map’s start and end locations.


int vnWidth Width in pixels of the sub maps.

int vnHeight Height in pixels of the sub maps.

ref string rpzURL Returns local URL path for the created HTML route report.

int vnURLSize Size of URL buffer.



0 Unknown error

1 Error creating route report

99 Success

Route Itinerary Info

Purpose Returns the road information for a given section of the route itinerary data for a route

calculated between two points using the calculate_route() function.

NOTE: Must have called 'calculate_route()' before calling this function.

Call [DllImport(@"RL6X.dll",EntryPoint="_route_itinerary_info”,CallingConvention=CallingCon

vention.Cdecl)]

private static extern void route_itinerary_info(

int vnItinNo,

[MarshalAs(UnmanagedType.I4)] ref int rpnNumPoints,

[MarshalAs(UnmanagedType.I4)] ref int rpnTime_s,


[MarshalAs(UnmanagedType.U1)] ref byte rpcLinkAccess,

[MarshalAs(UnmanagedType.U1)] ref byte rpcSectionType,

[MarshalAs(UnmanagedType.U1)] ref byte rpcRoadSurface,

[MarshalAs(UnmanagedType.U1)] ref byte rpcSpeedClass,

[MarshalAs(UnmanagedType.U1)] ref byte rpcRoadClass,

[MarshalAs(UnmanagedType.U1)] ref byte rpcInfo,

[MarshalAs(UnmanagedType.I4)] ref int rpnIdxLegalName,

[MarshalAs(UnmanagedType.I4)] ref int rpnIdxLocalName,

[MarshalAs(UnmanagedType.I4)] ref int rpnIdxLPostcode,

[MarshalAs(UnmanagedType.I4)] ref int rpnIdxRPostcode,

[MarshalAs(UnmanagedType.I4)] ref int rpnIdxCountry,


Parameters

Type Name Usage

int vnItinNo Itinerary number of the route results.

Zero is the first itinerary record. Must be positive, but

less than the total number of itinerary records returned by

‘rpnItinCount’ in ‘calculate_route()’.

ref int rpnNumPoints Number of points along road travelled (to be used with

calls to 'route_itinerary_data()')

ref int rpnTime_s Time in seconds of the road section.

ref int rpnDist_m Distance in metres of the road section.

ref byte rpcLinkAccess Byte value containing permitted access on road:

0x01 - Cars

0x02 - Bus

0x04 - HGV

0x08 - Carpools

0x10 - Pedestrians

0x20 - Trucks

0x40 - Through traffic

0x80 - Deliveries


ref byte rpcSectionType Byte value containing road type:

0x01 - Bridge

0x02 - Tunnel

0x04 - Ramp

0x08 - Tollway

0x10 - Roundabout

0x20 - Intersection Internal (segment is an internal

part of a junction)

0x40 - Indescribable (part of complicated junction)

0x80 - Manoeuvre (link is part of a manoeuvre from

one road to another, typically a slip way)

ref byte rpcRoadSurface Byte value containing addition road type information:

0x01 - Paved

0x02 - Private

0x04 - Divider (central divider down road)

0x08 - Exit/Junction (local road name marked as

exit/junction name)

0x30 - LaneCat (‘bit mask’ for number of lanes:

1 = single lane

2 = 2 or 3 lanes

3 = 4 or more

ref byte rpcSpeedClass Road Speed Classification:

1 - City Centre

2 - Minor Urban

3 - Minor Rural

4 - Primary Urban

5 - Primary Rural

6 - Dual-Carriageway Urban

7 - Dual-Carriageway Rural

8 - Motorway Urban

9 - Motorway Rural

ref byte rpcRoadClass Road Classification (1 – 8):

1 - Freeway/Motorway

2 - Primary/Trunk road

3 - Secondary road

4 - Minor road

5 - Unclassified

6 - International Ferry

7 - Domestic Ferry

8 - Tunnel

ref byte rpcInfo Byte value containing route calculation information for

this road section:

0x01 - if start is call point

0x02 - if end is at call point

0x10 - if link crosses another link

0x20 - if link is inaccessible

0x80 - if this is the last itinerary record

ref int rpnIdxLegalName Item number for legal road name (e.g. M6, E27).


Use ‘get_road_name()’ to retrieve text.

ref int rpnIdxLocalName Local road name (e.g. High Street, Main Road).

Use ‘get_road_name()’ to retrieve text.

ref int rpnIdxLPostcode Postal code on left side of road.

Use ‘get_postcode()’ to retrieve text.

ref int rpnIdxRPostcode Postal code on right side of road.

Use ‘get_postcode()’ to retrieve text.

ref int rpnIdxCountry Country that this road is located in.

Use ‘get_country()’ to retrieve text.


0 Unknown error

98 Success - Last itinerary record (STOP)

99 Success

Route Itinerary Data

Purpose Returns the road shape data for a given point in a given section of the route itinerary

data for a route calculated between two points using the calculate_route() and

route_itinerary_info() functions.

NOTE: Must have called 'calculate_route()' followed by 'route_itinerary_info()'

before calling this function.

Call [DllImport(@"RL6X.dll",EntryPoint="_route_itinerary_data”,CallingConvention=CallingCon

vention.Cdecl)]

private static extern void route_itinerary_data(

int vnItinNo,

int vnPointNo,




Parameters

Type Name Usage


Zero is the first itinerary record. Must be positive, but less than the

total number of itinerary records returned by ‘rpnItinCount’ in

‘calculate_route()’.

int vnPointNo Shaping point number of the itinerary instruction record.

Zero is the first shaping point for an itinerary record. Must be

positive, but less than the total number of shaping points returned by

‘rpnNumPoints’ in ‘route_itinerary_info()’.




0 Unknown error

99 Success


Route Itinerary Data 2

Purpose This function is the same as ‘Route Itinerary Data’, but uses micro-degrees (degrees x


Call [DllImport(@"RL6X.dll",EntryPoint="_route_itinerary_data2”,CallingConvention=CallingCo

nvention.Cdecl)]

private static extern void route_itinerary_data2(

int vnItinNo,

int vnPointNo,




Parameters

Type Name Usage


Zero is the first itinerary record. Must be positive, but less than the

total number of itinerary records returned by ‘rpnItinCount’ in

‘calculate_route()’.

int vnPointNo Shaping point number of the itinerary instruction record.

Zero is the first shaping point for an itinerary record. Must be

positive, but less than the total number of shaping points returned by

‘rpnNumPoints’ in ‘route_itinerary_info()’.




0 Unknown error

99 Success

Get Road Name

Purpose Returns the road name for an item number returned by a call to route_itinerary_info().

Call [DllImport(@"RL6X.dll",EntryPoint="_get_road_name”,CallingConvention=CallingConvention

.Cdecl)]

private static extern void get_road_name(

int vnIdxRoadName,

StringBuilder rpzRoadName,

int vnRoadNameSize,


Parameters

Type Name Usage

int vnIdxRoadName Item number for a road name returned by either

‘rpnIdxLegalName’ or ‘rpnIdxLocalName’ in

‘route_itinerary_info()’.

ref string rszRoadName Return string for the road name text (may return blank string).

int vnRoadNameSize Input size in bytes of the string variable ‘rszRoadName’.


0 Unknown error

99 Success


Get Postcode

Purpose Returns the postal code for an item number returned by a call to

route_itinerary_info().

Call [DllImport(@"RL6X.dll",EntryPoint="_get_postcode”,CallingConvention=CallingConvention.

Cdecl)]

private static extern void get_postcode(

int vnIdxPostcode,


int vnPostcodeSize,


Parameters

Type Name Usage

int vnIdxPostcode Item number for a road name returned by either

‘rpnIdxLPostcode’ or ‘rpnIdxRPostcode’ in


ref string rszPostcode Return string for the postcode text (may return blank string).

int vnPostcodeSize Input size in bytes of the string variable ‘rszPostcode’.


0 Unknown error

99 Success

Get Country

Purpose Returns the country for an item number returned by a call to route_itinerary_info().

Call [DllImport(@"RL6X.dll",EntryPoint="_get_country”,CallingConvention=CallingConvention.C

decl)]

private static extern void get_country(

int vnIdxCountry,

StringBuilder rpzCountry,

int vnCountrySize,


Parameters

Type Name Usage

int vnIdxCountry Item number for a country returned by ‘rpnIdxCountry’ in


ref string rszCountry Return string for the road name text.

int vnCountrySize Input size in bytes of the string variable ‘rszCountry’.


0 Unknown error

99 Success


Other Future Gazetteer Functions

Get Place Info

Purpose This call returns the place name, location, plus the district, region, country and nearest

ref-town item numbers for a given place name item number.

Call [DllImport(@"RL6X.dll",EntryPoint="_get_place_info”,CallingConvention=CallingConventio

n.Cdecl)]

private static extern void get_place_info(

int vnIdxPlaceName,

StringBuilder rpzPlaceName,

int vnPlaceNameSize,




[MarshalAs(UnmanagedType.U1)] ref byte rpcDirection,

[MarshalAs(UnmanagedType.I4)] ref int rpnIdxRefTown,

[MarshalAs(UnmanagedType.I4)] ref int rpnIdxDistrict,

[MarshalAs(UnmanagedType.I4)] ref int rpnIdxRegion,



Parameters

Type Name Usage

int vnIdxPlaceName Item number for a place name in the map database.

ref string rszPlaceName Return string for the place name text.

int vnPlaceNameSize Input size in bytes of the string variable ‘rszPlaceName’.

ref float rpfLat Returns decimal latitude.

ref float rpfLong Returns decimal longitude.

ref int rpnDist_m Returns distance in metres to the nearest reference town that

this place is located close to.

ref byte rpcDirection Returns direction to the nearest reference town that this place

is located close to.

ref int rpnIdxRefTown Nearest reference town that this place is located close to.

Use ‘get_ref_town_info()’ to retrieve text.

ref int rpnIdxDistrict District that this place is located in.

Use ‘get_district()’ to retrieve text.

ref int rpnIdxRegion Region that this place is located in.

Use ‘get_region()’ to retrieve text.

ref int rpnIdxCountry Country that this place is located in.



0 Unknown error

99 Success


Get Place Info 2

Purpose This function is the same as ‘Get Place Info’, but uses micro-degrees (degrees x 106)


Call [DllImport(@"RL6X.dll",EntryPoint="_get_place_info2”,CallingConvention=CallingConventi

on.Cdecl)]

private static extern void get_place_info2(

int vnIdxPlaceName,

StringBuilder rpzPlaceName,

int vnPlaceNameSize,




[MarshalAs(UnmanagedType.U1)] ref byte rpcDirection,

[MarshalAs(UnmanagedType.I4)] ref int rpnIdxRefTown,

[MarshalAs(UnmanagedType.I4)] ref int rpnIdxDistrict,




Parameters

Type Name Usage

int vnIdxPlaceName Item number for a place name in the map database.

ref string rszPlaceName Return string for the place name text.

int vnPlaceNameSize Input size in bytes of the string variable ‘rszPlaceName’.

ref int rpnPosY Returns latitude in micro-degrees.

ref int rpnPosX Returns longitude in micro-degrees.

ref int rpnDist_m Returns distance in metres to the nearest reference town that

this place is located close to.

ref byte rpcDirection Returns direction to the nearest reference town that this place

is located close to.

ref int rpnIdxRefTown Nearest reference town that this place is located close to.

Use ‘get_ref_town_info()’ to retrieve text.

ref int rpnIdxDistrict District that this place is located in.

Use ‘get_district()’ to retrieve text.

ref int rpnIdxRegion Region that this place is located in.


ref int rpnIdxCountry Country that this place is located in.



0 Unknown error

99 Success


Get Ref-Town Info

Purpose This call returns the reference town name, location, and radius, plus the country item

number for a given reference town item number.

Call [DllImport(@"RL6X.dll",EntryPoint="_get_ref_town_info2”,CallingConvention=CallingConve

ntion.Cdecl)]

private static extern void get_ref_town_info2(

int vnIdxRefTown,

StringBuilder rpzRefTown,

int vnRefTownSize,



[MarshalAs(UnmanagedType.I4)] ref int rpnRadius_m,



Parameters

Type Name Usage

int vnIdxRefTown Item number for a ref-town in the map database.

ref string rszRefTown Return string for the ref-town name text.

int vnRefTownSize Input size in bytes of the string variable ‘rszRefTown’.



ref int rpnRadius_m Returns estimated radius in metres of the reference town.

ref int rpnIdxCountry Country that this ref-town is located in.



0 Unknown error

99 Success

Get Ref-Town Info 2

Purpose This function is the same as ‘Get Ref-Town Info’, but uses micro-degrees (degrees x


Call [DllImport(@"RL6X.dll",EntryPoint="_get_ref_town_info2”,CallingConvention=CallingConve

ntion.Cdecl)]

private static extern void get_ref_town_info2(

int vnIdxRefTown,

StringBuilder rpzRefTown,

int vnRefTownSize,



[MarshalAs(UnmanagedType.I4)] ref int rpnRadius_m,




Parameters

Type Name Usage

int vnIdxRefTown Item number for a ref-town in the map database.

ref string rszRefTown Return string for the ref-town name text.

int vnRefTownSize Input size in bytes of the string variable ‘rszRefTown’.



ref int rpnRadius_m Returns estimated radius in metres of the reference town.

ref int rpnIdxCountry Country that this ref-town is located in.



0 Unknown error

99 Success

Get District

Purpose This call returns the district name and region item number for a given item number

returned by get_place_info().

Call [DllImport(@"RL6X.dll",EntryPoint="_get_district”,CallingConvention=CallingConvention.

Cdecl)]

private static extern void get_district(

int vnIdxDistrict,

StringBuilder rpzDistrictName,

int vnDistrictNameSize,



Parameters

Type Name Usage

int vnIdxDistrict Item number for a district returned by ‘rpnIdxDistrict’ in

‘get_place_info()’.

ref string rszDistrictName Return string for the district name text.

int vnDistrictNameSize Input size in bytes of the string variable ‘rszDistrictName’.

ref int rpnIdxRegion Region that this district is located in.



0 Unknown error

99 Success


Get Region

Purpose This call returns the region name and country item number for a given item number

returned by get_district() or get_place_info().

Call [DllImport(@"RL6X.dll",EntryPoint="_get_region”,CallingConvention=CallingConvention.Cd

ecl)]

private static extern void get_region(

int vnIdxRegion,

StringBuilder rpzRegionName,

int vnRegionNameSize,



Parameters

Type Name Usage

int vnIdxRegion Item number for a country returned by ‘rpnIdxRegion’ in

‘get_district()’.

ref string rszRegionName Return string for the region name text.

int vnRegionNameSize Input size in bytes of the string variable ‘rszRegionName’.

ref int rpnIdxCountry Country that this region is located in.



0 Unknown error

99 Success

Get Postcode Info

Purpose This call returns the postcode, location and country item number for a given postcode

item number.

Call [DllImport(@"RL6X.dll",EntryPoint="_get_postcode_info”,CallingConvention=CallingConven

tion.Cdecl)]

private static extern void get_postcode_info(

int vnIdxPostcode,


int vnPostcodeSize,





Parameters

Type Name Usage

int vnIdxPostcode Item number for a postcode in the map database.





ref int rpnIdxCountry Country that this postcode is located in.




0 Unknown error

99 Success

Get Postcode Info 2

Purpose This function is the same as ‘Get Postcode Info’, but uses micro-degrees (degrees x


Call [DllImport(@"RL6X.dll",EntryPoint="_get_postcode_info2”,CallingConvention=CallingConve

ntion.Cdecl)]

private static extern void get_postcode_info2(

int vnIdxPostcode,


int vnPostcodeSize,





Parameters

Type Name Usage

int vnIdxPostcode Item number for a postcode in the map database.





ref int rpnIdxCountry Country that this postcode is located in.



0 Unknown error

99 Success


Clean Up Functions

Clear Nodes

Purpose Clears all nodes data calculation nodes, base nodes and results.

Call [DllImport(@"RL6X.dll",EntryPoint="_clear_nodes”,CallingConvention=CallingConvention.C

decl)]

private static extern void clear_nodes(


Parameters

Type Name Usage

ref

byte


0 Unknown error

99 Success

Free Resources

Purpose A tidy-up function to safely release all non-essential allocated resources prior to

starting a new iteration of route calculation.

Call [DllImport(@"RL6X.dll",EntryPoint="_free_all”,CallingConvention=CallingConvention.Cdec

l)]

private static extern void free_all(


Parameters

Type Name Usage

ref

byte


0 Unknown error

99 Success


Release

Purpose A tidy-up function to safely release all allocated resources within the DLL and

associated resources prior to unloading the DLL.

NOTE: Must be called ONCE only and as the very last call to the DLL prior

to closing the application.

Call [DllImport(@"RL6X.dll",EntryPoint="_release”,CallingConvention=CallingConvention.Cdecl

)]

private static extern void release(


Parameters

Type Name Usage

ref

byte


0 Unknown error

99 Success

third party rl6 time and distance calculation dll

Documents