mergCL

mergCL is an iOS external for LiveCode that implements significant location change and region monitoring. Both of these services from the CoreLocation framework will start your app in the background if it's not running when the location event occurs. For this external to function reliably the exits on suspend key of the apps plist must be removed.

Documentation

command mergCLStartLocationManager pPurpose,[pAuthorizationType]

Start the location manager. This should be done at startup or preOpenStack from the script of the object you would like to handle to mergCL messages. If the app is started by iOS because of a location event then it will be in the background and only have a limited time to handle the event before being suspended again. If your app requires user attention send a local notification which will bring your app to the foreground if the user touches the banner.

Parameters:

  • pPurpose - If the user needs to authorize location services for the app then this purpose will be displayed.
  • pAuthorizationType - (optional with "always" default) iOS 8 requires an explicit call to authorize use of location services wither always on or just when the app is in use. One of:
    • always
    • in use

message mergCLAuthorizationChanged pStatus

This message is sent to the object that started the location manager when the authorization status of location services changes.

Parameters:

  • pStatus - Locations services authorization status. One of:|authorized|denied|not determined|restricted

Region Monotoring

function mergCLIsRegionMonitoringAvailable

Returns boolean

command mergCLStartMonitoringRegion pIdentifier,pLocation,pRadius,pDesiredAccuracy

Parameters:

  • pIdentifier - a unique identifier for a region. Using the same identifier twice will replace the first region.
  • pLocation - center lattitude,longitude in decimal form
  • pRadius - region radius in metres
  • pDesiredAccuracy - the desired accuracty of the coordinate in metres

message mergCLRegionEntered pIdentifier,pLocation,pRadius

This message is sent to the object that started the location manager when a monitored region is entered.

Parameters:

  • pIdentifier - The region identifier
  • pLocation - center lattitude,longitude in decimal form
  • pRadius - region radius in metres

message mergCLRegionExited pIdentifier,pLocation,pRadius

This message is sent to the object that started the location manager when a monitored region is exited.

Parameters:

  • pIdentifier - The region identifier
  • pLocation - center lattitude,longitude in decimal form
  • pRadius - region radius in metres

message mergCLRegionMonitoringFailed pIdentifier,pLocation,pRadius,pError

This message is sent to the object that started the location manager when region monitoring fails for a specific region.

Parameters:

  • pIdentifier - The region identifier
  • pLocation - center lattitude,longitude in decimal form
  • pRadius - region radius in metres
  • pError - an error description

function mergCLMaximumRegionMonitoringDistance

Returns real

function mergCLMonitoredRegions

Returns objc-string

command mergCLStopMonitoringRegion pIdentifier

Parameters:

  • pIdentifier - a unique identifier for a region. Using the same identifier twice will replace the first region.

function mergCLCoordinateWithin pTestCoordinate,pCenterCoordinate,pRadius

Returns boolean

command mergCLRequestRegionStatus pRegionIdentifier

This command requests the core location framework determine if the user is inside or outside the region

Parameters:

  • pRegionIdentifier -

iBeacons

command mergCLStartMonitoringBeaconRegion pIdentifier,pProximityUUID,pMajor,pMinor

Parameters:

  • pIdentifier - a unique identifier for a region. Using the same identifier twice will replace the first region.
  • pProximityUUID - a UUID for the region
  • pMajor - value identifying a group of beacons
  • pMinor - value identifying a specific beacon in a group

message mergCLBeaconRegionEntered pIdentifier,pProximityUUID,pMajor,pMinor

This message is sent to the object that started the location manager when a monitored region is entered.

Parameters:

  • pIdentifier - The region identifier
  • pProximityUUID - a UUID for the region
  • pMajor - value identifying a group of beacons
  • pMinor - value identifying a specific beacon in a group

message mergCLBeaconRegionExited pIdentifier,pProximityUUID,pMajor,pMinor

This message is sent to the object that started the location manager when a monitored region is exited.

Parameters:

  • pIdentifier - The region identifier
  • pProximityUUID - a UUID for the region
  • pMajor - value identifying a group of beacons
  • pMinor - value identifying a specific beacon in a group

message mergCLBeaconRegionMonitoringFailedForRegion pIdentifier,pProximityUUID,pMajor,pMinor,pError

This message is sent to the object that started the location manager when region monitoring fails for a specific region.

Parameters:

  • pIdentifier - The region identifier
  • pProximityUUID - a UUID for the region
  • pMajor - value identifying a group of beacons
  • pMinor - value identifying a specific beacon in a group
  • pError - an error description

function mergCLIsBeaconRegionMonitoringAvailable

Returns boolean

function mergCLIsBeaconRegionRangingAvailable

Returns boolean

command mergCLStartRangingBeaconsInRegion pIdentifier,pProximityUUID,[pMajor],[pMinor]

Parameters:

  • pIdentifier - a unique identifier for a region. Using the same identifier twice will replace the first region.
  • pProximityUUID - a UUID for the region
  • pMajor - (optional with -1 default) value identifying a group of beacons
  • pMinor - (optional with -1 default) value identifying a specific beacon in a group

message mergCLDidRangeBeacons pRangedBeacons

This message is sent to the object that started the location manager when beacons are ranged.

Parameters:

  • pRangedBeacons - A tab-delimited list with each line representing a beacon and items in the following order UUID, major, minor, RSSI, proximity, accuracy. Proximity will be one of immediate, near, far or unknown.

function mergCLMonitoredBeaconRegions

Returns objc-string

function mergCLRangedBeaconRegions

Returns objc-string

command mergCLStopRangingBeaconsInRegion pIdentifier

Parameters:

  • pIdentifier - a unique identifier for a region. Using the same identifier twice will replace the first region.

command mergCLRequestBeaconRegionStatus pRegionIdentifier

This command requests the core location framework determine if the user is inside or outside the region

Parameters:

  • pRegionIdentifier -

command mergCLBroadcastBeacon pIdentifier,pProximityUUID,pMajor,pMinor

Parameters:

  • pIdentifier - a unique identifier for a region. Using the same identifier twice will replace the first region.
  • pProximityUUID - a UUID for the region
  • pMajor - value identifying a group of beacons
  • pMinor - value identifying a specific beacon in a group

Significant Change Monotoring

function mergCLSignificantLocationChangeMonitoringAvailable

Returns boolean

command mergCLStartMonitoringSignificantLocationChanges

message mergCLLocationChanged pLocation

This message is sent to the object that started the location manager when the device location significantly changes.

Parameters:

  • pLocation - center lattitude,longitude in decimal form

command mergCLStopMonitoringSignificantLocationChanges

Visits (iOS 8)

command mergCLStartMonitoringVisits

Recieve the mergCLVisit message when a the system detects a new visit related event. If your app is terminated while monitoring visits it will be relaunched in th beackground to handle new visit events.

message mergCLVisit pLocation,pArrivalDate,pDepartureDate

This message is sent to the object that started the location manager when a visit event is detected.

Parameters:

  • pLocation - center lattitude,longitude in decimal form
  • pArrivalDate - The approximate time at which the user arrived at the specified location in seconds. This parameter may be empty.
  • pDepartureDate - The approximate time at which the user left the specified location in seconds. This parameter may be empty.

command mergCLStopMonitoringVisits

Stop monitoring vor visit events

Geocoding

command mergCLGeocode pAddressString

Request the placemarks found when searching for the address string. The mergCLGeocodeResult message is sent back to the control that called mergCLGeocode

Parameters:

  • pAddressString - An address string eg. 1 Infinite Loop, Cupertino

message mergCLGeocodeResult pResult

This message is sent to the object that called mergCLGeocode when the query returns from the server

Parameters:

  • pResult - A multi-dimensional array with keys detailing the address and coordinate for each placemark.

command mergCLReverseGeocode pCoordinate

Request the placemarks found when searching for the location. The mergCLGeocodeResult message is sent back to the control that called mergCLGeocode

Parameters:

  • pCoordinate - the location to test in lattitude,longitude in decimal form

message mergCLGeocodeResult pResult

This message is sent to the object that called mergCLGeocode when the query returns from the server

Parameters:

  • pResult - A multi-dimensional array with keys detailing the address and coordinate for each placemark.

function mergCLDistanceBetween pCoordinateFrom,pCoordinateTo

Calculate the distance between to coordinates taking into account the curvature of the earth

Returns real