You can define an area to monitor by specifying the geographic coordinates of a location and a radius around that location, or you can specify a set of coordinates representing a polygon. When you specify a set of coordinates representing a polygon, you must ensure that none of the lines intersect, or else the geofenced area might not trigger events correctly. Each coordinate in the array is joined to the coordinate that follows it with a straight line. The last coordinate in the array is joined to the first.

// Single Coordinates object, to be used along with a radius

Coordinates coords = new Coordinates(43.2750, -80.3318, 0);


// Array of three Coordinates objects, representing a three-sided polygon

Coordinates[] coords2 = new Coordinates[3];
coords2[0] = new Coordinates(43.2851, -80.3229, 0);
coords2[1] = new Coordinates(43.2945, -80.3220, 0);
coords2[2] = new Coordinates(43.2852, -80.3199, 0);

When you invoke monitorPerimeter(), you must pass in a reference to the class that implements GeofenceListener as an argument. You must also specify a tag for the area, a buffer around the area, and the length of time that you want to monitor that area. Use the tag to provide a unique description of the area. Use the buffer to define a distance around the perimeter where geofencing notifications can't occur, which can help prevent the application from broadcasting notifications repeatedly when a device user repeatedly leaves and reenters the area.

GFListener gfListener = new GFListener();
Geofence geofence = new Geofence();

// Starts monitoring the area defined by the coordinate and a radius

geofence.monitorPerimeter(gfListener, "RIM 12", coords, 500, 50, -1);

// Starts monitoring the area defined by the set of coordinates

geofence.monitorPerimeter(gfListener, "RIM campus", coords2, 50, -1);

To receive proximity alerts, implement the GeofenceListener interface, which contains three methods: errorOccurred(), perimeterEntered(), and perimeterExited(). When an area is being monitored, the application invokes one of these methods when the appropriate event occurs. The perimeterEntered() and perimeterExited() methods receive as parameters the tag for the location and a BlackBerryLocation object that represents where the user enters or leaves. You can use this information to describe the area that is being entered, or to center a map on the location.

private class GFListener implements GeofenceListener
{
    public void perimeterEntered(String tag, BlackBerryLocation location)
    {
        // Code that runs when a user enters the perimeter      
    }

    public void errorOccurred(int errorCode)
    {
        // Code that runs when an error occurs
    }

    public void perimeterExited(String tag, BlackBerryLocation location)
    {
        // Code that runs when a user leaves the perimeter     
    }
}