Destination
Contents
Msg_TripLoad
Allocate a trip message buffer and return its buffer handle. This needs to be included in every new trip/destination to be sent to CoPilot. This defines the options for how a trip is to be added. Trip messages have a variable number of stops. The DLL must allocate memory to store these stops in a trip message and pass the message to CoPilot. This function stores the main portion of a Trip message structure for subsequent calls to and Msg_SendTrip.
Use Msg_ParserDelete to free the memory when finished with ParserID.
Supported Since | Minimum Operating System |
---|---|
CoPilot 9.2.0 | Windows 10, Android 4.1 |
Syntax (Prototyped in alkmsg.h)
long Msg_TripLoad(long actionCode,
long tripID = 0,
long lMsgID = Msg_ID_Trip);
Defines
#define MSG_ACTION_NONE 0x00
#define MSG_ACTION_INSERT 0x01
#define MSG_ACTION_REPLACE 0x02
#define MSG_ACTION_APPEND 0x09
#define MSG_ACTION_SKIP_CURLOC 0x10
#define MSG_ACTOPT_NOCONFIRM 0x0100
#define MSG_ACTOPT_EXACTMATCHONLY 0x0300
#define MSG_ACTOPT_RETMULTIMATCH 0x0400
#define MSG_ACTOPT_CROSSSTREET 0x0800
#define MSG_ACTOPT_OPTIMIZE 0x1000
#define MSG_ACTOPT_IGNORE_BESTMATCH 0x2000
#define MSG_ACTOPT_OPTIMIZE_DESTFIXED 0x8000
Parameters
Parameter | Description |
---|---|
actionCode | The action to be performed on the trip. Values can be among the following: |
Msg_ACTION_INSERT: Insert the stops contained in this message at the beginning of the existing trip. If current location/GPS fix/Last known position is available then it will add the stop after current location/last known GPS position. If current location/GPS Fix/Last known position is not available, it will insert the stop at top in itinerary | |
Msg_ACTION_REPLACE: Replace the current trip. | |
Msg_ACTION_APPEND: Append the stops contained in this message at the end of the existing trip. | |
Msg_ACTION_SKIP_CURLOC: Don’t add the current location to the trip. This option can only be used when CoPilot is showing “Plan and Edit Trip Screen”. If CoPilot is showing then this flag will be ignored. | |
Msg_ACTOPT_NOCONFIRM: Disable the confirmation dialog in CoPilot. If this flag is not present, the user needs to confirm the trip in CoPilot. Response is sent from CoPilot as Msg_ID_Response and can be retrieved using Msg_ResponseGet. Confirmation is not supported in CoPilot v9 so user must pass this flag while using v9. | |
Msg_ACTOPT_OPTIMIZE: This will optimize the sequence of stops in the CoPilot itinerary if it contains no less than 2 and no more than 100 stops, otherwise optimizing will be performed. | |
Msg_ACTOPT_EXACTMATCHONLY: If this flag is set, CoPilot will only return destinations which match 100% based upon the input address details passed. It will not consider any nearly matches or multiple match. By default without this flag set CoPilot will provide the best match available, this will include the 100% match, as well as nearly matches. Due to backward compatibility, once this flag is set, confirmation dialog will be disabled in CoPilot. | |
Msg_ACTOPT_RETMULTIMATCH: If this flag is set, CoPilot will return all the multiple matches found for given stop. If this flag is set then CoPilot provides stops through Msg_ID_GeocodeResultSet message. By default without this flag set CoPilot will provide the best match available, this will include the 100% match, as well as nearly matches. | |
Msg_ACTOPT_CROSSSTREET: If this flag is set, CoPilot will return all cross streets based on given input. It will not consider any guessed or multiple match. If this flag is set, then CoPilot provides stops through Msg_ID_GeocodeResultSet message. To use this feature, the following flag should be set in the user.cfg If using this function ensure the following: | |
Msg_ACTOPT_IGNORE_BESTMATCH: If this flag is not set and CoPilot has found multiple matches then CoPilot will add the best guess stop into itinerary. If the user does not want to use CoPilot intelligence for best guess match, then set this flag. | |
Msg_ACTOPT_OPTIMIZE_DESTFIXED: It will optimize the sequence of stops excluding the current location and the final end location added. Note: Whenever you are sending multiple stops, you need to call Msg_TripLoad once followed by Msg_TripAddStopWithHouseNum for each stop, followed by Msg_SendTrip. (Please see sample code below under Adding Multiple Stops.) | |
tripID | Not used, pass 0. |
lMsgID | Trip message ID, always pass Msg_ID_TripNew. It is initialized to Msg_ID_Trip to provide backwards compatibility for earlier versions of CoPilot. |
Notes
-
To clear the trip, set actionCode = Msg_ACTION_REPLACE without adding any stops (i.e. do not call Msg_TripAddStop).
-
To disable the confirmation dialog on the CoPilot Application, set the actionCode parameter to the bitwise-OR of the desired action and Msg_ACTOPT_NOCONFIRM.
-
To optimize the stops in CoPilot’s trip itinerary, set the actionCode parameter to the bitwise-OR of the desired action and Msg_ACTOPT_OPTIMIZE OR Msg_ACTOPT_OPTIMIZE_DESTFIXED.
-
When GPS feed is provided, CoPilot will remove the first stop in the list.
Return Value
-
Less than 0 = Failed
-
Greater than or equal to 0 - Successful
Returned ID needed for subsequent calls to Msg_TripAddStopWithHouseNum and Msg_SendTrip.
Adding Single Stop
You need to use Msg_TripLoad trip, followed by a Msg_TripAddStopWithHouseNum followed by a Msg_SendTrip() in the same order with appropriate arguments.
Adding Multiple Stops
You need to use a Msg_TripLoad trip, followed by a multiple Msg_TripAddStopWithHouseNum (depending number of stops) followed by a Msg_SendTrip() in the same order with appropriate arguments.
The recommended code sequence for multiple stops:
lngTrip = Msg.Msg_TripLoad(Msg.MSG_ACTION_REPLACE | Msg.MSG_ACTOPT_NOCONFIRM | MSG_ACTOPT_OPTIMIZE_DESTFIXED, 0, Msg.MSG_ID_Trip);
for (int i = 0; i < addresses.Length; i++)
{
var address = addresses[i];
Log.Verbose(LogCategory.Copilot, "Address(" + (i + 1) + "): " + address);
lngTest = Msg.Msg_TripAddStopWithHouseNum(
(int)lngTrip,
CopilotUtil.ConvertString(i.ToString()),
CopilotUtil.ConvertString(address.street),
CopilotUtil.ConvertString(address.streetName),
CopilotUtil.ConvertString(address.city),
CopilotUtil.ConvertString(address.state),
CopilotUtil.ConvertString(address.zip),
null,
address.lat,
address.longt,
Msg.MSG_ID_TripNew, null, null, null, 1);
if (lngTest <= 0)
{ Msg.Msg_SendWindowMode(Msg.WM_SH_HIDE, -1); throw new Exception("Trip add stop failed"); }
}
Msg.Msg_SendTrip((int)lngTrip, -1, -1, Msg.MSG_ID_TripNew);
Msg_TripAddStopWithHouseNum
Add a stop to a previously allocated trip message buffer, all individual stops need to be added. To be used when House number and Street Address need to be defined separately.
Supported Since | Minimum Operating System |
---|---|
CoPilot 9.2.0 | Windows 10, Android 4.1 |
Syntax (Prototyped in alkmsg.h)
long Msg_TripAddStopWithHouseNum (long ID,
char *pName,
char *pHouseNum,
char *pAddress,
char *pCity,
char *pState,
char *pPostal,
char *pJurisdiction,
long lLat,
long lLon,
long lMsgID = Msg_ID_Trip,
char *pNorthing = NULL,
char *pEasting = NULL,
char *pGridSQ = NULL,
long lStopVia = 1);
Parameters
Parameter | Description |
---|---|
ID | ID returned from Msg_TripLoad (Mandatory) |
pName | Stop Name custom text field – please use this parameter to populate the ‘Destination’ field within the Info Bar. This can be used to provide the driver with the exact address details required for the destination. Its greatest benefit is to mask the address name if not 100% matched by CoPilot as this will show the exact name the driver needs to see. Maximum of 20 characters, single line. |
pHouseNum | House Number |
pAddress | Street Name |
pCity | City name. |
pState | In North America this is the State abbreviation. Outside of North America this is the Country abbreviation: Code — ISO 3166-1 alpha-2 code It is essential to include this for geocoding success |
pPostal | Valid 5-digit zip code (USA/Europe) or 4-7 digit full postcode (UK only) or 6 digit Netherlands postcode |
pJurisdiction | Jurisdiction |
lLat | Latitude, expressed as an integer value in millionths of a degree. |
lLon | Longitude, expressed as an integer value in millionths of a degree. |
lMsgID | Trip message ID, always pass Msg_ID_TripNew. It is initialized to Msg_ID_Trip to provide backwards compatibility for earlier versions of CoPilot. |
pNorthing | Northing for the OS Grid, the number of digits should be between 2-5 and should be equal to the number of digits in pEasting. |
pEasting | Easting for the OS Grid, the number of digits should be between 2-5 and should be equal to the number of digits in pNorthing. |
pGridSq | Grid Square abbreviation, the number of characters should be equal to 2. |
lStopVia | Signifies stop or waypoint. (1: Stop 0:Waypoint) (Currently not in use – should always be 1) To convert a stop to a waypoint (or visa-versa) we advise to use Msg_TripGetStopWaypointInfo along with Msg_IDT_TOGGLESTOPORWAYPOINT |
Return Value
- ≤ 0 - Failed
- Greater than 0 - Successful
Additional Notes
Latitude and Longitude Input All Latitude and Longitude values are sent as long integers. These values are encoded as millionths of a degree. North and East are positive values, South and West are negative values. For example, ALK London office is located at 0.122805W & 51.518220N so it should be passed as a -122805 longitude & 51518220 latitude.
ID and one of the following combination parameters are mandatory. 1. lLat and lLong 2. pState and (pCity OR pPostal) 3. pNorthing, pEasting and pGridSq
Logic when only sending in Lat/Long for address: When using a Latitude and Longitude only, the location does not exactly snap to a road, which can lead CoPilot to take the most convenient road to the route (not the nearest), which can cause issues in the routing. In order to overcome this issue, we would recommend that you add one of the following adjustments: Within User.cfg please add the following line:
> [Geocoding] <br>
> "CleanupBestChoiceOnly"=1 <br>
Other Option for either:
- If you pass street address with the lat/long, we try to match the address details if this is within a short distance of the Lat/Long provided, we will snap the location to the correct road.
Postcode search results:
- When entering postcode information and searching streets you may notice a number of results are returned for streets that do not match the postcode entered. These are stated as being within the neighboring area. This means that they do not match the exact postcode entered but they are nearby in case you have incorrect details.
To remove these addresses from the list of return destinations please add the following entry to user.cfg.
[Geocoding]
“DeleteOutOfCityMatches”=1
Address vs Coordinates vs Address and Coordinates What if I have a Latitude and Longitude value as well as the street address, what is the priority in CoPilot?
-
Scenario 1 – Only the full address is passed via SDK • This is straight forward CoPilot will try to geocode the address.
-
Scenario 2 – Only Lat is passed via SDK • This is straight forward. CoPilot will try to use lat-long to provide the route.
-
Scenario 3 – Both Address and Lat-Lon are passed via SDK • If CoPilot receives a complete lat/long and address details
- CoPilot will assume the lat/long is 100% correct
- CoPilot will identify all nearby street names and search each one by distance to match the street name provided in the input address. CoPilot will snap to the closest link, regardless of house number.
- In the address field CoPilot will mask the house number to match the version supplied, even if it is not the nearest house number to the Lat/Lon provided
- If no matching street name can be found within 1 mile, CoPilot will use the lat/long.
Msg_SendTrip
Send a new trip itinerary (list of stops) to the application. This is used following Msg_TripLoad and Msg_TripAddStopWithHouseNum
Sends a message with trip stop to destination ID.
Supported Since | Minimum Operating System |
---|---|
CoPilot 9.2.0 | Windows 10, Android 4.1 |
Syntax (Prototyped in alkmsg.h)
long Msg_SendTrip(long ID,
long lDestID = CONN_ID_NONE,
long lSrcID = CONN_ID_NONE,
long lMsgID = Msg_ID_Trip);
Parameters
Parameter | Description |
---|---|
ID | ID returned from Msg_TripLoad. |
lDestID | Destination ID received in the callback function established for handling connection event change messages (this callback function is the first parameter passed to Msg_Startup call). |
lSrcID | Unique ID of the sender of the message. Omit or set to CONN_ID_NONE when sending CoPilot control commands to same local machine. |
lMsgID | Trip message ID, always pass Msg_ID_TripNew. Msg_ID_Trip to provide backwards compatibility for earlier versions of CoPilot. Omit or set to CONN_ID_NONE when sending CoPilot control commands to same local machine. |
Return Value
- ≤ 0 - Failed
- Greater than 0 - Successful
Notes
-
CoPilot will send the acknowledgement by Msg_ID_GeocodeResultSet, if user does set the Msg_ACTOPT_RETMULTIMATCH during Msg_TripLoad.
-
CoPilot will send the acknowledgement by Msg_ID_GenericData (payload Msg_IDT_GEORESULT), if user does not set the Msg_ACTOPT_RETMULTIMATCH during Msg_TripLoad. For CoPilot 920 and above, we highly recommend customer to use Msg_IDT_GEOCODE. Msg_IDT_GEOCODE contains more information including any geocoding error, latitude, longitude, stop name, place errors and address errors.
-
Version 920 CoPilot and above
- CoPilot will respond with a geocode result to Msg_ID_GenericInformation (identifier Msg_IDT_GEOCODE). For further information, please read the Msg_ID_GenericInformation in detail.
Msg_TripParse
This is the first API to be used if you wish to receive all the details of the currently loaded Trip. Decodes and retrieves the message ID from a trip message buffer.
Supported Since | Minimum Operating System |
---|---|
CoPilot 9.2.0 | Windows 10, Android 4.1 |
Syntax (Prototyped in alkmsg.h)
long Msg_TripParse(void *pBytes,
unsigned long bytes,
long lMsgID = Msg_ID_Trip);
Parameters
Parameter | Description |
---|---|
pBytes | The message buffer passed by the system to the user-specified callback function, set by Msg_UpdateOptions(). |
bytes | The size of the message buffer in bytes, passed by the system to the user-specified callback function, set by Msg_UpdateOptions(). |
lMsgID | Trip message ID, always pass Msg_ID_Trip. |
Return Value
Returned ID needed for subsequent calls to Msg_TripGet and Msg_TripGetStopInfo.
Msg_SendTripJSON
This API is used to send stops in JSON format from the client application to CoPilot. This will include the stop location, side of street tolerance, stop icon as well as advanced ETA attributes.
If the user would NOT like to change views MSG_IDT_CURRENT_VIEW should be passed to CoPilot.
Supported Since | Minimum Operating System |
---|---|
CoPilot 10.9.0 | Windows 10, Android 4.1 |
Syntax (Prototyped in alkmsg.h)
Parameters
Parameter | Description |
---|---|
actionCode | Same as Msg_TripLoad action code |
lShowGUIIdentifier | The view you want to change to, available views are MSG_IDT_CURRENT_VIEW, MSG_IDT_SHOW_PLANEDITTRIP and MSG_IDT_SHOWROUTE |
bShowCoPilot | If this is true, we show CoPilot |
pJson | Complete contents of a JSON message describing a CoPilot set of stops |
lShowGUIIdentifier Identifiers
Identifier | Description |
---|---|
MSG_IDT_CURRENT_VIEW | Do not change view in CoPilot and continue with current view |
MSG_IDT_PLANEDITTRIP | |
MSG_IDT_SHOWROUTE | Show entire route that has been passed to CoPilot |
JSON Example
{
"Trip": {
"Name": "Road Test trip ",
"Stops": [
{
"Location": {
"Address": {
"StreetAddress": "1 Independence Way",
"City": "Princeton",
"State": "NJ",
"Zip": "08540",
"Country": ""
},
"Coords": {
"Lat": "40.361153",
"Lon": "-74.602685"
},
"VehicleRestricted": "false"
},
"stopType": 0,
"stopSequence": 0,
"Note": "2 Large Packages",
"SideOfStreet": 0,
"Name": "Current location : 1 Independence Way,Princeton, NJ 08540",
"SafeToTurnAround": 0,
"GeocodeType": 2,
"ID": "784552125"
},
{
"Location": {
"Address": {
"StreetAddress": "401 Kingston Terrace",
"City": "Princeton",
"State": "NJ",
"Zip": "08540",
"Country": ""
},
"Coords": {
"Lat": "40.376828",
"Lon": "-74.605018"
},
"VehicleRestricted": "false"
},
"CustomFields": {
"Note2": "2 + 3",
"Note3": "$",
"DetailsDisplay": "DEL: 4532 1 + 2 10:30 $"
},
"stopType": 0,
"stopSequence": 1,
"Note": "2 small boxes",
"SideOfStreet": 1,
"SafeToTurnAround": 1,
"Name": "Stop 2: 401 Kingston Terrace, Princeton, NJ 08540",
"GeocodeType": 2,
"ID": "321545614652641"
},
{
"Location": {
"Address": {
"StreetAddress": "3 Carter Brook Lane",
"City": "Princeton",
"State": "NJ",
"Zip": "08540",
"Country": ""
},
"Coords": {
"Lat": "40.379089",
"Lon": "-74.600965"
},
"VehicleRestricted": "false"
},
"stopType": 0,
"stopSequence": 2,
"Note": "Large envelope",
"SideOfStreet": 2,
"Name": "Stop 3: 3 Carter Brook Lane,Princeton, NJ 08540",
"SafeToTurnAround": 2,
"GeocodeType": 2,
"ID": "5146851946814"
}
]
}
}
Return Value
Value | Result |
---|---|
0 | Indicates a general connection failure |
Greater than 0 | Success and indicated that number of bytes sent successfully to CoPilot |
To receive return values a callback needs to be set up with Msg.Msg_UpdateOptions(Msg.MSG_ID_GenericInformation, true, false, delOnGenericInformation, Msg.callingConvention.convention_stdcall);
and listen for MSG_IDT_IMPORT_TRIP, the return values are te payload for that callback.
Return Codes
Value | Description |
---|---|
MSG_IDT_IMPORT_TRIP_SUCCESS | Successful in sending the request to CoPilot. |
MSG_IDT_IMPORT_TRIP_JSON_PARSE_ERROR | JSON parsing failed - ensure a valid json object is being passed |
MSG_IDT_IMPORT_TRIP_INVALID_TRIP_JSON | JSON has missing/incomplete fields required for trip integration |
Trip JSON field description
The JSON schema is defined below. All fields not marked as Optional are required.
Set
(array)Name
- (string; optional; 256 char) The unique trip name; not visible anywhere in CoPilot, used for organizational purposes.Stops
- (array)Location
- (array)Address
- (object) Used for geocoding stopStreetAddress
- (string; optional; 64 char max)City
- (string; optional; 34 char max)Zip
- (string; optional; 12 char max)State
- (string; optional; 4 char max) State (US) or Country (EU) abbreviationCounty
- (string; optional; 64 char max)
Coords
- (object) Used for geocoding stopLat
- (string) decimal degrees; positive for North, negative for SouthLon
- (string) decimal degrees, positive for East, negative for West
VehicleRestricted
- (boolean) True indicates the stop is on a road link for pedestrians and bicycles only. Available in CoPilot 10.14 and higherID
- (string;optional; 66535 char) Unique stop identifierName
- (string; optional; 256 char) Unique stop name. Displayed when viewing a stopStopSequence
- (unsigned integer; required) Used for identifying stop sequence number.eg ‘Stop n’ where n is the sequence number.Note
- (string; optional; 66535 char) Use this field to provide other specific information related to the stop. Displayed in stop detail view.GeocodeType
- (integer; optional) Used when geocoding stops- Default = 0
- AddressOnly = 1
- LatLonOnly = 2
- AddressAndLatLon = 3
StopType
- (integer; optional) Used for specific routing logic and for display- None = 0
- Origin = 1
- Work = 2
- WayPoint = 3
- FuelStop = 4
- RestStop = 7
- Destination = 9
SideOfStreet
- (integer; optional) Will be used in routing and guidance. This will override current side of street logic in CoPilot- Unknown = -1
- Left = 0
- Right = 1
SafeToTurnAround
- (integer; optional) Used to display information to the driver- Yes = 0
- No = 1
- Unknown = 2
StopIcon
- (string; optional; 66535 char) Use this field to provide stop icon name . No need to provide file extensionCustomFields
- (array) Key and value must be of type string (technically can hold up 66535 char, but the display, will be able to display all of those characters. Key can be any string with no spaces and cannot be a duplicate of a previous key.
CustomFields JSON Explanation
“Note2” - string to hold Note2 description
“Note3” - string to hold Note3 description
“CustomChevronDisplay” - custom message for underneath the Chevron. In general, this string can display around 23-24 characters.
“DetailsDisplay” - custom message banner along the top of the 3D Nav screen. In general, this should be able to hold between 21-24 characters.
Msg_TripGet
This is the second step to be used if you want to receive details of the currently loaded Trip. This provides header information including the total number stops
Supported Since | Minimum Operating System |
---|---|
CoPilot 9.2.0 | Windows 10, Android 4.1 |
Syntax (Prototyped in alkmsg.h)
long Msg_TripGet(long ID,
long &rActionCode,
long &rTripID,
long &rStopCount,
long &rSourceID,
long &rDestID,
char *pFromScreenName,
unsigned long maxFromScreenName,
long lMsgID = Msg_ID_Trip);
Parameters
Parameter | Description |
---|---|
ID | Message buffer handle returned by Msg_TripParse. |
rActionCode | Unused. |
rTripID | Unused. |
rStopCount | Number of stops in the message. |
rSourceID | Unique ID of the sender of the message. |
Omit or set to CONN_ID_NONE when sending CoPilot control commands to same local machine. | |
rDestID | Destination ID received in the callback function established for handling connection event change messages (this callback function is the first parameter passed to Msg_Startup call). Omit or set to CONN_ID_NONE when sending CoPilot control commands to same local machine. |
pFromScreenName | A user-allocated buffer to store the name of the sender. |
maxFromScreenName | The size of the user-allocated buffer pointed to by pFromScreenName. |
lMsgID | Trip message ID, always pass Msg_ID_Trip. |
Return Value
-
≤ 0 - Failed
-
Greater than 0 - Successful
Msg_TripGetStopInfo
Used in conjunction with Msg_Trip* APIs, returns itinerary stop list information from a Msg_ID_Trip message, returning all individual stop details. We recommend using Msg_tripGetStopWaypointInfo instead of Msg_TripGetStopInfo.
Supported Since | Minimum Operating System |
---|---|
CoPilot 9.2.0 | Windows 10 |
Syntax (Prototyped in alkmsg.h)
long Msg_TripGetStopInfo(long ID,
long index,
char *pName,
long lNameLen,
char *pCity,
long lCityLen,
char *pState,
long lStateLen,
char *pAddress,
long lAddressLen,
char *pZip,
long lZipLen,
char *pJuris,
long lJurisLen,
long &rLatitude,
long &rLongitude,
long lMsgID = Msg_ID_Trip);
Parameters
Parameter | Description |
---|---|
ID | Message buffer handle returned by Msg_TripParse. |
index | Index of the stop whose information is being retrieved. |
pName | A user-allocated buffer to store the name of the stop. |
lNameLen | The size of the user-allocated buffer pointed to by pName. |
pCity | A user-allocated buffer to store the city name of the stop. |
lCityLen | The size of the user-allocated buffer pointed to by pCity. |
pState | A user-allocated buffer to store the state name of the stop. |
lStateLen | The size of the user-allocated buffer pointed to by pState. |
pAddress | A user-allocated buffer to store the street address of the stop. |
lAddressLen | The size of the user-allocated buffer pointed to by pAddress. |
pZip | A user-allocated buffer to store the zip code of the stop. |
lZipLen | The size of the user-allocated buffer pointed to by pZip. |
pJuris | A user-allocated buffer to store the jurisdiction name of the stop. |
lJurisLen | The size of the user-allocated buffer pointed to by pJuris. |
rLatitude | Latitude of the stop (in millionths of a degree). Divide this number by 1,000,000 to obtain degrees Latitude. |
rLongitude | Longitude of the stop (in millionths of a degree). Divide this number by 1,000,000 to obtain degrees Longitude. |
lMsgID | Trip message ID, always pass Msg_ID_Trip. |
Return Value
-
≤ 0 - Failed
-
Greater than 0 - Successful
Notes: The first stop returned by Msg_TripGetStopInfo() is the current location of the vehicle and the rest are the stops present in CoPilot’s itinerary.
All Latitude and Longitude values are sent as long integers. These values are encoded as millionths of a degree. North and East are positive values, South and West are negative values. For example, the Trimble Maps London office is located at 0.122805W & 51.518220N so it should be pass as a -122805 longitude & 51518220 latitude.
Msg_TripGetStopWaypointInfo
Used in conjunction with Msg_Trip* APIs, returns itinerary stop list information from a Msg_ID_Trip message, returning all individual stop details including Waypoints. We recommend using Msg_tripGetStopWaypointInfo instead of Msg_TripGetStopInfo
Supported Since | Minimum Operating System |
---|---|
CoPilot 9.2.0 | Windows 10, Android 4.1 |
Syntax (Prototyped in alkmsg.h)
long Msg_TripGetStopWaypointInfo(long ID,
long index,
char *pName,
long lNameLen,
char *pCity,
long lCityLen,
char *pState,
long lStateLen,
char *pAddress,
long lAddressLen,
char *pZip,
long lZipLen,
char *pJuris,
long lJurisLen,
long &rLatitude,
long &rLongitude,
long &lStopVia,
long lMsgID = Msg_ID_TripNew);
Parameters
Parameter | Description |
---|---|
ID | Message buffer handle returned by Msg_TripParse. |
index | Index of the stop whose information is being retrieved. |
pName | A user-allocated buffer to store the name of the stop. |
lNameLen | The size of the user-allocated buffer pointed to by pName. |
pCity | A user-allocated buffer to store the city name of the stop. |
lCityLen | The size of the user-allocated buffer pointed to by pCity. |
pState | A user-allocated buffer to store the state name of the stop. |
lStateLen | The size of the user-allocated buffer pointed to by pState. |
pAddress | A user-allocated buffer to store the street address of the stop. |
lAddressLen | The size of the user-allocated buffer pointed to by pAddress. |
pZip | A user-allocated buffer to store the zip code of the stop. |
lZipLen | The size of the user-allocated buffer pointed to by pZip. |
pJuris | A user-allocated buffer to store the jurisdiction name of the stop. |
lJurisLen | The size of the user-allocated buffer pointed to by pJuris. |
rLatitude | Latitude of the stop (in millionths of a degree). Divide this number by 1,000,000 to obtain degrees Latitude. |
rLongitude | Longitude of the stop (in millionths of a degree). Divide this number by 1,000,000 to obtain degrees Longitude. |
lStopVia | Tells whether the Stop is waypoint or not (if value is 0, stop is waypoint) To convert a stop to a waypoint (or visa-versa) we advise to use Msg_TripGetStopWaypointInfo along with Msg_IDT_TOGGLESTOPORWAYPOINT |
lMsgID | Trip message ID, always pass Msg_ID_Trip. |
Return Value
-
≤ 0 - Failed
-
Greater than 0 - Successful
Note: The first stop returned by Msg_TripGetStopInfo() is the current location of the vehicle and the rest are the stops present in CoPilot’s itinerary.
Note: All Latitude and Longitude values are sent as long integers. These values are encoded as millionths of a degree. North and East are positive values, South and West are negative values. For example, the Trimble Maps London office is located at 0.122805W & 51.518220N so it should be pass as a -122805 longitude & 51518220 latitude.
Msg_SendTripStopInfoRequest
Sends the request to CoPilot to get the list of stops in CoPilot’s itinerary, to be followed by Msg_TripGet* APIs. We recommend using Msg_SendStopInfoRequest instead of Msg_SendTripStopInfoRequest
Supported Since | Minimum Operating System |
---|---|
CoPilot 9.2.0 | Windows 10 |
Syntax (Prototyped in alkmsg.h)
long Msg_SendTripStopInfoRequest(void);
Notes
In order to retrieve the list of stops in CoPilot’s itinerary, you must have previously set a callback for the Msg_ID_Trip message. This is done as follows. First, declare the callback:
void OnTripMsg(const char *pBuf, const unsigned long lBufLen){
// Declare all variables to be used in this function here
long msgID = Msg_TripParse(pBuffer, cBuffer,MSG_ID_Trip);
Msg_TripGet(msgID, actionCode, tripID, lStopCount,
lSourceID, destID, fromScreenName,
sizeof(fromScreenName), MSG_ID_Trip);
for (int i = 0; i <lStopCount; i++)
{
long ret = Msg_TripGetStopInfo(msgID, i, stopName, sizeof(stopName),
cityName, sizeof (cityName),
stateName, sizeof (stateName),
address, sizeof (address),
zipCode, sizeof (zipCode),
jurisName, sizeof (jurisName),
lLatitude, lLongitude,
MSG_ID_Trip);
}
// Use the data in your application here
}
Second, set the callback for Msg_ID_TripNew message via the SDK:
Msg_UpdateOptions(Msg_ID_Trip, true, true, false, (void *) OnTripMsg));
Finally, call Msg_SendTripStopInfoRequest() to request the position immediately:
Msg_SendTripStopInfoRequest();
Return Value
-
≤ 0 Failed
-
Greater than 0 Successful
Msg_SendStopInfoRequest
Sends the request to CoPilot to get the list of stops in CoPilot’s itinerary, to be followed by Msg_Trip* APIs, includes information on Waypoints. We recommend to use Msg_SendStopInfoRequest instead of Msg_SendTripStopInfoRequest
Supported Since | Minimum Operating System |
---|---|
CoPilot 9.2.0 | Windows 10, Android 4.1 |
Syntax (Prototyped in alkmsg.h)
long Msg_SendStopInfoRequest(void);
Parameters
None
Notes: In order to retrieve the list of stops in CoPilot’s itinerary, you must have previously set a callback for the Msg_ID_TripNew message. This is done as follows:
First, declare the callback:
void OnTripMsg(const char *pBuf, const unsigned long lBquen) {
//Declare all variables to be used in this function here
long msgID = Msg_TripParse(pBuffer, cBuffer, MSG_ID_TripNew);
Msg_TripGet(msgID, actionCode, tripID, lStopCount, lSourceID, destID,
fromScreenName, sizeof(fromScreenName), MSG_ID_TripNew);
for (int i = 0; i < lStopCount; i++) {
long ret = Msg_TripGetStopWaypointInfo(msgID, i,
stopName, sizeof(stopName),
cityName, sizeof(cityName),
stateName, sizeof(stateName),
address, sizeof(address),
zipCode, sizeof(zipCode),
jurisName, sizeof(jurisName),
lLatitude, lLongitude,
lStopVia, HSG_ID_TripNew);
}
// Use the data in your application here
}
Second, set the callback for Msg_ID_TripNew message via the SDK:
Msg_UpdateOptions(MSG_ID_TripNew, true, false, (void *)OnTripMsg);
Finally, call Msg_SendTripStopInfoRequest() to request the position:
Msg_SendTripStopInfoRequest();
Return Value
-
≤ 0 - Failed
-
Greater than 0 - Successful
Msg_SendStopInfoRequestJSON()
Sends the request to CoPilot to get the list of stops in CoPilot’s itinerary in JSON format.
Supported Since | Minimum Operating System |
---|---|
CoPilot 10.14 | Windows 10, Android 4.1 |
Syntax (Prototyped in alkmsg.h)
long Msg_SendStopInfoRequestJSON(void);
Parameters
None
Return Values
Less than or Equal to 0 - Error Great than 0 - Successful
Callback Function
private int OnSDKStopInfoResponse(IntPtr pData, uint numBytes);
Sample Code
//First, declare and implement the callback function:
public form_address_trip()
{
InitializeComponent();
delOnSDKStopInfoResponseCB = new Msg.delSDKDeliverCB(OnSDKStopInfoResponse);
}
private int OnSDKStopInfoResponse(IntPtr pData, uint numBytes);
{ String sJson = Msg.MarshalNativeUTF8ToManagedString(pData); }
//Second, set the callback attached to the “TSdkStopInfoJsonRsp” flex callback message via the SDK:
Msg.Msg_SetFlexCallback(Util.ConvertString("TSdkStopInfoJsonRsp"), delOnSDKStopInfoResponseCB);
//Finally, call Msg_SendTripStopInfoRequestJSON() to request the position:
Msg.Msg_SendStopInfoRequestJSON();
//The JSON representation of the itineraries stops will be received in the callback function.
Msg_MultiStopParse
Used in conjunction with Msg_TripLoad with the parameter Msg_ACTOPT_RETMULTIMATCH. Returns the message ID to be used with Msg_MultiStopGet* APIs
Supported Since | Minimum Operating System |
---|---|
CoPilot 9.2.0 | Windows 10, Android 4.1 |
Use Msg_ParserDelete to free the memory when finished with ParserID.
Syntax (Prototyped in alkmsg.h)
long Msg_MultiStopParse (void *pBytes, unsigned long bytes);
Parameters
Parameter | Description |
---|---|
pBytes | The message buffer passed by the system to the user-specified callback function, set by Msg_UpdateOptions(). |
bytes | The size of the message buffer in bytes, passed by the system to the user specified callback function, set by Msg_UpdateOptions(). |
Return Value
-
Less than 0 - Unable to allocate message buffer
-
Greater than 0 - Successful, Returned Message ID needed for subsequent calls to Msg_MultiStopGetHeader and Msg_MultiStopGetDetails
Identifier
#define Msg_ID_GeocodeResultSet 0xf1000411
Msg_MultiStopGetHeader
Used in conjunction with Msg_TripLoad with the parameter Msg_ACTOPT_RETMULTIMATCH returns the header information including the number of stops
Supported Since | Minimum Operating System |
---|---|
CoPilot 9.2.0 | Windows 10, Android 4.1 |
Syntax (Prototyped in alkmsg.h)
long Msg_MultiStopGetHeader (unsigned long lMultiStopMsgID,
long & rError,
unsigned long &rStopCount)
Parameters
Parameter | Description |
---|---|
lMultiStopMsgId | Message buffer handle returned by Msg_MultiStopParse. |
rError | Any error occurred during geocoding for requested stop otherwise 0. |
rStopCount | Number of stops in this message. |
Return Value
- 0 - Unable to find MultiStopMsgID from the cache list
- 1 - Successful
Error code returns in rError:
-2 Not enough memory
Msg_MultiStopGetDetails
Used in conjunction with Msg_TripLoad with the parameter Msg_ACTOPT_RETMULTIMATCH returns the individual stop details.
Supported Since | Minimum Operating System |
---|---|
CoPilot 9.2.0 | Windows 10, Android 4.1 |
Syntax (Prototyped in alkmsg.h)
long Msg_MultiStopGetDetails(unsigned long lMultiStopMsgId,
unsigned long lIndex,
char *pStreet,
unsigned long lStreetLen,
char *pCity,
unsigned long lCityLen,
char *pPostcode,
unsigned long lPostcodeLen,
char* pState,
unsigned long lStateLen,
char* pJuris,
unsigned long lJurisLen,
long &rLatitude,
long &rLongitude);
Parameters
Parameter | Description |
---|---|
lMultiStopMsgId | Message buffer handle returned by Msg_SearchParse. |
lIndex | Index of the stop whose information is being retrieved. |
pStreet | A user-allocated buffer to store the name of the street. |
lStreetLen | The size of the user-allocated buffer pointed to by pStreet. |
pCity | A user-allocated buffer to store the city of the current location. |
lCityLen | The size of the user-allocated buffer pointed to by pCity. |
pPostcode | A user-allocated buffer to store the state of the postcode. |
lPostcodeLen | The size of the user-allocated buffer pointed to by pPostCode. |
pState | A user-allocated buffer to store the zip code of the current location. |
lStateLen | The size of the user-allocated buffer pointed to by pState. |
pJuris | A user-allocated buffer to store the jurisdiction of the current location. |
lJurisLen | The size of the user-allocated buffer pointed to by pJuris. |
rLatitude | Latitude of the given stop. |
rLongitude | Longitude of the given stop. |
Return Value
-
0 - Unable to find MultiStopMsgID
-
-1 - Invalid index value
-
1 - Successful
Msg_requestGeocode
Request to CoPilot providing a latitude/longitude for an address.
Supported Since | Minimum Operating System |
---|---|
CoPilot 9.2.0 | Windows 10, Android 4.1 |
Syntax (Prototyped in alkmsg.h)
long Msg_RequestGeocode (char *pName,
unsigned long lHouseNumber,
char *pStreetName,
char *pCity,
char *pState,
char *pPostal,
char *pJurisdiction,
long lDestID = CONN_ID_NONE,
long lSrcID = CONN_ID_NONE);
Parameters
Parameter | Description |
---|---|
pName | Optional alias name for stop. |
lHouseNo | House number. |
pStreetName | Street name. Geocoded valid address is recommended. |
pCity | City name. Geocoded valid city name is recommended. |
pState | State abbreviation. |
pPostal | Valid 5-digit zip code (USA/Europe) or 4-7 digit full postcode (UK only) |
pJurisdiction | Jurisdiction of the stop. |
lDestID | Destination ID received in the callback function established for handling connection event change messages (this callback function is the first parameter passed to Msg_Startup call). Omit or set to CONN_ID_NONE when sending CoPilot control commands to same local machine. |
lSrcID | Unique ID of the sender of the message. Omit or set to CONN_ID_NONE when sending CoPilot control commands to same local machine. |
Return Value
- < 0 Failed to send message to the CoPilot.
- 0 Unable to send message as SDK didn’t find connection
- Greater than 0 = Successful
Note: Once sending a request, CoPilot will respond with a geocode result to Msg_ID_GenericInformation (identifier Msg_IDT_GEOCODE). For further information, please read the Msg_ID_GenericInformation in detail.
Tip: We highly recommend customer to use Msg_IDT_GEOCODE. Msg_IDT_GEOCODE contains more information including any geocoding error, latitude,longitude, stop name, place errors and address errors. CoPilot will respond with a geocode result to Msg_ID_GenericInformation identifier Msg_IDT_GEOCODE). For further information, please read the Msg_ID_GenericInformation in detail.
Msg_RequestReverseGeocode
Request to reverse geocode and provide the address closest to the given latitude and longitude.
Supported Since | Minimum Operating System |
---|---|
CoPilot 9.2.0 | Windows 10, Android 4.1 |
Syntax (Prototyped in alkmsg.h)
long Msg_RequestReverseGeocode(long lLatitude, long lLongitude,
long lDestID = CONN_ID_NONE,
long lSrcID = CONN_ID_NONE);
Parameters
Parameter | Description |
---|---|
lLatitude | Latitude, expressed as an integer value in millionths of a degree. |
lLongitude | Longitude, expressed as an integer value in millionths of a degree. |
lDestID | Destination ID received in the callback function established for handling connection event change messages (this callback function is the first parameter passed to Msg_Startup call). Omit or set to CONN_ID_NONE when sending CoPilot control commands to same local machine. |
lSrcID | Unique ID of the sender of the message. Omit or set to CONN_ID_NONE when sending CoPilot control commands to same local machine. |
Return Value
- < 0 - Failed to send message to the CoPilot
- 0 - Unable to send message as SDK did not find connection
- Greater than 0 - Successful
Note: All latitude and longitude values are sent as long integers. These values are encoded as millionths of a degree. North and East are positive values, South and West are negative values. For example, the Trimble Maps London office is located at 0.122805W & 51.518220N so it should be pass as a -122805 longitude & 51518220 latitude.
Msg_ReverseGeocodeInfo
Retrieves and decodes the address information from a Msg_ID_ReverseGeocode message. To be used in conjunction with Msg_RequestReverseGeocode.
Supported Since | Minimum Operating System |
---|---|
CoPilot 9.2.0 | Windows 10, Android 4.1 |
Syntax (Prototyped in alkmsg.h)
long Msg_ReverseGeocodeInfo (void *pBuffer,
unsigned long lBufLen,
long &rLatitude,
long& rLongitude,
long &rHouseNo,
char *pAddress,
unsigned long lAddressLen,
char* pCity,
unsigned long lCityLen,
char *pState,
unsigned long lStateLen,
char *pZip,
unsigned long lZip,
char *pJuris,
unsigned long lJurisLen);
Parameters
Parameter | Description |
---|---|
pBuffer | The message buffer passed by the system to the user-specified callback function, set by Msg_UpdateOptions(). |
lBufLen | The size of the message buffer in bytes, passed by the system to the user specified callback function, set by Msg_UpdateOptions(). |
rLatitude | Latitude, expressed as an integer value in millionths of a degree. |
rLongitude | Longitude, expressed as an integer value in millionths of a degree. |
rHouseNo | House number |
pAddress | A user-allocated buffer to store the street address of the current location. |
lAddressLen | The size of the user-allocated buffer pointed to by pAddress. |
pCity | A user-allocated buffer to store the city of the current location. |
lCityLen | The size of the user-allocated buffer pointed to by pCity. |
pState | A user-allocated buffer to store the state of the current location. |
lState | The size of the user-allocated buffer pointed to by pState. |
pZip | A user-allocated buffer to store the zip code of the current location. |
lZip | The size of the user-allocated buffer pointed to by pZip. |
pJuris | A user-allocated buffer to store the jurisdiction of the current location. |
lJuris | The size of the user-allocated buffer pointed to by pJuris. |
Return Value
- 0 - Failed to allocate memory to pass pBuffer
- 1 - Successful
lIdentifier
#define Msg_ID_ReverseGeocode 0xf1000210
Example
// Sending the lat/long information
Msg_RequestReverseGeocode;
//Receiving side either by callback or through message queue mechanism
if ( mgID == MSG_ID_ReverseGeocode)
Msg_ReverseGeocodeInfo ();
Note: All Latitude and Longitude values are sent as long integers. These values are encoded as millionths of a degree. North and East are positive values, South and West are negative values. For example, the Trimble Maps London office is located at 0.122805W & 51.518220N so it should be pass as a -122805 longitude & 51518220 latitude.
Msg_SearchCity
Request a search of Cities based upon provided criteria including: partial name, filtered by country if required.
Supported Since | Minimum Operating System |
---|---|
CoPilot 9.2.0 | Windows 10, Android 4.1 |
Syntax (Prototyped in alkmsg.h)
long Msg_SearchCity (char * pCityPrefix,
char * pState,
unsigned long lMaxResult,
long lDestID = CONN_ID_NONE,
long lSrcID = CONN_ID_NONE);
Parameters
Parameter | Description |
---|---|
pCityPrefix | City Prefix. |
pState | Country where user wants to search for city (Optional) |
lMaxResult | Maximum result returned by the SDK. Default is 25. |
lDestID | Destination ID received in the callback function established for handling connection event change messages (this callback function is the first parameter passed to Msg_Startup call). Omit or set to CONN_ID_NONE when sending CoPilot control commands to same local machine. |
lSrcID | Unique ID of the sender of the message. Omit or set to CONN_ID_NONE when sending CoPilot control commands to same local machine. |
Notes
Please use Msg_SearchCityAndPostcode API for quick search. Msg_SearchCity will be slower compare to Msg_SearchCityAndPostcode as Msg_SearchCity will filter city from the results and if provided state information, it will further filter so it will take significantly more time.
For a quick result, pass pState as a NULL. If pState is provided then the search will be slower as it needs to filter the results based on pState.
Please note you are required to enter at least one character to receive results.
Please note the lower number of max results required to return, the quicker results will be provided.
Once the address has been passed and your search is 100% completed, you will need to clear the cache memory of CoPilot
Return Value
-
< 0 Failed to send message to the CoPilot
-
0 Unable to send message as SDK didn’t find connection
-
Greater than 0 = Successful
Msg_SearchPostcode
Request a search of Postcodes based upon provided criteria including: partial postcode, filtered by country if required.
Supported Since | Minimum Operating System |
---|---|
CoPilot 9.2.0, Deprecated CoPilot 10.4.0 | Windows 10, Android 4.1 |
Syntax (Prototyped in alkmsg.h)
long Msg_SearchPostcode (char * pPostcodePrefix,
char * pState,
unsigned long lMaxResult,
long lDestID = CONN_ID_NONE,
long lSrcID = CONN_ID_NONE);
Parameters
Parameter | Description |
---|---|
pPostcodePrefix | Postcode Prefix. |
pState | Country where user wants to search for city (optional) |
lMaxResult | Maximum result returned by the SDK. Default is 25. |
lDestID | Destination ID received in the callback function established for handling connection event change messages (this callback function is the first parameter passed to Msg_Startup call). Omit or set to CONN_ID_NONE when sending CoPilot control commands to same local machine. |
lSrcID | Unique ID of the sender of the message. Omit or set to CONN_ID_NONE when sending CoPilot control commands to same local machine. |
Notes
Please use Msg_SearchCityAndPostcode API for quick search. Msg_SearchPostcode will be slower compare to Msg_SearchCityAndPostcode as Msg_SearchPostcode will filter city from the results and if provided state information, it will further filter so it will take significantly more time.
For a quick result, pass pState as a NULL. If pState is provided, then the search will be slower as it needs to filter the results based on pState.
Please note you are required to enter at least one character to receive results.
Please note the lower number of max results required to return, the quicker results will be provided.
Return Value
- < 0 - Failed to send message to CoPilot
- 0 - Unable to send message as SDK did not find connection
- Greater than 0 = Successful
Msg_SearchCityAndPostcode
Request a search for Cities and Postcode based upon prefix. Results are identical as user searching inside CoPilot.
Supported Since | Minimum Operating System |
---|---|
CoPilot 9.2.0 | Windows 10, Android 4.1 |
Syntax (Prototyped in alkmsg.h)
long Msg_SearchCityAndPostcode (char * pPrefix,
unsigned long lMaxResult,
long lDestID = CONN_ID_NONE,
long lSrcID = CONN_ID_NONE);
Parameters
Parameter | Description |
---|---|
pPrefix | City/Postcode Prefix. |
lMaxResult | Maximum result returned by the SDK. Default is 25. |
lDestID | Destination ID received in the callback function established for handling connection event change messages (this callback function is the first parameter passed to Msg_Startup call). Omit or set to CONN_ID_NONE when sending CoPilot control commands to same local machine. |
lSrcID | Unique ID of the sender of the message. Omit or set to CONN_ID_NONE when sending CoPilot control commands to same local machine. |
Notes
It is advisable to use Msg_SearchCityAndPostcode compare to using Msg_SearchCity and Msg_SearchPostcode. This API will provide results much faster like user searching address in CoPilot.
Return Value
-
< 0 Failed to send message to the CoPilot.
-
0 Unable to send message as SDK didn’t find connection.
-
Greater than 0 = Successful
Msg_SearchStreet
Following Msg_SearchCity or Msg_SearchPostcode this will request a search for a street based upon provided criteria including partial name.
Supported Since | Minimum Operating System |
---|---|
CoPilot 9.2.0 | Windows 10, Android 4.1 |
Syntax (Prototyped in alkmsg.h)
long Msg_SearchStreet(char * pStreetPrefix,
char * pCity,
char * pPostcode,
char * pState,
char* pJuris,
long lLatitude,
long lLongitude,
unsigned long lType,
long lGrid,
unsigned long lSize,
unsigned long lCityPostcodeIndex,
unsigned long lMaxResult,
long lDestID = CONN_ID_NONE,
long lSrcID = CONN_ID_NONE);
Parameters
Parameter | Description |
---|---|
pStreetPrefix | Street Prefix (optional) |
pCity | City Name, where user want to search street. (Optional) |
pPostalCode | PostCode where user wants to search for street. (Optional) |
pState | Country where user wants to search for street. (Optional) |
pJuris | Jurisdiction where user wants to search for street. (Optional) |
rLatitude | Latitude return by the city/postcode search, necessary to pass in street search. |
rLongitude | Longitude return by the city/postcode search, necessary to pass in street search. |
rType | Type return by the city/postcode search, necessary to pass in street search. |
rGrid | Grid return by the city/postcode search, necessary to pass in street search. |
rSize | Size return by the city/postcode search, necessary to pass in street search |
lCityPostcodeIndex | Pass city/postcode index, returned during city/postcode search. |
lMaxResult | Maximum result returned by the SDK. Default is 25. |
lDestID | Destination ID received in the callback function established for handling connection event change messages (this callback function is the first parameter passed to Msg_Startup call). Omit or set to CONN_ID_NONE when sending CoPilot control commands to same local machine. |
lSrcID | Unique ID of the sender of the message. Omit or set to CONN_ID_NONE when sending CoPilot control commands to same local machine. |
Return Value
- < 0 - Failed to send message to CoPilot
- 0 - Unable to send message as SDK didn’t find connection
- Greater than 0 = Successful
Note
-
pStreetPrefix is optional and enter as many characters as possible in order to reduce the search time.
-
Pass Latitude,longitude, type,grid and size returned during city/postcode search in order to reduce search time.
Msg_SearchExtendedStreet
Following Msg_SearchStreet returning complete street names, this API will return all multiple matches for the street and house number.
Supported Since | Minimum Operating System |
---|---|
CoPilot 9.2.0 | Windows 10, Android 4.1 |
Syntax (Prototyped in alkmsg.h)
long Msg_SearchExtendedStreet(unsigned long lHouseNo,
char * pStreet,
unsigned long lStreetIndex,
unsigned long lMaxResult,
long lDestID = CONN_ID_NONE,
long lSrcID = CONN_ID_NONE);
Parameters
Parameter | Description |
---|---|
lHouseNo | House Number, For center of the street pass 0 |
pStreet | Street Name, Selected during Msg_SearchStreet |
lStreetIndex | Pass street index, returned during street search. |
lMaxResult | Maximum result returned by the SDK. Default is 25. |
lDestID | Destination ID received in the callback function established for handling connection event change messages (this callback function is the first parameter passed to Msg_Startup call). Omit or set to CONN_ID_NONE when sending CoPilot control commands to same local machine. |
lSrcID | Unique ID of the sender of the message. Omit or set to CONN_ID_NONE when sending CoPilot control commands to same local machine. |
Return Value
- Less than 0 = Failed to send message to CoPilot
- Equal to 0 = Unable to send message as SDK didn’t find connection
- Greater than 0 = Successful
Note
-
pStreetName, selected street name during Msg_SearchStreet.
-
If no house number exists in the database, it returns no results. In this scenario, pass 0 as a house number.
Msg_RequestMoreSearch
Requests to retrieve more search results (city, postcode or street) based upon last request. Used when more results are available than the max results provided.
Supported Since | Minimum Operating System |
---|---|
CoPilot 9.2.0 | Windows 10, Android 4.1 |
Syntax (Prototyped in alkmsg.h)
long Msg_RequestMoreSearch(unsigned long lIdentifier,
unsigned long lMaxResult,
long lDestID = CONN_ID_NONE,
long lSrcID = CONN_ID_NONE);
Parameters
Parameter | Description |
---|---|
lIdentifier | Identifier indicates that more search is for city, postcode, street or extended street. |
lMaxResult | Maximum result returned by the SDK. Default is 25. |
lDestID | Destination ID received in the callback function established for handling connection event change messages (this callback function is the first parameter passed to Msg_Startup call). Omit or set to CONN_ID_NONE when sending CoPilot control commands to same local machine. |
lSrcID | Unique ID of the sender of the message. Omit or set to CONN_ID_NONE when sending CoPilot control commands to same local machine. |
Return Value
- Less than 0 = Failed to send message to CoPilot
- Equal to 0 = Unable to send message as SDK didn’t find connection
- Greater than 0 = Successful
Note
After the first request (Msg_SearchCity, Msg_SearchPostcode, Msg_SearchCityAndPostcode or Msg_SearchStreet), if client receives the ‘MoreSearch’ flag as true then you can request for further search results using this function.
Msg_SearchParse
Required to retrieve results following a city, street or postcode search. Decodes and retrieves the message ID from a search message buffer.
Use Msg_ParserDelete to free the memory when finished with ParserID.
Supported Since | Minimum Operating System |
---|---|
CoPilot 9.2.0 | Windows 10, Android 4.1 |
Syntax (Prototyped in alkmsg.h)
long Msg_SearchParse (void *pBytes,
unsigned long bytes);
Parameters
Parameter | Description |
---|---|
pBytes | The message buffer passed by the system to the user-specified callback function, set by Msg_UpdateOptions(). |
bytes | The size of the message buffer in bytes, passed by the system to the user specified callback function, set by Msg_UpdateOptions(). |
Return Value
- Less than 0 = Unable to allocate message buffer
- Greater than or equal to 0 = Successful , Returned Message ID needed for subsequent calls to Msg_SearchGetHeader and Msg_SearchGetDetail.
Msg_SearchGetHeader
Required to retrieve results following a city, street or postcode search. Retrieves the search address details from a given search.
Supported Since | Minimum Operating System |
---|---|
CoPilot 9.2.0 | Windows 10, Android 4.1 |
Syntax (Prototyped in alkmsg.h)
long Msg_SearchGetHeader (unsigned long lSearchMsgId,
unsigned long &rIdentifier,
long & rError,
unsigned long &rSearchCount bool &MoreSearch)
Parameters
Parameter | Description |
---|---|
lSearchMsgId | Message buffer handle returned by Msg_SearchParse. |
rIdentifier | Identifier indicates that search result is for city search or street search. |
rError | If any error occurred during address search otherwise 0. |
rSearchCount | Number of search results in this message. |
rMoreSearch | More search results are available or not |
Return Value
- 0 - Unable to find SearchMsgID from the cache list
- 1 - Successful
Error code returns in rError:
-2 Not enough memory.
Msg_SearchGetDetails
Required to retrieve results following a city, street or postcode search. Retrieves the search identifier, search count and error codes.
Supported Since | Minimum Operating System |
---|---|
CoPilot 9.2.0 | Windows 10, Android 4.1 |
Syntax (Prototyped in alkmsg.h)
long Msg_SearchGetDetails (unsigned long lSearchMsgId,
unsigned long lIndex,
char *pStreet,
unsigned long lStreetLen,
char *pCity,
unsigned long lCityLen,
char *pPostcode,
unsigned long lPostcodeLen,
char* pState,
unsigned long lStateLen,
char* pJuris,
unsigned long lJurisLen,
long &rLatitude,
long &rLongitude,
unsigned long &rType,
long &rGrid,
unsigned long &rSize,
unsigned long &rSearchIndex);
Parameters
Parameter | Description |
---|---|
lSearchMsgId | Message buffer handle returned by Msg_SearchParse. |
lIndex | Index of the stop whose information is being retrieved. |
pStreet | A user-allocated buffer to store the name of the street. |
lStreetLen | The size of the user-allocated buffer pointed to by pStreet. |
pCity | A user-allocated buffer to store the city of the current location. |
lCityLen | The size of the user-allocated buffer pointed to by pCity. |
pPostcode | A user-allocated buffer to store the state of the postcode. |
lPostcodeLen | The size of the user-allocated buffer pointed to by pPostCode. |
pState | A user-allocated buffer to store the zip code of the current location. |
lStateLen | The size of the user-allocated buffer pointed to by pState. |
pJuris | A user-allocated buffer to store the jurisdiction of the current location. |
lJurisLen | The size of the user-allocated buffer pointed to by pJuris. |
rLatitude | Latitude return by the city/postcode search, necessary to pass in street search. |
rLongitude | Longitude return by the city/postcode search, necessary to pass in street search. |
rType | Type return by the city/postcode search, necessary to pass in street search. |
rGrid | Grid return by the city/postcode search, necessary to pass in street search. |
rSize | Size return by the city/postcode search, necessary to pass in street search. |
rSearchIndex | SearchIndex need to be parse in subsequent operation. |
Return Value
- 0 - Unable to find SearchMsgID from the cache list
- -1 - Invalid index value
- 1 - Successful
Note
-
During street search, please ignore all other fields except pStreet.
-
During City/Postcode search, please store lat, long, type, grid, size and pass during street search in order to reduce the search time.
Msg_ClearSearchResults
Once the city, postcode or street search is completed, this API should be used to remove the cache results from the memory and stop searching.
If user is calling sequentially like city/postcode search and street search then after street search the user needs to call this function. The same memory is used by city, postcode and street search so once the user completes all the search, the user needs to call this function.
Supported Since | Minimum Operating System |
---|---|
CoPilot 9.2.0 | Windows 10, Android 4.1 |
Syntax (Prototyped in alkmsg.h)
long Msg_ClearSearchResults (long lDestID = CONN_ID_NONE,
long lSrcID = CONN_ID_NONE);
Parameters
Parameter | Description |
---|---|
lDestID | Destination ID received in the callback function established for handling connection event change messages (this callback function is the first parameter passed to Msg_Startup call). Omit or set to CONN_ID_NONE when sending CoPilot control commands to same local machine. |
lSrcID | Unique ID of the sender of the message. Omit or set to CONN_ID_NONE when sending CoPilot control commands to same local machine. |
Return Value
-
< 0 - Failed to send message to CoPilot
-
0 - Unable to send message as SDK didn’t find connection
-
Greater than 0 = Successful
Identifier
#define Msg_ID_AddressSearch 0xf1000e00L
#define Msg_IDT_CITYSEARCH 0x0001L
#define Msg_IDT_POSTCODESEARCH 0x0002L
#define Msg_IDT_STREETSEARCH 0x0003L
#define Msg_IDT_EXTENDEDSTREETSEARCH 0x0004L
#define Msg_IDT_CITYANDPOSTCODESEARCH 0x0009L
Example
Msg_SearchPOI
Please use Msg_SearchPOIEx.
Supported Since | Minimum Operating System |
---|---|
CoPilot 9.2.0, Deprecated CoPilot 10.4.0 | Windows 10 |
Syntax (Prototyped in alkmsg.h)
long Msg_SearchPOI (char * pPoiName,
unsigned long lCategoryID,
unsigned long lRadius,
unsigned long lMaxResult,
long lLatitude,
long lLongitude,
long lDestID = CONN_ID_NONE,
long lSrcID = CONN_ID_NONE);
Parameters
Parameter | Description |
---|---|
pPoiName | POI name. Try to enter as much character as possible in order to reduce search time. (Optional) |
lCategoryID | Category ID. (Optional) If left blank, all categories will be searched. Only one ID should be provided to search a specific category, with the exception of Android where multiple Category IDs can be included. |
lRadius | Search radius from current location (or provided lat/long). . If not passed it will take 10 as a default radius (Optional). Radius distance unit is same as current set value, for KM or Miles. |
lMaxResult | Maximum result returned by the SDK. Default is 25. Maximum is 50 |
lLatitude | Latitude, expressed as an integer value in millionths of a degree. (Optional) |
lLongitude | Longitude, expressed as an integer value in millionths of a degree. (Optional) |
lDestID | Destination ID received in the callback function established for handling connection event change messages (this callback function is the first parameter passed to Msg_Startup call). Omit or set to CONN_ID_NONE when sending CoPilot control commands to same local machine. |
lSrcID | Unique ID of the sender of the message. Omit or set to CONN_ID_NONE when sending CoPilot control commands to same local machine. |
Return Value
- Less than 0 = Failed to send message to CoPilot
- Equal to 0 = Unable to send message as SDK did not find connection
- Greater than 0 = Successful
Note
All parameters in Msg_SearchPOI are optional.
- pPoiName is null then it will search all the POIs for given category.
- lCategoryID is null then it will search all POIs for all category.
- Default lRadius is 10. If lRadius passed as a 0, then it will search in a default radius. Distance unit (km/mile) is based upon the selected unit in CoPilot. If lRadius is null then it will search in default radius.
- Default lMaxResult is 25. If lMaxResult passed as a 0 then it will return 25 results at a time.
- Default lat/long are 0xFFFFFFF. If user does not pass latitude and longitude then SDK will search POI from current location or last known location.
Msg_SearchPOIEx
Request a search of POI’s based upon a series of criteria including by category, location, on a route etc.
Supported Since | Minimum Operating System |
---|---|
CoPilot 9.2.0 | Windows 10, Android 4.1 |
Syntax (Prototyped in alkmsg.h)
long Msg_SearchPOIEx (char* pPoiName,
unsigned long lCategoryID,
unsigned long lRadius,
unsigned long lMaxResult,
long lLatitude,
long lLongitude,
long lSearchType,
long lDestID = CONN_ID_NONE,
long lSrcID = CONN_ID_NONE);
Parameters
Parameter | Description |
---|---|
pPoiName | POI name. Try to enter as much character as possible in order to reduce search time. (Optional) |
lCategoryID | Category ID. (Optional) |
lRadius | Search radius from current location (or provided lat/long). . If not passed it will take 10 as a default radius (Optional). Radius distance unit is same as current set value, for KM or Miles. |
lMaxResult | Maximum result returned by the SDK. Default is 25. Maximum is 50 |
lLatitude | Latitude, expressed as an integer value in millionths of a degree. (Optional) |
lLongitude | Longitude, expressed as an integer value in millionths of a degree. (Optional) |
lSearchType | Type of search requested based on EPoiSearchType |
lDestID | Destination ID received in the callback function established for handling connection event change messages (this callback function is the first parameter passed to Msg_Startup call). Omit or set to CONN_ID_NONE when sending CoPilot control commands to same local machine. |
lSrcID | Unique ID of the sender of the message. Omit or set to CONN_ID_NONE when sending CoPilot control commands to same local machine. |
It adds the lSearchType parameter. All parameters are similar to Msg_SearchPOI.
public enum EPoiSearchType
{
EUnknownPoiSearchType = 0,
ENearCurrentLocation,
EAlongRoute,
EPickFromMap,
ENearAnAddress,
EInACity
};
// case EAlongRoute:
// - will search the poi along the route
// - CoPilot requires a gps fix for this to work
// - It does not require a lat/long
// - Please note that lRadius is ignored when ‘AlongRoute’ is selected – the distance max distance is 50 miles.
// - Max results are capped at 50
// - Along the route also includes distances that can be up to 1 mile or 1 kilometer off the green routing line depending on the unit selected.
// case ENearCurrentLocation:
// - will search the poi near the current location
// - CoPilot should have a gps fix
// - does not need lat/long
// case EPickFromMap:
// case ENearAnAddress:
// case EInACity:
// - will use the lat/long provided
Return Value
-
Less than 0 = Failed to send message to CoPilot
-
Equal to 0 = Unable to send message as SDK did not find connection
-
Greater than 0 = Successful
Msg_RequestMorePOI
Sends a request to retrieve more POI based upon last request criteria provided in Msg_SearchPOIEx.
Supported Since | Minimum Operating System |
---|---|
CoPilot 9.2.0 | Windows 10, Android 4.1 |
Syntax (Prototyped in alkmsg.h)
long Msg_RequestMorePOI(unsigned long lMaxResult,
long lDestID = CONN_ID_NONE,
long lSrcID = CONN_ID_NONE);
Parameters
Parameter | Description |
---|---|
lMaxResult | Maximum result returned by the SDK. Default is 25. |
lDestID | Destination ID received in the callback function established for handling connection event change messages (this callback function is the first parameter passed to Msg_Startup call). Omit or set to CONN_ID_NONE when sending CoPilot control commands to same local machine. |
lSrcID | Unique ID of the sender of the message. Omit or set to CONN_ID_NONE when sending CoPilot control commands to same local machine. |
Return Value
- Less than 0 = Failed to send message to CoPilot
- Equal to 0 = Unable to send message as SDK didn’t find connection
- Greater 0 = Successful
Note
After first request, if user gets the MorePOI as a true then user can requestfor more POI using this function.
Msg_POIParse
Required to retrieve results following Msg_SearchPOIEx and Msg_RequestMorePOI. Decodes and retrieves the message ID from a POI search message buffer.
Use Msg_ParserDelete to free the memory when finished with ParserID.
Supported Since | Minimum Operating System |
---|---|
CoPilot 9.2.0 | Windows 10, Android 4.1 |
Syntax (Prototyped in alkmsg.h)
long lPOIMsgId = Msg_POIParse (void *pBytes,
unsigned long bytes);
Parameters
Parameter | Description |
---|---|
pBytes | The message buffer passed by the system to the user-specified callback function, set by Msg_UpdateOptions(). |
bytes | The size of the message buffer in bytes, passed by the system to the user specified callback function, set by Msg_UpdateOptions(). |
Return Value
- Less than 0 = Unable to allocate message buffer
- Greater than or equal to 0 = Successful, returned message ID needed for subsequent calls to Msg_POIGetHeader and Msg_POIGetDetail
Msg_POIGetHeader
Required to retrieve results following Msg_SearchPOIEx and Msg_RequestMorePOI. Decodes and retrieves the POI count and error codes.
Supported Since | Minimum Operating System |
---|---|
CoPilot 9.2.0 | Windows 10, Android 4.1 |
Syntax (Prototyped in alkmsg.h)
long Msg_POIGetHeader (unsigned long lPOIMsgId,
long & rError,
unsigned long & rPOICount,
bool & rMorePOI)
Parameters
Parameter | Description |
---|---|
lPOIMsgId | Message buffer handle returned by Msg_POIParse. |
rError | If any error occurred during POI search otherwise 0. |
rPOICount | Number of POI in this message. |
rMorePOI | More POI is available or not |
Return Value
- 0 - Unable to find POI MsgID from the cache list
- 1 - Successful
Error code returns in rError:
Error Code | Description |
---|---|
-1 | Unable to get current latitude/longitude |
-2 | Not enough memory |
Msg_POIGetDetails
Required to retrieve results following Msg_SearchPOIEx and Msg_RequestMorePOI. Returns the POI details for the selected result.
Supported Since | Minimum Operating System |
---|---|
CoPilot 9.2.0 | Windows 10, Android 4.1 |
Syntax (Prototyped in alkmsg.h)
long Msg_POIGetDetails(unsigned long lPOIMsgId,
unsigned long lIndex,
char *pName,
unsigned long lNameLen,
char *pAddress,
unsigned long lAddressLen,
char *pCity,
unsigned long lCityLen,
char *pJuris,
unsigned long lJurisLen,
char *pPostcode,
unsigned long lPostcodeLen,
char *pState,
unsigned long lStateLen,
long &rLatitude,
long &rLongitude,
char *pPhone,
unsigned long lPhoneLen,
char *Misc,
unsigned long lMisc,
unsigned long &rCatID,
double &rDist);
Parameters
Parameter | Description |
---|---|
lPOIMsgId | Message buffer handle returned by Msg_POIParse. |
lIndex | Index of the stop whose information is being retrieved. |
pName | A user-allocated buffer to store the name of the POI. |
lNameLen | The size of the user-allocated buffer pointed to by pName. |
pAddress | A user-allocated buffer to store the address of the POI. |
lAddressLen | The size of the user-allocated buffer pointed to by pAddress. |
pCity | A user-allocated buffer to store the city of the POI. |
lCityLen | The size of the user-allocated buffer pointed to by pCity. |
pJuris | A user-allocated buffer to store the jurisdiction of POI. |
lJurisLen | The size of the user-allocated buffer pointed to by pJuris. |
pZip | A user-allocated buffer to store the zip of the POI. |
lZipLen | The size of the user-allocated buffer pointed to by pZip. |
pState | A user-allocated buffer to store the country of the POI. |
lStateLen | The size of the user-allocated buffer pointed to by pState. |
rLatitude | Latitude of the stop (in millionths of a degree). Divide this number by 1,000,000 to obtain degrees Latitude. |
rLongitude | Longitude of the stop (in millionths of a degree). Divide this number by 1,000,000 to obtain degrees Longitude. |
pPhone | A user-allocated buffer to store the phone number. |
lPhoneLen | The size of the user-allocated buffer pointed to by pPhone. |
pMisc | A user-allocated buffer to store the miscellaneous information for this POI. |
lMiscLen | The size of the user-allocated buffer pointed to by pMisc. |
rCatID | Category ID |
rDist | Distance from the given lat/long, provided in Miles or KM based upon current CoPilot setting. |
Return Value
- 0 - Unable to find POIMsgID from the cache list
- -1 - Invalid index value
- 1 - Successful
Note: Declaration of this function has changed. If you are using an old reference, please update with the new one.
Msg_ClearPOIResults
Once the POI search is completed this API should be used to remove the cache results from the memory and stop searching POI.
Supported Since | Minimum Operating System |
---|---|
CoPilot 9.2.0 | Windows 10, Android 4.1 |
Syntax (Prototyped in alkmsg.h)
long Msg_ClearPOIResults (long lDestID = CONN_ID_NONE,
long lSrcID = CONN_ID_NONE);
Parameters
Parameter | Description |
---|---|
lDestID | Destination ID received in the callback function established for handling connection event change messages (this callback function is the first parameter passed to Msg_Startup call). Omit or set to CONN_ID_NONE when sending CoPilot control commands to same local machine. |
lSrcID | Unique ID of the sender of the message. Omit or set to CONN_ID_NONE when sending CoPilot control commands to same local machine. |
Return Value
Less than 0 = Failed to send message to CoPilot Equal to 0 = Unable to send message as SDK didn’t find connection Greater than 0 = Successful
lIdentifier
define Msg_ID_POISearch 0xf1000a03
Example
Msg_SetFavoritesStopInfo
It will set the given stop as a favorite based on given identifier (Home/Work/Others). It is recommend to pass all the stop details including latitude/longitude of the stop.
Supported Since | Minimum Operating System |
---|---|
CoPilot 9.2.0 | Windows 10, Android 4.1 |
Syntax (Prototyped in alkmsg.h)
long Msg_SetFavoritesStopInfo (long lCategoryID,
char *pName,
char *pAddress,
char *pCity,
char *pState,
char *pZip,
char *pJurisdiction,
long lLat, long lLon);
Parameters
Parameter | Description |
---|---|
lCategoryID | Type of the favorite category..(Home/Work/Others)..It is not possible to add Recent as a favorite |
pName | Name of the stop |
pAddress | Street Name |
pCity | City name |
pState | State abbreviation |
pZip | Valid 5-digit zip code (USA/Europe) or 4-7 digit full postcode (UK only) or 6 digit Netherlands postcode |
pJurisdiction | Jurisdiction |
lLat | Latitude, expressed as an integer value in millionths of a degree. |
lLon | Longitude, expressed as an integer value in millionths of a degree. |
//Identifiers for lCategoryID
define MSG_IDT_FAVORITES_HOME 0x0001L
define MSG_IDT_FAVORITES_WORK 0x0002L
define MSG_IDT_FAVORITES_OTHERS 0x0003L
Return Value
Less than or equal to 0 = Failed Greater than 0 = Successful
Note: CoPilot will send results by MSG_IDT_FAVORITES_SET_RESULT as part of MSG_ID_GenericData. Please check the MSG_IDT_FAVORITES_SET_RESULT for more details.
Msg_SendFavoritesStopRequest
Sends the request to CoPilot to to retrieve favorites. To be followed by Msg_FavoritesStopParse, Msg_FavoritesStopGetHeader, Msg_FavoritesStopGetDetails to retrieve favorite stop details.
Supported Since | Minimum Operating System |
---|---|
CoPilot 9.2.0 | Windows 10, Android 4.1 |
Syntax (Prototyped in alkmsg.h) long Msg_SendFavoritesStopRequest (long lIdentifier);
Parameters
Parameter | Description |
---|---|
lIdentifier | Type of favorite application want to retrieve from CoPilot. Please check the following valid identifier.e |
define MSG_ID_FavoritesSearch 0xf1000e01L
//Identifiers for MsgSendFavoritesStopRequest _define MSG_IDT_FAVORITES_HOME 0x0001L define MSG_IDT_FAVORITES_WORK 0x0002L define MSG_IDT_FAVORITES_OTHERS 0x0003L define MSG_IDT_FAVORITES_RECENT 0x0004L
Notes: In order to retrieve the requested favorite, you must have previously set a callback for the MSG_ID_FavoritesSearch message. This is done as follows:
Return Value Equal to or less than 0 = Failed Greater than 0 = Successful
Msg_FavoritesStopParse
This is the helper function to retrieve the favorite stops requested using Msg_SendFavoritesStopRequest. Returns the parser ID to be used with Msg_FavoritesStopGetHeader and Msg_FavoritesStopGetDetails.
Use Msg_ParserDelete to free the memory when finished with ParserID.
Supported Since | Minimum Operating System |
---|---|
CoPilot 9.2.0 | Windows 10, Android 4.1 |
Syntax (Prototyped in alkmsg.h)
long Msg_FavoritesStopParse (void *pBytes,
unsigned long bytes);
Parameters
Parameter | Description |
---|---|
pBytes | The message buffer passed by the system to the user-specified callback function, set by Msg_UpdateOptions(). |
bytes | The size of the message buffer in bytes, passed by the system to the user specified callback function, set by Msg_UpdateOptions(). |
Return Value <0 Unable to allocate message buffer ≥0 Successful, Returned Message ID needed for subsequent calls to
lIdentifier
define MSG_ID_FavoritesSearch 0xf1000e01L
Msg_FavoritesStopGetHeader
This is the helper function to retrieve the favorite stops requested using Msg_SendFavoritesStopRequest. Returns the header information including the number of stops and any error.
Supported Since | Minimum Operating System |
---|---|
CoPilot 9.2.0 | Windows 10, Android 4.1 |
Syntax (Prototyped in alkmsg.h)
long Msg_FavoritesStopGetHeader (unsigned long lFavoritesStopMsgID,
long & rError,
unsigned long &rStopCount)
Parameters
Parameter | Description |
---|---|
lFavoritesStopMsgID | Message buffer handle returned by Msg_FavoritesStopParse. |
rError | Not in use |
rStopCount | Number of stops in this message. |
Return Value
- 0 Error
- 1 Successful
Note: If rStopCount is less than 1 then favorite is not assigned. E.g if user is requesting for Home favorite and it is not assigned in CoPilot then user will get 0 stopcount.
Msg_FavoritesStopGetDetails
This is the helper function to retrieve the favorite stops requested using Msg_SendFavoritesStopRequest. Returns the individual stop details.
Supported Since | Minimum Operating System |
---|---|
CoPilot 9.2.0 | Windows 10, Android 4.1 |
Syntax (Prototyped in alkmsg.h)
long Msg_FavoritesStopGetDetails(unsigned long lFavoritesStopMsgId,
unsigned long lIndex,
char *pName,
unsigned long lNameLen,
char *pStreet,
unsigned long lStreetLen,
char *pCity,
unsigned long lCityLen,
char *pPostcode,
unsigned long lPostcodeLen,
char* pState,
unsigned long lStateLen,
char* pJuris,
unsigned long lJurisLen,
long &rLatitude,
long &rLongitude);
Parameters | Description |
---|---|
lFavoritesStopMsgId | Message buffer handle returned by Msg_FavoritesStopParse. |
lIndex | Index of the stop whose information is being retrieved. |
pName | A user-allocated buffer to store the name of the name of the favorite. |
lNameLen | The size of the user-allocated buffer pointed to by pName. |
pStreet | A user-allocated buffer to store the name of the street. |
lStreetLen | The size of the user-allocated buffer pointed to by pStreet. |
pCity | A user-allocated buffer to store the city of the current location. |
lCityLen | The size of the user-allocated buffer pointed to by pCity. |
pPostcode | A user-allocated buffer to store the state of the postcode. |
lPostcodeLen | The size of the user-allocated buffer pointed to by pPostCode. |
pState | A user-allocated buffer to store the zip code of the current location. |
lStateLen | The size of the user-allocated buffer pointed to by pState. |
pJuris | A user-allocated buffer to store the jurisdiction of the current location. |
lJurisLen | The size of the user-allocated buffer pointed to by pJuris. |
rLatitude | Latitude of the given stop. |
rLongitude | Longitude of the given stop. |
Return Value
- 0 Error
- 1 Successful
Msg_DrawImageAtCoordinates
Use this API call to dynamically add an Image Drawer category into CoPilot. This will draw a specified image at the lat/lons provided in the call. Please note the category provided will be created in isolation from any POI category that may be present on the device. For example, if you named a category ‘Fuel’, this Image Drawer Category would be completely independent from the POI category of the same name, ‘Fuel’. It is recommended that any Image Drawer Category should be given a different name from any of the POI categories present on the device.
Supported Since | Minimum Operating System |
---|---|
CoPilot 9.2.0 | Windows 10 |
Syntax (Prototyped in alkmsg.h)
long Msg_DrawImageAtCoordinates(char* pLatLong, char* pCategoryName, char* pImageName, bool bOverwrite)
Parameter
Parameter | Description | |||
---|---|---|---|---|
pLatLong | Series of lat/lons/IDs at which to draw the image. Note that the lat/lon/ID values should follow this format - The values should be multiplied by 1,000,000 | pipe character <br> - Each pair of lat/lons/IDs should be separated by a “,” comma <br> - Example: “42629813,-76179562,2 | 42628445,-76180578,3”<br> <p> **Note**: The ID field is option and lat/lon paris without the IS are supported. For example, "42629813, -76179562" is still a valid value for pLatLong` | |
pCategoryName | Name of the Image Drawer category. | |||
pImageName | The filename of the image to be drawn on the map. This should be a PNG file and should exist in the the CoPilot skin directory. If pImageName is empty then a default image is used instead. If the image does not exist but all other data is valid, then the category will still be created but no images will be displayed. | |||
bOverwrite | Indicates whether to overwrite a category if one already exists |
- true Overwrite the existing category with the new one.
- false Do not overwrite the existing category.|
Note: The ID field is optional and lat/lon pairs without the ID are supported. For example, “42629813,-76179562” is still a valid value for pLatLong.
Return Value
- -1 or less than 0 = Error
- Greater than 0 Successful in sending the request to CoPilot.
Notes
- When using this API CoPilot will respond with a result using the MSG_ID_GenericInformation callback with identifier MSG_IDT_IMAGE_DRAWER. For further information, please read the documentation for MSG_ID_GenericInformation in detail.
- All latitude and longitude values are sent as long integers. These values are encoded as millionths of a degree. North and East are positive values, South and West are negative values. For example, the Trimble Maps London office is located at 0.122805W & 51.518220N so the longitude value should be passed as -122805 and the latitude value should be passed as 51518220.
- The images that are drawn on the maps are slightly different to those used for POIs. As such, the user can not click on the image to get information and drive to that location, neither can they search for an image like the can when searching for a POI.
- The image file should be placed inside \skin\user folder so the API will be able to integrate the image.
- Images that are drawn on the maps are removed on CoPilot exit. So user needs to call this API again if CoPilot is relaunched.
- CoPilot displays 24-bit 44x44 icons correctly, but if they are of different size, CoPilot will size the icon appropriately to fit. If the images are too large, CoPilot will not display images properly.
Msg_DeleteAllCategory
This API can be used to delete all of the user defined Image Drawer categories that have been added into CoPilot.
Supported Since | Minimum Operating System |
---|---|
CoPilot 9.2.0 | Windows 10 |
Syntax (Prototyped in alkmsg.h)
long Msg_DeleteAllCategory()
Return Value -1 or less than 0 = Error. Greater than 0 = Successful in sending the request to CoPilot.
Note: When using this API CoPilot will respond with a result using the MSG_ID_GenericInformation callback with identifier MSG_IDT_IMAGE_DRAWER. For further information, please read the documentation for MSG_ID_GenericInformation in detail.
Msg_DeleteCategory
Deletes a user defined Image Drawer category matching the specified category. This will delete the Image Drawer category and all of the lat/long’s associated with it.
Supported Since | Minimum Operating System |
---|---|
CoPilot 9.2.0 | Windows 10 |
Syntax (Prototyped in alkmsg.h)
long Msg_DeleteCategory(char* pCategoryName)
Parameter
Parameter | Description |
---|---|
pCategoryName | A user defined name for the Image Category. A blank, null or invalid category name will not do anything. |
Return Value -1 or less than 0 = Error Greater than 0 = Successful in sending the request to CoPilot.
Note: When using this API CoPilot will respond with a result using the MSG_ID_GenericInformation callback with identifier MSG_IDT_IMAGE_DRAWER. For further information, please read the documentation for MSG_ID_GenericInformation in detail.
Msg_AddMapImageClickedHandler
This API is used to set callback to receive notifications when an image that was previously drawn using Msg_DrawImageAtCoordinates is touched by the user.
Supported Since | Minimum Operating System |
---|---|
CoPilot 9.6 | Windows 10 |
Syntax (Prototyped in alkmsg.h) int Msg_AddMapImageClickedHandler(delMapImageTouchedCB pCallback, Msg.callingConvention convention);
Parameter
Parameter | Description |
---|---|
pCallback | All back function of the following type: |
convention | Calling convention – Managed Apps should use convention_stdcall C |
Return Value
- -1 = (Signifies that there was an error)
- 0 = or any positive value (Signifies that value is set successfully)
MsgMapImageTouchedCB
Function definition of the callback function when setting a callback using Msg_AddMapImageClickedHandler.
Supported Since | Minimum Operating System |
---|---|
CoPilot 9.6 | Windows 10 |
Syntax (Prototyped in alkmsg.h)
void MapImageTouchedCB(int imageID, int latitude, int longitude);
Parameter
Parameter | Description |
---|---|
imageID | The image ID assigned to the image that was touched. This is an optional parameter when adding coordinates using Msg_DrawImageAtCoordinates. If no ID was supplied for this point when using Msg_DrawImageAtCoordinates, then the value will be -1. |
latitude | Latitude of the coordinate of the image that was touched. This is a required parameter when adding coordinates using Msg_DrawImageAtCoordinates. |
Longitude | Longitude of the coordinate of the image that was touched. This is a required parameter when adding coordinates using Msg_DrawImageAtCoordinates. |
Related API’s
- Msg_AddMapImageClickedHandler
- Msg_DrawImageAtCoordinates