Periodic updates

Function called Periodic updates is one of most powerful tools of Locus API. Shortest description may sound like "What is happen in Locus Map now?". Periodic updates allows you to react on activity (move of map, stats of track recording, navgation, etc.) in Locus Map application and offer some interesting response back to user (values on watches, points/tracks in around, etc.).

How to start

Nice sample how periodic updates works is in Dashboard sample.

1. prepare BroadcastReceiver

Periodic updates are based on receiving intents over BroadcastReceiver, so we need to initialize receiver for this at first. Class that extends BroadcastReceiver must be registered in your manifest.xml file in all cases. You cannot define new instance of receiver on runtime.

Receiver must have defined filter locus.api.android.ACTION_PERIODIC_UPDATE to received UpdateContainers.

Sample implementation with correct used PeriodicUpdatesHandler:

public class PeriodicUpdateReceiver extends BroadcastReceiver {

    @Override
    public void onReceive(Context context, Intent intent) {
	// prepare custom update listener ( maybe defined as global variable )
	PeriodicUpdatesHandler.OnUpdate onUpdateListener = new PeriodicUpdatesHandler.OnUpdate() {

            @Override
            public void onIncorrectData() {...}

            @Override
            public void onUpdate(LocusVersion locusVersion, UpdateContainer update) {
                // we have valid container, let's perform some tasks now
            }
        };

        // let handler handle received intent
        PeriodicUpdatesHandler.getInstance().onReceive(
                context, intent, onUpdateListener);
    }
};

2. Register BroadcastReceiver

It is necessary to register receiver in your manifest.xml file also with necessary intent-filter, like:

<receiver
        android:name=".receivers.PeriodicUpdateReceiver">

    <intent-filter>
        <action
            android:name="locus.api.android.ACTION_PERIODIC_UPDATE"/>

    </intent-filter>
</receiver>

3. Handle data

All is now correctly set, so let's handle received data in onUpdate method of PeriodicUpdatesHandler.OnUpdate class used in first step.

FAQ

No updates are received

To receive PeriodicUpdates it is necessary that

1. Locus is running - check it
2. Periodic updates are enabled - with known LocusInfo object, simply use locusInfo.isPeriodicUpdatesEnabled()

Start receiver manually only when needed?

Sure, it is possible. You may define your BroadcastReceiver as class registered in your manifest.xml file, like this

<receiver 
    android:name=".receivers.PeriodicUpdateReceiver"
    enabled="false">

    <intent-filter>
        <action 
            android:name="locus.api.android.ACTION_PERIODIC_UPDATE"/>
    </intent-filter>
</receiver>

With this setup, statically define receiver won't receive updates. This is very useful, method that may be used for cases when you wants to let user decide if he wants to react with your application on broadcasts.

To enable it, use ActionTools.enablePeriodicUpdatesReceiver() and ActionTools.disablePeriodicUpdatesReceiver() functions of Locus API.