Accessing geolocation data

How to

Access geolocation data (latitude, longitude, altitude, heading, and speed) on the BlackBerry 10 device.

Solution

bps_initialize();
                
geolocation_request_events(0);    //0 indicates that all events
                                  //are requested

geolocation_set_period(1); 

while (!exit_application) {
  bps_event_t *event = NULL;
  bps_get_event(&event, -1);    // -1 means that the function waits 
                                  // for an event before returning

  if (event) {
    if (bps_event_get_domain(event) == geolocation_get_domain()) {
      if (event == NULL || bps_event_get_code(event) !=
          GEOLOCATION_INFO) {
        return;
      }

      double latitude = geolocation_event_get_latitude(event);
      double longitude = geolocation_event_get_longitude(event);
      double accuracy = geolocation_event_get_accuracy(event);

      double altitude = geolocation_event_get_altitude(event);
      bool altitude_valid =
           geolocation_event_is_altitude_valid(event);

      double altitude_accuracy =
             geolocation_event_get_altitude_accuracy(event);
      bool altitude_accuracy_valid = 
           geolocation_event_is_altitude_accuracy_valid(event);

      double heading = geolocation_event_get_heading(event);
      bool heading_valid =
           geolocation_event_is_heading_valid(event);

      double speed = geolocation_event_get_speed(event);
      bool speed_valid = geolocation_event_is_speed_valid(event);

      double num_satellites =
             geolocation_event_get_num_satellites_used(event);
      bool num_satellites_valid =
           geolocation_event_is_num_satellites_valid(event);                
      }
  }
}

geolocation_stop_events(0);       //0 indicates that all events
                                  //are stopped

Build requirements

You must include the following header files from the BlackBerry Platform Services (BPS) library:
#include <bps/bps.h>
#include <bps/geolocation.h>

You must also set the application permissions to allow the use of the geolocation capability. To set this permission, in the Momentics IDE for BlackBerry, open the project's bar-descriptor.xml file and select the GPS Location check box on the Application tab.

Discussion

The geolocation of a device refers to its position, heading, and speed in the world. Latitude, longitude, and heading are reported in degrees, while altitude is reported in meters above Mean Sea Level, and speed is reported in meters per second. Accuracy applies to the latitude, longitude, and altitude values and is reported in meters. You can also determine the number of satellites that are used to report the device's geolocation.

The geolocation_set_period() function sets the period, in seconds, at which geolocation events are reported to the application. If the period is set to 0, a single geolocation event is delivered.

After your application registers to receive geolocation events using geolocation_request_events(), you can call bps_get_event() to retrieve the next available event from the BlackBerry Platform Services. After an event is received, you should determine whether it's a geolocation event by using bps_event_get_domain() and geolocation_get_domain(). You can also use navigator_get_domain() to determine whether the event was a request to close the application. To determine whether the event contains information about the current geolocation of the device, use bps_event_get_code() to compare the event code with the GEOLOCATION_INFO enumerator.

In the geolocation library, data is considered valid if the device has a GPS fix. A GPS fix is determined using the last update from the geolocation device driver. If the device does not have a GPS fix, the data is marked as invalid. The following geolocation attributes have associated functions that you can use to check for validity:
  • altitude
  • altitude accuracy
  • heading
  • speed
  • number of satellites used
  • total number of satellites reported

If the device cannot obtain a GPS fix but has Wi-Fi connectivity, the latitude, longitude, and accuracy are valid.

Once the application no longer requires geolocation data, call geolocation_stop_events() to stop the delivery of geolocation events.

Related resources

Last modified: 2014-05-14



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus