Geofence

Msg_ImportPolygonSet

This API is used to import Polygon Sets from an XML file. See note 2 for an example input file and note 3 for a description of the fields available for these objects.

Syntax (Prototyped in alkmsg.h)

long Msg_ImportPolygonSet(char* data)

Parameters

Return Values

• ≤ 0 - Error

• 0 - Successful in sending the request to CoPilot.

Note

• Once sent a Msg_ImportPolygonSet request, CoPilot will respond with the result via Msg_ID_GenericInformation (identifier Msg_IDT_IMPORTPOLYGONSET_RESULT). For further information, please read the Msg_ID_GenericInformation.

• The following is an example XML input file:

<importPolygonSet>
  <ArrayOfMapObjects Name="SampleSet1" Persistent="1" NotificationEvent="3" UINotification="1" RouteThroughEvent="1" NotifySDKOnEnterExit="both" NotifySDKOnRouteThrough="1" NotifyUIWhileInside="1" AvoidPolygon="0" BeepOnEnterExit="1" DrawBelowRoads="0">
    <MapObject Type="Polygon" InnerColor="0xb0345678" Label="Central London Geofence"  OuterColor="0x00ff0000" Order="0" Name="PolygonA">
      <Point lat="51.526229 " lon="-0.100130"/>
      <Point lat="51.524200" lon="-0.115837"/>
      <Point lat="51.517898" lon="-0.111374"/>
      <Point lat="51.517663" lon="-0.096817"/>
    </MapObject>
    <MapObject Type="Polygon"  InnerColor="0xaa9999ff" Label="Tottenham Geofence"  OuterColor="0x00ff00ff" Order="0" Name="PolygonB">
      <Point lat="51.609361" lon="-0.110413"/>
      <Point lat="51.609361" lon="-0.040031"/>
      <Point lat="51.580995" lon="-0.040031"/>
      <Point lat="51.580995" lon="-0.110413"/>
    </MapObject>
  </ArrayOfMapObjects>
</importPolygonSet>

Note 3

Polygons imported via this API are grouped into polygon sets. The sets have the following available fields:

Name – A name for the polygon set. If no name is given, this set will become part of the set “Default_Set_NonPersistent”. If the set name already exists, it will be overwritten with the information from the new set.

Persistent – “1” or “0”. If 1, the set and its polygons will be saved when the program is closed. If 0, the set and its polygons will be lost when the program is closed.

NotificationEvent - “0”, “1”, “2” or “3”. If 0, there will be no notification events sent for any polygons in this set. If 1, a notification event will be sent when the current position enters any polygon in this set. If 2, a notification event will be sent when the current position leaves any polygon in this set. If 3, a notification event will be sent when the current position enters or leaves any polygon in this set. For more information, see Msg_ID_GeofenceEvent

UINotification – “0” or “1”. If 1, a UI indicator will display on the screen whenever the users location is within the bounds of any polygons belonging to this set. If 0, no notification will be shown for any polygons within this set.

RouteThroughEvent = “0” or “1”. If 1, and a new route is created which passes through any polygons who belong to a set in which this property is set to 1, a message is sent which contains the list of all of the polygons with this [property set through which the route passes. See Msg_ID_GeofenceRoutingEvent

Beep – “0” or “1”. If this property is set to 1, an audible beep will sound when the user enters or leaves any polygons within this set. If 0, there will be no audible beep.

The polygons within these sets have the following fields:

Type – “Polygon”, “Line”, “Circle”, or “Rectangle”. Lines, circles and rectangles must have exactly 2 points. Polygons must have 3 or more points. Circles are defined by the largest drawable circle within the rectangle provided by the 2 points. Rectangles are defined by the corners, which are provided as the 2 points. InnerColor – The inner color of the polygon, in the format 0xAARRGGBB. Alpha values of zero will result in no fill for the polygon. OuterColor – The border color for the polygon in 0xAARRGGBB format. Alpha values of zero will result in no border being drawn, the equivalent to a border width of zero. Label – A text label that is drawn on the map along with the polygon. Order – “0” or “1”. A value of 0 draws the polygon under the road network on the map, while a value of 1 draws the polygon on top of the road network. Name – A name to refer to the polygon within the set BorderWidth – The width of the border drawn around the polygon

Msg_DeletePolygons

This API is used to delete polygons. It can delete all polygons, a specific polygon set, or a specific polygon or polygons within a specific set.

Syntax (Prototyped in alkmsg.h)

long Msg_DeletePolygons(char* polygonset, char* polygonlist)

Parameters

Return Values

• ≤ 0 - Error

• 0 - Successful in sending the request to CoPilot.

Note

Once receiving a request to delete the specified polygons, CoPilot will respond via Msg_ID_GenericInformation (identifier Msg_IDT_DELETEPOLYGONSET_RESULT) with the result. For further information, please read the Msg_ID_GenericInformation in detail.

Msg_SetPolygonSetProperty

This API is used to set a value of a polygon set after it has been imported.

Syntax (Prototyped in alkmsg.h)

long Msg_SetPolygonSetProperty(char* setName,char* propertyName,char* value)

Parameters

Return Values

• ≤ 0 - Error

• 0 - Successful in sending the request to CoPilot.

Note 1

Once sent a Msg_ImportPolygonSet request, CoPilot will respond with the result via Msg_ID_GenericInformation (identifier Msg_IDT_SETPOLYGONSETPROPERTY_RESULT). For further information, please read the Msg_ID_GenericInformation.

Msg_SetPolygonProperty

This API is used to set a value of a polygon after it has been imported.

Syntax (Prototyped in alkmsg.h)

long Msg_SetPolygonSetProperty(char* setName, char* objectName, char* propertyName, char* value)

Parameters

Return Values

• ≤ 0 - Error

• 0 - Successful in sending the request to CoPilot. |

Note 1

Once sent a Msg_ImportPolygonSet request, CoPilot will respond with the result via Msg_ID_GenericInformation (identifier Msg_IDT_SETPOLYGONPROPERTY_RESULT). For further information, please read the Msg_ID_GenericInformation.

Msg_GetPolygonSetProperty

This API is used to get a value of a property of a polygon set after it has been imported.

Syntax (Prototyped in alkmsg.h)

long Msg_GetPolygonSetProperty (char* setName, char* propertyName)

Parameters

Return Values

• ≤ 0 - Error

• 0 - Successful in sending the request to CoPilot.

Note 1

Once sent a Msg_ImportPolygonSet request, CoPilot will respond with the result via Msg_ID_GenericInformation (identifier Msg_IDT_GETPOLYGONSETPROPERTY_RESULT). For further information, please read the Msg_ID_GenericInformation.

Msg_GetPolygonProperty

This API is used to get a value of a property of a polygon after it has been imported.

Syntax (Prototyped in alkmsg.h)

long Msg_GetPolygonSetProperty (char* setName, char* objectName, char*
propertyName)

Parameters

Return Values

• ≤ 0 - Error

• 0 - Successful in sending the request to CoPilot.

Note 1

Once sent a Msg_ImportPolygonSet request, CoPilot will respond with the result via Msg_ID_GenericInformation (identifier Msg_IDT_GETPOLYGONPROPERTY_RESULT). For further information, please read the Msg_ID_GenericInformation.

Msg_GetGeofenceEventInfo

Decode and retrieve the information contained in a message buffer received through a subscription to Msg_ID_GeofenceEvent. These events occur when the users current position enters or leaves a geofence containing flags to send messages.

Syntax (Prototyped in alkmsg.h)

long Msg_GetGeofenceEventInfo(const void *pBuffer, unsigned long lBufLen, char
*pGeofenceSetName, unsigned long lGeofenceSetNameLen, char *pGeofenceName,
unsigned long lGeofenceNameLen, long &lTime, long &lDate,long &lLon, long &lLat,
char *pEventType, unsigned long lEventTypeLen)
{};

Parameters

Return Values

• ≤ 0 - Failed

• 0 - Successful

Example

Msg.Msg_Subscribe(Msg.MSG_ID_GeofenceEvent, -1, -1);
Msg.Msg_Updateoptions(Msg.MSG_ID_GeofenceEvent, true, false, delOnGeofenceEvent, Msg.callingConvention.convention_stdcall;

private void OnGeofenceEvent (uint pData, uint bytes)
{
  byte[] GeofenceSetName = new byte[100];
  byte[] GeofenceName = new byte[100];
  int time = 0;
  int date = 0:
  int lat = 0;
  int lon = 0;
  byte[] EventType = new byte[100];

  Msg.Msg_GetGeofenceEventInfo((uintjpData, (uintjbytes,
                                GeofenceSetName, 100,
                                GeofenceName, 100,
                                out time,
                                out date,
                                out lat,
                                out lon,
                                EventType, 100];

  String geofenceName = (Encoding.Default.GetString(GeofenceName, 0, GeofenceName.Length).ToString()).Trim('\0');
  String geofenceSetName = (Encoding.Default.GetString(GeofenceSetName, 0, GeofenceSetName.Length).ToString()).Trim('\0');
  String eventText = (Encoding.Default.GetString(EventType, 0, EventType.Length).ToString()).Trim('\0');
}

Identifier

#define    MSG_ID_GeofenceEvent

Msg_GetGeofenceRoutingEventInfo

Decode and retrieve the information contained in a message buffer received through a subscription to Msg_ID_GeofenceRoutingEvent. This event is triggered when a new route is created which passes through any geofences with the “RouteThroughEvent” property set.

Syntax (Prototyped in alkmsg.h)

long Msg_GetGeofenceRoutingInfo(const void *pBuffer, unsigned long lBufLen,
char *pGeofenceList, unsigned long lListLen)

Parameters

Return Values

• ≤ 0 - Failed

• 0 - Successful

Example

Msg.Msg_Subscribe(Meg.H3G_ID_GeofenceRoutingEvent, -1, -1):
Msg.Msg_Updateoption3(Meg.H3G_ID_GeofenceRoutingEvent, true, false, delOnGeofenceRoutingEvent, Msg.callingConvention.convention_stdcall);

private void OnGeofenceRoutingEvent(uint pData, uint bytes]
{
    byte[] GeofenceList = new byte[100];

    Msg.Msg_GetGeofenceRoutingInfo((uint)pData, (uint)bytes,
                                 GeofenceList, 100):

    String geofenceList = (Encoding.Default.GetString(GeofenceList, 0, GeofenceList.Length).ToString()).Trim('\0');
}