Name: mobileSetLocationHistoryLimit

Type: command

Syntax: mobileSetLocationHistoryLimit <historyLimit>

Summary:
Set the number of location changes to be retained

Introduced: 8.1

OS: ios, android

Platforms: mobile

Example:
-- retain all between calls to mobileGetLocationHistory()
mobileSetLocationHistoryLimit 0

Example:
-- retain the most recent 10 locations
mobileSetLocationHistoryLimit 10

Parameters:
historyLimit (integer):
The number of entries to retain from system
<locationChanged> events. The default history limit is 1 - meaning that 
only one sample is ever kept at a time. If an application wants 
historical access to all samples, then it should set the location 
history limit to the maximum number of samples it ever wants to record, 
or 0 to record the entire history (between calls to 
<mobileGetLocationHistory>).

Description:
System <locationChanged> events may occur more frequently than the
<locationChanged> message is sent because messages that were unable to
be sent as a result of other scripts executing are filtered when a new 
system <locationChanged> event occurs. 

Whenever a system <locationChanged> event occurs, the location reading
is pushed onto the front of a list. The list is capped at the length
set by <mobileSetLocationHistoryLimit>, dropping any old samples over 
this length.

The <mobileGetLocationHistory> <function> returns a numerically keyed
<array> of all accumulated samples since the last time it was called
with lower indices being older samples. Calling the function clears
the internal history.

Each <element> in the <array> is the same format as the detailed 
location <array> as returned from the <mobileSensorReading> 
<function>.

The best way to use the history is to fetch the list in 
<locationChanged> and process each sample in turn, rather than the 
sample provided with the <locationChanged> event (which will always be 
the last sample in the history). e.g.

    on locationChanged
        local tHistory
        put mobileGetLocationHistory() into tHistory
        repeat for each element tSample in tHistory
            processLocationChanged tSample
        end repeat
    end locationChanged


References: mobileStopTrackingSensor (command),
mobileStartTrackingSensor (command),
mobileGetLocationHistory (function),
mobileGetLocationHistoryLimit (function),
mobileSensorAvailable (function), mobileSensorReading (function),
mobileLocationAuthorizationStatus (function), function (glossary),
locationChanged (message), trackingError (message)

