Summary: Constants | Methods | Inherited Methods | [Expand All]
Since: API level 6
public class

Geofencing

extends Object
java.lang.Object
   ↳ com.samsung.android.knox.location.Geofencing

Class Overview

This class provides APIs to create, destroy and monitor geofences. Administrators can enable or disable geofencing operation, get geofencing status, device status and information about existing geofences.

A geofence is a virtual perimeter for a real world geographical area. Geofencing involves monitoring the location of any portable device to detect if it lies within or outside a created geofence and applying or revoking certain policies on the device for each respective case.

Since
API level 6
MDM 4.0

Summary

Constants
String ACTION_DEVICE_INSIDE_GEOFENCE Broadcast Action : Sent to inform administrator that the device is within a geofence.
String ACTION_DEVICE_LOCATION_UNAVAILABLE Broadcast Action : Sent to inform administrator that the device location could not be found or when no location provider is available.
String ACTION_DEVICE_OUTSIDE_GEOFENCE Broadcast Action : Sent to inform administrator that the device is outside a geofence.
String EXTRA_ID Used as an integer array extra field with ACTION_DEVICE_INSIDE_GEOFENCE.
String EXTRA_USER_ID Used as an int extra field returning the user Id in which the geofence was created
int TYPE_CIRCLE Circular Geofence with a center and radius in meters as entered by admin.
int TYPE_LINEAR Linear Geofence as a list of latitudinal and longitudinal points with a specified width on either side of the provided line.
int TYPE_POLYGON Polygonal Geofence as a list of latitudinal and longitudinal points forming a closed polygon along with an optional grace distance in meters for monitoring the location within an outer boundary of the polygon.
Public Methods
int createGeofence(Geofence geofence)
API to create a geofence either circular, polygonal, or linear.
boolean destroyGeofence(int id)
API to destroy an existing geofence.
List<Geofence> getGeofences()
API to retrieve and display existing geofences.
float getMinDistanceParameter()
API to get the currently set minimum distance interval for geofence monitoring.
long getMinTimeParameter()
API to get the minimum time interval set by calling administrator
List<Integer> isDeviceInsideGeofence()
API to check whether a device is within a created geofence.
boolean isGeofencingEnabled()
API to check whether geofencing is enabled for the calling administrator.
boolean setMinDistanceParameter(float distance)
API to set the minimum distance interval for geofence monitoring.
boolean setMinTimeParameter(long time)
API to set the minimum time interval for geofence monitoring.
boolean startGeofencing()
API to start geofence monitoring.
boolean stopGeofencing()
API to stop geofence monitoring.
[Expand]
Inherited Methods
From class java.lang.Object

Constants

public static final String ACTION_DEVICE_INSIDE_GEOFENCE

Since: API level 6

Broadcast Action : Sent to inform administrator that the device is within a geofence. Receiver must hold "com.samsung.android.knox.permission.KNOX_GEOFENCING" permission to receive this broadcast. This broadcast is sent to indicate that the device lies within one or more of the geofences created by the administrator.
The intent will have the following extra value:
EXTRA_ID indicating the list of geofence id's within which the device lies as an array of integers.

Since
API level 6
MDM 4.0
Constant Value: "com.samsung.android.knox.intent.action.DEVICE_INSIDE_GEOFENCE"

public static final String ACTION_DEVICE_LOCATION_UNAVAILABLE

Since: API level 6

Broadcast Action : Sent to inform administrator that the device location could not be found or when no location provider is available. Receiver must hold "com.samsung.android.knox.permission.KNOX_GEOFENCING" permission to receive this broadcast. This broadcast is sent to all administrators every time the device location could not be found or when no location provider is available.

Since
API level 6
MDM 4.0
Constant Value: "com.samsung.android.knox.intent.action.DEVICE_LOCATION_UNAVAILABLE"

public static final String ACTION_DEVICE_OUTSIDE_GEOFENCE

Since: API level 6

Broadcast Action : Sent to inform administrator that the device is outside a geofence. Receiver must hold "com.samsung.android.knox.permission.KNOX_GEOFENCING" permission to receive this broadcast. This broadcast is sent to indicate that the device lies within one or more of the geofences created by the administrator.

Since
API level 6
MDM 4.0
Constant Value: "com.samsung.android.knox.intent.action.DEVICE_OUTSIDE_GEOFENCE"

public static final String EXTRA_ID

Since: API level 6

Used as an integer array extra field with ACTION_DEVICE_INSIDE_GEOFENCE. Contains a list of id's of the geofences within which device is located. Retrieve it with getIntArrayExtra(String) .

Since
API level 6
MDM 4.0
Constant Value: "com.samsung.android.knox.intent.extra.ID"

public static final String EXTRA_USER_ID

Since: API level 12

Used as an int extra field returning the user Id in which the geofence was created

Since
API level 12
MDM 5.1
Constant Value: "com.samsung.android.knox.intent.extra.USER_ID"

public static final int TYPE_CIRCLE

Since: API level 6

Circular Geofence with a center and radius in meters as entered by admin.

Since
API level 6
MDM 4.0
Constant Value: 1 (0x00000001)

public static final int TYPE_LINEAR

Since: API level 6

Linear Geofence as a list of latitudinal and longitudinal points with a specified width on either side of the provided line.

Since
API level 6
MDM 4.0
Constant Value: 3 (0x00000003)

public static final int TYPE_POLYGON

Since: API level 6

Polygonal Geofence as a list of latitudinal and longitudinal points forming a closed polygon along with an optional grace distance in meters for monitoring the location within an outer boundary of the polygon.

Since
API level 6
MDM 4.0
Constant Value: 2 (0x00000002)

Public Methods

public int createGeofence (Geofence geofence)

Since: API level 6

API to create a geofence either circular, polygonal, or linear.

Parameters
geofence An object of circular, polygonal or linear geofence type
Returns
  • ID of the created geofence else returns -1
Throws
SecurityException If caller does not have required permissions
Usage
Circular Geofence
An administrator can use this API to create a geofence by specifying a latitude and longitude value as a center and a radius in meters for the circle. 

          EnterpriseDeviceManager edm = EnterpriseDeviceManager.getInstance(context); 
          Geofencing geofencingService = edm.getGeofencing();
          try {
              LatLongPoint center=new LatLongPoint(32.951496, -96.745460);
              double radius=50;
              CircularGeofence circularGeofence=new CircularGeofence(center, radius);
              int id = geofencingService.createGeofence(circularGeofence);
              return id; // Returns id of created circular geofence
          } catch (SecurityException se) {
               Log.e(TAG, "Security Exception : " + se);
          }
Polygonal Geofence
An administrator can enter three or more points to create a polygon. Edges are constructed between consecutive points and a concave, convex or intersecting polygon is created based on user input. The administrator also enters a value for the grace distance in meters which creates a boundary polygon outside the original polygon. A device lying within this boundary region is said to be within the geofence. 

 
          EnterpriseDeviceManager edm = EnterpriseDeviceManager.getInstance(context); 
          Geofencing geofencingService = edm.getGeofencing();
          try {
              List latLongPoints={(32.951496, -96.745460),(32.952504, -96.681773),
              (33.192444, -96.850370)};
              double graceDistance = 10;
              PolygonalGeofence polygonalGeofence=new PolygonalGeofence(latLongPoints, graceDistance);
              int id = geofencingService.createGeofence(polygonalGeofence);
              return id; // Returns id of created polygonal geofence
          } catch (SecurityException se) {
              Log.e(TAG, "Security Exception : " + se);
          }
Linear Geofence
An administrator can enter a sequence of two or more points that are interpreted as a series of line segments. The administrator also enters a width value in meters to specify the area above and below the series of line segments, which is considered to be part of the geofence to be monitored. 

         
          EnterpriseDeviceManager edm = EnterpriseDeviceManager.getInstance(context); 
          Geofencing geofencingService = edm.getGeofencing();
          try {
              List latLongPoints={(32.951496, -96.745460),(32.952504, -96.681773),
              (33.192444, -96.850370)};
              double width = 50;
              LinearGeofence linearGeofence=new LinearGeofence(latLongPoints, width);
              int id = geofencingService.createGeofence(linearGeofence);
              return id; // Returns id of created linear geofence
          } catch (SecurityException se) {
               Log.e(TAG, "Security Exception : " + se);
          }
For Container:
          // When you create container successfully, containerID will be returned via intent.
          // Use this containerID in below API.
          EnterpriseKnoxManager ekm = EnterpriseKnoxManager.getInstance(context);
          KnoxContainerManager kcm = ekm.getKnoxContainerManager(containerID);
          Geofencing geofencingService = kcm.getGeofencing();
          try {
              LatLongPoint center=new LatLongPoint(32.951496, -96.745460);
              double radius=50;
              CircularGeofence circularGeofence=new CircularGeofence(center, radius);
              int id = geofencingService.createGeofence(circularGeofence);
              return id; // Returns id of created circular geofence
          } catch (SecurityException se) {
               Log.e(TAG, "Security Exception : " + se);
          }
Polygonal Geofence
An administrator can enter three or more points to create a polygon. Edges are constructed between consecutive points and a concave, convex or intersecting polygon is created based on user input. The administrator also enters a value for the grace distance in meters which creates a boundary polygon outside the original polygon. A device lying within this boundary region is said to be within the geofence. 

 
          // When you create container successfully, containerID will be returned via intent.
          // Use this containerID in below API.
          EnterpriseKnoxManager ekm = EnterpriseKnoxManager.getInstance(context);
          KnoxContainerManager kcm = ekm.getKnoxContainerManager(containerID);
          Geofencing geofencingService = kcm.getGeofencing();
          try {
              List latLongPoints={(32.951496, -96.745460),(32.952504, -96.681773),
              (33.192444, -96.850370)};
              double graceDistance = 10;
              PolygonalGeofence polygonalGeofence=new PolygonalGeofence(latLongPoints, graceDistance);
              int id = geofencingService.createGeofence(polygonalGeofence);
              return id; // Returns id of created polygonal geofence
          } catch (SecurityException se) {
              Log.e(TAG, "Security Exception : " + se);
          }
Linear Geofence
An administrator can enter a sequence of two or more points that are interpreted as a series of line segments. The administrator also enters a width value in meters to specify the area above and below the series of line segments, which is considered to be part of the geofence to be monitored. 

          // When you create container successfully, containerID will be returned via intent.
          // Use this containerID in below API.
          EnterpriseKnoxManager ekm = EnterpriseKnoxManager.getInstance(context);
          KnoxContainerManager kcm = ekm.getKnoxContainerManager(containerID);
          Geofencing geofencingService = kcm.getGeofencing();
          try {
              List latLongPoints={(32.951496, -96.745460),(32.952504, -96.681773),
              (33.192444, -96.850370)};
              double width = 50;
              LinearGeofence linearGeofence=new LinearGeofence(latLongPoints, width);
              int id = geofencingService.createGeofence(linearGeofence);
              return id; // Returns id of created linear geofence
          } catch (SecurityException se) {
               Log.e(TAG, "Security Exception : " + se);
          }
Permission
The use of this API requires the caller to have the "com.samsung.android.knox.permission.KNOX_GEOFENCING" permissions with a protection level of signature
Since
API level 6
MDM 4.0
Multiuser Environment
User Scope
See Also

public boolean destroyGeofence (int id)

Since: API level 6

API to destroy an existing geofence.

Parameters
id Id of geofence to be destroyed
Returns
  • true if geofence is successfully destroyed, false if geofence cannot be destroyed.
Throws
SecurityException If caller does not have required permissions
Usage
An administrator can use this API to destroy an existing geofence. The administrator enters the Id of the geofence to be destroyed to remove it from the list of existing geofences. 

          EnterpriseDeviceManager edm = EnterpriseDeviceManager.getInstance(context); 
          Geofencing geofencingService = edm.getGeofencing();
          try {
              boolean result = geofencingService.destroyGeofence(id);
              // returns True if deleted successfully else returns False
          } catch (SecurityException se) {
              Log.e(TAG, "Security Exception : " + se);
          }
For Container:
          // When you create container successfully, containerID will be returned via intent.
          // Use this containerID in below API.
          EnterpriseKnoxManager ekm = EnterpriseKnoxManager.getInstance(context);
          KnoxContainerManager kcm = ekm.getKnoxContainerManager(containerID);
          Geofencing geofencingService = kcm.getGeofencing();
          try {
              boolean result = geofencingService.destroyGeofence(id);
              // returns True if deleted successfully else returns False
          } catch (SecurityException se) {
              Log.e(TAG, "Security Exception : " + se);
          }
Permission
The use of this API requires the caller to have the "com.samsung.android.knox.permission.KNOX_GEOFENCING" permissions with a protection level of signature
Since
API level 6
MDM 4.0
Multiuser Environment
User Scope
See Also

public List<Geofence> getGeofences ()

Since: API level 6

API to retrieve and display existing geofences.

Returns
  • List of created geofences
Throws
SecurityException If caller does not have required permissions
Usage
An administrator can view all existing geofences created by itself on a map. A list of geofences classified as circular, polygonal, or linear can be retrieved and displayed on a map. 

          EnterpriseDeviceManager edm = EnterpriseDeviceManager.getInstance(context); 
          Geofencing geofencingService = edm.getGeofencing();
          try {
              List geofences;
              geofences = geofencingService.getGeofences();
              return geofences;
          } catch (SecurityException se) {
              Log.e(TAG, "Security Exception : " + se);
          }
For Container:
          // When you create container successfully, containerID will be returned via intent.
          // Use this containerID in below API.
          EnterpriseKnoxManager ekm = EnterpriseKnoxManager.getInstance(context);
          KnoxContainerManager kcm = ekm.getKnoxContainerManager(containerID);
          Geofencing geofencingService = kcm.getGeofencing();
          try {
              List geofences;
              geofences = geofencingService.getGeofences();
              return geofences;
          } catch (SecurityException se) {
              Log.e(TAG, "Security Exception : " + se);
          }
Permission
The use of this API requires the caller to have the "com.samsung.android.knox.permission.KNOX_GEOFENCING" permissions with a protection level of signature
Since
API level 6
MDM 4.0
Multiuser Environment
User Scope
See Also

public float getMinDistanceParameter ()

Since: API level 6

API to get the currently set minimum distance interval for geofence monitoring.

Returns
  • Distance in meters or 0.0 if distance is not set.
Usage
An administrator can use this API to check the its current set minimum distance interval for geofence monitoring and configure it appropriately. If multiple administrators are present, then the strictest (lower value) will be taken.
Since
API level 6
MDM 4.0
Multiuser Environment
User Scope
See Also

public long getMinTimeParameter ()

Since: API level 6

API to get the minimum time interval set by calling administrator

Returns
  • Time in milliseconds or 0 if time is not set.
Usage
An administrator can use this API to check the its current set minimum time interval for geofence monitoring and configure it appropriately. If multiple administrators are present, then the strictest (lower value) will be taken.
Since
API level 6
MDM 4.0
Multiuser Environment
User Scope
See Also

public List<Integer> isDeviceInsideGeofence ()

Since: API level 6

API to check whether a device is within a created geofence.

Returns
  • List of geofence Ids within which a device is located or null if a device is outside all geofences.
Throws
SecurityException If caller does not have required permissions
Usage
An administrator can use this API to check whether a device is within any existing geofence.

 
          EnterpriseDeviceManager edm = EnterpriseDeviceManager.getInstance(context); 
          Geofencing geofencingService = edm.getGeofencing();
          try {
              List listOfGeofences = geofencingService.isDeviceInsideGeofence();
              //Returns list of integer Ids within which device lies if it is within a geofence or
              // empty list if the device is outside all geofences
          } catch (SecurityException se) {
              Log.e(TAG, "Security Exception : " + se);
          }
For Container:
          // When you create container successfully, containerID will be returned via intent.
          // Use this containerID in below API.
          EnterpriseKnoxManager ekm = EnterpriseKnoxManager.getInstance(context);
          KnoxContainerManager kcm = ekm.getKnoxContainerManager(containerID);
          Geofencing geofencingService = kcm.getGeofencing();
          try {
              List listOfGeofences = geofencingService.isDeviceInsideGeofence();
              //Returns list of integer Ids within which device lies if it is within a geofence or
              // empty list if the device is outside all geofences
          } catch (SecurityException se) {
              Log.e(TAG, "Security Exception : " + se);
          }
Permission
The use of this API requires the caller to have the "com.samsung.android.knox.permission.KNOX_GEOFENCING" permissions with a protection level of signature
Since
API level 6
MDM 4.0
Multiuser Environment
User Scope

public boolean isGeofencingEnabled ()

Since: API level 6

API to check whether geofencing is enabled for the calling administrator.

Returns
  • true if geofencing is enabled, false if geofencing is disabled.
Throws
SecurityException If caller does not have required permissions
Usage
An administrator can use this API to check whether geofencing is currently enabled for its geofences 

          EnterpriseDeviceManager edm = EnterpriseDeviceManager.getInstance(context); 
          Geofencing geofencingService = edm.getGeofencing();
          try {
              boolean result = geofencingService.isGeofencingEnabled();
              // Returns true if geofencing is enabled, else returns false
          } catch (SecurityException se) {
               Log.e(TAG, "Security Exception : " + se);
          }
For Container:
          // When you create container successfully, containerID will be returned via intent.
          // Use this containerID in below API.
          EnterpriseKnoxManager ekm = EnterpriseKnoxManager.getInstance(context);
          KnoxContainerManager kcm = ekm.getKnoxContainerManager(containerID);
          Geofencing geofencingService = kcm.getGeofencing();
          try {
              boolean result = geofencingService.isGeofencingEnabled();
              // Returns true if geofencing is enabled, else returns false
          } catch (SecurityException se) {
               Log.e(TAG, "Security Exception : " + se);
          }
Permission
The use of this API requires the caller to have the "com.samsung.android.knox.permission.KNOX_GEOFENCING" permissions with a protection level of signature
Since
API level 6
MDM 4.0
Multiuser Environment
User Scope
See Also

public boolean setMinDistanceParameter (float distance)

Since: API level 6

API to set the minimum distance interval for geofence monitoring.

Parameters
distance Distance in meters specified for geofence monitoring
Returns
  • true if the distance parameter is set correctly else returns false
Throws
SecurityException If caller does not have required permissions
Usage
An administrator can use this API to control how frequently geofence checks should be performed by configuring the minimum distance interval. For example, if the administrator wants to reduce the number of checks for geofence monitoring, the minimum distance parameter can be increased, thereby reducing the frequency of geofence checks.

The device performs geofence checks only when it moves at least the minimum distance. Specifying a higher value for the minimum distance parameter conserves battery life when geofencing is enabled, while specifying a lower value reduces battery life.

The administrator can specify a non-negative value as the distance parameter. If no value is set a default distance parameter of 0 meters is be used.
Permission
The use of this API requires the caller to have the "com.samsung.android.knox.permission.KNOX_GEOFENCING" permissions with a protection level of signature
Since
API level 6
MDM 4.0
Multiuser Environment
User Scope
See Also

public boolean setMinTimeParameter (long time)

Since: API level 6

API to set the minimum time interval for geofence monitoring.

Parameters
time Time interval in milliseconds for geofence monitoring
Returns
  • true if time parameter is set correctly else returns false.
Throws
SecurityException If caller does not have required permissions
Usage
An administrator can use this API to control how frequently geofence checks should be performed by configuring the minimum time interval. For example, if the administrator wants to reduce the number of checks for geofence monitoring, the minimum time parameter can be increased, thereby reducing the frequency of geofence checks.

The elapsed time between geofence checks is never less than the minimum time. Specifying a higher value for the minimum time parameter conserves battery life when geofencing is enabled, while specifying a lower value reduces battery life.

The administrator can specify a non-negative value as the time parameter. If no value is set or on 0 value a default time parameter of 60000 milliseconds will be used.
Permission
The use of this API requires the caller to have the "com.samsung.android.knox.permission.KNOX_GEOFENCING" permissions with a protection level of signature
Since
API level 6
MDM 4.0
Multiuser Environment
User Scope
See Also

public boolean startGeofencing ()

Since: API level 6

API to start geofence monitoring.

Returns
  • true if geofencing is successfully enabled, false if geofencing cannot be started or or administrator does not have any geofence created.
Throws
SecurityException If caller does not have required permissions
Usage
An administrator can use this API to start geofence monitoring. The device is monitored for location updates based on administrator-set parameters for minimum distance and minimum time, after which the device is checked as to whether it is within any geofence. If the administrator does not set these values prior to starting geofencing, default parameters for time and distance are set to 60000 milliseconds and 0 meters respectively. If device enters a geofence, leaves a geofence or is such that it cannot receive location updates, respective broadcasts indicating these conditions are sent to the administrator. If multiple administrators are present, then the strictest (lower value) will be taken for time and distance

 
          EnterpriseDeviceManager edm = EnterpriseDeviceManager.getInstance(context); 
          Geofencing geofencingService = edm.getGeofencing();
          try {
              boolean result = geofencingService.startGeofencing();
              // Returns true on starting geofencing successfully, else returns false
          } catch (SecurityException se) {
              Log.e(TAG, "Security Exception : " + se);
          }
For Container:
          // When you create container successfully, containerID will be returned via intent.
          // Use this containerID in below API.
          EnterpriseKnoxManager ekm = EnterpriseKnoxManager.getInstance(context);
          KnoxContainerManager kcm = ekm.getKnoxContainerManager(containerID);
          Geofencing geofencingService = kcm.getGeofencing();
          try {
              boolean result = geofencingService.startGeofencing();
              // Returns true on starting geofencing successfully, else returns false
          } catch (SecurityException se) {
              Log.e(TAG, "Security Exception : " + se);
          }
Permission
The use of this API requires the caller to add the "com.samsung.android.knox.permission.KNOX_GEOFENCING" permissions with a protection level of signature
Since
API level 6
MDM 4.0
Multiuser Environment
User Scope
See Also

public boolean stopGeofencing ()

Since: API level 6

API to stop geofence monitoring.

Returns
  • true if geofencing is successfully disabled, false if geofencing cannot be stopped or administrator does not have any geofence created.
Throws
SecurityException If caller does not have required permissions
Usage
An administrator can stop geofence monitoring. All requests for location updates will be stopped and the administrator will no longer receive notifications of the device being inside or outside a geofence. 

          EnterpriseDeviceManager edm = EnterpriseDeviceManager.getInstance(context); 
          Geofencing geofencingService = edm.getGeofencing();
          try {
              boolean result = geofencingService.stopGeofencing();
              // Returns true on stopping geofencing successfully, else returns false
          } catch (SecurityException se) {
              Log.e(TAG, "Security Exception : " + se);
          }
For Container:
          // When you create container successfully, containerID will be returned via intent.
          // Use this containerID in below API.
          EnterpriseKnoxManager ekm = EnterpriseKnoxManager.getInstance(context);
          KnoxContainerManager kcm = ekm.getKnoxContainerManager(containerID);
          Geofencing geofencingService = kcm.getGeofencing();
          try {
              boolean result = geofencingService.stopGeofencing();
              // Returns true on stopping geofencing successfully, else returns false
          } catch (SecurityException se) {
              Log.e(TAG, "Security Exception : " + se);
          }
Permission
The use of this API requires the caller to have the "com.samsung.android.knox.permission.KNOX_GEOFENCING" permissions with a protection level of signature
Since
API level 6
MDM 4.0
Multiuser Environment
User Scope
See Also