GPS BT connection library
=========================

Application that needs GPS data can use this API to manage GPS daemon start
and stop and to find out what serial port device (/dev/rfcommX) the GPS device
is using. The API uses services provided by libgpsmgr that handles the GPS
daemon start and stop.

The client API contains following 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);
  - start function finds out the available GPS BT devices and starts
    the gpsd if it is not running. If no GPS BT device is found, then
    an error is returned.
  - if bda (BT address) is null, then the library tries to find it out,
    if the caller knows the address, then it can be given here
  - error text can be returned to the caller if the caller has supplied
    an error buffer in the call
  - returns 0 if everything was ok, other value indicates error
    (see errno for more details)
  - context is returned to the caller (the buffer must have been allocated
    by the caller, also the context buffer must be cleared by the caller)
  - 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


int gpsbt_stop(gpsbt_t *ctx);
  - stop function stops the gpsd if it was running and nobody was using it.


int gpsbt_set_debug_level(int level);
  - Set the debug level of the library (not gpsd). The debugs are printed to
    stdout.
  - new level (0=no debugging, >0 debug level)
  - returns -1 if the program was not compiled with debugging mode
    and other value is the previous debugging mode value


Following test program is provided:

  app_test
      - simulates application, uses start() and stop() functions

NOTE
  The gpsbt_stop() function tries to remove the used /dev/rfcommX devices,
  normally this works ok but in following scenario it is not done (because
  the API does not know the device in question).
  - App1 starts and lauches gpsd
  - App2 starts and notices gpsd is already running
  - App1 stops but does not kill gpsd or clear used rfcomm devices because
    the App2 is running and using gpsd
  - App2 stops and kills gpsd because it is the only user of gpsd left
    but it cannot clear rfcomm because it does not know which device is in
    use by gpsd (because App1 started started the gpsd)
  This is a feature, so no bug reports should be generated about this.
  This feature should not be a big problem thou.


About GPS BT devices
  Some GPS BT devices do not advertise themselves as GPS capable i.e., they
  do not set the positioning bit to 1 in BT service class. For example,
  Nokia LD-3W sets the bit correctly but Nokia LD-1W, Holux GR-231,
  Insmat BT-GPS-3244C8 and TomTom Wireless GPS MkII do not set it, they are
  just uncategorized BT devices.
  The libgpsbt handles this situation like this:
  - if the API founds BT devices that have positioning bit set, then
    those devices are used (rfcomm device is created only for them)
  - if no such device is found, then the API gets the name of the
    device and connects to those devices that it knows to be GPS 
    capable
  - if no such device is found, then it is let to the calling application
    to find out what device is to be used


$Id:$

