Skip to content

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 Since Minimum Operating System
CoPilot 9.6.0 Windows 10

Syntax (Prototyped in alkmsg.h)

long Msg_ImportPolygonSet(char* data)

Parameters

Parameter Description
data The data from the input XML document

Return Values

  • ≤ 0 - Error
  • > 0 - Successful in sending the request to CoPilot.

Related APIs

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 Since Minimum Operating System
CoPilot 9.6.0 Windows 10

Syntax (Prototyped in alkmsg.h)

long Msg_DeletePolygons(char* polygonset, char* polygonlist)

Parameters

Parameter Description
polygonset The name of the polygon set to delete. If this value and polygonlist are both NULL, all polygons are deleted.
polygonlist A 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.

Related APIs

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 Since Minimum Operating System
CoPilot 9.6.0 Windows 10

Syntax (Prototyped in alkmsg.h)

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

Parameters

Parameter Description
setName The name of the polygon set for which the property is to be changed
propertyName The name of the property which is to be changed
value The 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 Since Minimum Operating System
CoPilot 9.6.0 Windows 10

Syntax (Prototyped in alkmsg.h)

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

Parameters

Parameter Description
setName The name of the polygon set to which the polygon belongs
objectName The name of the polygon for which the specified property is to be changed
propertyName The name of the property which is to be set
value The 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 Since Minimum Operating System
CoPilot 9.6.0 Windows 10

Syntax (Prototyped in alkmsg.h)

long Msg_GetPolygonSetProperty (char* setName, char* propertyName)

Parameters

Parameter Description
setName The Polygon Set name for which the property is desired
propertyName The 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 Since Minimum Operating System
CoPilot 9.6.0 Windows 10

Syntax (Prototyped in alkmsg.h)

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

Parameters

Parameter Description
setName The Polygon Set name to which the desired polygon belongs
objectName The name of the object for which the property value is desired
propertyName The 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 Since Minimum Operating System
CoPilot 9.6.0 Windows 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

Parameter Description
pBuffer The message buffer
lBufLen The message buffer length
pGeofenceSetName The name of the set to which the geofence belongs
lGeofenceSetNameLen The length of the geofence set name
pGeofenceName The name of the geofence
lGeofenceNameLen The length of the geofence name
lTime The time at which the event occurred
lDate The date when which the event occurred
lLon The longitude of the entry/exit point
lLat The latitude of the entry/exit point
pEventType Wether the event was an “entry” or “exit”
lEventTypeLen The 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 Since Minimum Operating System
CoPilot 9.6.0 Windows 10

Syntax (Prototyped in alkmsg.h)

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

Parameters

Parameter Description
pBuffer The message buffer
lBufLen The message buffer length
pGeofenceList A comma separated list of the geofences through which the current route passes
lListLen The 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 update: November 6, 2019