Package com.skyhookwireless.wps

Class WPS

  • All Implemented Interfaces:
    IWPS
    Direct Known Subclasses:
    XPS
    public class WPS
extends com.skyhookwireless.wps.WPSExtra
    Calculate geographic location based on observed Wi-Fi access points and cell towers.

    • Constructor Detail

      • WPS

        public WPS​(android.content.Context context)

    • Method Detail

      • setServerUrl

        public static void setServerUrl​(java.lang.String url)
        Overwrite the server's url from its default value.
        Parameters:
        url - the url to the server. A value of null turns off remote determination of location.

      • setProxy

        public static void setProxy​(java.lang.String address,
                            int port,
                            java.lang.String username,
                            java.lang.String password)
        Set up a proxy server.
        Parameters:
        address - the internet address of the proxy server.
        port - the TCP port number of the proxy server.
        username - the username to authenticate with the proxy server. Can be set to null for un-authenticated proxy servers.
        password - the password for authentication with the proxy server. Can be set to null for un-authenticated proxy servers.

      • getVersion

        public static java.lang.String getVersion()
        Get the SDK version.
        Returns:
        a string containing the version information as <major>.<minor>.<revision>.<build>

      • abort

        public void abort()
        Description copied from interface: IWPS
        Attempts to immediately cancel any operations that are executing in the background, before returning.
        Specified by:
        abort in interface IWPS

      • destroy

        public void destroy()
        Specified by:
        destroy in interface IWPS

      • getPeriodicLocation

        public void getPeriodicLocation​(WPSAuthentication authentication,
                                WPSStreetAddressLookup streetAddressLookup,
                                long period,
                                int iterations,
                                WPSPeriodicLocationCallback callback)
        Description copied from interface: IWPS
        Requests periodic geographic location.
        Specified by:
        getPeriodicLocation in interface IWPS
        Parameters:
        authentication - must be null for new applications that use IWPS.setKey(java.lang.String) or IWPS.setAuthentication(java.lang.String, java.lang.String), otherwise set to the user's authentication information.
        streetAddressLookup - request street address lookup in addition to latitude/longitude lookup. Note that street address lookup is only performed when the location is determined by the remote server (network-centric model), not when the location is determined locally.
        period - maximum time in milliseconds between location reports.
        WPS will invoke the callback at least every period, either with a location update or with an error if no location can be determined. WPS may report location updates more often than the specified period if a new or better location becomes available within a given period.
        This parameter is also used to specify the preferred Wi-Fi scan period, which WPS may override for optimal performance and power savings.
        iterations - number of time a location is to be reported. A value of zero indicates an unlimited number of iterations.
        callback - a WPSPeriodicLocationCallback
        Throws:
        java.lang.SecurityException - if caller does not have permission to access location

      • getPeriodicLocation

        public void getPeriodicLocation​(WPSAuthentication authentication,
                                WPSStreetAddressLookup streetAddressLookup,
                                boolean timeZoneLookup,
                                long period,
                                int iterations,
                                WPSPeriodicLocationCallback callback)
        Description copied from interface: IWPS
        Requests periodic geographic location.
        Specified by:
        getPeriodicLocation in interface IWPS
        Parameters:
        authentication - must be null for new applications that use IWPS.setKey(java.lang.String) or IWPS.setAuthentication(java.lang.String, java.lang.String), otherwise set to the user's authentication information.
        streetAddressLookup - request street address lookup in addition to latitude/longitude lookup. Note that specifying a street address lookup will enforce locations to be determined by the remote server (network-centric model).
        timeZoneLookup - request timezone lookup in addition to latitude/longitude lookup. Note that specifying a time zone lookup will enforce locations to be determined by the remote server (network-centric model).
        period - maximum time in milliseconds between location reports.
        WPS will invoke the callback at least every period, either with a location update or with an error if no location can be determined. WPS may report location updates more often than the specified period if a new or better location becomes available within a given period.
        This parameter is also used to specify the preferred Wi-Fi scan period, which WPS may override for optimal performance and power savings.
        iterations - number of time a location is to be reported. A value of zero indicates an unlimited number of iterations.
        Using this parameter to set a finite number of iterations is not recommended for new applications. The preferred way to bound the duration of the location request is to explicitly interrupt it by returning WPSContinuation.WPS_STOP or invoking IWPS.abort().
        callback - a WPSPeriodicLocationCallback
        Throws:
        java.lang.SecurityException - if caller does not have permission to access location

      • getOfflineToken

        public byte[] getOfflineToken​(WPSAuthentication authentication,
                              byte[] key)
        Description copied from interface: IWPS
        Retrieve an offline token based on the latest observed Wi-Fi access points and cell towers. This token can be saved and converted to a location later by calling getOfflineLocation.

        A sensible time to call getOfflineToken is from either getLocation or getPeriodicLocation callback with a WPS_ERROR_SERVER_UNAVAILABLE error code (indicating the device is offline).

        Offline tokens are only valid for 90 days after they are generated. Attempting to redeem a token more than 90 days old will result in an error.

        Sample Code: 

            final byte[] token = _wps.getOfflineToken(null, null);
    if (token == null)
    {
        System.err.println("no token to save");
    }
    else
    {
        // save the token in persistent storage
        // ...
    }
        Specified by:
        getOfflineToken in interface IWPS
        Parameters:
        authentication - must be null for new applications that use IWPS.setKey(java.lang.String) or IWPS.setAuthentication(java.lang.String, java.lang.String), otherwise set to the user's authentication information.
        key - deprecated and must be set to null
        Returns:
        the offline token or null if XPS does not have enough information to be able to determine a location later.
        Throws:
        java.lang.SecurityException - if caller does not have permission to access location
        See Also:
        IWPS.getOfflineLocation(WPSAuthentication, byte[], byte[], WPSLocationCallback)

      • getOfflineLocation

        public void getOfflineLocation​(WPSAuthentication authentication,
                               byte[] key,
                               byte[] token,
                               WPSLocationCallback callback)
        Description copied from interface: IWPS
        Requests geographic location based on a token collected at a different time.

        This method may be called while a getLocation or getPeriodicLocation call is in progress. If it is called while another getOfflineLocation call is already in progress, then that one will be aborted.

        Offline tokens are only valid for 90 days after they are generated. Attempting to redeem a token more than 90 days old will result in an error.

        Although a token can be collected when a location has been calculated getOfflineLocation is not guaranteed to return a location with that same token.

        Sample Code: 

            // restore token stored earlier
    final byte[] token = ... ;

    _wps.getOfflineLocation(null, null, token, new WPSLocationCallback()
        {
            public void handleWPSLocation(final WPSLocation location)
            {
                // use the location
                // ...
            }

            public WPSContinuation handleError(final WPSReturnCode error)
            {
                System.err.println("getOfflineLocation() failed: "+error);
                // ...
                return WPSContinuation.WPS_STOP;
            }

            public void done()
            {
                //...
            }
        });
        Specified by:
        getOfflineLocation in interface IWPS
        Parameters:
        authentication - must be null for new applications that use IWPS.setKey(java.lang.String) or IWPS.setAuthentication(java.lang.String, java.lang.String), otherwise set to the user's authentication information.
        key - deprecated and must be set to null
        token - the token to be converted to a location.
        callback - a WPSLocationCallback.
        See Also:
        IWPS.getOfflineToken(WPSAuthentication, byte[])

      • setKey

        public void setKey​(java.lang.String key)
        Description copied from interface: IWPS
        Set the user's API key.

        Make sure to call this method before making any other calls, such as during initialization of the application.

        After this call you should pass null as authentication to other calls like getLocation.

        Must not be used in conjunction with IWPS.setAuthentication(java.lang.String, java.lang.String).

        Specified by:
        setKey in interface IWPS
        Parameters:
        key - an existing user's API key.

      • setAuthentication

        public void setAuthentication​(java.lang.String key,
                              java.lang.String sku)
        Description copied from interface: IWPS
        Set the user's authentication information.

        Make sure to call this method before making any other calls, such as during initialization of the application.

        After this call you should pass null as authentication to other calls like getLocation.

        Must not be used in conjunction with IWPS.setKey(java.lang.String).

        Specified by:
        setAuthentication in interface IWPS
        Parameters:
        key - an existing user's API key.
        sku - product's SKU.

      • renewAuthentication

        @Deprecated
public void renewAuthentication()
        Deprecated.
        Not supported in this release
        Specified by:
        renewAuthentication in class com.skyhookwireless.wps.WPSExtra

      • enableCalibration

        public void enableCalibration​(boolean enable)
        Specified by:
        enableCalibration in class com.skyhookwireless.wps.WPSExtra

      • resetCalibration

        public void resetCalibration()
        Specified by:
        resetCalibration in class com.skyhookwireless.wps.WPSExtra

      • setRegistrationUser

        public void setRegistrationUser​(WPSAuthentication authentication)
        Description copied from interface: IWPS
        Set the user's authentication information.

        Make sure to call this method before making any other calls, such as during initialization of the application.

        After this call you should pass null as authentication to other calls like getLocation.

        Must not be used in conjunction with IWPS.setKey(java.lang.String).

        Specified by:
        setRegistrationUser in interface IWPS
        Parameters:
        authentication - an existing user's authentication information.

      • registerUser

        public void registerUser​(WPSAuthentication authentication,
                         WPSAuthentication newAuth,
                         RegistrationCallback callback)
        Description copied from interface: IWPS
        Register a new user.

        New applications are encouraged to simply use the auto-registration feature by calling registerUser, such as during initialization of the application.
        For example: 

            // Info from Skyhook
    private static final String WPS_USERNAME = "myusername";
    private static final String WPS_REALM = "myrealm";

    private final WPSAuthentication _wpsUser =
        new WPSAuthentication(WPS_USERNAME, WPS_REALM);

    void wpsInit()
    {
        _wps.registerUser(_wpsUser, null, new RegistrationCallback()
            {
                public void handleSuccess()
                {
                    // ...
                }

                public WPSContinuation handleError(final WPSReturnCode error)
                {
                    // ...
                    return WPSContinuation.WPS_CONTINUE;
                }

                public void done()
                {
                    //...
                }
            });
    }
        Applications that still want to control how usernames are generated can continue to do so as they did before since version 4.2 is backward compatible with 4.1. For example: 
            // Info from Skyhook
    private static final String WPS_USERNAME = "myusername";
    private static final String WPS_REALM = "myrealm";

    // Where generateUsername() returns your own generated username
    private final WPSAuthentication _wpsUser =
        new WPSAuthentication(generateUsername(), WPS_REALM);

    void wpsInit()
    {
        // Where readUsername() returns the saved username, or null if
        // there isn't one saved
        if (_wpsUser.getUsername().equals(readUsername()))
        {
            // user already registered (and matched generated username)
            return;
        }

        _wps.registerUser(new WPSAuthentication(WPS_USERNAME, WPS_REALM),
                          _wpsUser,
                          new RegistrationCallback()
            {
                public void handleSuccess()
                {
                    // ...
                    saveUsername(_wpsUser.getUsername());
                }

                public WPSContinuation handleError(final WPSReturnCode error)
                {
                    // ...
                    return WPSContinuation.WPS_CONTINUE;
                }

                public void done()
                {
                    //...
                }
            });
    }
        Note that the generated username should be stable -- ie. remain constant over time, every time it is generated -- to avoid unnecessary re-registrations. Care should be taken when generating a username to protect the privacy of the user, and should not contain any personally identifiable information.
        Now whenever your application needs to determine a location, it can simply call getLocation() or getPeriodicLocation(), even if registerUser() is still ongoing, or if it has failed. For example: 
            _wps.getLocation(_wpsUser,
                     WPSStreetAddressLookup.WPS_FULL_STREET_ADDRESS_LOOKUP
                     new WPSLocationCallback() {...});
        Specified by:
        registerUser in interface IWPS
        Parameters:
        authentication - an existing user's authentication information.
        newAuth - the new user's authentication information or null to trigger auto-registration.
        callback - a RegistrationCallback

      • tuneLocation

        public void tuneLocation​(WPSAuthentication authentication,
                         WPSLocation newLocation,
                         TuneLocationCallback callback)
        Description copied from interface: IWPS
        Tune the last location returned. The device must be at the location specified in newLocation during the entire duration of this call. Note that pure GPS locations will not reflect any tuning.

        Tuning is not an effective strategy for trying to make small adjustments to a location. It is best used for adding to our coverage or fixing results that are off by hundreds of meters.

        Specified by:
        tuneLocation in interface IWPS
        Parameters:
        authentication - must be null for new applications that use IWPS.setKey(java.lang.String) or IWPS.setAuthentication(java.lang.String, java.lang.String), otherwise set to the user's authentication information.
        newLocation - the tuned location
        callback - a TuneLocationCallback

      • setLocalFilePaths

        public void setLocalFilePaths​(java.util.List<java.lang.String> paths)
        Description copied from interface: IWPS
        Set the path to local files so location determination can be performed locally.
        Specified by:
        setLocalFilePaths in interface IWPS
        Parameters:
        paths - a list of compressed positioning data file paths. This list replaces all previous values. Use null to clear and release local files.

      • setTiling

        public void setTiling​(java.lang.String dirpath,
                      long maxDataSizePerSession,
                      long maxDataSizeTotal,
                      TilingListener listener)
        Description copied from interface: IWPS
        Setup tiling so location determination can be performed locally. Tiles are typically less then 50KB in size, so to download an area of 3x3 tiles for each session you would set maxDataSizePerSession to 450KB, i.e. 460,800. It is recommended that maxDataSizePerSession be a factor of 2 - 10 smaller than maxDataSizeTotal, so that tiles from several areas can be cached.
        Specified by:
        setTiling in interface IWPS
        Parameters:
        dirpath - the path to a directory to store tiles.
        maxDataSizePerSession - the maximum size of data downloaded per session, in bytes. A value of 0 disables any further tile downloads.
        maxDataSizeTotal - the maximum size of all stored tiles, in bytes. A value of 0 causes all stored tiles to be deleted.
        listener - the callback function to control the tile download. By default, all tiles are downloaded.

      • setGeoFence

        public WPSGeoFence.Handle setGeoFence​(WPSGeoFence geofence,
                                      GeoFenceCallback callback)
        Description copied from interface: IWPS
        Define a new geofence.

        Sample Code: 

            final WPSGeoFence geofence =
        new WPSGeoFence(42.1234, -71.5678, 100, WPSGeoFence.Type.WPS_GEOFENCE_ENTER, 0);

    final WPSGeoFence.Handle handle = _wps.setGeoFence(geofence, new MyGeoFenceCallback());
    if (handle == null)
        System.err.println("setGeoFence() failed");

    _wps.getPeriodicLocation(null,
                             WPSStreetAddressLookup.WPS_NO_STREET_ADDRESS_LOOKUP,
                             60 * 60 * 1000,
                             0,
                             new MyPeriodicLocationCallback());
        Specified by:
        setGeoFence in interface IWPS
        Parameters:
        geofence - the geofence to monitor
        callback - the GeoFenceCallback to invoke when this geofence is triggered
        Returns:
        a WPSGeoFence.Handle that can be used to cancel geofence or null if geofence cannot be registered.
        Throws:
        java.lang.SecurityException - if caller does not have permission to access location
        See Also:
        IWPS.cancelGeoFence(WPSGeoFence.Handle)

      • injectLocation

        @Deprecated
public void injectLocation​(WPSLocation userLocation)
        Deprecated.
        Not supported in this release
        Specified by:
        injectLocation in class com.skyhookwireless.wps.WPSExtra