2 * Copyright (c) 2014 Samsung Electronics Co., Ltd All Rights Reserved
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
8 * http://www.apache.org/licenses/LICENSE-2.0
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
17 #ifndef __MAPS_GEOAREA_H__
18 #define __MAPS_GEOAREA_H__
20 #include <maps_coordinates.h>
23 * @ingroup CAPI_MAPS_SERVICE_MODULE
24 * @defgroup CAPI_MAPS_GEOAREA_MODULE Area
27 * @brief This file contains the definitions, structures, and functions related
28 * to area information.
30 * @addtogroup CAPI_MAPS_GEOAREA_MODULE
32 * @brief This provides APIs related to geographical area.
40 * @brief Handle of the Geographical Area.
41 * @details The Geographical Area handle can be obtained via call of
42 * maps_area_create_rectangle() or maps_area_create_circle().
44 * \n To release the handle use maps_area_destroy().
45 * \n To clone the handle use maps_area_clone().
48 * @see maps_area_create_rectangle()
49 * @see maps_area_create_circle()
50 * @see maps_area_destroy()
51 * @see maps_area_clone()
53 typedef void *maps_area_h;
56 * @brief Enumeration of supported types of the Geographical Area.
57 * @details This enumeration represents allowed geographical type of
58 * Geographical Area: rectangular and circular.
59 * \n This enumeration is used in #maps_area_s.
65 MAPS_AREA_NONE = 0, /**< Undefined geographical area type. */
66 MAPS_AREA_RECTANGLE, /**< Rectangular geographical area type. */
67 MAPS_AREA_CIRCLE, /**< Circle geographical area type. */
71 * @brief Structure of the rectangular Geographical Area.
72 * @details This structure represents a rectangular Geographical Area,
73 * specified with left top and right bottom coordinates.
74 * \n This structure is used in #maps_area_s.
79 typedef struct _maps_area_rectangle_s {
80 maps_coordinates_s top_left; /**< The top left position
82 maps_coordinates_s bottom_right; /**< The bottom right position
84 } maps_area_rectangle_s;
87 * @brief Structure of the circular Geographical Area, specified with a
88 * center coordinates and a radius.
89 * @details This structure represents a circular Geographical Area.
90 * \n This structure is used in #maps_area_s.
95 typedef struct _maps_area_circle_s {
97 maps_coordinates_s center; /**< The center position of a circle. */
98 double radius; /**< The radius of a circle. */
102 * @brief Structure of the Geographical Area.
103 * @details This structure represents a Geographical Area, specified with a
104 * type, circular or rectangular, and appropriate coordinates and radius.
107 * @see maps_area_type_e
108 * @see maps_area_rectangle_s
109 * @see maps_area_circle_s
111 typedef struct _maps_area_s {
112 maps_area_type_e type; /**< The area type of this information. */
114 maps_area_rectangle_s rect; /**< The geographical
115 information of a rectangle. */
116 maps_area_circle_s circle; /**< The geographical
117 information of a circle. */
121 /*----------------------------------------------------------------------------*/
124 * @brief Creates a rectangular type of new Geographical Area with a
125 * specified information.
126 * @details This function creates a rectangular type of new #maps_area_s with a
127 * specified left top and right bottom coordinates.
129 * @remarks @a area must be released using maps_area_destroy().
130 * \n @a area may be cloned using maps_area_clone().
131 * \n @a top_left and @a bottom_right must be released using
132 * maps_coordinates_destroy().
134 * @param[in] top_left The left top position
135 * @param[in] bottom_right The right bottom position
136 * @param[out] area The area handle
137 * @return 0 on success, otherwise a negative error value
138 * @retval #MAPS_ERROR_NONE Successful
139 * @retval #MAPS_ERROR_OUT_OF_MEMORY Out of memory
140 * @retval #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
142 * @pre @a top_left and @a bottom_right are created using
143 * maps_coordinates_create().
145 * @see maps_area_clone()
146 * @see maps_area_destroy()
147 * @see maps_area_create_circle()
149 * @see maps_coordinates_create()
150 * @see maps_coordinates_destroy()
152 int maps_area_create_rectangle(const maps_coordinates_h top_left,
153 const maps_coordinates_h bottom_right,
157 * @brief Creates a circular type of new Geographical Area with a
158 * specified information.
159 * @details This function creates a circular type of new #maps_area_s
160 * Geographical Area with a specified center coordinates and a radius.
162 * @remarks @a area must be released using maps_area_destroy().
163 * \n @a center must be released using maps_coordinates_destroy().
164 * \n The @a radius is specified in units, listed in #maps_distance_unit_e.
165 * \n To get and set distance units use maps_preference_get_distance_unit() and
166 * maps_preference_set_distance_unit() respectively.
168 * @param[in] center The central position of the area
169 * @param[in] radius The radius of the area
170 * @param[out] area The area handle
171 * @return 0 on success, otherwise a negative error value
172 * @retval #MAPS_ERROR_NONE Successful
173 * @retval #MAPS_ERROR_OUT_OF_MEMORY Out of memory
174 * @retval #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
176 * @pre @a center is created using maps_coordinates_create().
178 * @see maps_area_clone()
179 * @see maps_area_destroy()
180 * @see maps_area_create_rectangle()
182 * @see maps_coordinates_create()
183 * @see maps_coordinates_destroy()
184 * @see maps_preference_get_distance_unit()
185 * @see maps_preference_set_distance_unit()
187 int maps_area_create_circle(const maps_coordinates_h center,
188 const double radius, maps_area_h *area);
191 * @brief Destroys the Geographical Area and releases all its resources.
192 * @details This function destroys the Geographical Area #maps_area_s and
193 * releases all its resources.
196 * @param[in] area The area #maps_area_s
197 * @return 0 on success, otherwise a negative error value
198 * @retval #MAPS_ERROR_NONE Successful
199 * @retval #MAPS_ERROR_OUT_OF_MEMORY Out of memory
200 * @retval #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
202 * @pre @a area can be created using maps_area_create_rectangle() or
203 * maps_area_create_circle().
205 * @see maps_area_create_rectangle()
206 * @see maps_area_create_circle()
208 int maps_area_destroy(maps_area_h area);
211 * @brief Clones the Geographical Area.
212 * @details This function makes a clone of the @a origin Geographical Area of
215 * @remarks @a cloned must be released using maps_area_destroy().
217 * @param[in] origin The area #maps_area_s to be copied
218 * @param[out] cloned The cloned area #maps_area_s handle
219 * @return 0 on success, otherwise a negative error value
220 * @retval #MAPS_ERROR_NONE Successful
221 * @retval #MAPS_ERROR_OUT_OF_MEMORY Out of memory
222 * @retval #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
224 * @pre @a origin is created using maps_area_create_rectangle() or
225 * maps_area_create_circle().
227 * @see maps_area_create_rectangle()
228 * @see maps_area_create_circle()
229 * @see maps_area_destroy()
232 int maps_area_clone(const maps_area_h origin, maps_area_h *cloned);
240 #endif /* __MAPS_GOEAREA_H__ */