RouteSync

RouteSync is a feature which aids route compliance and improves in-vehicle consistency from the back office to the mobile workforce devices. Routes can be planned on back office systems and by passing location information via API to CoPilot this route will be sent to CoPilot.

Msg_SendFlex

This API is used to send flex message (flex object) to CoPilot. Currently only used for sending RouteSync Flex object to CoPilot (received from PC*Miler). This API should be used to handle, parse, and call appropriate callbacks under this framework which will be done by CoPilot and alksdk.dll

The messaging framework will provide the message updates by calling Notification Status Callback. (E.g Received@CoPilot, Received@Client, Accepted@CoPilot etc)

Syntax (Prototyped in alkmsg.h)

long Msg_SendFlex (const char *pdata,
   unsigned long lByteCount,
   NotifStatusCB fnNotifStatusCB);

Parameters

Callback Function Description (fnNotifStatusCB)

typedef long (*NotifStatusCB) (const char* pToken,
   unsigned long ulTokenBytes,
   long srcID,
   long destID,
   const char* pState);

Return Value

• -1 - (Signifies that there was an error).
• 0 - or any positive value (Signifies that value is set successfully).

Msg_SetFlexCallback

This API is used to register for callback for specific type “flex message type”. Once registered for specific flex message (defined using the pID), flex messaging framework will call registered callback once it receives the particular type of flex message from CoPilot.

Notes: In order to get more details about implementation as well RouteSyncEvent, please refer to the SDK Sample Application. Implementation of .NET can be found in C# sample application. Implementation of Java can be found in SDK Application in Android.

Syntax (Prototyped in alkmsg.h)

long Msg_SetFlexCallback (const char *pID,
   NotifSDKDeliverCB
   fnNotifSDKDeliverCB);

Parameters

Callback Function Description (fnNotifSDKDeliverCB)

typedef long (*NotifStatusCB) (const char* bytes,
   unsigned long numbytes);

Return Value

• -1 - (Signifies that there was an error).
• 0 - or any positive value (Signifies that value is set successfully).

Msg_SendManagedRouteJSON

This API is used to send a RouteSync message in JSON format from the client application to CoPilot.

Syntax (Prototyped in alkmsg.h)

long Msg_SendManagedRouteJSON(const char* pJson);

Parameter

pJson: Complete contents of a JSON message describing a CoPilot managed route. See Note 1 for details on this format.

Return Value

-1 = Error parsing JSON Greater than zero = Successful in sending the request to CoPilot.

Related APIs

• Msg_ManagedRouteCallback - Used to set the callback and receive notification about successful processing of the message by CoPilot.
• Msg_SetFlexCallback
• MsgSdkManagedRouteCB

Note: The following is a description of the JSON format expected by the API including optional/required fields.

JSON Format

{
  "Compliance": 0,
  "OorDistance": 0.2,
  "Legs": [
    {
      "Coords": [
        -74730013, //Coords for roads you'd like the route to follow from Stop A -> Stop B
        40297252
      ]
    },
    {
      "Coords": [
        -74660179, //Coords for roads you'd like the route to follow from Stop B -> Stop C
        40348429,
        -74660635,
        40349433
      ]
    }
  ],
  "Trip": {
    "Name": "Test name",
    "Profile": {
      "name": "",
      "vehicleType": 4,
      "routingType": 3,
      "tollRoadType": 2,
      "maxHeight": 12900,
      "maxWidth": 9600,
      "totalLength": 48000,
      "totalWeight": 3300,
      "totalWeightPerAxle": 2300,
      "hazmatType": 0,
      "displayRestrictions": 2,
      "nationalNetwork": false,
      "fiftyThreeFootTrailer": false,
      "overrideRestrictions": true,
      "bordersOpen": true,
      "CongestionZonesOpen": 0,
      "LowEmissionZonesOpen": 0,
      "propane": false,
      "ferryClosed": false,
      "tollAvoid": false,
      "tollClosed": false,
      "truckDimensions": 0,
      "wrongSideofStreetCost": 1000,
      "autoSetStopDirection": 1
    },
    "Stops": [
      {
        "Location": {
          "Address": {
            "StreetAddress": "",
            "City": "Lawrence Township",
            "State": "NJ",
            "Zip": "08648",
            "County": "Mercer",
            "Country": ""
          },
          "Coords": {
            "Lat": "40.297263",
            "Lon": "-74.730034"
          }
        },
        "Waypoint": false,
        "Name": "Stop A"
      },
      {
        "Location": {
          "Coords": {
            "Lat": "40.348727",
            "Lon": "-74.659049"
          }
        },
        "Waypoint": false,
        "Name": "Stop B"
      },
      {
        "Location": {
          "Address": {
            "StreetAddress": "",
            "City": "New York",
            "State": "NY",
            "Zip": "10001",
            "County": "New York",
            "Country": ""
          }
        },
        "Waypoint": false,
        "Name": "Stop C"
      }
    ]
  }
}

Msg_SendManagedRoute

This API is used to send the RouteSync message from a series of lat/long to CoPilot from the client application. When the lat/long positions are sent to CoPilot a compliance and out of route alert parameter should be included. The compliance parameter will indicate how strongly CoPilot should route the driver back to the RouteSync route if they leave the route. If the route is left, a warning callback can be triggered via the out of route distance information.

Please note this API is deprecated within CoPilot Version 10. Msg_SendManagedRouteJSON is recommended to be used in place of this API. Syntax (Prototyped in alkmsg.h) long Msg_SendManagedRoute(char* latLongs, int eOORCompliance, double dOORDist);

Parameter

Return Value

Related APIs Msg_ManagedRouteCallback Msg_SetFlexCallback MsgSdkManagedRouteCB

Note: This API can be use in coordination with MSG_IDT_ROUTE_LATLONLIST. MSG_IDT_ROUTE_LATLONLIST retrieve lat/long for the given route which can be pass to Msg_SendManagedRoute to verify the that Msg_SendManagedRoute follows exactly same route for test environment.

Tip: Can handle multiple start/stop pair. Stops are written as follows – Example - “42636605,-76178562,1”. The 1 identifies it as a stop. For further details about eOORCompliance and CoPilot behavior, please refer to the CoPilot Feature Guide.

Msg_ManagedRouteCallback

This API is used to set callback to receive notifications when sending a managed route request (as a series of lat/long or JSON) using Msg_SendManagedRouteJSON.

Syntax (Prototyped in alkmsg.h)

long Msg_ManagedRouteCallback(void* fnProcessMsg, callingConvention convention = convention_default);

Parameter

Return Value 1

Enum

enum callingConvention {
  convention_default,
  convention_cdecl,
  convention_stdcall
};

MsgSdkManagedRouteCB

Function definition of the callback function when setting a callback using Msg_ManagedRouteCallback.

Syntax (Prototyped in alkmsg.h)

typedef long (*MsgSdkManagedRouteCB) (char* cName, int iResponse);

Parameter

Return Value - 1

Msg_GetPointsOffRouteSyncRoute

Provides details of the lat/long coordinates that are included within the RouteSync input file but are not on the route generated by CoPilot. These details are provided through the subscription of MSG_ID_RouteSyncPointsOff.

Syntax (Prototyped in alkmsg.h)

long MsgGetPointsOffRouteSyncRoute(void _pBytes, unsigned long bytesLen, char strPayload, long lPayload);

Parameter

Return Value

• Less than 0 = Failed
• Greater than 0 = Successful