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