GPS BT API functions


int gpsbt_start (char *bda, int debug_level, int gpsd_debug_level, short port, char *error_buf, int error_buf_max_len, int timeout_ms, gpsbt_t *ctx)
int gpsbt_stop (gpsbt_t *ctx)
int gpsbt_set_debug_level (int level)
int gpsbt_init_pairing (char *bda)

Function Documentation

int gpsbt_init_pairing char *  bda  ) 

Start the pairing process. This is not needed if the device is already paired. The BT address must be given. Normally this function is not called because there is UI for GPS pairing in N800 and later.

bda Bluetooth address
Return values:
0 ok
<0 fail

int gpsbt_set_debug_level int  level  ) 

Set the debug level. The debugs are printed to stdout.

level new level (0=no debugging, >0 debug level)
Return values:
-1 the program was not compiled with debugging mode
other previous debugging mode value

int gpsbt_start char *  bda,
int  debug_level,
int  gpsd_debug_level,
short  port,
char *  error_buf,
int  error_buf_max_len,
int  timeout_ms,
gpsbt_t *  ctx

Start function finds out the available GPS BT devices and starts the gpsd if it is not running. If no GPS BT devices are found, then an error is returned.

bda BT address of the GPS device, normally this is left to null but if this API cannot find a suitable GPS BT device, the application can ask the BT device from the user and supply the address here.
debug_level debug level (set to 0 to use the default)
gpsd_debug_level gpsd debug level (set to 0 to use the default)
port gpsd port (set to 0 to use the default (2947))
error_buf user supplied error buffer (optional), if there is an error the API puts error message to this buffer
error_buf_max_len max length of the error buffer, set to 0 if error message is not needed in caller program
timeout_ms timeout (in ms) when waiting dbus replies, set to 0 to use the library default (5 seconds), if set to <0 then use the dbus default (whatever that is).
ctx caller must allocate and clear this struct before call
Return values:
<0 error, check errno for more details
0 ok
Example: The default call would be gpsbt_start(NULL, 0, 0, 0, &ctx);

If the GPSD_PROG environment variable is defined, then it is used when starting the program, otherwise "gpsd" will be used as a program name. This way you can override the program name and/or path if necessary.

If the GPSD_CTRL_SOCK environment variable is defined, then it is used as a location to gpsd control socket, otherwise the default control socket is /tmp/.gpsd_ctrl_sock

If the GPS_SERIAL_PORTS environment variable is defined, then it used to tell which extra serial ports are being used. This is typically needed for non BT GPS devices. Multiple serial ports can be given and they should be separated by spaces. For practical use, this env var should be set for every process started (because the value is needed when starting the gpsd and gpsd is only started by first caller of this API function). The device names in the env var must start with slash "/".

If the GPS_NO_BT environment variable is defined and set to 1, then it means that no bluetooth GPS device should be used even if the system has one connected to it. If this option is set, then GPS_SERIAL_PORTS should be also set, otherwise the API cannot connect to any GPS device.

Because some UI application might want to disable/enable BT GPS device, then it is necessary to control the API from external process. The gpsctrl API contains functions for this purpose (see gpsctrl.h for more details)

The start API might have unexpected behaviour in following scenario:

  • application X starts using the API, it does not supply the BT address of the device i.e., bda==NULL so every GPS device is connected to gpsd process.
  • application B calls start with a BT address (bda!=NULL) after app A has started gpsd, in this case the app B call is ignored because gpsd is already running

Note for the API user:

  • gpsbt_start() starts gpsd if it is not yet running
  • gpsbt_start() does not guarantee that gpsd is running i.e., is up and listening the socket when the function returns
  • If application calls gps_open() (found in osso-gpsd package) to get a fix, the function might return an error because gpsd is not yet running. In this case user should wait and call gps_open() again.

int gpsbt_stop gpsbt_t *  ctx  ) 

Stop function stops the gpsd if it was running and nobody was using it.

ctx context returned by gpsbt_start()
Return values:
<0 error, check errno for more details
0 ok

Generated on Thu Oct 4 12:58:01 2007 for libgpsbt by  doxygen 1.4.6