Location API

This page details all of the available NEON API functionality contained within the static API class Neon.

Requesting Permissions for NEON Location Service

Before you can begin tracking, the user needs to grant NEON Location Service two permissions: LOCATION and STORAGE. This allows NEON Location Service the ability to access the location of the device, and to access data stored on Android external storage.

NOTE: If you call Neon.bind() without obtaining these permissions, a security exception will be thrown.

Neon.startPermissionActivityForResult(visibleActivity, requestCode) should be called if Neon.hasRequiredPermissions(context) returns false. You should then handle the user accepting or rejecting those permissions by checking the result code returned to the supplied request code. If the result code is Activity.RESULT_OK, then the location service can be started. If Activity.RESULT_CANCELED, then the user has rejected the permissions and the location service cannot be started.

boolean hasRequiredPermissions(Context context)
boolean startPermissionActivityForResult(Activity visibleActivity, int requestCode)

The following code snippet gives an example of requesting and handling permissions:


public static final int PERMISSION_ACTIVITY_REQUEST_CODE = 1003;

void startLocationService() {

    if(!Neon.hasRequiredPermissions(mapsActivity.getApplicationContext()))
    {
        Log.i(LOG_TAG, "starting NEON permissions activity");
        Neon.startPermissionActivityForResult(mapsActivity, PERMISSION_ACTIVITY_REQUEST_CODE);
    }
    else
    {
        if (!Neon.isBound())
        {
            Log.i(LOG_TAG, "starting NEON Location Service");
            Neon.registerLocationUpdates(this);
            Neon.registerEvents(this);
            Neon.bind(mapsActivity.getApplicationContext());
        }
    }
}

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) 
{
    switch (requestCode) 
    {
        case PERMISSION_ACTIVITY_REQUEST_CODE:
            switch (resultCode) 
            {
                case Activity.RESULT_CANCELED:
                    Log.i(LOG_TAG, "no permission granted, exit");
                    finish();
                case Activity.RESULT_OK:
                    Log.i(LOG_TAG, "permissions granted, start the location service");
                    startLocationService();
                    break;
                default:
                    break;
            }
            break;
    }
}

Binding to the NEON API

In order to start the NEON Location Service and begin tracking, you need to call Neon.bind(). Generally, you want to pass the application context here. Events passed out of the NEON Location Service to your application will be received on the eventHandler you supply, or the Main Looper if you don’t specify.

Neon.unbind() should be called when you application no longer wants to receive events and location updates. If your application is the only one bound to the NEON Location Service, it will be shutdown once you unbind.

NOTE: You should not call Neon.bind() if your application is already bound - an exception will be thrown. You can check whether you are currently bound with Neon.isBound().

boolean bind(Context c, Handler eventHandler)
void unbind()
boolean isBound()

Registering for Events

The NEON Location Service will send events to notify any connected applications about state changes. Some events are status notifications about battery life, or tracking quality. Others indicate that authentication is needed or that the NEON Location Service needs to be upgraded.

void registerEvents(INeonEventListener listener)
boolean unregisterEvents(INeonEventListener listener)

Events will be returned on the INeonEventListener’s onEvent() function.

Registering for Locations

Once the NEON Location Service has been bound, locations will be sent to all registered applications. Implement an INeonLocationListener and choose a NeonLocationType.

NeonLocationType Description
Current Only the most up-to-date locations
Per Step The location at every step
Corrected Updates locations in the past as NEON Location Service corrects them

Locations will be returned on the INeonLocationListener’s onLocationChanged() function. Make sure to unregister your listener when you unbind from the NEON Location Service.

void registerLocationUpdates(INeonLocationListener listener, NeonLocationType type)
boolean unregisterLocationUpdates(INeonLocationListener listener)

Check whether NEON Location Service is Installed

This function can verify whether the NEON Location service is installed on the phone.

boolean isNeonInstalled(Context c)