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

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]	state	The boundary state
[in]	user_data	The 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]	coords	The coordinates
[in]	user_data	The 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

enum location_bound_error_e

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

enum location_boundary_state_e

Enumeration for the boundary state.

Since :: 2.3

Enumerator:

LOCATIONS_BOUNDARY_IN	Boundary In (Zone In)
LOCATIONS_BOUNDARY_OUT	Boundary Out (Zone Out)

enum location_bounds_type_e

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

bool location_bounds_contains_coordinates	(	location_bounds_h	bounds,
		location_coords_s	coords
	)

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]	bounds	The location bounds handle
[in]	coords	The coordinates

Returns:: true if the bounds contains the specified coordinates, otherwise else false

Exceptions:

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

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.

Since :: 6.0

Parameters:

[in]	bounds	The location bounds handle
[in]	coords	The coordinates
[in]	tolerance	tolerance in metres

Returns:: true if the distance between edges of bounds and point at coords are not farther than tolerance otherwise false

Exceptions:

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

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]	center	The center position
[in]	radius	The radius of a circle (meters)
[out]	bounds	The location bounds handle that is newly created

Returns:: 0 on success, otherwise a negative error value

Return values:

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

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_list	The list of coordinates
[in]	length	The length of the coordinates list
[out]	bounds	The location bounds handle that is newly created on success

Returns:: 0 on success, otherwise a negative error value

Return values:

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

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_left	The top left position
[in]	bottom_right	The bottom right position
[out]	bounds	The location bounds handle that is newly created

Returns:: 0 on success, otherwise a negative error value

Return values:

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

See also:: location_bounds_get_rect_coords(); location_bounds_destroy()

int location_bounds_destroy ( location_bounds_h bounds )

Releases the location bounds.

Since :: 2.3

Parameters:

[in] bounds The location bounds handle

Returns:: 0 on success, otherwise a negative error value

Return values:

LOCATION_BOUNDS_ERROR_NONE	Successful
LOCATION_BOUNDS_ERROR_INVALID_PARAMETER	Invalid parameter
LOCATION_BOUNDS_ERROR_NOT_SUPPORTED	Not 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]	bounds	The location bounds handle
[in]	callback	The iteration callback
[in]	user_data	The user data to be passed to the callback function

Returns:: 0 on success, otherwise a negative error value

Return values:

LOCATION_BOUNDS_ERROR_NONE	Successful
LOCATION_BOUNDS_ERROR_INVALID_PARAMETER	Invalid parameter
LOCATION_BOUNDS_ERROR_NOT_SUPPORTED	Not supported
LOCATION_BOUNDS_ERROR_INCORRECT_TYPE	Incorrect 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]	bounds	The location bounds handle
[out]	center	The center position of the circle
[out]	radius	The radius of the circle

Returns:: 0 on success, otherwise a negative error value

Return values:

LOCATION_BOUNDS_ERROR_NONE	Successful
LOCATION_BOUNDS_ERROR_INVALID_PARAMETER	Invalid parameter
LOCATION_BOUNDS_ERROR_NOT_SUPPORTED	Not supported
LOCATION_BOUNDS_ERROR_INCORRECT_TYPE	Incorrect 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]	bounds	The location bounds handle
[out]	top_left	The top left position
[out]	bottom_right	The bottom right position

Returns:: 0 on success, otherwise a negative error value

Return values:

LOCATION_BOUNDS_ERROR_NONE	Successful
LOCATION_BOUNDS_ERROR_INVALID_PARAMETER	Invalid parameter
LOCATION_BOUNDS_ERROR_NOT_SUPPORTED	Not supported
LOCATION_BOUNDS_ERROR_INCORRECT_TYPE	Incorrect bounds type

See also:: location_bounds_create_rect()

int location_bounds_get_type	(	location_bounds_h	bounds,
		location_bounds_type_e *	type
	)

Gets the type of location bounds.

Since :: 2.3

Parameters:

[in]	bounds	The location bounds handle
[out]	type	The type of location bounds

Returns:: 0 on success, otherwise a negative error value

Return values:

LOCATION_BOUNDS_ERROR_NONE	Successful
LOCATION_BOUNDS_ERROR_INVALID_PARAMETER	Invalid parameter
LOCATION_BOUNDS_ERROR_NOT_SUPPORTED	Not supported

See also:: location_bounds_create_rect(); location_bounds_create_circle(); location_bounds_create_polygon()

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.

Since :: 2.3

Parameters:

[in]	bounds	The location bounds 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:

LOCATION_BOUNDS_ERROR_NONE	Successful
LOCATION_BOUNDS_ERROR_INVALID_PARAMETER	Invalid parameter
LOCATION_BOUNDS_ERROR_NOT_SUPPORTED	Not supported

Postcondition:: location_bounds_state_changed_cb() will be invoked.

See also:: location_bounds_unset_state_changed_cb(); location_bounds_state_changed_cb()

int location_bounds_unset_state_changed_cb ( location_bounds_h bounds )

Unregisters the callback function.

Since :: 2.3

Parameters:

[in] bounds The location bounds handle

Returns:: 0 on success, otherwise a negative error value

Return values:

LOCATION_BOUNDS_ERROR_NONE	Successful
LOCATION_BOUNDS_ERROR_INVALID_PARAMETER	Invalid parameter
LOCATION_BOUNDS_ERROR_NOT_SUPPORTED	Not supported

See also:: location_bounds_set_state_changed_cb()

Required Header

Overview

Related Features

Functions

Typedefs

Typedef Documentation

Enumeration Type Documentation

Function Documentation