Third Party RL6 Time and Distance Calculation DLL · Document :...
Transcript of Third Party RL6 Time and Distance Calculation DLL · Document :...
Document : ThirdPartyRL6TimeAndDistanceCalculationDLL.doc Dated : 08/05/2017
Third Party RL6 Time and Distance
Calculation DLL
Design
Version 1.8
Document : ThirdPartyRL6TimeAndDistanceCalculationDLL.doc Dated : 08/05/2017
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
Document : ThirdPartyRL6TimeAndDistanceCalculationDLL.doc Dated : 08/05/2017
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.
Document : ThirdPartyRL6TimeAndDistanceCalculationDLL.doc Page 3 Dated : 08/05/2017
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.
Document : ThirdPartyRL6TimeAndDistanceCalculationDLL.doc Page 4 Dated : 08/05/2017
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.
Document : ThirdPartyRL6TimeAndDistanceCalculationDLL.doc Page 5 Dated : 08/05/2017
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
Document : ThirdPartyRL6TimeAndDistanceCalculationDLL.doc Page 6 Dated : 08/05/2017
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
Document : ThirdPartyRL6TimeAndDistanceCalculationDLL.doc Page 7 Dated : 08/05/2017
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,
[MarshalAs(UnmanagedType.U1)] ref byte rpcResult);
//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
rpcResult Always overwrites field:-
0 Unknown error
1 Database not found
Document : ThirdPartyRL6TimeAndDistanceCalculationDLL.doc Page 9 Dated : 08/05/2017
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(
[MarshalAs(UnmanagedType.U1)] ref byte rpcResult);
Parameters
Type Name Usage
ref
byte
rpcResult Always overwrites field:-
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,
[MarshalAs(UnmanagedType.U1)] ref byte rpcResult);
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
rpcResult Always overwrites field:-
0 Unknown error
1 Map not found
2 Invalid map path
3 Error loading map
or no vehicles in map
99 Success
Document : ThirdPartyRL6TimeAndDistanceCalculationDLL.doc Page 10 Dated : 08/05/2017
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,
[MarshalAs(UnmanagedType.U1)] ref byte rpcResult);
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
rpcResult Always overwrites field:-
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,
Document : ThirdPartyRL6TimeAndDistanceCalculationDLL.doc Page 11 Dated : 08/05/2017
byte vcPercentEfficiency,
[MarshalAs(UnmanagedType.U1)] ref byte rpcResult);
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.
byte vcPercentEfficiency Percentage of normal speed. Zero is a complete ban.
ref
byte
rpcResult Always overwrites field:-
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,
byte vcPercentEfficiency,
[MarshalAs(UnmanagedType.U1)] ref byte rpcResult);
Parameters
Type Name Usage
float vfLat Decimal latitude.
float vfLong Decimal longitude.
int vnRadius Area radius in metres.
byte vcPercentEfficiency Percentage of normal speed. Zero is a complete ban.
ref
byte
rpcResult Always overwrites field:-
0 Invalid data
99 Success
Add Avoid 2
Purpose This function is the same as ‘Add Avoid’, but uses micro-degrees (degrees x 106)
instead of decimal degrees.
Call [DllImport(@"RL6X.dll",EntryPoint="_add_avoid2”,CallingConvention=CallingConvention.Cd
ecl)]
private static extern void add_avoid2(
int vnPosY,
int vnPosX,
Document : ThirdPartyRL6TimeAndDistanceCalculationDLL.doc Page 12 Dated : 08/05/2017
int vnRadius,
byte vcPercentEfficiency,
[MarshalAs(UnmanagedType.U1)] ref byte rpcResult);
Parameters
Type Name Usage
int vnPosY Latitude in micro-degrees.
int vnPosX Longitude in micro-degrees.
int vnRadius Area radius in metres.
byte vcPercentEfficiency Percentage of normal speed. Zero is a complete ban.
ref
byte
rpcResult Always overwrites field:-
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,
[MarshalAs(UnmanagedType.U1)] ref byte rpcResult);
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
rpcResult Always overwrites field:-
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,
[MarshalAs(UnmanagedType.U1)] ref byte rpcResult);
Document : ThirdPartyRL6TimeAndDistanceCalculationDLL.doc Page 13 Dated : 08/05/2017
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
rpcResult Always overwrites field:-
0 Invalid rectangle
99 Success
Document : ThirdPartyRL6TimeAndDistanceCalculationDLL.doc Page 14 Dated : 08/05/2017
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,
[MarshalAs(UnmanagedType.U1)] ref byte rpcResult);
Document : ThirdPartyRL6TimeAndDistanceCalculationDLL.doc Page 15 Dated : 08/05/2017
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
rpcResult Always overwrites field:-
0 Invalid data
99 Success
Number of Vehicles
Purpose This call returns the current number of vehicles available.
Document : ThirdPartyRL6TimeAndDistanceCalculationDLL.doc Page 16 Dated : 08/05/2017
Call [DllImport(@"RL6X.dll",EntryPoint="_num_vehicles”,CallingConvention=CallingConvention.
Cdecl)]
private static extern void num_vehicles(
[MarshalAs(UnmanagedType.I4)] ref int rpnNumVehicles,
[MarshalAs(UnmanagedType.U1)] ref byte rpcResult);
Parameters
Type Name Usage
ref int rpnNumVehicles Total number of vehicles available.
ref
byte
rpcResult Always overwrites field:-
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,
[MarshalAs(UnmanagedType.U1)] ref byte rpcResult);
Document : ThirdPartyRL6TimeAndDistanceCalculationDLL.doc Page 17 Dated : 08/05/2017
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
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
Document : ThirdPartyRL6TimeAndDistanceCalculationDLL.doc Page 18 Dated : 08/05/2017
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
rpcResult Always overwrites field:-
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)]
Document : ThirdPartyRL6TimeAndDistanceCalculationDLL.doc Page 19 Dated : 08/05/2017
private static extern void save_vehicle(
int vnItem,
[MarshalAs(UnmanagedType.LPStr)] string vszName,
[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,
[MarshalAs(UnmanagedType.U1)] ref byte rpcResult);
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 vszName Vehicle’s unique identity.
Null terminated string. Maximum 8 characters.
string vszDescription Vehicle’s description.
Null terminated string. Maximum 64 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
Document : ThirdPartyRL6TimeAndDistanceCalculationDLL.doc Page 20 Dated : 08/05/2017
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
rpcResult Always overwrites field:-
0 Invalid data
1 Main class object does not exist
2 Map database not loaded
3 Vehicle already exists
or error saving vehicle details
4 COM object failed to initialise
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.
Document : ThirdPartyRL6TimeAndDistanceCalculationDLL.doc Page 21 Dated : 08/05/2017
Call [DllImport(@"RL6X.dll",EntryPoint="_set_vehicle”,CallingConvention=CallingConvention.C
decl)]
private static extern void set_vehicle(
[MarshalAs(UnmanagedType.LPStr)] string vszName,
[MarshalAs(UnmanagedType.U1)] ref byte rpcResult);
Parameters
Type Name Usage
string vszName Vehicle’s unique identity.
Null terminated string. Maximum 8 characters.
ref
byte
rpcResult Always overwrites field:-
0 Invalid data
1 Main class object does not exist
2 Map database not loaded
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,
[MarshalAs(UnmanagedType.U1)] ref byte rpcResult);
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
rpcResult Always overwrites field:-
0 Invalid data
1 Main class object does not exist
2 Map database not loaded
3 COM object failed to initialise
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
Document : ThirdPartyRL6TimeAndDistanceCalculationDLL.doc Page 23 Dated : 08/05/2017
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,
[MarshalAs(UnmanagedType.U1)] ref byte rpcResult);
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
rpcResult Always overwrites field:-
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,
[MarshalAs(UnmanagedType.U1)] ref byte rpcResult);
Document : ThirdPartyRL6TimeAndDistanceCalculationDLL.doc Page 24 Dated : 08/05/2017
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 string rpzPlace Place name 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 rpzPostcode,
StringBuilder rpzLocation,
[MarshalAs(UnmanagedType.I4)] ref int rpnPosY,
[MarshalAs(UnmanagedType.I4)] ref int rpnPosX,
[MarshalAs(UnmanagedType.I4)] ref int rpnConfidence,
[MarshalAs(UnmanagedType.U1)] ref byte rpcResult);
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 string rpzPlace Place name 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.
ref byte rpcResult Always overwrites field:-
0 Unknown error
1 Nothing found
99 Success
Document : ThirdPartyRL6TimeAndDistanceCalculationDLL.doc Page 25 Dated : 08/05/2017
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,
[MarshalAs(UnmanagedType.U1)] ref byte rpcResult);
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
rpcResult Always overwrites field:-
0 Unknown error
1 Main class object does not exist
2 Map database not loaded
98 Address not found
99 Successfully found at least one address
Document : ThirdPartyRL6TimeAndDistanceCalculationDLL.doc Page 26 Dated : 08/05/2017
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,
[MarshalAs(UnmanagedType.U1)] ref byte rpcResult);
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 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
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
rpcResult Always overwrites field:-
0 Unknown error
1 Main class object does not exist
2 Map database not loaded
98 Address not found
99 Success, at least one address found
Document : ThirdPartyRL6TimeAndDistanceCalculationDLL.doc Page 27 Dated : 08/05/2017
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,
[MarshalAs(UnmanagedType.R4)] ref float rpfLat,
[MarshalAs(UnmanagedType.R4)] ref float rpfLong,
[MarshalAs(UnmanagedType.I4)] ref int rpnConfidence,
[MarshalAs(UnmanagedType.U1)] ref byte rpcResult);
Parameters
Type Name Usage
byte vcResultType 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
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 float rpfLat Decimal latitude.
ref float rpfLong Decimal longitude.
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 rpcResult Always overwrites field:-
0 Unknown error
1 Main class object does not exist
2 Map database not loaded
3 Geocoding object does not exist
4 Error retrieving address result
98 Address found, but no co-ordinates returned
99 Success
Document : ThirdPartyRL6TimeAndDistanceCalculationDLL.doc Page 28 Dated : 08/05/2017
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,
[MarshalAs(UnmanagedType.I4)] ref int rpnPosY,
[MarshalAs(UnmanagedType.I4)] ref int rpnPosX,
[MarshalAs(UnmanagedType.I4)] ref int rpnConfidence,
[MarshalAs(UnmanagedType.U1)] ref byte rpcResult);
Parameters
Type Name Usage
byte vcResultType 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
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 rpnPosY Latitude in micro-degrees.
ref int rpnPosX Longitude in micro-degrees.
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
rpcResult Always overwrites field:-
0 Unknown error
1 Main class object does not exist
2 Map database not loaded
3 Geocoding object does not exist
4 Error retrieving address result
98 Address found, but no latitude or longitude returned
99 Success
Document : ThirdPartyRL6TimeAndDistanceCalculationDLL.doc Page 29 Dated : 08/05/2017
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(
[MarshalAs(UnmanagedType.U1)] ref byte rpcResult);
Parameters
Type Name Usage
ref
byte
rpcResult Always overwrites field:-
0 Unknown error
99 Success
Document : ThirdPartyRL6TimeAndDistanceCalculationDLL.doc Page 30 Dated : 08/05/2017
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,
[MarshalAs(UnmanagedType.U1)] ref byte rpcResult);
Parameters
Type Name Usage
float vfLat Decimal latitude.
float vfLong Decimal longitude.
ref
byte
rpcResult Always overwrites field:-
0 Unknown error
1 Main class object does not exist
2 Map database not loaded
3 COM object failed to initialise
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)
instead of decimal degrees.
Call [DllImport(@"RL6X.dll",EntryPoint="_set_base_node2”,CallingConvention=CallingConventio
n.Cdecl)]
private static extern void set_base_node2(
int vnPosY,
int vnPosX,
[MarshalAs(UnmanagedType.U1)] ref byte rpcResult);
Parameters
Type Name Usage
int vnPosY Latitude in micro-degrees.
int vnPosX Longitude in micro-degrees.
ref
byte
rpcResult Always overwrites field:-
0 Unknown error
1 Main class object does not exist
2 Map database not loaded
3 COM object failed to initialise
4 Point not within boundary geo-rectangle
98 Point already existed and was reassigned as the base node
99 Point successfully added
Document : ThirdPartyRL6TimeAndDistanceCalculationDLL.doc Page 31 Dated : 08/05/2017
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(
[MarshalAs(UnmanagedType.LPStr)] string vszName,
float vfLat,
float vfLong,
[MarshalAs(UnmanagedType.U1)] ref byte rpcResult);
Parameters
Type Name Usage
string vszName Null terminated string.
Nodes unique identifier.
float vfLat Decimal latitude.
float vfLong Decimal longitude.
ref
byte
rpcResult Always overwrites field:-
0 Unknown error
1 Main class object does not exist
2 Map database not loaded
3 COM object failed to initialise
4 Point not within boundary geo-rectangle
97 Point already exists
98 Point already existed and was reassigned as the base node
99 Point successfully added
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(
[MarshalAs(UnmanagedType.LPStr)] string vszName,
int vnPosY,
int vnPosX,
[MarshalAs(UnmanagedType.U1)] ref byte rpcResult);
Parameters
Type Name Usage
string vszName Null terminated string.
Nodes unique identifier.
int vnPosY Latitude in micro-degrees.
int vnPosX Longitude in micro-degrees.
ref
byte
rpcResult Always overwrites field:-
0 Unknown error
1 Main class object does not exist
2 Map database not loaded
Document : ThirdPartyRL6TimeAndDistanceCalculationDLL.doc Page 32 Dated : 08/05/2017
3 COM object failed to initialise
4 Point not within boundary geo-rectangle
97 Point already exists
98 Point already existed and was reassigned as the base node
99 Point successfully added
Document : ThirdPartyRL6TimeAndDistanceCalculationDLL.doc Page 33 Dated : 08/05/2017
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,
[MarshalAs(UnmanagedType.U1)] ref byte rpcResult);
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
rpcResult Always overwrites field:-
0 Unknown error
3 Map database not loaded
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.
Document : ThirdPartyRL6TimeAndDistanceCalculationDLL.doc Page 34 Dated : 08/05/2017
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,
[MarshalAs(UnmanagedType.U1)] ref byte rpcResult);
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
rpcResult Always overwrites field:-
0 Unknown error
99 Success
Document : ThirdPartyRL6TimeAndDistanceCalculationDLL.doc Page 35 Dated : 08/05/2017
Calculate Route 2
Purpose This function is the same as ‘Calculate Route’, but uses micro-degrees (degrees x 106)
instead of decimal degrees.
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 rpnTotalTime_s,
[MarshalAs(UnmanagedType.I4)] ref int rpnTotalDist_m,
[MarshalAs(UnmanagedType.I4)] ref int rpnItinCount,
[MarshalAs(UnmanagedType.U1)] ref byte rpcResult);
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
rpcResult Always overwrites field:-
0 Unknown error
99 Success
Document : ThirdPartyRL6TimeAndDistanceCalculationDLL.doc Page 36 Dated : 08/05/2017
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.LPStr)] string vszName,
[MarshalAs(UnmanagedType.I4)] ref int rpnTime_s,
[MarshalAs(UnmanagedType.I4)] ref int rpnDist_m,
[MarshalAs(UnmanagedType.U1)] ref byte rpcResult);
Parameters
Type Name Usage
string vszName Null terminated string.
Nodes unique identifier.
ref int rpnTime_s Return value for journey time in seconds.
ref int rpnDist_m Return value for journey distance in metres.
ref
byte
rpcResult Always overwrites field:-
0 Unknown error
1 Main class object does not exist
2 Map database not loaded
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,
Document : ThirdPartyRL6TimeAndDistanceCalculationDLL.doc Page 37 Dated : 08/05/2017
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,
[MarshalAs(UnmanagedType.I4)] ref int rpnTotalTime_s,
[MarshalAs(UnmanagedType.I4)] ref int rpnTotalDist_m,
[MarshalAs(UnmanagedType.U1)] ref byte rpcResult);
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
rpcResult Always overwrites field:-
0 Unknown error
99 Success
Document : ThirdPartyRL6TimeAndDistanceCalculationDLL.doc Page 38 Dated : 08/05/2017
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,
[MarshalAs(UnmanagedType.I4)] ref int rpnTotalTime_s,
[MarshalAs(UnmanagedType.I4)] ref int rpnTotalDist_m,
[MarshalAs(UnmanagedType.U1)] ref byte rpcResult);
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.
Document : ThirdPartyRL6TimeAndDistanceCalculationDLL.doc Page 39 Dated : 08/05/2017
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
rpcResult Always overwrites field:-
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,
[MarshalAs(UnmanagedType.U1)] ref byte rpcResult);
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.
This can be 0 to not draw this sub map.
int vnRadius3 Radius in km for the third sub map’s start and end locations.
This can be 0 to not draw this sub map.
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.
Document : ThirdPartyRL6TimeAndDistanceCalculationDLL.doc Page 40 Dated : 08/05/2017
ref byte rpcResult Always overwrites field:-
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.I4)] ref int rpnDist_m,
[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,
[MarshalAs(UnmanagedType.U1)] ref byte rpcResult);
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
Document : ThirdPartyRL6TimeAndDistanceCalculationDLL.doc Page 41 Dated : 08/05/2017
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).
Document : ThirdPartyRL6TimeAndDistanceCalculationDLL.doc Page 42 Dated : 08/05/2017
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.
ref byte rpcResult Always overwrites field:-
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,
[MarshalAs(UnmanagedType.R4)] ref float rpfLat,
[MarshalAs(UnmanagedType.R4)] ref float rpfLong,
[MarshalAs(UnmanagedType.U1)] ref byte rpcResult);
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()’.
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()’.
ref float rpfLat Decimal latitude.
ref float rpfLong Decimal longitude.
ref byte rpcResult Always overwrites field:-
0 Unknown error
99 Success
Document : ThirdPartyRL6TimeAndDistanceCalculationDLL.doc Page 43 Dated : 08/05/2017
Route Itinerary Data 2
Purpose This function is the same as ‘Route Itinerary Data’, but uses micro-degrees (degrees x
106) instead of decimal degrees.
Call [DllImport(@"RL6X.dll",EntryPoint="_route_itinerary_data2”,CallingConvention=CallingCo
nvention.Cdecl)]
private static extern void route_itinerary_data2(
int vnItinNo,
int vnPointNo,
[MarshalAs(UnmanagedType.I4)] ref int rpnPosY,
[MarshalAs(UnmanagedType.I4)] ref int rpnPosX,
[MarshalAs(UnmanagedType.U1)] ref byte rpcResult);
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()’.
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()’.
ref int rpnPosY Latitude in micro-degrees.
ref int rpnPosX Longitude in micro-degrees.
ref byte rpcResult Always overwrites field:-
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,
[MarshalAs(UnmanagedType.U1)] ref byte rpcResult);
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’.
ref byte rpcResult Always overwrites field:-
0 Unknown error
99 Success
Document : ThirdPartyRL6TimeAndDistanceCalculationDLL.doc Page 44 Dated : 08/05/2017
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,
StringBuilder rpzPostcode,
int vnPostcodeSize,
[MarshalAs(UnmanagedType.U1)] ref byte rpcResult);
Parameters
Type Name Usage
int vnIdxPostcode Item number for a road name returned by either
‘rpnIdxLPostcode’ or ‘rpnIdxRPostcode’ in
‘route_itinerary_info()’.
ref string rszPostcode Return string for the postcode text (may return blank string).
int vnPostcodeSize Input size in bytes of the string variable ‘rszPostcode’.
ref byte rpcResult Always overwrites field:-
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,
[MarshalAs(UnmanagedType.U1)] ref byte rpcResult);
Parameters
Type Name Usage
int vnIdxCountry Item number for a country returned by ‘rpnIdxCountry’ in
‘route_itinerary_info()’.
ref string rszCountry Return string for the road name text.
int vnCountrySize Input size in bytes of the string variable ‘rszCountry’.
ref byte rpcResult Always overwrites field:-
0 Unknown error
99 Success
Document : ThirdPartyRL6TimeAndDistanceCalculationDLL.doc Page 45 Dated : 08/05/2017
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.R4)] ref float rpfLat,
[MarshalAs(UnmanagedType.R4)] ref float rpfLong,
[MarshalAs(UnmanagedType.I4)] ref int rpnDist_m,
[MarshalAs(UnmanagedType.U1)] ref byte rpcDirection,
[MarshalAs(UnmanagedType.I4)] ref int rpnIdxRefTown,
[MarshalAs(UnmanagedType.I4)] ref int rpnIdxDistrict,
[MarshalAs(UnmanagedType.I4)] ref int rpnIdxRegion,
[MarshalAs(UnmanagedType.I4)] ref int rpnIdxCountry,
[MarshalAs(UnmanagedType.U1)] ref byte rpcResult);
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.
Use ‘get_country()’ to retrieve text.
ref byte rpcResult Always overwrites field:-
0 Unknown error
99 Success
Document : ThirdPartyRL6TimeAndDistanceCalculationDLL.doc Page 46 Dated : 08/05/2017
Get Place Info 2
Purpose This function is the same as ‘Get Place Info’, but uses micro-degrees (degrees x 106)
instead of decimal degrees.
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.I4)] ref int rpnPosY,
[MarshalAs(UnmanagedType.I4)] ref int rpnPosX,
[MarshalAs(UnmanagedType.I4)] ref int rpnDist_m,
[MarshalAs(UnmanagedType.U1)] ref byte rpcDirection,
[MarshalAs(UnmanagedType.I4)] ref int rpnIdxRefTown,
[MarshalAs(UnmanagedType.I4)] ref int rpnIdxDistrict,
[MarshalAs(UnmanagedType.I4)] ref int rpnIdxRegion,
[MarshalAs(UnmanagedType.I4)] ref int rpnIdxCountry,
[MarshalAs(UnmanagedType.U1)] ref byte rpcResult);
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.
Use ‘get_region()’ to retrieve text.
ref int rpnIdxCountry Country that this place is located in.
Use ‘get_country()’ to retrieve text.
ref byte rpcResult Always overwrites field:-
0 Unknown error
99 Success
Document : ThirdPartyRL6TimeAndDistanceCalculationDLL.doc Page 47 Dated : 08/05/2017
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.R4)] ref float rpfLat,
[MarshalAs(UnmanagedType.R4)] ref float rpfLong,
[MarshalAs(UnmanagedType.I4)] ref int rpnRadius_m,
[MarshalAs(UnmanagedType.I4)] ref int rpnIdxCountry,
[MarshalAs(UnmanagedType.U1)] ref byte rpcResult);
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 float rpfLat Returns decimal latitude.
ref float rpfLong Returns decimal longitude.
ref int rpnRadius_m Returns estimated radius in metres of the reference town.
ref int rpnIdxCountry Country that this ref-town is located in.
Use ‘get_country()’ to retrieve text.
ref byte rpcResult Always overwrites field:-
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
106) instead of decimal degrees.
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 rpnPosY,
[MarshalAs(UnmanagedType.I4)] ref int rpnPosX,
[MarshalAs(UnmanagedType.I4)] ref int rpnRadius_m,
[MarshalAs(UnmanagedType.I4)] ref int rpnIdxCountry,
[MarshalAs(UnmanagedType.U1)] ref byte rpcResult);
Document : ThirdPartyRL6TimeAndDistanceCalculationDLL.doc Page 48 Dated : 08/05/2017
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 rpnPosY Returns latitude in micro-degrees.
ref int rpnPosX Returns longitude in micro-degrees.
ref int rpnRadius_m Returns estimated radius in metres of the reference town.
ref int rpnIdxCountry Country that this ref-town is located in.
Use ‘get_country()’ to retrieve text.
ref byte rpcResult Always overwrites field:-
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,
[MarshalAs(UnmanagedType.I4)] ref int rpnIdxRegion,
[MarshalAs(UnmanagedType.U1)] ref byte rpcResult);
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.
Use ‘get_region()’ to retrieve text.
ref byte rpcResult Always overwrites field:-
0 Unknown error
99 Success
Document : ThirdPartyRL6TimeAndDistanceCalculationDLL.doc Page 49 Dated : 08/05/2017
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,
[MarshalAs(UnmanagedType.I4)] ref int rpnIdxCountry,
[MarshalAs(UnmanagedType.U1)] ref byte rpcResult);
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.
Use ‘get_country()’ to retrieve text.
ref byte rpcResult Always overwrites field:-
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,
StringBuilder rpzPostcode,
int vnPostcodeSize,
[MarshalAs(UnmanagedType.R4)] ref float rpfLat,
[MarshalAs(UnmanagedType.R4)] ref float rpfLong,
[MarshalAs(UnmanagedType.I4)] ref int rpnIdxCountry,
[MarshalAs(UnmanagedType.U1)] ref byte rpcResult);
Parameters
Type Name Usage
int vnIdxPostcode Item number for a postcode in the map database.
ref string rszPostcode Return string for the postcode text (may return blank string).
int vnPostcodeSize Input size in bytes of the string variable ‘rszPostcode’.
ref float rpfLat Returns decimal latitude.
ref float rpfLong Returns decimal longitude.
ref int rpnIdxCountry Country that this postcode is located in.
Use ‘get_country()’ to retrieve text.
Document : ThirdPartyRL6TimeAndDistanceCalculationDLL.doc Page 50 Dated : 08/05/2017
ref byte rpcResult Always overwrites field:-
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
106) instead of decimal degrees.
Call [DllImport(@"RL6X.dll",EntryPoint="_get_postcode_info2”,CallingConvention=CallingConve
ntion.Cdecl)]
private static extern void get_postcode_info2(
int vnIdxPostcode,
StringBuilder rpzPostcode,
int vnPostcodeSize,
[MarshalAs(UnmanagedType.I4)] ref int rpnPosY,
[MarshalAs(UnmanagedType.I4)] ref int rpnPosX,
[MarshalAs(UnmanagedType.I4)] ref int rpnIdxCountry,
[MarshalAs(UnmanagedType.U1)] ref byte rpcResult);
Parameters
Type Name Usage
int vnIdxPostcode Item number for a postcode in the map database.
ref string rszPostcode Return string for the postcode text (may return blank string).
int vnPostcodeSize Input size in bytes of the string variable ‘rszPostcode’.
ref int rpnPosY Returns latitude in micro-degrees.
ref int rpnPosX Returns longitude in micro-degrees.
ref int rpnIdxCountry Country that this postcode is located in.
Use ‘get_country()’ to retrieve text.
ref byte rpcResult Always overwrites field:-
0 Unknown error
99 Success
Document : ThirdPartyRL6TimeAndDistanceCalculationDLL.doc Page 51 Dated : 08/05/2017
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(
[MarshalAs(UnmanagedType.U1)] ref byte rpcResult);
Parameters
Type Name Usage
ref
byte
rpcResult Always overwrites field:-
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(
[MarshalAs(UnmanagedType.U1)] ref byte rpcResult);
Parameters
Type Name Usage
ref
byte
rpcResult Always overwrites field:-
0 Unknown error
99 Success
Document : ThirdPartyRL6TimeAndDistanceCalculationDLL.doc Page 52 Dated : 08/05/2017
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(
[MarshalAs(UnmanagedType.U1)] ref byte rpcResult);
Parameters
Type Name Usage
ref
byte
rpcResult Always overwrites field:-
0 Unknown error
99 Success