Syntax
long PCMSGetRouteSyncMsg (Trip trip, void **pBuffer, long lOORCompliance, double dOORDist, const char* externalRouteID, long startingIndex)
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.
void **pBuffer – A pointer to a pointer that Connect will attempt to put the RouteSync message into. The client program that makes the function call will be responsible for freeing the memory allocated into 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.
const char* externalRouteID – This value will sets a route identifier that will be passed along to CoPilot and eventually to FleetPortal. It only has an effect when JSON format is selected, the default value is NULL.
long startingIndex – This value sets the index of the first stop CoPilot will navigate to in a trip. All stops before that index will be skipped. The typical use case for this is a re-dispatch where the driver was navigating from A à B à C à D, had already passed stop B, and dispatch wants to send a modified route from A à B à Q à C à D. If the starting index is set to 2, the driver will be immediately routed to stop Q, then C à D, completing the route. This parameter only has effect when JSON format is selected, the default value is 0.
Description
Creates a data packet (blob) used to send a route from PC*MILER|Connect to a CoPilot client. If the Connect log is enabled, the created blob will be written to the log file directory with the name "rs_blob_PCMSGetRouteSyncMsg.dat". (Licenses for PC*MILER|RouteSync and PC*MILER|Streets are required.)
Return Values
Returns a long value indicating the length in bytes of the byte array pointed by pBuffer.
Sample Code
NewSection("TestRouteSyncJSON()");
Log_Pcmstest("Generating RouteSync data packet JSON...");
// 0 = strict, 1 = moderate, 2 = none
long lCompliance = 0;
// distance allowed off route before an OOR event is generated (measured in miles)
double fOORdist = 0.2;
// controls whether the first leg is managed or not
bool bManagedFirstLeg = true;
long lRet = 0;
void *pBuffer = new char[1];
const char externalRouteID[] = {"ALK Route 1"};
long startingIndex = 0;
lRet = PCMSGetRouteSyncMsg (trip, &pBuffer, lCompliance, fOORdist, externalRouteID, startingIndex );
//deallocate the memory
if(lRet)
delete [] pBuffer;
Log_Pcmstest("Returned JSON Message size: %d ", lRet);Supported Since: PC*MILER|Connect 25
Category: RouteSync
