Functions to define and monitor geographic areas.
This file defines the geomonitor service, which provides functions for creating and monitoring virtual perimeters (regions) for real-world geographic areas. To use the geomonitor service, the application must have the access_location_services capability. To grant an application the access_location_services capability, the bar-descriptor.xml file in the application's project must contain the line "<permission>access_location_services</permission>".
You can use the functions from the Geomonitor library's geomonitor.h to create, add, remove, and manage monitored regions. The function bps_geomonitor_event_get_service_event() returns a geomonitor_service_event_t structure. You can use the accessor functions defined in the Geomonitor library to access information from a geomonitor_service_event_t structure (e.g., geomonitor_service_event_get_type()).
The following sample code demonstrates how to use this library to create and add a region for monitoring:
#include <geomonitor.h>
#include <bps/geomonitor.h>
// 1. Create a new region, give it a unique name, and set its location.
geomonitor_region_t region = NULL;
geomonitor_create_region(®ion, "Home");
geomonitor_region_set_circle_shape(region, 45.342102,-75.770581, 200.0);
// 2. Set additional optional parameters.
// Set region monitoring mode to persistent so that the region is monitored
// even when the application that added the region is not running.
// Note! The default monitoring mode is transient, which requires you to
// create and initialize at least one instance of geomonitor_service_t prior
// to adding a region. Persistent regions do not require a
// geomonitor_service_t to be initialized.
geomonitor_region_set_monitoring_mode( region,
GEOMONITOR_MONITORING_MODE_PERSISTENT);
// Set notification invoke target. This notification is pushed to the Hub
// where the user taps on it and an application is launched.
// Note! Application has to be registered with the invocation framework
// and to have "blackberry.sample.myapp" - as a valid invoke target.
geomonitor_region_set_notification_invoke_target(region,
"blackberry.sample.myapp",
GEOMONITOR_NOTIFICATION_UIB);
// Set Hub notification message content.
geomonitor_region_set_notification_message(region, "Message content");
// Set the expiration of the region. Convert the date/time of the expiration
// to its UTC equivalent. For example, to set the expiration of the region to
// November 7, 2012 at 16:34:45, use the UTC value 1352306085.
geomonitor_region_set_expiration(region, 1352306085);
// Remove the monitored region once device leaves the region.
geomonitor_region_set_stop_monitoring_event(region,
GEOMONITOR_EVENT_TYPE_EXIT);
// 3. Add the region and start monitoring.
geomonitor_add(region);
// Release the region instance.
geomonitor_destroy_region(®ion);
// 4. Initialize BPS library
bps_initialize();
// Request geomonitor events
bps_geomonitor_request_events(0);
bps_event_t * event;
// Wait for the event
bps_get_event(&event, -1);
// Check that received event is valid and belongs to the geomonitor domain
if (bps_event_get_domain(event) == bps_geomonitor_get_domain() &&
bps_event_get_code(event) == GEOMONITOR_INFO ) {
// extract geomonitor event
geomonitor_service_event_t geomonitor_event;
geomonitor_event = bps_geomonitor_event_get_service_event(event);
// extract the event properties
geomonitor_event_type_t event_type = GEOMONITOR_EVENT_TYPE_NONE;
geomonitor_region_t region = NULL;
geomonitor_geolocation_t location = NULL;
geomonitor_service_event_get_type(geomonitor_event, &event_type);
geomonitor_service_event_get_region(geomonitor_event, ®ion);
geomonitor_service_event_get_location(geomonitor_event, &location);
// extract monitored region name and event location
char *region_name = NULL;
geomonitor_region_get_name(region, ®ion_name);
double lat = 0.0, lon = 0.0, acc = 0.0;
geomonitor_geolocation_get_latitude(location, &lat);
geomonitor_geolocation_get_longtitude(location, &lon);
geomonitor_geolocation_get_accuracy(location, &acc);
}
// 5. The region must be explicitly removed when it no longer needs
// to be monitored; otherwise it will be continuously monitored.
geomonitor_remove("Home");