Package com.skyhookwireless.wps

Interface IWPS

  • All Known Implementing Classes:
    WPS, XPS
    public interface IWPS

    • Method Detail

      • abort

        void abort()
        Attempts to immediately cancel any operations that are executing in the background, before returning.

      • destroy

        void destroy()
        Since:
        5.7

      • getPeriodicLocation

        @Deprecated
void getPeriodicLocation​(WPSAuthentication authentication,
                         WPSStreetAddressLookup streetAddressLookup,
                         long period,
                         int iterations,
                         WPSPeriodicLocationCallback callback)
        Deprecated.
        replaced by getPeriodicLocation(WPSAuthentication, WPSStreetAddressLookup, boolean, long, int, WPSPeriodicLocationCallback)
        Requests periodic geographic location.
        Parameters:
        authentication - must be null for new applications that use setKey(java.lang.String) or 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.
        iterations - number of time a location is to be reported. A value of zero indicates an unlimited number of iterations.
        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.
        callback - a WPSPeriodicLocationCallback

      • getPeriodicLocation

        void getPeriodicLocation​(WPSAuthentication authentication,
                         WPSStreetAddressLookup streetAddressLookup,
                         boolean timeZoneLookup,
                         long period,
                         int iterations,
                         WPSPeriodicLocationCallback callback)
        Requests periodic geographic location.
        Parameters:
        authentication - must be null for new applications that use setKey(java.lang.String) or 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).
        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 abort().
        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.
        callback - a WPSPeriodicLocationCallback
        Since:
        5.0

      • getOfflineToken

        byte[] getOfflineToken​(WPSAuthentication authentication,
                       byte[] key)
        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
        // ...
    }
        Parameters:
        authentication - must be null for new applications that use setKey(java.lang.String) or 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.
        Since:
        4.5
        See Also:
        getOfflineLocation(WPSAuthentication, byte[], byte[], WPSLocationCallback)

      • getOfflineLocation

        void getOfflineLocation​(WPSAuthentication authentication,
                        byte[] key,
                        byte[] token,
                        WPSLocationCallback callback)
        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()
            {
                //...
            }
        });
        Parameters:
        authentication - must be null for new applications that use setKey(java.lang.String) or 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.
        Since:
        4.5
        See Also:
        getOfflineToken(WPSAuthentication, byte[])

      • setKey

        void setKey​(java.lang.String key)
        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 setAuthentication(java.lang.String, java.lang.String).

        Parameters:
        key - an existing user's API key.
        Throws:
        java.lang.IllegalArgumentException - if the key is malformed
        Since:
        4.9

      • setAuthentication

        void setAuthentication​(java.lang.String key,
                       java.lang.String sku)
        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 setKey(java.lang.String).

        Parameters:
        key - an existing user's API key.
        sku - product's SKU.
        Throws:
        java.lang.IllegalArgumentException - if the key or SKU string is malformed
        Since:
        5.8

      • setRegistrationUser

        @Deprecated
void setRegistrationUser​(WPSAuthentication authentication)
        Deprecated.
        Replaced by setKey(java.lang.String) and setAuthentication(java.lang.String, java.lang.String). This method is no longer supported starting with version 5.5.
        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 setKey(java.lang.String).

        Parameters:
        authentication - an existing user's authentication information.
        Since:
        4.8

      • registerUser

        @Deprecated
void registerUser​(WPSAuthentication authentication,
                  WPSAuthentication newUser,
                  RegistrationCallback callback)
        Deprecated.
        Replaced by setKey(java.lang.String) and setAuthentication(java.lang.String, java.lang.String). This method is no longer supported starting with version 5.5.
        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() {...});
        Parameters:
        authentication - an existing user's authentication information.
        newUser - the new user's authentication information or null to trigger auto-registration.
        callback - a RegistrationCallback

      • tuneLocation

        void tuneLocation​(WPSAuthentication authentication,
                  WPSLocation newLocation,
                  TuneLocationCallback callback)
        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.

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

      • setLocalFilePaths

        void setLocalFilePaths​(java.util.List<java.lang.String> paths)
        Set the path to local files so location determination can be performed locally.
        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

        void setTiling​(java.lang.String dirpath,
               long maxDataSizePerSession,
               long maxDataSizeTotal,
               TilingListener listener)
        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.
        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

        WPSGeoFence.Handle setGeoFence​(WPSGeoFence geofence,
                               GeoFenceCallback callback)
        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());
        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.
        Since:
        4.4
        See Also:
        cancelGeoFence(WPSGeoFence.Handle)