Syntax 

long PCMSGetManagedRouteMsgBytes(Trip trip, char *pBuffer, long bufSize, long lOORCompliance, double dOORDist, bool bIsFirstLegManaged)

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.

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.

bool bIsFirstLegManaged – Dictates whether or not the first leg of the given trip will be considered “managed”.  True = managed, false = unmanaged.

Description

Creates a RouteSync message to send a route from PC*MILER|Connect to a CoPilot client. (Licenses for PC*MILER|RouteSync and PC*MILER|Streets are required.)

The message is created internally and the byte array representing that message is copied into the buffer. It is recommended to call PCMSGetManagedRouteMsgBytes with a buffer size of 0, first, in order to get the size of the buffer necessary.

You are then responsible for transporting this byte array to a CoPilot client and injecting it via the CoPilot SDK. The byte array will contain a list of latitudes/longitudes that form the route and will also adhere to any avoid/favors created on the desktop (user interface) installation. 

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 negative one (-1). If street-level routing is not enabled, the function will return negative one (-1) and the error code from PCMSGetError will be 1600.

Sample Code

PCMServerID server = PCMSOpenServer(NULL, NULL);   
// NOTE: OpenServer and CloseServer should be executed sparingly due to excess overhead.
Trip trip = PCMSNewTrip(server);
PCMSSetRouteLevel(trip, TRUE);  // turn streets on    
PCMSAddStop(trip,"Philadelphia, PA");
PCMSAddStop(trip,"Hamilton, NJ");
PCMSAddStop(trip,"Manhattan,NY");
PCMSSetCalcType(trip, CALC_AVOIDTOLL);  
PCMSSetCalcType(trip, CALC_NATIONAL);
PCMSCalculate(trip);

long bufRetLength = 0; char * pBuffer = NULL;long OORCompliance = 0; double OORDist = .5; bool IsFirstLegManaged = true;

bufRetLength = PCMSGetManagedRouteMsgBytes(trip,NULL,0,OORCompliance,OORDist, IsFirstLegManaged);

pBuffer = new char[bufRetLength];
bufRetLength = PCMSGetManagedRouteMsgBytes(trip, pBuffer, bufRetLength,   OORCompliance, OORDist, IsFirstLegManaged);

// Send the pBuffer data blob via your communication method to the CoPilot device. 

Supported Since: PC*MILER|Connect 25

Category: RouteSync