Tizen Native API  5.5

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:

  • http://tizen.org/feature/location
  • http://tizen.org/feature/location.gps
  • http://tizen.org/feature/location.wps

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 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.
bool location_bounds_contains_coordinates_on_edge (location_bounds_h bounds, location_coords_s coords, double tolerance)
 Checks whether the edges of the bounds contain the specified coordinates within tolerance.
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.1
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.1
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.1
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.1
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.1
Enumerator:
LOCATIONS_BOUNDARY_IN 

Boundary In (Zone In)

LOCATIONS_BOUNDARY_OUT 

Boundary Out (Zone Out)

Enumeration for Location boundary type.

Since :
2.3.1
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.1
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()
bool location_bounds_contains_coordinates_on_edge ( location_bounds_h  bounds,
location_coords_s  coords,
double  tolerance 
)

Checks whether the edges of the bounds contain the specified coordinates within tolerance.

Parameters:
[in]boundsThe location bounds handle
[in]coordsThe coordinates
[in]tolerancetolerance in metres
Returns:
true if the edges of the bounds contain the specified coordinates within tolerance, 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.1
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.1
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.1
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.1
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.1
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.1
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.1
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.1
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.1
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.1
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()