Classes
struct	WPS_SimpleAuthentication

struct	WPS_NameCode

struct	WPS_StreetAddress

struct	WPS_Location

struct	WPS_IPLocation

struct	WPS_GeoFence

Typedefs
typedef WPS_Continuation(WPSAPI_CALL *	WPS_LocationCallback) (void arg, WPS_ReturnCode code, const WPS_Location location, const void *reserved)

typedef WPS_Continuation(WPSAPI_CALL *	WPS_CertifiedLocationCallback) (void arg, WPS_ReturnCode code, const WPS_Location locations, unsigned nlocations, const void reserved)

typedef WPS_Continuation(WPSAPI_CALL *	WPS_TilingCallback) (void *arg, unsigned tileNumber, unsigned tileTotal)

typedef void *	WPS_GeoFenceHandle

typedef WPS_Continuation(WPSAPI_CALL *	WPS_GeoFenceCallback) (void arg, const WPS_GeoFence geofence, const WPS_Location location, const void reserved)

Enumerations
enum	WPS_ReturnCode { WPS_OK = 0, WPS_ERROR_SCANNER_NOT_FOUND = 1, WPS_ERROR_WIFI_NOT_AVAILABLE = 2, WPS_ERROR_NO_WIFI_IN_RANGE = 3, WPS_ERROR_UNAUTHORIZED = 4, WPS_ERROR_SERVER_UNAVAILABLE = 5, WPS_ERROR_LOCATION_CANNOT_BE_DETERMINED = 6, WPS_ERROR_PROXY_UNAUTHORIZED = 7, WPS_ERROR_FILE_IO = 8, WPS_ERROR_INVALID_FILE_FORMAT = 9, WPS_ERROR_TIMEOUT = 10, WPS_NOT_APPLICABLE = 11, WPS_GEOFENCE_ERROR = 12, WPS_ERROR_NOT_TUNED = 13, WPS_ERROR_NOT_SIGNED = 14, WPS_ERROR_LOCATION_SETTING_DISABLED = 15, WPS_ERROR_LOCATION_NOT_PERMITTED = 16, WPS_NOT_SUPPORTED = 17, WPS_ERROR_SERVICE_EXPIRED = 18, WPS_NOMEM = 98, WPS_ERROR = 99 }

enum	WPS_Continuation { WPS_STOP = 0, WPS_CONTINUE = 1 }

enum	WPS_StreetAddressLookup { WPS_NO_STREET_ADDRESS_LOOKUP, WPS_LIMITED_STREET_ADDRESS_LOOKUP, WPS_FULL_STREET_ADDRESS_LOOKUP }

enum	WPS_LocationType { WPS_LOCATION_TYPE_2D, WPS_LOCATION_TYPE_3D }

enum	WPS_GeoFenceType { WPS_GEOFENCE_ENTER, WPS_GEOFENCE_LEAVE, WPS_GEOFENCE_INSIDE, WPS_GEOFENCE_OUTSIDE }

Functions
WPSAPI_EXPORT const char *WPSAPI_CALL	WPS_version ()

WPSAPI_EXPORT WPS_ReturnCode WPSAPI_CALL	WPS_load ()

WPSAPI_EXPORT void WPSAPI_CALL	WPS_unload ()

WPSAPI_EXPORT WPS_ReturnCode WPSAPI_CALL	WPS_location (const WPS_SimpleAuthentication authentication, WPS_StreetAddressLookup street_address_lookup, WPS_Location *location)

WPSAPI_EXPORT WPS_ReturnCode WPSAPI_CALL	WPS_periodic_location (const WPS_SimpleAuthentication authentication, WPS_StreetAddressLookup street_address_lookup, unsigned long period, unsigned iterations, WPS_LocationCallback callback, void arg)

WPSAPI_EXPORT WPS_ReturnCode WPSAPI_CALL	WPS_certified_location (const WPS_SimpleAuthentication authentication, WPS_StreetAddressLookup street_address_lookup, WPS_CertifiedLocationCallback callback, void arg)

WPSAPI_EXPORT WPS_ReturnCode WPSAPI_CALL	WPS_signed_certified_location (const WPS_SimpleAuthentication authentication, WPS_StreetAddressLookup street_address_lookup, const unsigned char salt, unsigned saltLen, WPS_CertifiedLocationCallback callback, void *arg)

WPSAPI_EXPORT WPS_ReturnCode WPSAPI_CALL	WPS_ip_location (const WPS_SimpleAuthentication authentication, WPS_StreetAddressLookup street_address_lookup, WPS_IPLocation *location)

WPSAPI_EXPORT WPS_ReturnCode WPSAPI_CALL	WPS_offline_token (const WPS_SimpleAuthentication authentication, const unsigned char key, unsigned key_length, unsigned char *token, unsigned token_size)

WPSAPI_EXPORT WPS_ReturnCode WPSAPI_CALL	WPS_offline_location (const WPS_SimpleAuthentication authentication, const unsigned char key, unsigned key_length, const unsigned char token, unsigned token_size, WPS_Location *location)

WPSAPI_EXPORT void WPSAPI_CALL	WPS_free_offline_token (unsigned char *token)

WPSAPI_EXPORT void WPSAPI_CALL	WPS_free_location (WPS_Location *)

WPSAPI_EXPORT void WPSAPI_CALL	WPS_free_ip_location (WPS_IPLocation *)

WPSAPI_EXPORT void WPSAPI_CALL	WPS_set_proxy (const char address, int port, const char user, const char *password)

WPSAPI_EXPORT void WPSAPI_CALL	WPS_set_server_url (const char *url)

WPSAPI_EXPORT void WPSAPI_CALL	WPS_set_user_agent (const char *ua)

WPSAPI_EXPORT WPS_ReturnCode WPSAPI_CALL	WPS_set_local_files_path (const char **paths)

WPSAPI_EXPORT WPS_ReturnCode WPSAPI_CALL	WPS_set_tier2_area (const char *dirpath, unsigned size)

WPSAPI_EXPORT WPS_ReturnCode WPSAPI_CALL	WPS_set_tiling (const WPS_SimpleAuthentication authentication, const char dirpath, unsigned maxDataSizePerSession, unsigned maxDataSizeTotal, WPS_TilingCallback callback, void *arg)

WPSAPI_EXPORT WPS_ReturnCode WPSAPI_CALL	WPS_tiling (const char dirpath, unsigned maxDataSizePerSession, unsigned maxDataSizeTotal, WPS_TilingCallback callback, void arg)

WPSAPI_EXPORT WPS_ReturnCode WPSAPI_CALL	WPS_set_key (const char *key)

WPSAPI_EXPORT WPS_ReturnCode WPSAPI_CALL	WPS_set_auth (const char key, const char sku)

WPSAPI_EXPORT WPS_ReturnCode WPSAPI_CALL	WPS_set_auth_token (const char *token)

WPSAPI_EXPORT WPS_ReturnCode WPSAPI_CALL	WPS_set_registration_user (const WPS_SimpleAuthentication *authentication)

WPSAPI_EXPORT WPS_ReturnCode WPSAPI_CALL	WPS_register_user (const WPS_SimpleAuthentication authentication, const WPS_SimpleAuthentication new_authentication)

WPSAPI_EXPORT WPS_ReturnCode WPSAPI_CALL	WPS_tune_location (const WPS_SimpleAuthentication authentication, const WPS_Location location)

WPSAPI_EXPORT WPS_ReturnCode WPSAPI_CALL	WPS_geofence_set (const WPS_GeoFence geofence, WPS_GeoFenceCallback callback, void arg, WPS_GeoFenceHandle *handle)

WPSAPI_EXPORT WPS_ReturnCode WPSAPI_CALL	WPS_geofence_cancel (WPS_GeoFenceHandle handle)

WPSAPI_EXPORT WPS_ReturnCode WPSAPI_CALL	WPS_geofence_cancel_all ()

WPSAPI_EXPORT WPS_ReturnCode WPSAPI_CALL	WPS_set_tunable (const char key, const char value)

Typedef Documentation

◆ WPS_CertifiedLocationCallback

typedef WPS_Continuation(WPSAPI_CALL * WPS_CertifiedLocationCallback) (void *arg, WPS_ReturnCode code, const WPS_Location **locations, unsigned nlocations, const void *reserved)

Callback routine for WPS_certified_location().

Parameters

arg	the `arg` passed to `WPS_certified_location()`.
code	the `WPS_ReturnCode` of the last request.
locations	If `code` is `WPS_OK` points to an array of pointers to `WPS_Location` This pointer does not need to be freed.
locationsSize	size of locations array

Returns: WPS_CONTINUE if WPS_certified_location() should continue,
WPS_STOP if WPS_certified_location() should stop.

Since: 4.8

◆ WPS_GeoFenceCallback

typedef WPS_Continuation(WPSAPI_CALL * WPS_GeoFenceCallback) (void *arg, const WPS_GeoFence *geofence, const WPS_Location *location, const void *reserved)

Callback routine for WPS_geofence_set().

For a WPS_GEOFENCE_ENTER geofence, this callback will be called whenever the user enters the geofence (but only once for as long as the user remains inside the geofence). For a WPS_GEOFENCE_LEAVE geofence, this callback will be called whenever the user leaves the geofence (but only once for as long as the user remains outside the geofence).

Parameters

arg	the `arg` passed to `WPS_geofence_set()`.
geofence	the geofence that triggered this callback.
location	the actual calculated location.

Returns: WPS_CONTINUE if WPS_periodic_location() should continue,
WPS_STOP if WPS_periodic_location() should stop (and no more callback will be invoked).

Since: 4.4

Sample Code:: WPS_Continuation

geofence_callback(void*,

const WPS_GeoFence* geofence,

const WPS_Location* location,

const void*)

{

if (geofence->type == WPS_GEOFENCE_ENTER)

{

printf("entering");

}

else // geofence->type == WPS_GEOFENCE_LEAVE

{

printf("leaving");

}

printf(" geofence (%.6f, %.6f +/-%um) at %.6f, %.6f +/-%.0fm\n",

geofence->latitude,

geofence->longitude,

geofence->radius,

location->latitude,

location->longitude,

location->hpe);

return WPS_CONTINUE;

}

◆ WPS_GeoFenceHandle

typedef void* WPS_GeoFenceHandle

Geofence handle.

Since: 4.4

◆ WPS_LocationCallback

typedef WPS_Continuation(WPSAPI_CALL * WPS_LocationCallback) (void *arg, WPS_ReturnCode code, const WPS_Location *location, const void *reserved)

Callback routine for WPS_periodic_location().

Parameters

arg	the `arg` passed to `WPS_periodic_location()`.
code	the `WPS_ReturnCode` of the last request.
location	If `code` is `WPS_OK` points to a `WPS_Location` This pointer does not need to be freed.

Returns: WPS_CONTINUE if WPS_periodic_location() should continue,
WPS_STOP if WPS_periodic_location() should stop.

Since: 2.4

Sample Code:: WPS_Continuation

periodic_callback(void*,

WPS_ReturnCode code,

const WPS_Location* location,

const void*)

{

if (code != WPS_OK)

{

fprintf(stderr, "*** failure (%d)!\n", code);

}

else

{

print_location(location);

}

return WPS_CONTINUE;

}

◆ WPS_TilingCallback

typedef WPS_Continuation(WPSAPI_CALL * WPS_TilingCallback) (void *arg, unsigned tileNumber, unsigned tileTotal)

Callback routine for WPS_set_tiling().

Parameters

arg	the `arg` passed to `WPS_set_tiling()`.
tileNumber	the number of the tile to be downloaded next.
tileTotal	the total number of tiles to be downloaded (in this session).

Note: tileNumber ranges from 0 to tileTotal (not inclusive), but if a tile has already been downloaded it will be skipped and the callback will not be called for that tile.

Returns: WPS_CONTINUE if WPS should continue downloading tiles,
WPS_STOP if WPS should stop downloading tiles.

Since: 2.6

Sample Code:: WPS_Continuation

tiling_callback(void*,

unsigned tileNumber,

unsigned tileTotal)

{

printf("downloading tile %d/%d...\n", tileNumber, tileTotal);

return WPS_CONTINUE;

}

Enumeration Type Documentation

◆ WPS_Continuation

enum WPS_Continuation

WPS continuation.

Since: 2.6

Enumerator
WPS_STOP
WPS_CONTINUE

◆ WPS_GeoFenceType

enum WPS_GeoFenceType

Geofence type.

Since: 4.4

Enumerator
WPS_GEOFENCE_ENTER	identify a geofence that triggers when the user enters the defined zone
WPS_GEOFENCE_LEAVE	identify a geofence that triggers when the user leaves the defined zone
WPS_GEOFENCE_INSIDE	identify a geofence that triggers when the user's location starts within or enters the defined zone Since 4.8
WPS_GEOFENCE_OUTSIDE	identify a geofence that triggers when the user's location starts outside of or leaves the defined zone Since 4.8

◆ WPS_LocationType

enum WPS_LocationType

Calculated location type.

Since: 3.2

Enumerator
WPS_LOCATION_TYPE_2D
WPS_LOCATION_TYPE_3D

◆ WPS_ReturnCode

enum WPS_ReturnCode

WPS return codes.

Enumerator
WPS_OK	The call was successful.
WPS_ERROR_SCANNER_NOT_FOUND	The `WPSScanner.dll` was not found. Deprecated: This error code is no longer relevant.
WPS_ERROR_WIFI_NOT_AVAILABLE	No Wi-Fi adapter was detected.
WPS_ERROR_NO_WIFI_IN_RANGE	No Wi-Fi reference points in range.
WPS_ERROR_UNAUTHORIZED	User authentication failed.
WPS_ERROR_SERVER_UNAVAILABLE	The server is unavailable.
WPS_ERROR_LOCATION_CANNOT_BE_DETERMINED	A location couldn't be determined.
WPS_ERROR_PROXY_UNAUTHORIZED	Proxy authentication failed.
WPS_ERROR_FILE_IO	A file IO error occurred while reading the local file. Since 2.4
WPS_ERROR_INVALID_FILE_FORMAT	The local file has an invalid format. Since 2.4
WPS_ERROR_TIMEOUT	Network operation timed out. Since 3.0
WPS_NOT_APPLICABLE	Call cannot be completed at this time. Since 3.3
WPS_GEOFENCE_ERROR	An error occurred when processing a geofence. See also `WPS_geofence_set()` `WPS_geofence_cancel()` Since 4.4
WPS_ERROR_NOT_TUNED	Could not tune the location. Since 4.7
WPS_ERROR_NOT_SIGNED	Could not sign the certified location. Since 4.9.1
WPS_ERROR_LOCATION_SETTING_DISABLED	Location services are disabled in the system. Since 4.9.2
WPS_ERROR_LOCATION_NOT_PERMITTED	The application is not permitted to determine location. Since 5.0
WPS_NOT_SUPPORTED	Functionality is not supported. Since 5.4
WPS_ERROR_SERVICE_EXPIRED	Service has expired. Since 5.4
WPS_NOMEM	Cannot allocate memory. Since 2.6.1
WPS_ERROR	Some other error occurred.

◆ WPS_StreetAddressLookup

enum WPS_StreetAddressLookup

Street address lookup.

Note: The server returns as much information as requested, but is not required to fill in all the requested fields.
Only the fields the server could reverse geocode are returned.

Enumerator
WPS_NO_STREET_ADDRESS_LOOKUP	no street address lookup is performed.
WPS_LIMITED_STREET_ADDRESS_LOOKUP	a limited address lookup is performed to return, at most, city information.
WPS_FULL_STREET_ADDRESS_LOOKUP	a full street address lookup is performed returning the most specific street address.

Function Documentation

◆ WPS_certified_location()

WPSAPI_EXPORT WPS_ReturnCode WPSAPI_CALL WPS_certified_location	(	const WPS_SimpleAuthentication *	authentication,
		WPS_StreetAddressLookup	street_address_lookup,
		WPS_CertifiedLocationCallback	callback,
		void *	arg
	)

Requests certified periodic geographic location based on observed Wi-Fi access points, cell towers, and GPS signals.

Parameters

authentication	must be `NULL` for new applications that use `WPS_set_key()` or `WPS_set_auth()`, otherwise set to the user's authentication information.
street_address_lookup	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.
callback	the callback routine to report locations to.
arg	an opaque parameter passed to the callback routine.

Returns: a WPS_ReturnCode

Note: This call is blocking – it will not return until a- an error occurs while setting up, or b- the number of iterations have been processed, or c- the callback returns WPS_STOP.

Since: 4.8

◆ WPS_free_ip_location()

WPSAPI_EXPORT void WPSAPI_CALL WPS_free_ip_location ( WPS_IPLocation * )

Free a WPS_IPLocation struct returned by WPS_ip_location().

◆ WPS_free_location()

WPSAPI_EXPORT void WPSAPI_CALL WPS_free_location ( WPS_Location * )

Free a WPS_Location struct returned by WPS_location().

◆ WPS_free_offline_token()

WPSAPI_EXPORT void WPSAPI_CALL WPS_free_offline_token ( unsigned char * token )

Free a token returned by WPS_offline_token().

Since: 4.5

◆ WPS_geofence_cancel()

WPSAPI_EXPORT WPS_ReturnCode WPSAPI_CALL WPS_geofence_cancel ( WPS_GeoFenceHandle handle )

Cancel a geofence.

Parameters

handle the handle of the geofence to cancel.

Returns: a WPS_ReturnCode. WPS_GEOFENCE_ERROR indicates the geofence for this handle isn't defined.

See also: WPS_geofence_set()

Since: 4.4

◆ WPS_geofence_cancel_all()

WPSAPI_EXPORT WPS_ReturnCode WPSAPI_CALL WPS_geofence_cancel_all ( )

Cancel all geofences.

Returns: a WPS_ReturnCode

See also: WPS_geofence_set()

Since: 4.4

◆ WPS_geofence_set()

WPSAPI_EXPORT WPS_ReturnCode WPSAPI_CALL WPS_geofence_set	(	const WPS_GeoFence *	geofence,
		WPS_GeoFenceCallback	callback,
		void *	arg,
		WPS_GeoFenceHandle *	handle
	)

Define a new geofence.

Parameters

geofence	the geofence to monitor.
callback	the `WPS_GeoFenceCallback` to invoke when this geofence is triggered.
arg	an opaque parameter passed to the `WPS_GeoFenceCallback`.
handle	receives `WPS_GeoFenceHandle` which can be used to cancel this geofence.

Returns: a WPS_ReturnCode.

See also: WPS_geofence_cancel()

Since: 4.4

Sample Code:: WPS_GeoFence geofence;

WPS_GeoFenceHandle handle;

WPS_ReturnCode rc;

geofence.size = sizeof(WPS_GeoFence);

geofence.latitude = 42.1234;

geofence.longitude = -71.5678;

geofence.radius = 100;

geofence.type = WPS_GEOFENCE_ENTER;

geofence.period = 0;

rc = WPS_geofence_set(&geofence,

geofence_callback,

NULL,

&handle);

if (rc != WPS_OK)

{

fprintf(stderr, "*** WPS_geofence_set failed (%d)!\n", rc);

}

rc = WPS_periodic_location(NULL,

WPS_NO_STREET_ADDRESS_LOOKUP,

60 * 60 * 1000,

0,

NULL,

NULL);

if (rc != WPS_OK)

{

fprintf(stderr, "*** WPS_periodic_location failed (%d)!\n", rc);

}

rc = WPS_geofence_cancel(handle);

if (rc != WPS_OK)

{

fprintf(stderr, "*** WPS_geofence_cancel failed (%d)!\n", rc);

}

rc = WPS_geofence_cancel_all();

if (rc != WPS_OK)

{

fprintf(stderr, "*** WPS_geofence_cancel_all failed (%d)!\n", rc);

}

◆ WPS_ip_location()

WPSAPI_EXPORT WPS_ReturnCode WPSAPI_CALL WPS_ip_location	(	const WPS_SimpleAuthentication *	authentication,
		WPS_StreetAddressLookup	street_address_lookup,
		WPS_IPLocation **	location
	)

Request geographic location information based on the IP address of the client making the request.

Note: This information is likely not accurate, but may give some indication as to the general location of the request and may provide some hints for the client software to act and react appropriately.

: WPS_ip_location() requires network connectivity.

Parameters

authentication	must be `NULL` for new applications that use `WPS_set_key()` or `WPS_set_auth()`, otherwise set to the user's authentication information.
street_address_lookup	request street address lookup in addition to lat/long lookup.
location	pointer to return a `WPS_IPLocation` struct. This pointer must be freed by calling `WPS_free_ip_location()`

Returns: a WPS_ReturnCode

Sample Code:: WPS_IPLocation* location;

WPS_ReturnCode rc;

rc = WPS_ip_location(NULL,

WPS_NO_STREET_ADDRESS_LOOKUP,

&location);

if (rc != WPS_OK)

{

fprintf(stderr, "*** WPS_ip_location failed (%d)!\n", rc);

}

else

{

print_ip_location(location);

WPS_free_ip_location(location);

}

◆ WPS_load()

WPSAPI_EXPORT WPS_ReturnCode WPSAPI_CALL WPS_load ( )

Initializes WPS API. Should be called before making other WPS API calls.

Since: 4.4

Note: This call is not mandatory. WPS will be initialized automatically upon the first API call.

◆ WPS_location()

WPSAPI_EXPORT WPS_ReturnCode WPSAPI_CALL WPS_location	(	const WPS_SimpleAuthentication *	authentication,
		WPS_StreetAddressLookup	street_address_lookup,
		WPS_Location **	location
	)

Requests geographic location based on observed Wi-Fi access points, cell towers, and GPS signals.

Parameters

authentication	must be `NULL` for new applications that use `WPS_set_key()` or `WPS_set_auth()`, otherwise set to the user's authentication information.
street_address_lookup	request street address lookup in addition to latitude/longitude lookup.
location	pointer to return a `WPS_Location` struct. This pointer must be freed by calling `WPS_free_location()`.

Returns: a WPS_ReturnCode

Sample Code:: WPS_Location* location;

WPS_ReturnCode rc;

rc = WPS_location(NULL,

WPS_NO_STREET_ADDRESS_LOOKUP,

&location);

if (rc != WPS_OK)

{

fprintf(stderr, "*** WPS_location failed (%d)!\n", rc);

}

else

{

print_location(location);

WPS_free_location(location);

}

◆ WPS_offline_location()

WPSAPI_EXPORT WPS_ReturnCode WPSAPI_CALL WPS_offline_location	(	const WPS_SimpleAuthentication *	authentication,
		const unsigned char *	key,
		unsigned	key_length,
		const unsigned char *	token,
		unsigned	token_size,
		WPS_Location **	location
	)

Request a geographic location from a token collected at a different time.

Parameters

authentication	must be `NULL` for new applications that use `WPS_set_key()` or `WPS_set_auth()`, otherwise set to the user's authentication information.
key	a key used to encrypt the `token`.
key_length	the length of the key used to encrypt the `token`
token	the token to be converted to a location
token_size	the size of the `token`
location	pointer to return a `WPS_Location` struct. This pointer should be freed by calling `WPS_free_location()`

Returns: a WPS_ReturnCode

Note: A different username can be used to replay a token than the username used to collect the token, however both users must belong to the same realm.

: 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.

: The same key used to encrypt the token in WPS_offline_token() must be provided to WPS_offline_location().

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

See also: WPS_offline_token()

Since: 4.5

Sample Code:: WPS_Location* location;

WPS_ReturnCode rc;

unsigned char key[16];

unsigned char* token;

unsigned token_size;

// restore the key and token stored earlier

// ...

rc = WPS_offline_location(NULL,

key,

sizeof(key),

token,

token_size,

&location);

if (rc != WPS_OK)

{

fprintf(stderr, "*** WPS_offline_location failed (%d)!\n", rc);

}

else

{

print_location(location);

WPS_free_location(location);

}

◆ WPS_offline_token()

WPSAPI_EXPORT WPS_ReturnCode WPSAPI_CALL WPS_offline_token	(	const WPS_SimpleAuthentication *	authentication,
		const unsigned char *	key,
		unsigned	key_length,
		unsigned char **	token,
		unsigned *	token_size
	)

Retrieve a secure 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 WPS_offline_location().

Parameters

authentication	must be `NULL` for new applications that use `WPS_set_key()` or `WPS_set_auth()`, otherwise set to the user's authentication information.
key	a key used to encrypt the token. The longer the key the more effective the encryption. It is recommended to have a key of at least 16 bytes.
key_length	the length of the key.
token	a pointer to receive the token. This pointer must be freed by calling `WPS_free_offline_token()`.
token_size	a pointer to receive the size of `token`.

Returns: a WPS_ReturnCode

Note: A sensible time to call WPS_offline_token() is after either WPS_location() failed with WPS_ERROR_SERVER_UNAVAILABLE or WPS_ERROR_LOCATION_CANNOT_BE_DETERMINED, or from the WPS_periodic_location() callback again with a WPS_ERROR_SERVER_UNAVAILABLE or WPS_ERROR_LOCATION_CANNOT_BE_DETERMINED error code.

: 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.

See also: WPS_offline_location(); WPS_free_offline_token()

Since: 4.5

Sample Code:: WPS_ReturnCode rc;

unsigned char key[16];

unsigned char* token;

unsigned token_size;

// generate the key

// ...

rc = WPS_offline_token(NULL,

key,

sizeof(key),

&token,

&token_size);

if (rc != WPS_OK)

{

fprintf(stderr, "*** WPS_offline_token failed (%d)!\n", rc);

}

else

{

// save the key and token in persistent storage

// ...

WPS_free_offline_token(token);

}

◆ WPS_periodic_location()

WPSAPI_EXPORT WPS_ReturnCode WPSAPI_CALL WPS_periodic_location	(	const WPS_SimpleAuthentication *	authentication,
		WPS_StreetAddressLookup	street_address_lookup,
		unsigned long	period,
		unsigned	iterations,
		WPS_LocationCallback	callback,
		void *	arg
	)

Requests periodic geographic location based on observed Wi-Fi access points, cell towers, and GPS signals.

Parameters

authentication	must be `NULL` for new applications that use `WPS_set_key()` or `WPS_set_auth()`, otherwise set to the user's authentication information.
street_address_lookup	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 user 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 times a location is to be reported. A value of zero indicates an unlimited number of iterations.
callback	the callback routine to report locations to.
arg	an opaque parameter passed to the callback routine.

Returns: a WPS_ReturnCode

Precondition: period must be strictly greater than 0.

Note: This call is blocking – it will not return until a- an error occurs while setting up, or b- the number of iterations have been processed, or c- the callback returns WPS_STOP.

Since: 2.4

Sample Code:: WPS_ReturnCode rc;

rc = WPS_periodic_location(NULL,

WPS_NO_STREET_ADDRESS_LOOKUP,

1000,

0,

periodic_callback,

NULL);

if (rc != WPS_OK)

{

fprintf(stderr, "*** WPS_periodic_location failed (%d)!\n", rc);

}

◆ WPS_register_user()

WPSAPI_EXPORT WPS_ReturnCode WPSAPI_CALL WPS_register_user	(	const WPS_SimpleAuthentication *	authentication,
		const WPS_SimpleAuthentication *	new_authentication
	)

Register a new user.

Deprecated:: Replaced by WPS_set_key() and WPS_set_auth()

Parameters

authentication	an existing user's authentication information.
new_authentication	the new user's authentication information or `NULL` to trigger auto-registration.

Returns: a WPS_ReturnCode

Since: 2.3.1

Sample Code:: New applications are encouraged to simply use the auto-registration feature by calling WPS_register_user(), maybe during initialization of the application. For example:
// info from Skyhook

#define WPS_USERNAME "myusername"

#define WPS_REALM "myrealm"

WPS_SimpleAuthentication wpsUser;

WPS_ReturnCode rc;

void wpsInit()

{

wpsUser.username = WPS_USERNAME;

wpsUser.realm = WPS_REALM;

while ((rc = WPS_register_user(&wpsUser, NULL)) != WPS_OK)

{

// registration failed... retry

sleep(5 + rand() * 5); // some randomness

}

}

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

#define WPS_USERNAME "myusername"

#define WPS_REALM "myrealm"

WPS_SimpleAuthentication wpsUser;

void saveUsername(const char*); // save registered username

const char* readUsername(); // read registered username, or NULL if not found

const char* generateUsername(); // your own generated username

void wpsInit()

{

WPS_SimpleAuthentication wpsReg;

WPS_ReturnCode rc;

const char* savedUsername = readUsername(); // retrieve previously registered username

const char* generatedUsername = generateUsername();

wpsUser.username = generatedUsername;

wpsUser.realm = WPS_REALM;

if (savedUsername != NULL && strcmp(savedUsername, generatedUsername) == 0)

{

// user already registered (and match generated username)

return;

}

wpsReg.username = WPS_USERNAME;

wpsReg.realm = WPS_REALM;

while ((rc = WPS_register_user(&wpsReg, &wpsUser) != WPS_OK)

{

// registration failed... retry

sleep(5 + rand() * 5); // some randomness

}

saveUsername(generatedusername); // save registered username

}

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. This can be achieved, for example, by hashing a unique identifier of the device, like the IMEI, or the MAC, or some other hardware ID.

: Once registration is complete wpsUser can be used in any WPS_* calls. For example:
WPS_Location* location;

WPS_ReturnCode rc = WPS_location(&wpsUser,

WPS_NO_STREET_ADDRESS_LOOKUP,

&location);

◆ WPS_set_auth()

WPSAPI_EXPORT WPS_ReturnCode WPSAPI_CALL WPS_set_auth	(	const char *	key,
		const char *	sku
	)

Set the user's authentication information.

Parameters

key	an existing user's API key.
sku	product's SKU.

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 WPS_location.

Note: Must not be used in conjunction with WPS_set_auth()

Since: 4.9

◆ WPS_set_auth_token()

WPSAPI_EXPORT WPS_ReturnCode WPSAPI_CALL WPS_set_auth_token ( const char * token )

Set the user's authentication token.

Parameters

key	an existing user's authentication token.

This authentication method is only supported in custom API server environments.
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 WPS_location.

Note: Must not be used in conjunction with WPS_set_key() and WPS_set_auth()

Since: 4.9.8

◆ WPS_set_key()

WPSAPI_EXPORT WPS_ReturnCode WPSAPI_CALL WPS_set_key ( const char * key )

Set the user's API key.

Parameters

key	an existing 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 WPS_location.

Note: Must not be used in conjunction with WPS_set_auth()

Since: 4.9

◆ WPS_set_local_files_path()

WPSAPI_EXPORT WPS_ReturnCode WPSAPI_CALL WPS_set_local_files_path ( const char ** paths )

Set the path to local files so location determination can be performed locally.

Parameters

paths an array (terminated by NULL) of complete path to local files.
This array replaces all previous values.
Use NULL to clear and release local files.

Returns: a WPS_ReturnCode

Deprecated:: Replaced by the tiling model.

Since: 2.4

Sample Code:: const char* paths[] = { "myfile1", "myfile2", NULL };

WPS_ReturnCode rc = WPS_set_local_files_path(paths);

if (rc != WPS_OK)

{

fprintf(stderr, "*** WPS_set_local_files_path failed (%d)!\n", rc);

}

◆ WPS_set_proxy()

WPSAPI_EXPORT void WPSAPI_CALL WPS_set_proxy	(	const char *	address,
		int	port,
		const char *	user,
		const char *	password
	)

Setup a proxy server.

Parameters

address	the internet address of the proxy server.
port	the TCP port number of the proxy server.
user	the username to authenticate with the proxy server.
password	the password to authentication with the proxy server.

Note: user and password are optional and can be set to NULL for un-authenticated proxy servers.

Returns: a WPS_ReturnCode

◆ WPS_set_registration_user()

WPSAPI_EXPORT WPS_ReturnCode WPSAPI_CALL WPS_set_registration_user ( const WPS_SimpleAuthentication * authentication )

Set the user's authentication information.

Deprecated:: Replaced by WPS_set_key() and WPS_set_auth()

Parameters

authentication an existing 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 WPS_location.

Note: Must not be used in conjunction with WPS_set_key()

Since: 4.8

◆ WPS_set_server_url()

WPSAPI_EXPORT void WPSAPI_CALL WPS_set_server_url ( const char * url )

Overwrite the WPS server's url from its default value.

Parameters

url	the url to the server. A value of `NULL` turns off remote determination of location.

◆ WPS_set_tier2_area()

WPSAPI_EXPORT WPS_ReturnCode WPSAPI_CALL WPS_set_tier2_area	(	const char *	dirpath,
		unsigned	size
	)

Setup the tier2 area.

Parameters

dirpath	the path to a directory to store the tier2 files.
size	the approximate max total size of the tier2 files, in kilobytes.

Returns: a WPS_ReturnCode

Deprecated:: This call is no longer relevant.

Since: 2.6

◆ WPS_set_tiling()

WPSAPI_EXPORT WPS_ReturnCode WPSAPI_CALL WPS_set_tiling	(	const WPS_SimpleAuthentication *	authentication,
		const char *	dirpath,
		unsigned	maxDataSizePerSession,
		unsigned	maxDataSizeTotal,
		WPS_TilingCallback	callback,
		void *	arg
	)

Setup tiling so location determination can be performed locally.
Tiles are managed automatically (download of new tiles when required and remove of old tiles) by WPS_location and WPS_periodic_location.

Parameters

authentication	must be `NULL` for new applications that use `WPS_set_key()` or `WPS_set_auth()`, otherwise set to the user's authentication information.
dirpath	the path to a directory to store tiles. `dirpath` must end with a directory separator character. (i.e. '\' on Windows platforms and '/' on Unix platforms)
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.
callback	the callback function to control the tile download. By default, all tiles are downloaded.
arg	the opaque parameter to pass to the callback function.

Note: 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.

: Applications should not attempt to access tiles directly, in particular to delete them.

Returns: a WPS_ReturnCode

Since: 3.3

Sample Code:: WPS_ReturnCode rc;

rc = WPS_set_tiling(NULL,

"/tiles/",

450 * 1024, // 450KB

2 * 1024 * 1024, // 2MB

NULL,

NULL);

if (rc != WPS_OK)

{

fprintf(stderr, "*** WPS_set_tiling failed (%d)!\n", rc);

}

◆ WPS_set_tunable()

WPSAPI_EXPORT WPS_ReturnCode WPSAPI_CALL WPS_set_tunable	(	const char *	key,
		const char *	value
	)

Set a tunable value.

Returns: a WPS_ReturnCode

Since: 4.9.5

◆ WPS_set_user_agent()

WPSAPI_EXPORT void WPSAPI_CALL WPS_set_user_agent ( const char * ua )

Overwrite the default user agent of the requests going to the server.

Parameters

ua	the user agent string.

Since: 2.7

◆ WPS_signed_certified_location()

WPSAPI_EXPORT WPS_ReturnCode WPSAPI_CALL WPS_signed_certified_location	(	const WPS_SimpleAuthentication *	authentication,
		WPS_StreetAddressLookup	street_address_lookup,
		const unsigned char *	salt,
		unsigned	saltLen,
		WPS_CertifiedLocationCallback	callback,
		void *	arg
	)

Requests certified geographic location updates that are signed by Skyhook's servers. The user may verify the signature of the returned location using Skyhook's public certificate.

See also: signature in WPS_Location for details on the format of the signature.; sample code for verifying the signature in the example/CertifiedSignatureTestJava and example/CertifiedSignatureTestPhp directories

Parameters

authentication	must be `NULL` for new applications that use `WPS_set_key()` or `WPS_set_auth()`, otherwise set to the user's authentication information.
street_address_lookup	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.
salt	random data that is used as an additional input to the hash of the returned location.
saltLen	length of the salt.
callback	the callback routine to report locations to.
arg	an opaque parameter passed to the callback routine.

Returns: a WPS_ReturnCode

Note: This call is blocking – it will not return until a- an error occurs while setting up, or b- the number of iterations have been processed, or c- the callback returns WPS_STOP.; The salt is a mandatory parameter and will return WPS_ERROR if salt is NULL or saltLen is not greater than 0.; This call requires the device's local time to be correct. WPS_ERROR_NOT_SIGNED is returned to WPS_CertifiedLocationCallback if the local time is outside of the acceptable range.

Since: 4.9.1

◆ WPS_tiling()

WPSAPI_EXPORT WPS_ReturnCode WPSAPI_CALL WPS_tiling	(	const char *	dirpath,
		unsigned	maxDataSizePerSession,
		unsigned	maxDataSizeTotal,
		WPS_TilingCallback	callback,
		void *	arg
	)

Deprecated:: Replaced by WPS_set_tiling()

Since: 2.6

◆ WPS_tune_location()

WPSAPI_EXPORT WPS_ReturnCode WPSAPI_CALL WPS_tune_location	(	const WPS_SimpleAuthentication *	authentication,
		const WPS_Location *	location
	)

Tune the last location returned.

Parameters

authentication	an existing user's authentication information.
location	the tuned location.

Returns: a WPS_ReturnCode

Note: The device must be at the location specified in location 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.

Since: 3.0

◆ WPS_unload()

WPSAPI_EXPORT void WPSAPI_CALL WPS_unload ( )

Releases all resources consumed by WPS API and stops any background activity. Must be called before the calling application or module is unloaded.

Since: 4.4

◆ WPS_version()

WPSAPI_EXPORT const char* WPSAPI_CALL WPS_version ( )

Return a string containing the version information as <major>.<minor>.<revision>.<build>

Returns: the version information

Since: 3.0

Classes

Typedefs

Enumerations

Functions

Typedef Documentation

◆ WPS_CertifiedLocationCallback

◆ WPS_GeoFenceCallback

◆ WPS_GeoFenceHandle

◆ WPS_LocationCallback

◆ WPS_TilingCallback

Enumeration Type Documentation

◆ WPS_Continuation

◆ WPS_GeoFenceType

◆ WPS_LocationType

◆ WPS_ReturnCode

◆ WPS_StreetAddressLookup

Function Documentation

◆ WPS_certified_location()

◆ WPS_free_ip_location()

◆ WPS_free_location()

◆ WPS_free_offline_token()

◆ WPS_geofence_cancel()

◆ WPS_geofence_cancel_all()

◆ WPS_geofence_set()

◆ WPS_ip_location()

◆ WPS_load()

◆ WPS_location()

◆ WPS_offline_location()

◆ WPS_offline_token()

◆ WPS_periodic_location()

◆ WPS_register_user()

◆ WPS_set_auth()

◆ WPS_set_auth_token()

◆ WPS_set_key()

◆ WPS_set_local_files_path()

◆ WPS_set_proxy()

◆ WPS_set_registration_user()

◆ WPS_set_server_url()

◆ WPS_set_tier2_area()

◆ WPS_set_tiling()

◆ WPS_set_tunable()

◆ WPS_set_user_agent()

◆ WPS_signed_certified_location()

◆ WPS_tiling()

◆ WPS_tune_location()

◆ WPS_unload()

◆ WPS_version()