LOCATIONKIT API REFERENCE

NAVBUILDER INSIDE LBS SDK

INTRODUCTION

The LocationKit API provides a unified library across platforms and devices that can be used to request location information.

 There are two types of location requests:

  • A single request
  • A tracking request

 Single requests are usually requested to get local search information or to place the device on a map. Tracking requests are used to show the position of the device on the map in real time or to navigate to a destination.

 LocationKit supports three different methods to obtain location information:

  • Standalone GPS (SGPS) uses the GPS chipset in devices that can obtain GPS information without network assistance
  • Cell ID uses the location of the cell the device is currently talking to provide a quick approximate location that can be used to obtain local information
  • Wi Fi ID uses the visible Wi-Fi networks that the device can see (assuming the Wi-Fi radio is turned ON) to obtain an approximate location that is much more accurate than the Cell ID location when a match is found in the database

 The above services have very different characteristics, so special algorithms are provided to let the system decide how to use them effectively and provide the best possible user experience.

INDEX

API

PLATFORM-SPECIFIC CONSIDERATIONS

This document is meant as a general description of the LocationKit API, without platform considerations. The following differences will become apparent when looking at the actual implementation of the APIs for each platform:

  • Java platforms provide garbage collection, so there is no need for “destroy” functions
  • Java requires all functions to belong to a class. This may result in slightly different grouping of methods, but function names should be similar
  • Java and C++ use classes, so some of the parameters may not be needed as they can be retrieved from the class
  • Brew uses C, so the function calls need additional parameters
  • Data types are kept generic in this document, but will have specific types on the target platforms. Please refer to the dynamically generated documentation for accuracy

USER API

The NBI User API provides a very simple system for obtaining location information:

  • The host application requests a single fix or a stream of fixes
    • If a single fix is desired, then the host application specifies how much time is willing to give the hardware for obtaining the best possible location
    • If multiple fixes are desired, then the host application just requests a stream of fixes
  • The desired request is submitted
  • Whenever location information is available, a listener/callback is called to pass the information to the host application

NBI DATA STRUCTURES

DATA STRUCTURES

Type Name Description
struct NBI_LocationConfig Structure passed to the NBI_LocationInitialize function.
struct NBI_Location Location structure returned to the caller.

CONSTANTS

Type Name Description
#define NBI_INVALID_ALTITUDE A sentinel value for an invalid altitude.
#define NBI_INVALID_HEADING A sentinel value for an invalid heading.
#define NBI_INVALID_SPEED A sentinel value for an invalid speed

TYPE DEFINITIONS

Type Name Description
typedef NBI_LocationContext Opaque structure containing the context
typedef NBI_LocationDeviceStateCallback Function prototype for a callback that is called when the location HW state changes.
typedef NBI_LocationInitializeCallback Function prototype for a callback that is called when the provider is initialized
typedef NBI_LocationCallback Function prototype for a callback that is called with each location fix

ENUMERATIONS

Type Name Description
enum

NBI_LocationState

  • PGS_Undefined
  • PGS_InitializePending
  • PGS_DestroyPending
  • PGS_Initialized
  • PGS_TrackingGPS
  • PGS_TrackingNetwork
  • PGS_Suspended
  • PGS_Resume
  • PGS_LocationSettingOff
Enumeration used to provide the status of the Location Provider.
enum

NBI_LocationValid

  • PGV_None
  • PGV_Latitude
  • PGV_Longitude
  • PGV_Altitude
  • PGV_Heading
  • PGV_HorizontalVelocity
  • PGV_VerticalVelocity
  • PGV_HorizontalUncertainty
  • PGV_AxisUncertainty
  • PGV_PerpendicularUncertainty
  • PGV_VerticalUncertainty
  • PGV_UTCOffset
  • PGV_SatelliteCount
Valid flags set when a location fix is received. Used to indicate which fields in the structure contain valid data.

These constants are used to set individual bits in the valid field and to test if the bits are set.

Some of these values are platform-specific and may not be available in certain versions of LK.
enum

NBI_FixType

  • NBI_FixType_Fast
  • NBI_FixType_Normal
  • NBI_FixType_Accurate
The fix type is used to define the type of request that LK will do:  
  • Fast will provide a quick location using the best available provider that can respond within a couple of seconds
  • Normal will allow the hardware up to 8 seconds (as needed) to provide a better location
  • Accurate will allow the hardware to provide an accurate SGPS location with up to 120 seconds of warmup

NBI_LOCATIONCONFIG

This structure is passed to the NBI_LocationInitialize function.

Type Name Description
boolean emulationMode If true, do emulation
string emulationFilename Path to the emulation file that contains location fixes
boolean warmUpFix If true, LK will request a fix during initialization to warm up the Hardware. If the radio fails to get a fix within 3 minutes on Android/RIM/Brew devices, the radio will be shut down until the next request comes in.
int emuPlayStart Number of seconds to skip the playback file.
boolean collectWiFiProbes If TRUE, then enable collection of WiFi probes.
boolean useOwnNetworkLocation If this is set to TRUE, then LocationKit will not use the service application to request network-based locations.

NBI_LOCATION

This structure contains the location information returned to the caller every time there is new positioning data available.

Type Name Description
double altitude Altitude in meters, WGS-84 ellipsoid.
nbi_gpsTime gpsTime Time in seconds since the GPS Epoch: Midnight, January 6, 1980.
double heading Heading in degrees.
double horizontalUncertaintyAlongAxis Standard deviation of horizontal uncertainty along the axis of uncertainty
double horizontalUncertaintyAlongPerpendicular Standard deviation of horizontal uncertainty perpendicular to the axis of uncertainty
double horizontalUncertaintyAngleOfAxis Heading in degrees of the axis of uncertainty
double horizontalVelocity Horizontal velocity in meters/second
double latitude Latitude in degrees, WGS-84 ellipsoid
double longitude Longitude in degrees, WGS-84 ellipsoid
uint16 numberOfSatellites Number of satellites acquired
int32 status Response status
int16 utcOffset Difference in seconds between GPS time and UTC time (leap seconds)
uint32 valid NBI_LocationValid flags indicating which fields in the struct have valid values
double verticalUncertainty Standard deviation of vertical uncertainty
double verticalVelocity Vertical velocity in meters/seconds

FUNCTIONS

NBI_LOCATIONCANCELGETONEFIX

This function cancels an outstanding location request that was previously initiated by NBI_LocationGetOneFix. Since more than one call can be active at the same time, the callback that was originally passed to NBI_LocationGetOneFix must be passed as a parameter to allow the libraries to identify which request to cancel.

typedef void (CALLBACK* NBI_LocationCallback)(

      void* appData,

      NBI_LocationContext *context,

      NBI_Location * location,

      NBI_Error error);

NBI_Error NBI_LocationCancelGetOneFix(

      NBI_LocationCallback callback,

      NBI_LocationContext * locationContext)

PARAMETERS

Type Name Description
NBI_LocationCallback callback

Pointer to the callback function that was passed to NBI_LocationGetOneFix.

Note: If this callback has been reused in multiple calls, then all pending requests using the callback will be canceled.

NBI_LocationContext* locationContext Pointer to the NBI location context

NBI_LOCATIONCONTEXTCREATE

This function creates the location povider instance.

This function should be called before an other NBI_Location… functions to create the location provider. The caller is responsible for saving the pointer returned in the locationContext parameter. The context is then used in all subsequent calls to the NBI Location API.

Note: calling this function twice with the same NBI_Context should return the same NBI_LocationContext.

NBI_Error NBI_LocationContextCreate(

NBI_Context * context,

NBI_LocationContext ** locationContext)

PARAMETERS

Type Name Description
NBI_Context* context Pointer to the NBI context
NBI_LocationContext** locationContext Pointer to the NBI location context

NBI_LOCATIONCONTEXTDESTROY

This function closes the location provider and releases all associated resources.

NBI_Error NBI_LocationContextDestroy(NBI_LocationContext * locationContext)

PARAMETERS

Type Name Description
NBI_LocationContext* locationContext Pointer to the NBI location context

NBI_LOCATIONGETAPILEVEL

The NBI_LocationGetAPILevel function returns a number representing the supported API level for the version of LocationKit being used. Each time a release adds or changes functionality, the API level will increase by 1. LocationKit will guarantee compatibility for applications written for a lower API level, but not for a higher one.

int NBI_LocationGetAPILevel(

     NBI_LocationContext *locationContext)

PARAMETERS

Type Name Description
NBI_LocationContext* locationContext Pointer to the NBI location context

Possible return values:

  • <API level> an integer representing the API level of the NBI libraries being used.

NBI_LOCATIONGETONEFIX

This function is used to get a single location with predefined settings. Three different standard cases are supported: Fast, Normal and Accurate.

typedef void (CALLBACK* NBI_LocationCallback)(

      void* appData,

      NBI_LocationContext *context,

      NBI_Location * location,

      NBI_Error error);

NBI_Error NBI_LocationGetOneFix(

       NBI_LocationContext * locationContext,

       NBI_LocationCallback callback,

       NBI_FixType fixType,

       void *appData)

PARAMETERS

Type Name Description
NBI_LocationContext* locationContext Pointer to the NBI location context
NBI_LocationCallback callback Pointer to the callback function that will receive fixes
NBI_FixType fixType Type of fix desired
void* appData Application context that will be passed to the callback

NBI_LOCATIONGETSTATE

This function is used to get the current state of the location provider.

NBI_Error NBI_LocationGetState(

       NBI_LocationContext * locationContext,

       NBI_LocationState *locationState)

PARAMETERS

Type Name Description
NBI_LocationContext* locationContext Pointer to the NBI location context
NBI_LocationState* locationState Out parameter that will contain the location provider state

NBI_LOCATIONINITIALIZE

This function is used to initialize the location provider.

NBI_Error NBI_LocationInitialize(

       NBI_LocationContext * locationContext,

       const NBI_LocationConfig * config,

       NBI_LocationInitializeCallback * userCallback,

       NBI_LOcationDeviceStateCallback * userCallbackDevState,

       const void *userData)

PARAMETERS

Type Name Description
NBI_LocationContext* locationContext Pointer to the NBI location context
NBI_LocationConfig config Structure describing the desired location configuration
NBI_LocationInitializeCallback userCallback Callback function that is called when the provider is initialized
NBI_LocationDeviceStateCallback userCallbackDevState Optional callback function that is called when the location HW state changes. Pass NULL if you do not wish to receive device state notifications
void* userData Optional pointer for user supplied data that will be passed to the callback

NBI_LOCATIONSTARTRECEIVINGFIXES

This function is used to initiate a tracking session. LK does tracking using the device’s SGPS hardware, with a fallback to a network-based location obtained using Cell ID or Wi-Fi positioning.

typedef void (CALLBACK* NBI_LocationCallback)(

      void* appData,

      NBI_LocationContext *context,

      NBI_Location * location,

      NBI_Error error);

NBI_Error NBI_LocationStartReceivingFixes(

      NBI_LocationContext * locationContext,

      NBI_LocationCallback callback,

      void * appData)

PARAMETERS

Type Name Description
NBI_LocationContext* locationContext Pointer to the NBI location context
NBI_LocationCallback callback Pointer to the callback function that will receive fixes
void* appData Application context that will be passed to the callback

NBI_LOCATIONSTOPRECEIVINGFIXES

This function is used to stop the tracking session that was started by calling NBI_LocationStartReceivingFixes.

NBI_Error NBI_LocationStopReceivingFixes(

       NBI_LocationContext * locationContext,

       NBI_LocationCallback callback)

PARAMETERS

Type Name Description
NBI_LocationContext* locationContext Pointer to the NBI location context
NBI_LocationCallback callback Pointer to the callback function that is receiving fixes. This is used to identify which listener needs to be removed from the queue.