# Geofencing Library

A library for the geomonitor service.

The geomonitor service API provide functions to create virtual perimeters (regions) for real-world geographic areas. Perimeters are monitored by the geomonitor service and applications receive online (via geomonitor events) or offline (via invocation framework) notifications when the device enters or exits the observed perimeters.

A region is defined by its name (which must be unique in the scope of the application) and location.

A geomonitoring event consists of a region, event type, and the location where the event occurred.

To use the geomonitor service API functions, the application must have `access_location_services` capability. To grant an application `access_location_services` capability, the BAR application descriptor file (bar-descriptor.xml) in the application's project must contain the line "<permission>access_location_services</permission>".

The following sample code demonstrates how to use this library to create and add a region for monitoring:

      // Scenario #1 (Persistent region monitoring)

      // 1. Create a new region, give it a name and set its location.

      geomonitor_region_t region = NULL;
      geomonitor_create_region(&region, "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
      // directly to the application.
      // 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_DIRECT);

      // 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.
      // Note! This will not remove the region from the list of
      // monitored regions.
      geomonitor_destroy_region(&region);

      // 4. Initialize the geomonitor service handle and wait for
      //    notifications.

      // Declare and initialize service.
      geomonitor_service_t geomonitor = NULL;
      geomonitor_service_initialize(&geomonitor);

      // Get service fd.
      int fd = 0;
      geomonitor_service_get_fd(geomonitor, &fd);

      // Wait for the notification.
      fd_set fds;
      FD_ZERO( &fds );
      FD_SET( fd, &fds );
      while ( select( fd+1, &fds, NULL, NULL, NULL ) > 0)
      {
          if (FD_ISSET(fd, &fds)) {
              // Read and parse the notifications.
              geomonitor_service_event_t event = NULL;
              geomonitor_service_get_event(geomonitor, &event);

              // Get region, event type, and location.
              geomonitor_event_type_t event_type =
                                          GEOMONITOR_EVENT_TYPE_NONE;
              geomonitor_service_event_get_type(event, &event_type);
              geomonitor_region_t event_region = NULL;
              geomonitor_service_event_get_region(event, &event_region );
              geomonitor_geolocation_t event_location = NULL;
              geomonitor_service_event_get_location(event, &event_location);

              // Handle event here
              // ...
              // and release the geomonitor event
              geomonitor_service_destroy_event(&event);
          }
      }
      // 5. Shut down the geomonitor service handle and remove the region.

      geomonitor_service_shutdown(&geomonitor);
      // The region must be explicitly removed when it no longer needs
      // to be monitored; otherwise it will be continuously monitored.
      geomonitor_remove("Home");

      // Scenario #2 (Transient region monitoring)

      // 1. Initialize the geomonitor service handle and get fd.

      // Declare and initialize service.
      geomonitor_service_t geomonitor = NULL;
      geomonitor_service_initialize(&geomonitor);

      // Get service fd.
      int fd = 0;
      geomonitor_service_get_fd(geomonitor, &fd);

      // 2. Create a new region, give it a name and set its location.

      // Note! Default monitoring state is transient so there is no
      // need to set it explicitly.
      geomonitor_region_t region = NULL;
      geomonitor_create_region(&region, "Home");
      geomonitor_region_set_circle_shape(region, 45.342102,
                                         -75.770581, 200.0);

      // 3. Add the region and start monitoring.

      geomonitor_add(region);

      // Release the region.
      // Note! This will not remove the region from the list of
      // monitored regions.
      geomonitor_destroy_region(&region);

      // 4. Wait for notifications, get an event and handle it.

      // Wait for the notification.
      fd_set fds;
      FD_ZERO( &fds );
      FD_SET( fd, &fds );
      while ( select( fd+1, &fds, NULL, NULL, NULL ) > 0)
      {
          if (FD_ISSET(fd, &fds)) {
              // Read/parse the notifications, handle the event
              // and release it afterwards
              // ...
          }
      }

      // 5. Shut down the geomonitor service handle and
      //    remove the region.

      // Note! When the last geomonitor instance is shut down, all
      // the regions in the GEOMONITOR_MONITORING_MODE_TRANSIENT will
      // be removed automatically.
      geomonitor_service_shutdown(&geomonitor);