Tizen Native API  4.0

The Location Bounds APIs provides functions related to geographic bounds information.

Required Header

#include <locations.h>

Overview

Boundary defines geographical boundary. It is same as geo-fence which is a virtual perimeter for a real-world geographic area. If you create a boundary, you can trigger some activities when a device enters(or exits) the boundaries defined by you.

Related Features

This API is related with the following features:

Functions

int location_bounds_create_rect (location_coords_s top_left, location_coords_s bottom_right, location_bounds_h *bounds)
 Creates a rect type of new location bounds.
int location_bounds_create_circle (location_coords_s center, double radius, location_bounds_h *bounds)
 Creates a circle type of new location bounds.
int location_bounds_create_polygon (location_coords_s *coords_list, int length, location_bounds_h *bounds)
 Creates a polygon type of new location bounds.
bool location_bounds_contains_coordinates (location_bounds_h bounds, location_coords_s coords)
 Checks whether the bounds contains the specified coordinates.
int location_bounds_get_type (location_bounds_h bounds, location_bounds_type_e *type)
 Gets the type of location bounds.
int location_bounds_get_rect_coords (location_bounds_h bounds, location_coords_s *top_left, location_coords_s *bottom_right)
 Gets the center position and radius of circle bounds.
int location_bounds_get_circle_coords (location_bounds_h bounds, location_coords_s *center, double *radius)
 Gets the center position and radius of circle bounds.
int location_bounds_foreach_polygon_coords (location_bounds_h bounds, polygon_coords_cb callback, void *user_data)
 Get the coordinates of a polygon.
int location_bounds_destroy (location_bounds_h bounds)
 Releases the location bounds.
int location_bounds_set_state_changed_cb (location_bounds_h bounds, location_bounds_state_changed_cb callback, void *user_data)
 Registers a callback function to be invoked when the boundary area is entered or exited.
int location_bounds_unset_state_changed_cb (location_bounds_h bounds)
 Unregisters the callback function.

Typedefs

typedef struct location_bounds_s * location_bounds_h
 The location boundary handle.
typedef bool(* polygon_coords_cb )(location_coords_s coords, void *user_data)
 Gets called iteratively to notify you of coordinates of a polygon.
typedef void(* location_bounds_state_changed_cb )(location_boundary_state_e state, void *user_data)
 Called when the given boundary is entered or exited.

Typedef Documentation

typedef struct location_bounds_s* location_bounds_h

The location boundary handle.

Since :
2.3
typedef void(* location_bounds_state_changed_cb)(location_boundary_state_e state, void *user_data)

Called when the given boundary is entered or exited.

Since :
2.3
Parameters:
[in]stateThe boundary state
[in]user_dataThe user data passed from the start function
Precondition:
location_manager_start() will invoke this callback if you register this callback using location_bounds_set_state_changed_cb().
See also:
location_boundary_state_e
location_manager_start()
location_bounds_set_state_changed_cb()
typedef bool(* polygon_coords_cb)(location_coords_s coords, void *user_data)

Gets called iteratively to notify you of coordinates of a polygon.

Since :
2.3
Parameters:
[in]coordsThe coordinates
[in]user_dataThe user data passed from the foreach function
Returns:
true to continue with the next iteration of the loop,
false to break out of the loop
Precondition:
location_bounds_foreach_polygon_coords() will invoke this callback.
See also:
location_bounds_foreach_polygon_coords()

Enumeration Type Documentation

Enumeration for error code for Location manager.

Since :
2.3
Enumerator:
LOCATION_BOUNDS_ERROR_NONE 

Successful

LOCATION_BOUNDS_ERROR_OUT_OF_MEMORY 

Out of memory

LOCATION_BOUNDS_ERROR_INVALID_PARAMETER 

Invalid parameter

LOCATION_BOUNDS_ERROR_NOT_SUPPORTED 

Not supported

LOCATION_BOUNDS_ERROR_INCORRECT_TYPE 

Incorrect bounds type for a given call

LOCATION_BOUNDS_ERROR_IS_ADDED 

Cannot remove bounds handle from location manager

Enumeration for the boundary state.

Since :
2.3
Enumerator:
LOCATIONS_BOUNDARY_IN 

Boundary In (Zone In)

LOCATIONS_BOUNDARY_OUT 

Boundary Out (Zone Out)

Enumeration for Location boundary type.

Since :
2.3
Enumerator:
LOCATION_BOUNDS_RECT 

Rectangular geographical area type.

LOCATION_BOUNDS_CIRCLE 

Circle geographical area type..

LOCATION_BOUNDS_POLYGON 

Polygon geographical area type..


Function Documentation

Checks whether the bounds contains the specified coordinates.

Since :
2.3
Remarks:
The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
Parameters:
[in]boundsThe location bounds handle
[in]coordsThe coordinates
Returns:
true if the bounds contains the specified coordinates, otherwise else false
Exceptions:
LOCATION_BOUNDS_ERROR_NONESuccessful
LOCATION_BOUNDS_ERROR_OUT_OF_MEMORYOut of memory
LOCATION_BOUNDS_ERROR_INVALID_PARAMETERInvalid parameter
LOCATION_BOUNDS_ERROR_NOT_SUPPORTEDNot supported
See also:
location_bounds_create_rect()
location_bounds_create_circle()
location_bounds_create_polygon()
int location_bounds_create_circle ( location_coords_s  center,
double  radius,
location_bounds_h bounds 
)

Creates a circle type of new location bounds.

Since :
2.3
Remarks:
You must release bounds using location_bounds_destroy().
Parameters:
[in]centerThe center position
[in]radiusThe radius of a circle (meters)
[out]boundsThe location bounds handle that is newly created
Returns:
0 on success, otherwise a negative error value
Return values:
LOCATION_BOUNDS_ERROR_NONESuccessful
LOCATION_BOUNDS_ERROR_OUT_OF_MEMORYOut of memory
LOCATION_BOUNDS_ERROR_INVALID_PARAMETERInvalid parameter
LOCATION_BOUNDS_ERROR_NOT_SUPPORTEDNot supported
See also:
location_bounds_get_circle_coords()
location_bounds_destroy()
int location_bounds_create_polygon ( location_coords_s coords_list,
int  length,
location_bounds_h bounds 
)

Creates a polygon type of new location bounds.

Since :
2.3
Remarks:
You must release bounds using location_bounds_destroy().
length should be more than 3 to represent polygon.
Parameters:
[in]coords_listThe list of coordinates
[in]lengthThe length of the coordinates list
[out]boundsThe location bounds handle that is newly created on success
Returns:
0 on success, otherwise a negative error value
Return values:
LOCATION_BOUNDS_ERROR_NONESuccessful
LOCATION_BOUNDS_ERROR_OUT_OF_MEMORYOut of memory
LOCATION_BOUNDS_ERROR_INVALID_PARAMETERInvalid parameter
LOCATION_BOUNDS_ERROR_NOT_SUPPORTEDNot supported
See also:
location_bounds_foreach_polygon_coords()
location_bounds_destroy()
int location_bounds_create_rect ( location_coords_s  top_left,
location_coords_s  bottom_right,
location_bounds_h bounds 
)

Creates a rect type of new location bounds.

Since :
2.3
Remarks:
You must release bounds using location_bounds_destroy().
Parameters:
[in]top_leftThe top left position
[in]bottom_rightThe bottom right position
[out]boundsThe location bounds handle that is newly created
Returns:
0 on success, otherwise a negative error value
Return values:
LOCATION_BOUNDS_ERROR_NONESuccessful
LOCATION_BOUNDS_ERROR_OUT_OF_MEMORYOut of memory
LOCATION_BOUNDS_ERROR_INVALID_PARAMETERInvalid parameter
LOCATION_BOUNDS_ERROR_NOT_SUPPORTEDNot supported
See also:
location_bounds_get_rect_coords()
location_bounds_destroy()

Releases the location bounds.

Since :
2.3
Parameters:
[in]boundsThe location bounds handle
Returns:
0 on success, otherwise a negative error value
Return values:
LOCATION_BOUNDS_ERROR_NONESuccessful
LOCATION_BOUNDS_ERROR_INVALID_PARAMETERInvalid parameter
LOCATION_BOUNDS_ERROR_NOT_SUPPORTEDNot supported
See also:
location_bounds_create_rect()
location_bounds_create_circle()
location_bounds_create_polygon()
int location_bounds_foreach_polygon_coords ( location_bounds_h  bounds,
polygon_coords_cb  callback,
void *  user_data 
)

Get the coordinates of a polygon.

Since :
2.3
Parameters:
[in]boundsThe location bounds handle
[in]callbackThe iteration callback
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
LOCATION_BOUNDS_ERROR_NONESuccessful
LOCATION_BOUNDS_ERROR_INVALID_PARAMETERInvalid parameter
LOCATION_BOUNDS_ERROR_NOT_SUPPORTEDNot supported
LOCATION_BOUNDS_ERROR_INCORRECT_TYPEIncorrect bounds type
Postcondition:
It invokes polygon_coords_cb() to get coordinates of polygon.
See also:
polygon_coords_cb()
location_bounds_create_polygon()
int location_bounds_get_circle_coords ( location_bounds_h  bounds,
location_coords_s center,
double *  radius 
)

Gets the center position and radius of circle bounds.

Since :
2.3
Parameters:
[in]boundsThe location bounds handle
[out]centerThe center position of the circle
[out]radiusThe radius of the circle
Returns:
0 on success, otherwise a negative error value
Return values:
LOCATION_BOUNDS_ERROR_NONESuccessful
LOCATION_BOUNDS_ERROR_INVALID_PARAMETERInvalid parameter
LOCATION_BOUNDS_ERROR_NOT_SUPPORTEDNot supported
LOCATION_BOUNDS_ERROR_INCORRECT_TYPEIncorrect bounds type
See also:
location_bounds_create_circle()
int location_bounds_get_rect_coords ( location_bounds_h  bounds,
location_coords_s top_left,
location_coords_s bottom_right 
)

Gets the center position and radius of circle bounds.

Since :
2.3
Parameters:
[in]boundsThe location bounds handle
[out]top_leftThe top left position
[out]bottom_rightThe bottom right position
Returns:
0 on success, otherwise a negative error value
Return values:
LOCATION_BOUNDS_ERROR_NONESuccessful
LOCATION_BOUNDS_ERROR_INVALID_PARAMETERInvalid parameter
LOCATION_BOUNDS_ERROR_NOT_SUPPORTEDNot supported
LOCATION_BOUNDS_ERROR_INCORRECT_TYPEIncorrect bounds type
See also:
location_bounds_create_rect()

Gets the type of location bounds.

Since :
2.3
Parameters:
[in]boundsThe location bounds handle
[out]typeThe type of location bounds
Returns:
0 on success, otherwise a negative error value
Return values:
LOCATION_BOUNDS_ERROR_NONESuccessful
LOCATION_BOUNDS_ERROR_INVALID_PARAMETERInvalid parameter
LOCATION_BOUNDS_ERROR_NOT_SUPPORTEDNot supported
See also:
location_bounds_create_rect()
location_bounds_create_circle()
location_bounds_create_polygon()

Registers a callback function to be invoked when the boundary area is entered or exited.

Since :
2.3
Parameters:
[in]boundsThe location bounds handle
[in]callbackThe callback function to register
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
LOCATION_BOUNDS_ERROR_NONESuccessful
LOCATION_BOUNDS_ERROR_INVALID_PARAMETERInvalid parameter
LOCATION_BOUNDS_ERROR_NOT_SUPPORTEDNot supported
Postcondition:
location_bounds_state_changed_cb() will be invoked.
See also:
location_bounds_unset_state_changed_cb()
location_bounds_state_changed_cb()

Unregisters the callback function.

Since :
2.3
Parameters:
[in]boundsThe location bounds handle
Returns:
0 on success, otherwise a negative error value
Return values:
LOCATION_BOUNDS_ERROR_NONESuccessful
LOCATION_BOUNDS_ERROR_INVALID_PARAMETERInvalid parameter
LOCATION_BOUNDS_ERROR_NOT_SUPPORTEDNot supported
See also:
location_bounds_set_state_changed_cb()