Requesting Lat/Long Coordinates Along a Rail Route
The following function returns a list of latitude/longitude coordinates along a route line in sequential order, starting at the origin and ending at the destination. When the sequence of lat/longs has been obtained in Connect, you can overlay the PC*Miler Rail route line onto the mapping product of your choice.
This API does not have any limit on the number of legs in the input trip. The coordinates list will be returned for all legs of a multi-leg trip.
Function Signature:
HRESULT PCRSLatLongsEnRoute(Trip tripID, double* latlong, long numPairs)
- Trip refers to the trip setup through PC*Miler Rail-Connect.
- latlong is the list of lat/long pairs.
- numPairs is the number of lat/long pairs returned in the list.
This function is meant to be used in a two-call sequence:
- Initial Call: When calling the API initially, you instruct the PC*Miler Rail software to gather the number of coordinate pairs. The return value of this call will be the number of lat/long pairs. The initial call looks like this:
numPairs = PCRSLatLongsEnRoute(myTrip, NULL, 0)
It is important to pass a NULL pointer to the second argument and zero to the third argument. This tells the software to gather the count of pairs. If an error occurs, the return value will be a negative number mapping to a PC*Miler Rail error code.
- Allocate Memory: After the initial API request, allocate memory for the array of lat/long coordinates. For example, if the API returns 10 for the number of pairs:
double* coordArray = new double[2 * numPairs];
- Final Call: After allocating memory, make the final request to get the array of lat/longs:
srvRet = PCRSLatLongsEnRoute(myTrip, coordArray, numPairs)