Skip to main content

Geofence

Contents

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.

Supported SinceMinimum Operating System
CoPilot 9.6.0Windows 10

Syntax (Prototyped in alkmsg.h)

long Msg_ImportPolygonSet(char* data)

Parameters

ParameterDescription
dataThe data from the input XML document

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.

Supported SinceMinimum Operating System
CoPilot 9.6.0Windows 10

Syntax (Prototyped in alkmsg.h)

long Msg_DeletePolygons(char* polygonset, char* polygonlist)

Parameters

ParameterDescription
polygonsetThe name of the polygon set to delete. If this value and polygonlist are both NULL, all polygons are deleted.
polygonlistA list of polygons to be deleted, separated by commas. If this value and polygonset are both NULL, all of the polygons are deleted. If this value is NULL, but there is a set name in polygonset, the polygon set and all of its polygons will be deleted

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.

Supported SinceMinimum Operating System
CoPilot 9.6.0Windows 10

Syntax (Prototyped in alkmsg.h)

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

Parameters

ParameterDescription
setNameThe name of the polygon set for which the property is to be changed
propertyNameThe name of the property which is to be changed
valueThe value to which this property should be set

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.

Supported SinceMinimum Operating System
CoPilot 9.6.0Windows 10

Syntax (Prototyped in alkmsg.h)

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

Parameters

ParameterDescription
setNameThe name of the polygon set to which the polygon belongs
objectNameThe name of the polygon for which the specified property is to be changed
propertyNameThe name of the property which is to be set
valueThe value to which this property should be set

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.

Supported SinceMinimum Operating System
CoPilot 9.6.0Windows 10

Syntax (Prototyped in alkmsg.h)

long Msg_GetPolygonSetProperty (char* setName, char* propertyName)

Parameters

ParameterDescription
setNameThe Polygon Set name for which the property is desired
propertyNameThe property name which is desired

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.

Supported SinceMinimum Operating System
CoPilot 9.6.0Windows 10

Syntax (Prototyped in alkmsg.h)

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

Parameters

ParameterDescription
setNameThe Polygon Set name to which the desired polygon belongs
objectNameThe name of the object for which the property value is desired
propertyNameThe property name which is desired

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.

Supported SinceMinimum Operating System
CoPilot 9.6.0Windows 10

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

ParameterDescription
pBufferThe message buffer
lBufLenThe message buffer length
pGeofenceSetNameThe name of the set to which the geofence belongs
lGeofenceSetNameLenThe length of the geofence set name
pGeofenceNameThe name of the geofence
lGeofenceNameLenThe length of the geofence name
lTimeThe time at which the event occurred
lDateThe date when which the event occurred
lLonThe longitude of the entry/exit point
lLatThe latitude of the entry/exit point
pEventTypeWether the event was an “entry” or “exit”
lEventTypeLenThe length of the event

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.

Supported SinceMinimum Operating System
CoPilot 9.6.0Windows 10

Syntax (Prototyped in alkmsg.h)

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

Parameters

ParameterDescription
pBufferThe message buffer
lBufLenThe message buffer length
pGeofenceListA comma separated list of the geofences through which the current route passes
lListLenThe length of the geofence list

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');
}
Last updated October 19, 2022.