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) |
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 |
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) |
-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 |
<0 | error, check errno for more details | |
0 | ok |
If return value is <0, then errno can be used to tell more specific what went wrong. ECANCELED User did not accept disclaimer. ENODATA User did not enable the GPS subsystem (so no fixes will be received because gpsd is not running). EPERM Will be returned if caller is root. The API should be used as normal user. ECOMM Device is in flight mode.
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:
Note for the API user:
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() |
<0 | error, check errno for more details | |
0 | ok |