Syntax
long PCMSCreateManagedRouteMsgBytes(Trip trip, char *pBuffer, long bufSize, const char *pLatLongs, long lOORCompliance, double dOORDist)
Parameters
Trip trip – Handle to a trip. This trip should already be filled out with all of the desired stops and trip options. It is recommended that you run the trip before calling this API to get the RouteSync message data.
char *pBuffer – An empty byte array that Connect will attempt to put the RouteSync message into.
long bufSize – The amount of memory allocated for pBuffer.
const char *pLatLongs – A delimited string of latitude/longitude values dictating the actual route to be traveled. Each pair of lat/long values should be kept in a format that is geocodable by any other PC*MILER API. Each pair of lat/longs should be separated by a “|” character. A sample input string:
“40.389408N,74.656269W|40.389116N,74.655889W|40.388820N,74.655497W”
long lOORCompliance – This value will dictate how the CoPilot client will handle re-routing. That is, how strictly CoPilot should try to return to the original (sent) route in the event that the driver is out-of-route. There are three possible values: 0 – Strict Compliance; 1 – Moderate Compliance; 2 – Minimal Compliance.
- Strict: CoPilot will try to navigate back to the original route at all costs, even if it means the driver needs to turn around and drive back to rejoin the prescribed route.
- Moderate: CoPilot will try to navigate back to the original route but will take into account the driver’s current position in relation to the destination; i.e. CoPilot will try to rejoin the prescribed route as it navigates towards the destination, but along a route that is more reasonable than what the Strict compliance level would follow.
- Minimal: At this level, the original prescribed route is not taken into consideration. The route taken may still rejoin the original route, but its first objective is to navigate to the destination from the driver’s current position.
double dOORDist – This value will determine how far away from the planned route the CoPilot-equipped vehicle must be to generate an out-of-route (OOR) alert. The default value is 0.2 miles.
Description
Creates a RouteSync message to send a route from PC*MILER Connect to a CoPilot client. (Licenses for RouteSync and the Streets add-on are required.)
The trip handle given by the user is only needed to retrieve the desired routing options that will be applied on the CoPilot side. The actual route generated by that trip, and the stop information it contains, is not put into the message. Instead, you must specify the actual route by providing a “bread crumb” trail of latitude/longitude values.
It is assumed that this trail of lat/longs will be a fully-run route that was created outside of PC*MILER and that you are providing it to be packaged up into a RouteSync message that CoPilot will be able to consume. It is also assumed that this trail of lat/longs has sufficient resolution to map a fully navigable route onto the Trimble MAPS road network with little to no additional routing calculations needed.
Return Values
Returns a long value indicating the length in bytes of the byte array stored in pBuffer. If pBuffer was allocated but did not contain enough space to hold the entire message, it will return -1.
Supported Since: PC*MILER Connect 25
Category: RouteSync