Tizen Native API
|
Functions | |
int | geofence_manager_is_supported (bool *supported) |
Checks whether the geofence manager is available or not. | |
int | geofence_manager_create (geofence_manager_h *manager) |
Creates a new geofence manager. | |
int | geofence_manager_destroy (geofence_manager_h manager) |
Releases the geofence manager. | |
int | geofence_manager_start (geofence_manager_h manager, int geofence_id) |
Starts the geofencing service. | |
int | geofence_manager_stop (geofence_manager_h manager, int geofence_id) |
Stops the geofenceing service. | |
int | geofence_manager_add_place (geofence_manager_h manager, const char *place_name, int *place_id) |
Creates a new place for geofencing service. | |
int | geofence_manager_update_place (geofence_manager_h manager, int place_id, const char *place_name) |
Updates the place name of a given place id. | |
int | geofence_manager_remove_place (geofence_manager_h manager, int place_id) |
Removes the specific place for geofencing service. | |
int | geofence_manager_add_fence (geofence_manager_h manager, const geofence_h fence, int *geofence_id) |
Adds a geofence for a given geofence manager. | |
int | geofence_manager_remove_fence (geofence_manager_h manager, int geofence_id) |
Removes a geofence with a given geofence id. | |
int | geofence_manager_set_geofence_state_changed_cb (geofence_manager_h manager, geofence_state_changed_cb callback, void *user_data) |
Registers a callback function to be invoked when a device enters or exits the specific geofence. | |
int | geofence_manager_unset_geofence_state_changed_cb (geofence_manager_h manager) |
Unregisters the callback function. | |
int | geofence_manager_set_geofence_event_cb (geofence_manager_h manager, geofence_event_cb callback, void *user_data) |
Registers a callback function to be invoked when a response comes. | |
int | geofence_manager_unset_geofence_event_cb (geofence_manager_h manager) |
Unregisters the callback function. | |
int | geofence_manager_foreach_geofence_list (geofence_manager_h manager, geofence_manager_fence_cb callback, void *user_data) |
Retrieves a list of fences registered in the specified geofence manager. | |
int | geofence_manager_foreach_place_geofence_list (geofence_manager_h manager, int place_id, geofence_manager_fence_cb callback, void *user_data) |
Retrieves a list of fences registered in the specified place. | |
int | geofence_manager_foreach_place_list (geofence_manager_h manager, geofence_manager_place_cb callback, void *user_data) |
Retrieves a list of place registered in the specified geofence manager. | |
int | geofence_manager_get_place_name (geofence_manager_h manager, int place_id, char **place_name) |
Gets the name of place. | |
Typedefs | |
typedef void(* | geofence_state_changed_cb )(int geofence_id, geofence_state_e state, void *user_data) |
Called when a device enters or exits the given geofence. | |
typedef void(* | geofence_event_cb )(int place_id, int geofence_id, geofence_manager_error_e error, geofence_manage_e manage, void *user_data) |
Called when the some event occurs in geofence and place such as add, update, etc.. | |
typedef bool(* | geofence_manager_fence_cb )(int geofence_id, geofence_h fence, int fence_index, int fence_cnt, void *user_data) |
Called when the fence list is requested. | |
typedef bool(* | geofence_manager_place_cb )(int place_id, const char *place_name, int place_index, int place_cnt, void *user_data) |
Called when the place list is requested. | |
typedef struct geofence_manager_s * | geofence_manager_h |
The geofence manager handle. | |
typedef struct geofence_s * | geofence_h |
The geofence handle. | |
typedef struct geofence_status_s * | geofence_status_h |
The geofence status handle. |
This Geofence Manager API provides service related to geofence(geo-fence).
Required Header
#include <geofence_manager.h>
Overview
This Geofence Manager API provides service related to geofence(geo-fence). A geofence is a virtual perimeter for a real-world geographic area. This API provides functions to set geofence with geopoint, MAC address of Wi-Fi and Bluetooth address. And, notifications on events like changing in service status are provided.
There are two kinds of places and fences:
- Public places and fences that are created by MyPlace app can be used by all apps.
- Private places and fences that are created by specified app can be used by the same app.
Notifications can be received about the following events:
- Zone in when a device enters a specific area
- Zone out when a device exits a specific area
- Results and errors for each event requested to geofence module
The Geofence manager has the following properties:
- geofence type
- status
- 'Service state change' callback
The geofence type property of geofence manager (geofence_type_e) specified the type of virtual perimeter.
The status property describes the current state and duration of a geofence. state (geofence_state_e) can be uncertain, in, or out.
Related Features
This API is related with the following features:
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.
- Since :
- 2.4
Typedef Documentation
typedef void(* geofence_event_cb)(int place_id, int geofence_id, geofence_manager_error_e error, geofence_manage_e manage, void *user_data) |
Called when the some event occurs in geofence and place such as add, update, etc..
The events of public geofence is also received if there are public geofences.
- Since :
- 2.4
- Remarks:
- The value of place_id or geofence_id is -1 when the place id or geofence id is not assigned.
- Parameters:
-
[in] place_id The place id [in] geofence_id The specified geofence id [in] error The error code for the particular action [in] manage The result code for the particular place and geofence management [in] user_data The user data passed from callback registration function
- Precondition:
- geofence_manager_start() will invoke this callback if you register this callback using geofence_manager_set_geofence_state_changed_cb()
typedef struct geofence_s* geofence_h |
The geofence handle.
- Since :
- 2.4
typedef bool(* geofence_manager_fence_cb)(int geofence_id, geofence_h fence, int fence_index, int fence_cnt, void *user_data) |
Called when the fence list is requested.
- Since :
- 2.4
- Parameters:
-
[in] geofence_id The geofence id [in] fence The fence handle [in] fence_index The index number of the fences in the list [in] fence_cnt The total number of fences that exists for the requester [in] user_data The user data passed from callback registration function
- Returns:
- true to continue iterating, otherwise false
- Precondition:
- geofence_manager_foreach_geofence_list() and geofence_manager_foreach_place_geofence_list() will invoke this callback if you specify this callback using geofence_manager_foreach_geofence_list().
- See also:
- geofence_manager_foreach_geofence_list()
- geofence_manager_foreach_place_geofence_list()
- geofence_manager_add()
typedef struct geofence_manager_s* geofence_manager_h |
The geofence manager handle.
- Since :
- 2.4
typedef bool(* geofence_manager_place_cb)(int place_id, const char *place_name, int place_index, int place_cnt, void *user_data) |
Called when the place list is requested.
- Since :
- 2.4
- Parameters:
-
[in] place_id The current place id [in] place_name The current place name [in] place_index The index number of the places in the list [in] place_cnt The total number of places that exists for the requester [in] user_data The user data passed from callback registration function
- Returns:
- true to continue iterating, otherwise false
- Precondition:
- geofence_manager_foreach_place_list() will invoke this callback if you specify this callback using geofence_manager_foreach_place_list().
typedef void(* geofence_state_changed_cb)(int geofence_id, geofence_state_e state, void *user_data) |
Called when a device enters or exits the given geofence.
- Since :
- 2.4
- Parameters:
-
[in] geofence_id The specified geofence id [in] state The geofence state [in] user_data The user data passed from callback registration function
- Precondition:
- geofence_manager_start() will invoke this callback if you register this callback using geofence_manager_set_geofence_state_changed_cb().
typedef struct geofence_status_s* geofence_status_h |
The geofence status handle.
- Since :
- 2.4
Enumeration Type Documentation
enum geofence_manage_e |
Enumerations for geofence management events.
- Since :
- 2.4
- Enumerator:
Enumerations of error code for Geofence manager.
- Since :
- 2.4
- Enumerator:
enum geofence_state_e |
enum geofence_type_e |
Function Documentation
int geofence_manager_add_fence | ( | geofence_manager_h | manager, |
const geofence_h | fence, | ||
int * | geofence_id | ||
) |
Adds a geofence for a given geofence manager.
- Since :
- 2.4
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/location
- Parameters:
-
[in] manager The geofence manager handle [in] fence The geofence handle [out] geofence_id The geofence id handle to be newly created on success
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
GEOFENCE_MANAGER_ERROR_NONE Successful GEOFENCE_MANAGER_ERROR_INVALID_PARAMETER Illegal argument GEOFENCE_MANAGER_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function GEOFENCE_MANAGER_ERROR_NOT_INITIALIZED Not initialized GEOFENCE_MANAGER_ERROR_EXCEPTION Exception occurred
int geofence_manager_add_place | ( | geofence_manager_h | manager, |
const char * | place_name, | ||
int * | place_id | ||
) |
Creates a new place for geofencing service.
- Since :
- 2.4
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/location
- Parameters:
-
[in] manager The geofence manager handle [in] place_name A place name to be created [out] place_id The place id to be newly created on success
- Return values:
-
GEOFENCE_MANAGER_ERROR_NONE Successful GEOFENCE_MANAGER_ERROR_INVALID_PARAMETER Illegal argument GEOFENCE_MANAGER_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function GEOFENCE_MANAGER_ERROR_NOT_INITIALIZED Not initialized GEOFENCE_MANAGER_ERROR_EXCEPTION Exception occurred
int geofence_manager_create | ( | geofence_manager_h * | manager | ) |
Creates a new geofence manager.
- Since :
- 2.4
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/location
- Remarks:
- The manager must be released using geofence_manager_destroy().
- Parameters:
-
[out] manager A geofence manager handle to be newly created on success
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
GEOFENCE_MANAGER_ERROR_NONE Successful GEOFENCE_MANAGER_ERROR_OUT_OF_MEMORY Out of memory GEOFENCE_MANAGER_ERROR_INVALID_PARAMETER Illegal argument GEOFENCE_MANAGER_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function GEOFENCE_MANAGER_ERROR_NOT_INITIALIZED Not initialized GEOFENCE_MANAGER_ERROR_EXCEPTION Exception occurred
- See also:
- geofence_manager_destroy()
int geofence_manager_destroy | ( | geofence_manager_h | manager | ) |
Releases the geofence manager.
- Since :
- 2.4
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/location
- Parameters:
-
[in] manager The geofence manager handle
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
GEOFENCE_MANAGER_ERROR_NONE Successful GEOFENCE_MANAGER_ERROR_INVALID_PARAMETER Illegal argument GEOFENCE_MANAGER_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function GEOFENCE_MANAGER_ERROR_EXCEPTION Exception occurred
- Precondition:
- geofence_manager_stop() is called before.
int geofence_manager_foreach_geofence_list | ( | geofence_manager_h | manager, |
geofence_manager_fence_cb | callback, | ||
void * | user_data | ||
) |
Retrieves a list of fences registered in the specified geofence manager.
- Since :
- 2.4
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/location
- Parameters:
-
[in] manager The geofence manager handle [in] callback The callback function to deliver each fence [in] user_data The user data to be passed to the callback function
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
GEOFENCE_MANAGER_ERROR_NONE Successful GEOFENCE_MANAGER_ERROR_INVALID_PARAMETER Illegal argument GEOFENCE_MANAGER_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function GEOFENCE_MANAGER_ERROR_DATABASE Database error
- Postcondition:
- This function invokes geofence_manager_fence_cb().
- See also:
- geofence_manager_fence_cb()
- geofence_manager_add()
int geofence_manager_foreach_place_geofence_list | ( | geofence_manager_h | manager, |
int | place_id, | ||
geofence_manager_fence_cb | callback, | ||
void * | user_data | ||
) |
Retrieves a list of fences registered in the specified place.
- Since :
- 2.4
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/location
- Parameters:
-
[in] place_id The place id [in] callback The callback function to deliver each fence of the specified place [in] user_data The user data to be passed to the callback function
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
GEOFENCE_MANAGER_ERROR_NONE Successful GEOFENCE_MANAGER_ERROR_INVALID_PARAMETER Illegal argument GEOFENCE_MANAGER_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function GEOFENCE_MANAGER_ERROR_DATABASE Database error GEOFENCE_MANAGER_ERROR_PLACE_ACCESS_DENIED Access to specified place is denied
- Postcondition:
- This function invokes geofence_manager_fence_cb().
- See also:
- geofence_manager_fence_at_place_cb()
- geofence_manager_add_place()
int geofence_manager_foreach_place_list | ( | geofence_manager_h | manager, |
geofence_manager_place_cb | callback, | ||
void * | user_data | ||
) |
Retrieves a list of place registered in the specified geofence manager.
- Since :
- 2.4
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/location
- Parameters:
-
[in] manager The geofence manager handle [in] callback The callback function to deliver each place of the specified geofence manager [in] user_data The user data to be passed to the callback function
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
GEOFENCE_MANAGER_ERROR_NONE Successful GEOFENCE_MANAGER_ERROR_INVALID_PARAMETER Illegal argument GEOFENCE_MANAGER_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function GEOFENCE_MANAGER_ERROR_DATABASE Database error
- Postcondition:
- This function invokes geofence_manager_place_cb().
int geofence_manager_get_place_name | ( | geofence_manager_h | manager, |
int | place_id, | ||
char ** | place_name | ||
) |
Gets the name of place.
- Since :
- 2.4
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/location
- Remarks:
- The place_name must be released using free().
- Parameters:
-
[in] manager The geofence manager handle [in] place_id The place id [out] place_name The name of the place
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
GEOFENCE_MANAGER_ERROR_NONE Successful GEOFENCE_MANAGER_ERROR_INVALID_PARAMETER Illegal argument GEOFENCE_MANAGER_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function #GEOFENCE_MANAGER_ERROR_INVALI_ID GEOFENCE_MANAGER_ERROR_DATABASE Database error GEOFENCE_MANAGER_ERROR_PLACE_ACCESS_DENIED Access to specified place is denied
int geofence_manager_is_supported | ( | bool * | supported | ) |
Checks whether the geofence manager is available or not.
- Since :
- 2.4
- Parameters:
-
[out] supported true
if geofence service is supported, otherwisefalse
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
GEOFENCE_MANAGER_ERROR_NONE Successful
- See also:
- geofence_manager_create()
int geofence_manager_remove_fence | ( | geofence_manager_h | manager, |
int | geofence_id | ||
) |
Removes a geofence with a given geofence id.
- Since :
- 2.4
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/location
- Parameters:
-
[in] manager The geofence manager handle [in] geofence_id The specified geofence id
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
GEOFENCE_MANAGER_ERROR_NONE Successful GEOFENCE_MANAGER_ERROR_INVALID_PARAMETER Illegal argument GEOFENCE_MANAGER_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function GEOFENCE_MANAGER_ERROR_NOT_INITIALIZED Not initialized GEOFENCE_MANAGER_ERROR_EXCEPTION Exception occurred GEOFENCE_MANAGER_ERROR_GEOFENCE_ACCESS_DENIED Access to specified geofence is denied
- Precondition:
- geofence_manager_stop() is called before.
- See also:
- geofence_manager_add_fence()
int geofence_manager_remove_place | ( | geofence_manager_h | manager, |
int | place_id | ||
) |
Removes the specific place for geofencing service.
- Since :
- 2.4
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/location
- Remarks:
- The place must have no geofences.
- Parameters:
-
[in] manager The geofence manager handle [in] place_id The specified place id
- Return values:
-
GEOFENCE_MANAGER_ERROR_NONE Successful GEOFENCE_MANAGER_ERROR_INVALID_PARAMETER Illegal argument GEOFENCE_MANAGER_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function GEOFENCE_MANAGER_ERROR_NOT_INITIALIZED Not initialized GEOFENCE_MANAGER_ERROR_EXCEPTION Exception occurred GEOFENCE_MANAGER_ERROR_PLACE_ACCESS_DENIED Access to specified place is denied
- Precondition:
- geofence_manager_remove_fence() in all geofence is called before.
int geofence_manager_set_geofence_event_cb | ( | geofence_manager_h | manager, |
geofence_event_cb | callback, | ||
void * | user_data | ||
) |
Registers a callback function to be invoked when a response comes.
- Since :
- 2.4
- Parameters:
-
[in] manager The geofence manager handle [in] callback The callback function to register [in] user_data The user data to be passed to the callback function
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
GEOFENCE_MANAGER_ERROR_NONE Successful GEOFENCE_MANAGER_ERROR_INVALID_PARAMETER Illegal argument
- Postcondition:
- This function invokes geofence_event_cb().
int geofence_manager_set_geofence_state_changed_cb | ( | geofence_manager_h | manager, |
geofence_state_changed_cb | callback, | ||
void * | user_data | ||
) |
Registers a callback function to be invoked when a device enters or exits the specific geofence.
- Since :
- 2.4
- Parameters:
-
[in] manager The geofence manager handle [in] callback The callback function to register [in] user_data The user data to be passed to the callback function
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
GEOFENCE_MANAGER_ERROR_NONE Successful GEOFENCE_MANAGER_ERROR_INVALID_PARAMETER Illegal argument
- Postcondition:
- This function invokes geofence_state_changed_cb().
int geofence_manager_start | ( | geofence_manager_h | manager, |
int | geofence_id | ||
) |
Starts the geofencing service.
- Since :
- 2.4
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/location
- Remarks:
- There is no limit on number of geofence managers for which this function called
Calling this function invokes a location service event. When the location service is enabled, the service state change callback (set using geofence_manager_set_geofence_state_changed_cb()) notifies the user with geofence id as the 1st argument, geofence zone state(GEOFENCE_STATE_IN and GEOFENCE_STATE_OUT) as the 2nd argument, and the service starts
- Parameters:
-
[in] manager The geofence manager handle [in] geofence_id The specified geofence id
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
GEOFENCE_MANAGER_ERROR_NONE Successful GEOFENCE_MANAGER_ERROR_INVALID_PARAMETER Illegal argument GEOFENCE_MANAGER_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function GEOFENCE_MANAGER_ERROR_EXCEPTION Exception occurred GEOFENCE_MANAGER_ERROR_GEOFENCE_ACCESS_DENIED Access to specified geofence is denied
int geofence_manager_stop | ( | geofence_manager_h | manager, |
int | geofence_id | ||
) |
Stops the geofenceing service.
- Since :
- 2.4
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/location
- Remarks:
- This function initiates the process of stopping the service.
You can stop and start the geofence manager as needed.
- Parameters:
-
[in] manager The geofence manager handle [in] geofence_id The specified geofence id
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
GEOFENCE_MANAGER_ERROR_NONE Successful GEOFENCE_MANAGER_ERROR_INVALID_PARAMETER Illegal argument GEOFENCE_MANAGER_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function GEOFENCE_MANAGER_ERROR_NOT_INITIALIZED Not initialized GEOFENCE_MANAGER_ERROR_EXCEPTION Exception occurred GEOFENCE_MANAGER_ERROR_GEOFENCE_ACCESS_DENIED Access to specified geofence is denied
- See also:
- geofence_manager_start()
int geofence_manager_unset_geofence_event_cb | ( | geofence_manager_h | manager | ) |
Unregisters the callback function.
- Since :
- 2.4
- Parameters:
-
[in] manager The geofence manager handle
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
GEOFENCE_MANAGER_ERROR_NONE Successful GEOFENCE_MANAGER_ERROR_INVALID_PARAMETER Illegal argument
- See also:
- geofence_event_cb()
Unregisters the callback function.
- Since :
- 2.4
- Parameters:
-
[in] manager The geofence manager handle
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
GEOFENCE_MANAGER_ERROR_NONE Successful GEOFENCE_MANAGER_ERROR_INVALID_PARAMETER Illegal argument
- See also:
- geofence_state_changed_cb()
int geofence_manager_update_place | ( | geofence_manager_h | manager, |
int | place_id, | ||
const char * | place_name | ||
) |
Updates the place name of a given place id.
- Since :
- 2.4
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/location
- Parameters:
-
[in] manager The geofence manager handle [in] place_id The specified place id [in] place_name A new place name of the place id
- Return values:
-
GEOFENCE_MANAGER_ERROR_NONE Successful GEOFENCE_MANAGER_ERROR_INVALID_PARAMETER Illegal argument GEOFENCE_MANAGER_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function GEOFENCE_MANAGER_ERROR_NOT_INITIALIZED Not initialized GEOFENCE_MANAGER_ERROR_EXCEPTION Exception occurred GEOFENCE_MANAGER_ERROR_PLACE_ACCESS_DENIED Access to specified place is denied