Tizen Native API  7.0

The Geofence defines a virtual perimeter.

Required Header

#include <geofence_manager.h>

Overview

Geofence defines a virtual perimeter for a real-world geographic area. If you create a geofence, you can trigger some activities when a device enters(or exits) the geofence defined by you. You can create a geofence with the information of Geopoint, Wi-Fi, or BT. 1. Geopoint: Geofence is specified by coordinates (Latitude and Longitude) and Radius
2. WIFI: Geofence is specified by BSSID of Wi-Fi access point
3. BT: Geofence is specified by Bluetooth address
Basic service set identification (BSSID): The BSSID is the MAC address of the wireless access point (WAP) generated by combining the 24 bit Organization Unique Identifier (the manufacturer's identity) and the manufacturer's assigned 24-bit identifier for the radio chipset in the WAP.

Related Features

This API is related with the following features:

  • http://tizen.org/feature/location
  • http://tizen.org/feature/location.geofence

It is recommended to design feature related codes in your application for reliability.
You can check if a device supports the related features for this API by using System Information, thereby controlling the procedure of your application.
To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.
More details on featuring your application can be found from Feature Element.

Functions

int geofence_create_geopoint (int place_id, double latitude, double longitude, int radius, const char *address, geofence_h *fence)
 Creates a geopoint type of new geofence.
int geofence_create_bluetooth (int place_id, const char *bssid, const char *ssid, geofence_h *fence)
 Creates a bluetooth type of new geofence.
int geofence_create_wifi (int place_id, const char *bssid, const char *ssid, geofence_h *fence)
 Creates a Wi-Fi type of new geofence.
int geofence_destroy (geofence_h fence)
 Releases the geofence.
int geofence_get_type (geofence_h fence, geofence_type_e *type)
 Gets the type of geofence.
int geofence_get_place_id (geofence_h fence, int *place_id)
 Gets the ID of place.
int geofence_get_latitude (geofence_h fence, double *latitude)
 Gets the latitude of geofence.
int geofence_get_longitude (geofence_h fence, double *longitude)
 Gets the longitude of geofence.
int geofence_get_radius (geofence_h fence, int *radius)
 Gets the radius of geofence.
int geofence_get_address (geofence_h fence, char **address)
 Gets the address of geofence.
int geofence_get_bssid (geofence_h fence, char **bssid)
 Gets the bssid of geofence.
int geofence_get_ssid (geofence_h fence, char **ssid)
 Gets the ssid of geofence.
int geofence_status_create (int geofence_id, geofence_status_h *status)
 Returns The geofence status of specified geofence.
int geofence_status_destroy (geofence_status_h status)
 Releases the memory, used by the status data.
int geofence_status_get_state (geofence_status_h status, geofence_state_e *state)
 Gets the state of geofence.
int geofence_status_get_duration (geofence_status_h status, int *seconds)
 Gets the amount of seconds geofence is in the current state.

Function Documentation

int geofence_create_bluetooth ( int  place_id,
const char *  bssid,
const char *  ssid,
geofence_h fence 
)

Creates a bluetooth type of new geofence.

Since :
2.4
Remarks:
The fence must be released using geofence_destroy().
Since 3.0, http://tizen.org/privilege/location privilege is not required.
Parameters:
[in]place_idThe current place ID
[in]bssidSpecifies the value of BSSID of BT MAC address
[in]ssidSpecifies the value of SSID of BT Device
[out]fenceA geofence handle to be newly created on success
Returns:
0 on success, otherwise a negative error value
Return values:
GEOFENCE_MANAGER_ERROR_NONESuccessful
GEOFENCE_MANAGER_ERROR_INVALID_PARAMETERIllegal argument
GEOFENCE_MANAGER_ERROR_NOT_SUPPORTEDNot supported
GEOFENCE_MANAGER_ERROR_PERMISSION_DENIEDThe application does not have the privilege to call this function
GEOFENCE_MANAGER_ERROR_EXCEPTIONException occurred
GEOFENCE_MANAGER_ERROR_PLACE_ACCESS_DENIEDAccess to specified place is denied
See also:
geofence_create_geopoint()
geofence_create_wifi()
geofence_destroy()
int geofence_create_geopoint ( int  place_id,
double  latitude,
double  longitude,
int  radius,
const char *  address,
geofence_h fence 
)

Creates a geopoint type of new geofence.

Since :
2.4
Remarks:
The fence must be released using geofence_destroy().
Since 3.0, http://tizen.org/privilege/location privilege is not required.
Parameters:
[in]place_idThe current place ID
[in]latitudeSpecifies the value of latitude of geofence [-90.0 ~ 90.0] (degrees)
[in]longitudeSpecifies the value of longitude of geofence [-180.0 ~ 180.0] (degrees)
[in]radiusSpecifies the value of radius of geofence [100 ~ 500](meter)
[in]addressSpecifies the value of address
[out]fenceA geofence handle to be newly created on success
Returns:
0 on success, otherwise a negative error value
Return values:
GEOFENCE_MANAGER_ERROR_NONESuccessful
GEOFENCE_MANAGER_ERROR_INVALID_PARAMETERIllegal argument
GEOFENCE_MANAGER_ERROR_NOT_SUPPORTEDNot supported
GEOFENCE_MANAGER_ERROR_PERMISSION_DENIEDThe application does not have the privilege to call this function
GEOFENCE_MANAGER_ERROR_EXCEPTIONException occurred
GEOFENCE_MANAGER_ERROR_PLACE_ACCESS_DENIEDAccess to specified place is denied
See also:
geofence_create_bluetooth()
geofence_create_wifi()
geofence_destroy()
int geofence_create_wifi ( int  place_id,
const char *  bssid,
const char *  ssid,
geofence_h fence 
)

Creates a Wi-Fi type of new geofence.

Since :
2.4
Remarks:
The fence must be released using geofence_destroy().
Since 3.0, http://tizen.org/privilege/location privilege is not required.
Parameters:
[in]place_idThe current place ID
[in]bssidSpecifies the value of BSSID of Wi-Fi MAC address
[in]ssidSpecifies the value of SSID of Wi-Fi Device
[out]fenceA geofence handle to be newly created on success
Returns:
0 on success, otherwise a negative error value
Return values:
GEOFENCE_MANAGER_ERROR_NONESuccessful
GEOFENCE_MANAGER_ERROR_INVALID_PARAMETERIllegal argument
GEOFENCE_MANAGER_ERROR_NOT_SUPPORTEDNot supported
GEOFENCE_MANAGER_ERROR_PERMISSION_DENIEDThe application does not have the privilege to call this function
GEOFENCE_MANAGER_ERROR_EXCEPTIONException occurred
GEOFENCE_MANAGER_ERROR_PLACE_ACCESS_DENIEDAccess to specified place is denied
See also:
geofence_create_geopoint()
geofence_create_bluetooth()
geofence_destroy()
int geofence_destroy ( geofence_h  fence)

Releases the geofence.

Since :
2.4
Remarks:
Since 3.0, http://tizen.org/privilege/location privilege is not required.
Parameters:
[in]fenceThe geofence handle
Returns:
0 on success, otherwise a negative error value
Return values:
GEOFENCE_MANAGER_ERROR_NONESuccessful
GEOFENCE_MANAGER_ERROR_INVALID_PARAMETERIllegal argument
GEOFENCE_MANAGER_ERROR_NOT_SUPPORTEDNot supported
GEOFENCE_MANAGER_ERROR_PERMISSION_DENIEDThe application does not have the privilege to call this function
See also:
geofence_create_geopoint()
geofence_create_bluetooth()
geofence_create_wifi()
int geofence_get_address ( geofence_h  fence,
char **  address 
)

Gets the address of geofence.

Since :
2.4
Remarks:
The geofence has address only when geofence_type_e is GEOFENCE_TYPE_GEOPOINT. The address must be released using free().
Parameters:
[in]fenceThe geofence handle
[out]addressSpecifies the value of address
Returns:
0 on success, otherwise a negative error value
Return values:
GEOFENCE_MANAGER_ERROR_NONESuccessful
GEOFENCE_MANAGER_ERROR_INVALID_PARAMETERIllegal argument
GEOFENCE_MANAGER_ERROR_NOT_SUPPORTEDNot supported
See also:
geofence_get_latitude()
geofence_get_longitude()
geofence_get_radius()
geofence_get_type()
geofence_create_geopoint()
int geofence_get_bssid ( geofence_h  fence,
char **  bssid 
)

Gets the bssid of geofence.

Since :
2.4
Remarks:
The geofence has bssid only when geofence_type_e is GEOFENCE_TYPE_BLUETOOTH or GEOFENCE_TYPE_WIFI. The bssid must be released using free().
Parameters:
[in]fenceThe geofence handle
[out]bssidThe bssid of geofence
Returns:
0 on success, otherwise a negative error value
Return values:
GEOFENCE_MANAGER_ERROR_NONESuccessful
GEOFENCE_MANAGER_ERROR_INVALID_PARAMETERIllegal argument
GEOFENCE_MANAGER_ERROR_NOT_SUPPORTEDNot supported
See also:
geofence_get_type()
geofence_create_bluetooth()
geofence_create_wifi()
geofence_get_ssid()
int geofence_get_latitude ( geofence_h  fence,
double *  latitude 
)

Gets the latitude of geofence.

Since :
2.4
Remarks:
The geofence has latitude only when geofence_type_e is GEOFENCE_TYPE_GEOPOINT.
Parameters:
[in]fenceThe geofence handle
[out]latitudeThe latitude of geofence
Returns:
0 on success, otherwise a negative error value
Return values:
GEOFENCE_MANAGER_ERROR_NONESuccessful
GEOFENCE_MANAGER_ERROR_INVALID_PARAMETERIllegal argument.
GEOFENCE_MANAGER_ERROR_NOT_SUPPORTEDNot supported
See also:
geofence_get_longitude()
geofence_get_radius()
geofence_get_address()
geofence_get_type()
geofence_create_geopoint()
int geofence_get_longitude ( geofence_h  fence,
double *  longitude 
)

Gets the longitude of geofence.

Since :
2.4
Remarks:
The geofence has longitude only when geofence_type_e is GEOFENCE_TYPE_GEOPOINT.
Parameters:
[in]fenceThe geofence handle
[out]longitudeThe longitude of geofence
Returns:
0 on success, otherwise a negative error value
Return values:
GEOFENCE_MANAGER_ERROR_NONESuccessful
GEOFENCE_MANAGER_ERROR_INVALID_PARAMETERIllegal argument
GEOFENCE_MANAGER_ERROR_NOT_SUPPORTEDNot supported
See also:
geofence_get_latitude()
geofence_get_radius()
geofence_get_address()
geofence_get_type()
geofence_create_geopoint()
int geofence_get_place_id ( geofence_h  fence,
int *  place_id 
)

Gets the ID of place.

Since :
2.4
Parameters:
[in]fenceThe geofence handle
[out]place_idThe ID of the place
Returns:
0 on success, otherwise a negative error value
Return values:
GEOFENCE_MANAGER_ERROR_NONESuccessful
GEOFENCE_MANAGER_ERROR_INVALID_PARAMETERIllegal argument
GEOFENCE_MANAGER_ERROR_NOT_SUPPORTEDNot supported
See also:
geofence_create_geopoint()
geofence_create_bluetooth()
geofence_create_wifi()
int geofence_get_radius ( geofence_h  fence,
int *  radius 
)

Gets the radius of geofence.

Since :
2.4
Remarks:
The geofence has radius only when geofence_type_e is GEOFENCE_TYPE_GEOPOINT.
Parameters:
[in]fenceThe geofence handle
[out]radiusThe radius of geofence
Returns:
0 on success, otherwise a negative error value
Return values:
GEOFENCE_MANAGER_ERROR_NONESuccessful
GEOFENCE_MANAGER_ERROR_INVALID_PARAMETERIllegal argument
GEOFENCE_MANAGER_ERROR_NOT_SUPPORTEDNot supported
See also:
geofence_get_latitude()
geofence_get_longitude()
geofence_get_address()
geofence_get_type()
geofence_create_geopoint()
int geofence_get_ssid ( geofence_h  fence,
char **  ssid 
)

Gets the ssid of geofence.

Since :
2.4
Remarks:
The geofence has ssid only when geofence_type_e is GEOFENCE_TYPE_BLUETOOTH or GEOFENCE_TYPE_WIFI. The ssid must be released using free().
Parameters:
[in]fenceThe geofence handle
[out]ssidThe ssid of geofence
Returns:
0 on success, otherwise a negative error value
Return values:
GEOFENCE_MANAGER_ERROR_NONESuccessful
GEOFENCE_MANAGER_ERROR_INVALID_PARAMETERIllegal argument
GEOFENCE_MANAGER_ERROR_NOT_SUPPORTEDNot supported
See also:
geofence_get_type()
geofence_create_bluetooth()
geofence_create_wifi()
geofence_get_bssid()
int geofence_get_type ( geofence_h  fence,
geofence_type_e type 
)

Gets the type of geofence.

Since :
2.4
Parameters:
[in]fenceThe geofence handle
[out]typeThe type of geofence
Returns:
0 on success, otherwise a negative error value
Return values:
GEOFENCE_MANAGER_ERROR_NONESuccessful
GEOFENCE_MANAGER_ERROR_INVALID_PARAMETERIllegal argument
GEOFENCE_MANAGER_ERROR_NOT_SUPPORTEDNot supported
See also:
geofence_get_geopoint()
geofence_get_radius()
geofence_get_bssid()
int geofence_status_create ( int  geofence_id,
geofence_status_h status 
)

Returns The geofence status of specified geofence.

Since :
2.4
Remarks:
A status must be released using geofence_status_destroy()
Parameters:
[in]geofence_idThe geofence ID
[out]statusThe status handle of a specified geofence
Returns:
0 on success, otherwise a negative error value
Return values:
GEOFENCE_MANAGER_ERROR_NONESuccessful
GEOFENCE_MANAGER_ERROR_INVALID_PARAMETERIllegal argument
GEOFENCE_MANAGER_ERROR_PERMISSION_DENIEDThe application does not have the privilege to call this function
GEOFENCE_MANAGER_ERROR_NOT_SUPPORTEDNot supported
GEOFENCE_MANAGER_ERROR_GEOFENCE_ACCESS_DENIEDAccess to specified geofence is denied
See also:
geofence_status_destroy()
geofence_manager_start()
geofence_manager_stop()

Releases the memory, used by the status data.

Since :
2.4
Parameters:
[in]statusThe status handle of a specified geofence
Returns:
0 on success, otherwise a negative error value
Return values:
GEOFENCE_MANAGER_ERROR_NONESuccessful
GEOFENCE_MANAGER_ERROR_INVALID_PARAMETERIllegal argument
GEOFENCE_MANAGER_ERROR_NOT_SUPPORTEDNot supported
See also:
geofence_status_create()
geofence_status_get_state()
geofence_status_get_duration()
int geofence_status_get_duration ( geofence_status_h  status,
int *  seconds 
)

Gets the amount of seconds geofence is in the current state.

Since :
2.4
Parameters:
[in]statusThe geofence status handle
[out]secondsThe amount of seconds geofence is in the current state
Returns:
0 on success, otherwise a negative error value
Return values:
GEOFENCE_MANAGER_ERROR_NONESuccessful
GEOFENCE_MANAGER_ERROR_INVALID_PARAMETERIllegal argument
GEOFENCE_MANAGER_ERROR_NOT_SUPPORTEDNot supported
See also:
geofence_status_get_state()

Gets the state of geofence.

Since :
2.4
Parameters:
[in]statusThe geofence status handle
[out]stateThe state of geofence
Returns:
0 on success, otherwise a negative error value
Return values:
GEOFENCE_MANAGER_ERROR_NONESuccessful
GEOFENCE_MANAGER_ERROR_INVALID_PARAMETERIllegal argument
GEOFENCE_MANAGER_ERROR_NOT_SUPPORTEDNot supported
See also:
geofence_status_get_duration()