Skip to main content

Geocoding

Contents

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

code


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

code


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
- Each lat/lon pair should be delimited by a `

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 forpLatLong`
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

  1. 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.
  2. 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.
  3. 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.
  4. The image file should be placed inside \skin\user folder so the API will be able to integrate the image.
  5. Images that are drawn on the maps are removed on CoPilot exit. So user needs to call this API again if CoPilot is relaunched.
  6. 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:

void MapImageTouchedCB(int imageID, int latitude, int longitude); convention

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
Last updated January 10, 2024.