Geofence: Creating and Using Geofences

This tutorial demonstrates how you can implement geofence-related information and services.

This feature is supported in mobile applications only.

Warm-up

Become familiar with Geofence API basics by learning about:

Initializing the Geofence Service
Create the geofence, start the geofence service, and stop it when no longer needed.
Getting the Geofence Event State
Get the success or failure state of each event.
Getting Geofence Alerts
Define the geofence and track state changes.
Tracking the User for Geofence Alerts
Track the user location and update the geofence state.
Retrieving Geofence Information
Get information on geofences.

Initializing the Geofence Service

To initialize the geofence features:

To use the functions and data types of the Geofence Manager API, include the <geofence_manager.h> header file in your application:
```
#include <geofence_manager.h>
```
Create a geofence manager handle using the geofence_manager_create() function:
```
geofence_manager_h manager;
geofence_manager_create(&manager);
```
Each geofence manager is an independent service. The callbacks are set for a given geofence manager and are called only if the service is started by their manager.
Create a place to be used for the geofences:
```
int place_id = -1; // This is for creating a place
geofence_manager_add_place(manager, "place_name", &place_id);
```
Note

A place is used to accommodate a number of geofences and is identified by a place ID. Each place can have a name. A geofence is identified by a geofence ID.

Note
A place is used to accommodate a number of geofences and is identified by a place ID. Each place can have a name. A geofence is identified by a geofence ID.

Create the geofences:

// Geopoint geofence
double latitude = 12.756738;
double longitude = 77.386474;
int radius = 100;
char* address = "India"; 
geofence_h fence_h;
geofence_create_geopoint(place_id, latitude, longitude, radius, address, &fence_h);

// Wi-Fi/BT geofence
char* bssid = "82:45:67:7E:4A:3B";
char* ssid = "Cafeteria";
geofence_h fence_h;
geofence_create_bluetooth(place_id, bssid, ssid, &fence_h);

Add the geofence to the manager:

int geofence_id = -1;
geofence_manager_add_fence(manager, fence_h, &geofence_id);

Start the geofence service using the geofence_manager_start() function.

This call is asynchronous and only initiates the process of starting the service. Once the service is started, the registered callbacks are invoked when their corresponding events take place. To know when the service becomes enabled, use the geofence_manager_set_geofence_state_changed_cb() callback.
```
geofence_manager_start(manager, geofence_id);
```
Using the geofence service for geopoints is power consuming, so if the service is not used, stop the status alerts using the geofence_manager_stop() function. Call the geofence_manager_start() function again if the alerts are needed.
```
geofence_manager_stop(manager, geofence_id);
```
Destroy all used resources, such as the geofence manager handle, using the geofence_manager_destroy() function:
```
geofence_manager_destroy(manager);
manager = NULL;
```
If you destroy the handle, there is no need to call the geofence_manager_stop() function to stop the service as the service is automatically stopped. Also, you do not have to unset the previously set callbacks.

Getting the Geofence Event State

To get the state of all geofence events, use the geofence event callback. The geofence event callback is invoked whenever there is a request from the user, for example, to add a geofence or to start a geofence service.

Register the callback using the geofence_manager_set_geofence_event_cb() function:
```
geofence_manager_set_geofence_event_cb(manager, geofence_event, NULL);
```

Get the success or failure state of the event in the callback:

geofence_manage_e user_action;
geofence_error_e user_error;
void 
geofence_event(int place_id, int geofence_id, geofence_manager_error_e error, 
               geofence_manage_e manage, void *user_data)
{
   user_action = manage;
   user_error = error;
}

Note
This event callback is used to let the user know whether the request is successful in the server side. This event callback is invoked only in case of an asynchronous API. In case of a synchronous API, an error is immediately returned.

Getting Geofence Alerts

To get alerts of the geofence state changes, use the geofence state callback. There is no periodic call, but the callback is invoked if there is a state change. The callback is called only if the geofence service has been started.

geofence_manager_set_geofence_state_changed_cb(manager, geofence_state_changed, NULL);

When the alert is received, you can use the callback to, for example, update the variables that store the current state:

geofence_state_e received_state;
void 
geofence_state_changed(int geofence_id, geofence_state_e state, void *user_data)
{
   received_state = state;
}

Tracking the User for Geofence Alerts

To get information about the in or out state for the geofence:

Receive event-based notifications:
1. You can get notifications about the in or out state updates using the state update callback. The callback is invoked on an event, receiving the current state of the user with respect to geofences with each call.
  
  Register the geofence state update callback using the geofence_manager_set_geofence_state_changed_cb() function.
```
geofence_manager_set_geofence_state_changed_cb(manager, geofence_state_changed, NULL);
```
2. Define the callback function:
```
void 
geofence_state_changed(int geofence_id, geofence_state_e state, void *user_data) {}
```
Receive the current state on request.

You can get the current state of the user with respect to a fence, such as the in or out state and the duration of the current state.
- To access the state or the duration, first create a state handle:
```
int geofence_id = 1;
geofence_status_h status_h;
geofence_status_create(geofence_id, &status_h);
geofence_status_destroy(status_h);
```
- To get the current state, call the geofence_status_get_state() function:
```
geofence_state_e state;
geofence_status_get_state(status_h, &state);
```
- To get the duration of the current state, call the geofence_status_get_duration() function:
```
int duration;
geofence_status_get_duration(status_h, &duration);
```
  The duration is provided in seconds.

Retrieving Geofence Information

To get information about the geofence:

Get common information (such as the type and place) about the geofences:

geofence_type_e type;
int place_id;
geofence_get_type(fence_h, &type);
geofence_get_place_id(fence_h, &place_id);

Retrieve the geopoint geofence information:

double latitude;
double longitude;
int radius;
char *address;
geofence_get_latitude(fence_h, &latitude);
geofence_get_longitude(fence_h, &longitude);
geofence_get_radius(fence_h, &radius);
geofence_get_address(fence_h, &address);

Retrieve the Wi-Fi or Bluetooth geofence information:

char *bssid;
char *ssid;
geofence_get_bssid(fence_h, &bssid);
geofence_get_sssid(fence_h, &ssid);