POI Integration

Msg_IntegrateCustomPOI

This API is used to draw custom POIs in JSON format on the map.

Syntax (Prototyped in alkmsg.h)

long Msg_IntegrateCustomPOI(const char* pJson);

alkmsg.cs
  public static extern int Msg_IntegrateCustomPOI (byte[] json);

Parameters

JSON Example

[
  {
    "Name": "my set name",
    "Persist": false,
    "Replace": true,
    "Categories": [
      {
        "Name": "Custom Fuel",
        "MaxZoomLevel": 4,
        "Options": 21
      },
      {
        "Name": "Custom Restaurant",
        "MaxZoomLevel": 4,
        "Options": 21
      }
    ],
    "Places": [
      {
        "Address": {
          "StreetAddress": "14807 Crain Hwy",
          "City": "Clinton",
          "Zip": "20735",
          "State": "MD",
          "County": null
        },
        "Coords": {
          "Lat": "38.6825",
          "Lon": "-76.87278"
        },
        "PlaceName": "My Restaurant",
        "CategoryName": "Custom Restaurant",
        "Phone": ""
      },
      {
        "Address": {
          "StreetAddress": "1720 Route 309",
          "City": "Coopersburg",
          "Zip": "18036",
          "State": "PA",
          "County": null
        },
        "Coords": {
          "Lat": "40.50306",
          "Lon": "-75.38667"
        },
        "PlaceName": "My Fuel Stop",
        "CategoryName": "Custom Fuel",
        "Info": "",
        "Phone": ""
      }
    ]
  }
]

Return Values

To receive return codes the 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_IMPORTPOISET_RESULT, the return values are the payload for that callback.

Return Codes

POI JSON field description

The JSON schema is defined below. All fields not marked as Optional are required.

• Set - (array)
  • Name - (string) - The unique set name; not visible anywhere in CoPilot, used for organizational purposes.
  • Persist - (bool) Whether the place set and all its data will be serialized to disk and persist through a restart of the CoPilot application. Setting this to false will keep the set in-memory only, and significantly improve the performance of this API by eliminating disk I/O.
  • Replace - (bool) Whether an existing set with this name will be replaced (all places will be deleted before adding the new places) or whether the new places will be appended to the current set.
  • Deleted - (bool) Will delete a current set with the same name.
  • Categories - (array)
    • Name - (string) The name of the POI category. Visible in CoPilot in the POI Search dialog as long as at least one place mapped to this category exists on the device.
    • Icon - (string; optional) The name of the alk place category icon that will be used when display this category. If this value is not provided, CoPilot will search user provided images for one with the category name.
    • MaxZoomLevel - (integer) The maximum zoom level that POIs of this category will be visible on the map. Range is 0 (zoomed in to a very small portion of the map) to 7 (zoomed out to a much larger portion of the map.)
    • Options - (integer) Bitwise OR of three possible values. Use 21 to enable all options.
      • 1 - Display on Map
      • 4 - Searchable Whether this category appears in the POI search dialog
      • 16 - Alertable Whether this category appears in the POI alert settings
  • Places - (array)
    • Address - (object) Displayed when viewing the POI
      • StreetAddress - (string; optional; 128 char max)
      • City - (string; optional; 128 char max)
      • Zip - (string; optional; 16 char max)
      • State - (string; optional; 4 char max) State (US) or Country (EU) abbreviation
      • County - (string; optional; 64 char max)
    • Coords - (object) Used to draw the POI on the map, and when routing to the POI
      • Lat - (string) decimal degrees, positive for North, negative for South
      • Lon - (string) decimal degrees, positive for East, negative for West
    • CategoryName - (string) Assigns this POI to a category (category name must exist in the category array described above for this set).
    • PlaceName - (string; 128 char max); Displayed when viewing the POI.
    • Phone - (string; optional; 64 char max) Displayed when viewing the POI.

Msg_ImportPOISet

This API is used to send xml files that contain POI set details to import into CocPilot using Msg_SendGenericTextData API

Syntax (Prototyped in alkmsg.h)

int Msg_ImportPOISet(int setid, char* data, int strlength);

Parameters

Return Value

• Equal to or less than 0 - Failed
• Greater than 0 - Successful

Sample Code

private void importPOISet(File fileName){
  try {
    String content = new Scanner(fileName).useDelimiter("\\Z").next();
    //content = readFile(fileName);
    //content = content.replace('"','\"' );
    AlkMsg.Msg_ImportPOISet(0, content, content.length());
  }catch (Exception e){
    e.printStackTrace();
  }
}

private void buttonImportPOI_Click(object sender, EventArgs e)
{
  string inputFileName;
  OpenFileDialog openFileDialog = new OpenFileDialog();
  openFileDialog.InitialDirectory = Path.GetDirectoryName(System.Reflection.Assembly.GetExecutingAssembly().ManifestModule.FullyQualifiedName);
  if (openFileDialog.ShowDialog() != DialogResult.OK)
  return;
  inputFileName = openFileDialog.FileName;
  using (BinaryReader br = new BinaryReader(File.Open(inputFileName, FileMode.Open)))
  {
    long length = br.BaseStream.Length;
    byte[] data = new byte[length];
    br.Read(data, 0, (int)length);
    Msg.Msg_ImportPOISet(0, data, (int)length);
  }
}

Msg_DeletePOISet

This API is used to delete POI set. This API is used to send xml file contains POI set details to be deleting using Msg_SendGenericTextData API.

Syntax (Prototyped in alkmsg.h)

int Msg_DeletePOISet(char* data, int strlength);

Parameters

Return Value

• Equal to or less than 0 - Failed
• Greater than 0 - Successful

Sample Code

private void onDeletePOI(){
  EditText txtDeletePOISetName = (EditText) findViewById(R.id.txtDeletePOISetName);
  String strPoiSet = txtDeletePOISetName.getText().toString();
  if(strPoiSet.isEmpty()){
    toastMessage("Please enter the POI Name to delete");
    return;
  }
  AlkMsg.Msg_DeletePOISet(strPoiSet, strPoiSet.length());
}

private void buttonDeletePOI_Click(object sender, EventArgs e)
{
  Msg.Msg_DeletePOISet(Util.ConvertString(textBoxSet.Text), textBoxSet.Text.Length);
}